mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2025-12-15 10:30:25 -08:00
Code Issues Projects Releases Wiki Activity

Improve documentation of locale-specific string comparison

Browse source 
* doc/lispref/strings.texi (Text Comparison):
* src/fns.c (Fstring_collate_equalp): Improve documentation of
'string-collate-equalp' and 'string-collate-lessp'.  (Bug#59275)
This commit is contained in:
Eli Zaretskii 2022-11-23 16:54:01 +02:00
parent 5568ac2db0
commit 43e616aca5
2 changed files with 24 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

32
doc/lispref/strings.texi
View file

@ -558,11 +558,13 @@ differences, like @code{char-equal} when @code{case-fold-search} is
@cindex locale-dependent string equivalence
@defun string-collate-equalp string1 string2 &optional locale ignore-case
This function returns @code{t} if @var{string1} and @var{string2} are
equal with respect to collation rules. A collation rule is not only
equal with respect to the collation rules of the specified
@var{locale}, which defaults to your current system locale. A
collation rule is not only
determined by the lexicographic order of the characters contained in
@var{string1} and @var{string2}, but also further rules about
@var{string1} and @var{string2}, but also by further rules about
relations between these characters. Usually, it is defined by the
@var{locale} environment Emacs is running with and by the Standard C
locale environment with which Emacs is running and by the Standard C
library against which Emacs was linked@footnote{
For more information about collation rules and their locale
dependencies, see @uref{https://unicode.org/reports/tr10/, The Unicode
@ -589,8 +591,12 @@ dependent; a @var{locale} @code{"en_US.UTF-8"} is applicable on POSIX
systems, while it would be, e.g., @code{"enu_USA.1252"} on MS-Windows
systems.
If @var{ignore-case} is non-@code{nil}, characters are converted to lower-case
before comparing them.
If @var{ignore-case} is non-@code{nil}, characters are compared
case-insensitively, by converting them to lower-case. However, if the
underlying system library doesn't provide locale-specific collation
rules, this function falls back to @code{string-equal}, in which case
the @var{ignore-case} argument is ignored, and the comparison will
always be case-sensitive.
@vindex w32-collate-ignore-punctuation
To emulate Unicode-compliant collation on MS-Windows systems,
@ -672,11 +678,13 @@ This function returns the result of comparing @var{string1} and
@cindex locale-dependent string comparison
@defun string-collate-lessp string1 string2 &optional locale ignore-case
This function returns @code{t} if @var{string1} is less than
@var{string2} in collation order. A collation order is not only
@var{string2} in collation order of the specified @var{locale}, which
defaults to your current system locale. A collation order is not only
determined by the lexicographic order of the characters contained in
@var{string1} and @var{string2}, but also further rules about
@var{string1} and @var{string2}, but also by further rules about
relations between these characters. Usually, it is defined by the
@var{locale} environment Emacs is running with.
locale environment with which Emacs is running, and by the Standard C
library against which Emacs was linked.
For example, punctuation and whitespace characters might be ignored
for sorting (@pxref{Sequence Functions}):
@ -706,8 +714,12 @@ systems. The @var{locale} value of @code{"POSIX"} or @code{"C"} lets
@end group
@end example
If @var{ignore-case} is non-@code{nil}, characters are converted to lower-case
before comparing them.
If @var{ignore-case} is non-@code{nil}, characters are compared
case-insensitively, by converting them to lower-case. However, if the
underlying system library doesn't provide locale-specific collation
rules, this function falls back to @code{string-lessp}, in which case
the @var{ignore-case} argument is ignored, and the comparison will
always be case-sensitive.
To emulate Unicode-compliant collation on MS-Windows systems,
bind @code{w32-collate-ignore-punctuation} to a non-@code{nil} value, since