From: Eli Zaretskii Date: Sun, 29 Nov 2015 17:52:16 +0000 (+0200) Subject: Improve documentation of string-collate-* functions X-Git-Tag: emacs-25.0.90~598 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=36255fba58b6c73fcf1c810877cc128091fa2a68;p=emacs.git Improve documentation of string-collate-* functions * doc/lispref/strings.texi (Text Comparison): Improve wording and indexing of 'string-collate-equalp' and 'string-collate-lessp'. * etc/NEWS: Move the entry of 'string-collate-equalp' and 'string-collate-lessp' to "Lisp Changes" section and mark it as documented. --- diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index f8685d9312c..8aa4539bd78 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -465,6 +465,7 @@ Representations}. @code{string-equal} is another name for @code{string=}. @end defun +@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 @@ -493,6 +494,7 @@ systems. If @var{ignore-case} is non-@code{nil}, characters are converted to lower-case before comparing them. +@vindex w32-collate-ignore-punctuation To emulate Unicode-compliant collation on MS-Windows systems, bind @code{w32-collate-ignore-punctuation} to a non-@code{nil} value, since the codeset part of the locale cannot be @code{"UTF-8"} on MS-Windows. @@ -518,7 +520,7 @@ optional argument @var{ignore-case} is non-@code{nil}, the comparison ignores case differences. @end defun -@cindex lexical comparison +@cindex lexical comparison of strings @defun string< string1 string2 @c (findex string< causes problems for permuted index!!) This function compares two strings a character at a time. It @@ -576,6 +578,7 @@ are used. @code{string-lessp} is another name for @code{string<}. @end defun +@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 @@ -594,15 +597,15 @@ for sorting (@pxref{Sequence Functions}): @end group @end example -This behavior is system-dependent; punctuation and whitespace are -never ignored on Cygwin, regardless of locale. +This behavior is system-dependent; e.g., punctuation and whitespace +are never ignored on Cygwin, regardless of locale. The optional argument @var{locale}, a string, overrides the setting of your current locale identifier for collation. The value is system 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. The @var{locale} @code{"POSIX"} lets @code{string-collate-lessp} -behave like @code{string-lessp}: +systems. The @var{locale} value of @code{"POSIX"} or @code{"C"} lets +@code{string-collate-lessp} behave like @code{string-lessp}: @example @group diff --git a/etc/NEWS b/etc/NEWS index dc3758f8eb2..180e48ffc36 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -181,23 +181,6 @@ for use in Emacs bug reports. hiding character but the default `.' can be used by let-binding the variable `read-hide-char'. -** The new functions `string-collate-lessp' and `string-collate-equalp' -preserve the collation order as defined by the system's locale(1) -environment. For the time being this is implemented for modern POSIX -systems and for MS-Windows, for other systems they fall back to their -counterparts `string-lessp' and `string-equal'. - -*** The ls-lisp package uses `string-collate-lessp' to sort file names. -If you want the old, locale-independent sorting, customize the new -option `ls-lisp-use-string-collate' to a nil value. - -*** The MS-Windows specific variable `w32-collate-ignore-punctuation', -if set to a non-nil value, causes the above 2 functions to ignore -symbol and punctuation characters when collating strings. This -emulates the behavior of modern Posix platforms when the locale's -codeset is "UTF-8" (as in "en_US.UTF-8"). This is needed because -MS-Windows doesn't support UTF-8 as codeset in its locales. - +++ ** The new function `bidi-find-overridden-directionality' allows to find characters whose directionality was, perhaps maliciously, @@ -1199,6 +1182,26 @@ evaluated (and should return a string) when the closure is built. ** New function `string-greaterp', which return the opposite result of `string-lessp'. ++++ +** The new functions `string-collate-lessp' and `string-collate-equalp' +preserve the collation order as defined by the system's locale(1) +environment. For the time being this is implemented for modern POSIX +systems and for MS-Windows, for other systems they fall back to their +counterparts `string-lessp' and `string-equal'. + +--- +*** The ls-lisp package uses `string-collate-lessp' to sort file names. +If you want the old, locale-independent sorting, customize the new +option `ls-lisp-use-string-collate' to a nil value. + ++++ +*** The MS-Windows specific variable `w32-collate-ignore-punctuation', +if set to a non-nil value, causes the above 2 functions to ignore +symbol and punctuation characters when collating strings. This +emulates the behavior of modern Posix platforms when the locale's +codeset is "UTF-8" (as in "en_US.UTF-8"). This is needed because +MS-Windows doesn't support UTF-8 as codeset in its locales. + ** New function `alist-get', which is also a valid place (aka lvalue). ** New function `funcall-interactively', which works like `funcall'