[Emacs-diffs] /srv/bzr/emacs/emacs-24 r111039: * fns.c (Fcompare_strings): Doc fix.

[Chong Yidong]

------------------------------------------------------------
revno: 111039
fixes bug: http://debbugs.gnu.org/13081
committer: Chong Yidong <address@hidden>
branch nick: emacs-24
timestamp: Sat 2012-12-15 21:44:41 +0800
message:
  * fns.c (Fcompare_strings): Doc fix.
  
  * strings.texi (Text Comparison): Doc fix for compare-strings.
modified:
  doc/lispref/ChangeLog
  doc/lispref/strings.texi
  src/ChangeLog
  src/fns.c

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-12-11 18:43:57 +0000
+++ b/doc/lispref/ChangeLog     2012-12-15 13:44:41 +0000
@@ -1,3 +1,7 @@
+2012-12-15  Chong Yidong  <address@hidden>
+
+       * strings.texi (Text Comparison): Doc fix for compare-strings.
+
 2012-12-09  Stefan Monnier  <address@hidden>
 
        * control.texi (Pattern matching case statement): New node.

=== modified file 'doc/lispref/strings.texi'
--- a/doc/lispref/strings.texi  2012-09-30 09:18:38 +0000
+++ b/doc/lispref/strings.texi  2012-12-15 13:44:41 +0000
@@ -517,25 +517,29 @@
 @end defun
 
 @defun compare-strings string1 start1 end1 string2 start2 end2 &optional 
ignore-case
-This function compares the specified part of @var{string1} with the
+This function compares a specified part of @var{string1} with a
 specified part of @var{string2}.  The specified part of @var{string1}
-runs from index @var{start1} up to index @var{end1} (@code{nil} means
-the end of the string).  The specified part of @var{string2} runs from
-index @var{start2} up to index @var{end2} (@code{nil} means the end of
-the string).
+runs from index @var{start1} (inclusive) up to index @var{end1}
+(exclusive); @code{nil} for @var{start1} means the start of the
+string, while @code{nil} for @var{end1} means the length of the
+string.  Likewise, the specified part of @var{string2} runs from index
address@hidden up to index @var{end2}.
 
-The strings are both converted to multibyte for the comparison
-(@pxref{Text Representations}) so that a unibyte string and its
-conversion to multibyte are always regarded as equal.  If
address@hidden is address@hidden, then case is ignored, so that
-upper case letters can be equal to lower case letters.
+The strings are compared by the numeric values of their characters.
+For instance, @var{str1} is considered ``smaller than'' @var{str2} if
+its first differing character has a smaller numeric value.  If
address@hidden is address@hidden, characters are converted to
+lower-case before comparing them.  Unibyte strings are converted to
+multibyte for comparison (@pxref{Text Representations}), so that a
+unibyte string and its conversion to multibyte are always regarded as
+equal.
 
 If the specified portions of the two strings match, the value is
 @code{t}.  Otherwise, the value is an integer which indicates how many
-leading characters agree, and which string is less.  Its absolute value
-is one plus the number of characters that agree at the beginning of the
-two strings.  The sign is negative if @var{string1} (or its specified
-portion) is less.
+leading characters agree, and which string is less.  Its absolute
+value is one plus the number of characters that agree at the beginning
+of the two strings.  The sign is negative if @var{string1} (or its
+specified portion) is less.
 @end defun
 
 @defun assoc-string key alist &optional case-fold

=== modified file 'src/ChangeLog'
--- a/src/ChangeLog     2012-12-14 09:09:36 +0000
+++ b/src/ChangeLog     2012-12-15 13:44:41 +0000
@@ -1,3 +1,7 @@
+2012-12-15  Chong Yidong  <address@hidden>
+
+       * fns.c (Fcompare_strings): Doc fix (Bug#13081).
+
 2012-12-14  Eli Zaretskii  <address@hidden>
 
        * w32.c (get_name_and_id): Always pass NULL as the first argument

=== modified file 'src/fns.c'
--- a/src/fns.c 2012-10-19 00:54:35 +0000
+++ b/src/fns.c 2012-12-15 13:44:41 +0000
@@ -211,12 +211,18 @@
 
 DEFUN ("compare-strings", Fcompare_strings, Scompare_strings, 6, 7, 0,
        doc: /* Compare the contents of two strings, converting to multibyte if 
needed.
-In string STR1, skip the first START1 characters and stop at END1.
-In string STR2, skip the first START2 characters and stop at END2.
-END1 and END2 default to the full lengths of the respective strings.
+The arguments START1, END1, START2, and END2, if non-nil, are
+positions specifying which parts of STR1 or STR2 to compare.  In
+string STR1, compare the part between START1 (inclusive) and END1
+\(exclusive).  If START1 is nil, it defaults to 0, the beginning of
+the string; if END1 is nil, it defaults to the length of the string.
+Likewise, in string STR2, compare the part between START2 and END2.
 
-Case is significant in this comparison if IGNORE-CASE is nil.
-Unibyte strings are converted to multibyte for comparison.
+The strings are compared by the numeric values of their characters.
+For instance, STR1 is "less than" STR2 if its first differing
+character has a smaller numeric value.  If IGNORE-CASE is non-nil,
+characters are converted to lower-case before comparing them.  Unibyte
+strings are converted to multibyte for comparison.
 
 The value is t if the strings (or specified portions) match.
 If string STR1 is less, the value is a negative number N;