From: Michael Albinus Date: Sun, 7 Sep 2014 11:02:33 +0000 (+0200) Subject: * strings.texi (Text Comparison): Describe `string-collate-equalp' X-Git-Tag: emacs-25.0.90~2635^2~679^2~339 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=d3cb31cbdfa38a19e9517bf817f106ee82d62986;p=emacs.git * strings.texi (Text Comparison): Describe `string-collate-equalp' and `string-collate-lessp'. --- diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 7b375a7a819..185e5045be7 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,8 @@ +2014-09-07 Michael Albinus + + * strings.texi (Text Comparison): Describe `string-collate-equalp' + and `string-collate-lessp'. + 2014-09-06 Leo Liu * control.texi (Pattern matching case statement): Document vector diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index e6b00f06f79..5e0148b75a9 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -458,6 +458,59 @@ Representations}. @code{string-equal} is another name for @code{string=}. @end defun +@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 +determined by the lexicographic order of the characters contained in +@var{string1} and @var{string2}, but also further rules about +relations between these characters. Usually, it is defined by the +@var{locale} environment Emacs is running with. + +For example, characters with different coding points but +the same meaning might be considered as equal, like different grave +accent Unicode characters: + +@example +@group +(string-collate-equalp (string ?\uFF40) (string ?\u1FEF)) + @result{} t +@end group +@end example + +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} "en_US.UTF-8" is applicable on POSIX +systems, while it would be, e.g., "enu_USA.1252" on MS-Windows +systems. + +If @var{IGNORE-CASE} is non-nil, characters are converted to lower-case +before comparing them. + +To emulate Unicode-compliant collation on MS-Windows systems, +bind @code{w32-collate-ignore-punctuation} to a non-nil value, since +the codeset part of the locale cannot be "UTF-8" on MS-Windows. + +If your system does not support a locale environment, this function +behaves like @code{string-equal}. + +Do NOT use this function to compare file names for equality, only +for sorting them. +@end defun + +@defun string-prefix-p string1 string2 &optional ignore-case +This function returns non-@code{nil} if @var{string1} is a prefix of +@var{string2}; i.e., if @var{string2} starts with @var{string1}. If +the optional argument @var{ignore-case} is non-@code{nil}, the +comparison ignores case differences. +@end defun + +@defun string-suffix-p suffix string &optional ignore-case +This function returns non-@code{nil} if @var{suffix} is a suffix of +@var{string}; i.e., if @var{string} ends with @var{suffix}. If the +optional argument @var{ignore-case} is non-@code{nil}, the comparison +ignores case differences. +@end defun + @cindex lexical comparison @defun string< string1 string2 @c (findex string< causes problems for permuted index!!) @@ -516,6 +569,50 @@ are used. @code{string-lessp} is another name for @code{string<}. @end defun +@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 +determined by the lexicographic order of the characters contained in +@var{string1} and @var{string2}, but also further rules about +relations between these characters. Usually, it is defined by the +@var{locale} environment Emacs is running with. + +For example, punctuation and whitespace characters might be considered +less significant for @ref{Sorting,,sorting}. + +@example +@group +(sort '("11" "12" "1 1" "1 2" "1.1" "1.2") 'string-collate-lessp) + @result{} ("11" "1 1" "1.1" "12" "1 2" "1.2") +@end group +@end example + +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} "en_US.UTF-8" is applicable on POSIX +systems, while it would be, e.g., "enu_USA.1252" on MS-Windows +systems. The @var{locale} "POSIX" lets @code{string-collate-lessp} +behave like @code{string-lessp}: + +@example +@group +(sort '("11" "12" "1 1" "1 2" "1.1" "1.2") + (lambda (s1 s2) (string-collate-lessp s1 s2 "POSIX"))) + @result{} ("1 1" "1 2" "1.1" "1.2" "11" "12") +@end group +@end example + +If @var{IGNORE-CASE} is non-nil, characters are converted to lower-case +before comparing them. + +To emulate Unicode-compliant collation on MS-Windows systems, +bind @code{w32-collate-ignore-punctuation} to a non-nil value, since +the codeset part of the locale cannot be "UTF-8" on MS-Windows. + +If your system does not support a locale environment, this function +behaves like @code{string-lessp}. +@end defun + @defun string-prefix-p string1 string2 &optional ignore-case This function returns non-@code{nil} if @var{string1} is a prefix of @var{string2}; i.e., if @var{string2} starts with @var{string1}. If