procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve documentation of string-collate-* functions

Browse source 
* 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.
This commit is contained in:
Eli Zaretskii 2015-11-29 19:52:16 +02:00
parent f3bd8262a2
commit 36255fba58
2 changed files with 28 additions and 22 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
doc/lispref/strings.texi
View file

@ -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

37
etc/NEWS
View file

@ -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'