[Emacs-diffs] trunk r117832: * strings.texi (Text Comparison): Describe `string-collate-equalp'

[Michael Albinus]

------------------------------------------------------------
revno: 117832
revision-id: address@hidden
parent: address@hidden
committer: Michael Albinus <address@hidden>
branch nick: trunk
timestamp: Sun 2014-09-07 13:02:33 +0200
message:
  * strings.texi (Text Comparison): Describe `string-collate-equalp'
  and `string-collate-lessp'.
modified:
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/strings.texi       
strings.texi-20091113204419-o5vbwnq5f7feedwu-6212

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2014-09-06 00:59:00 +0000
+++ b/doc/lispref/ChangeLog     2014-09-07 11:02:33 +0000
@@ -1,3 +1,8 @@
+2014-09-07  Michael Albinus  <address@hidden>
+
+       * strings.texi (Text Comparison): Describe `string-collate-equalp'
+       and `string-collate-lessp'.
+
 2014-09-06  Leo Liu  <address@hidden>
 
        * control.texi (Pattern matching case statement): Document vector

=== modified file 'doc/lispref/strings.texi'
--- a/doc/lispref/strings.texi  2014-04-24 15:11:04 +0000
+++ b/doc/lispref/strings.texi  2014-09-07 11:02:33 +0000
@@ -458,6 +458,59 @@
 @code{string-equal} is another name for @code{string=}.
 @end defun
 
address@hidden 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
address@hidden and @var{string2}, but also further rules about
+relations between these characters.  Usually, it is defined by the
address@hidden 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:
+
address@hidden
address@hidden
+(string-collate-equalp (string ?\uFF40) (string ?\u1FEF))
+     @result{} t
address@hidden group
address@hidden 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.
address@hidden defun
+
address@hidden string-prefix-p string1 string2 &optional ignore-case
+This function returns address@hidden if @var{string1} is a prefix of
address@hidden; i.e., if @var{string2} starts with @var{string1}.  If
+the optional argument @var{ignore-case} is address@hidden, the
+comparison ignores case differences.
address@hidden defun
+
address@hidden string-suffix-p suffix string &optional ignore-case
+This function returns address@hidden if @var{suffix} is a suffix of
address@hidden; i.e., if @var{string} ends with @var{suffix}.  If the
+optional argument @var{ignore-case} is address@hidden, the comparison
+ignores case differences.
address@hidden defun
+
 @cindex lexical comparison
 @defun string< string1 string2
 @c (findex string< causes problems for permuted index!!)
@@ -516,6 +569,50 @@
 @code{string-lessp} is another name for @code{string<}.
 @end defun
 
address@hidden string-collate-lessp string1 string2 &optional locale ignore-case
+This function returns @code{t} if @var{string1} is less than
address@hidden in collation order.  A collation order is not only
+determined by the lexicographic order of the characters contained in
address@hidden and @var{string2}, but also further rules about
+relations between these characters.  Usually, it is defined by the
address@hidden environment Emacs is running with.
+
+For example, punctuation and whitespace characters might be considered
+less significant for @ref{Sorting,,sorting}.
+
address@hidden
address@hidden
+(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")
address@hidden group
address@hidden 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}:
+
address@hidden
address@hidden
+(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")
address@hidden group
address@hidden 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}.
address@hidden defun
+
 @defun string-prefix-p string1 string2 &optional ignore-case
 This function returns address@hidden if @var{string1} is a prefix of
 @var{string2}; i.e., if @var{string2} starts with @var{string1}.  If