From 5bec25eb1e1c91a2fe0aee9c332ff1506b021aa9 Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Sat, 15 Dec 2012 21:44:41 +0800 Subject: [PATCH] * fns.c (Fcompare_strings): Doc fix. * strings.texi (Text Comparison): Doc fix for compare-strings. Fixes: debbugs:13081 --- doc/lispref/ChangeLog | 4 ++++ doc/lispref/strings.texi | 34 +++++++++++++++++++--------------- src/ChangeLog | 4 ++++ src/fns.c | 18 ++++++++++++------ 4 files changed, 39 insertions(+), 21 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 9dbce599bd1..9aeff403ec3 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,7 @@ +2012-12-15 Chong Yidong + + * strings.texi (Text Comparison): Doc fix for compare-strings. + 2012-12-09 Stefan Monnier * control.texi (Pattern matching case statement): New node. diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 865435c91b3..c127cec8f8a 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -517,25 +517,29 @@ comparison ignores case differences. @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). - -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 -@var{ignore-case} is non-@code{nil}, then case is ignored, so that -upper case letters can be equal to lower case letters. +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 +@var{start2} up to index @var{end2}. + +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 +@var{ignore-case} is non-@code{nil}, 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 diff --git a/src/ChangeLog b/src/ChangeLog index fe30528da91..c123606efda 100644 --- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,3 +1,7 @@ +2012-12-15 Chong Yidong + + * fns.c (Fcompare_strings): Doc fix (Bug#13081). + 2012-12-14 Eli Zaretskii * w32.c (get_name_and_id): Always pass NULL as the first argument diff --git a/src/fns.c b/src/fns.c index b1ba5ce9509..539e8888dbc 100644 --- a/src/fns.c +++ b/src/fns.c @@ -211,12 +211,18 @@ Symbols are also allowed; their print names are used instead. */) 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. - -Case is significant in this comparison if IGNORE-CASE is nil. -Unibyte strings are converted to multibyte for comparison. +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. + +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; -- 2.39.5