@c -*- mode: texinfo; coding: utf-8 -*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2016 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Strings and Characters
@end example
@end defun
-@defun substring string start &optional end
+@defun substring string &optional start end
This function returns a new string which consists of those characters
from @var{string} in the range from (and including) the character at the
index @var{start} up to (but excluding) the character at the index
-@var{end}. The first character is at index zero.
+@var{end}. The first character is at index zero. With one argument,
+this function just copies @var{string}.
@example
@group
@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
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.
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
@end example
Symbols are also allowed as arguments, in which case their print names
-are used.
+are compared.
@end defun
@defun string-lessp string1 string2
@code{string-lessp} is another name for @code{string<}.
@end defun
+@defun string-greaterp string1 string2
+This function returns the result of comparing @var{string1} and
+@var{string2} in the opposite order, i.e., it is equivalent to calling
+@code{(string-lessp @var{string2} @var{string1})}.
+@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
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}.
+For example, punctuation and whitespace characters might be ignored
+for sorting (@pxref{Sequence Functions}):
@example
@group
@end group
@end example
+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
behaves like @code{string-lessp}.
@end defun
+@defun string-version-lessp string1 string2
+This function compares strings lexicographically, except it treats
+sequences of numerical characters as if they comprised a base-ten
+number, and then compares the numbers. So @samp{foo2.png} is
+``smaller'' than @samp{foo12.png} according to this predicate, even if
+@samp{12} is lexicographically ``smaller'' than @samp{2}.
+@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