Merge from emacs-23; up to 2010-06-12T11:17:12Z!eliz@gnu.org.

[bpt/emacs.git] / doc / lispref / strings.texi

diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 37c19fc..05ac40e 100644 (file)
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -1,7 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.

-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
-@c   2002, 2003, 2004, 2005, 2006, 2007, 2008  Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2011
+@c   Free Software Foundation, Inc.

 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/strings
 @node Strings and Characters, Lists, Numbers, Top
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/strings
 @node Strings and Characters, Lists, Numbers, Top


@@ -31,7 +31,7 @@ keyboard character events.
 * String Conversion::         Converting to and from characters and strings.
 * Formatting Strings::        @code{format}: Emacs's analogue of @code{printf}.
 * Case Conversion::           Case conversion functions.
 * String Conversion::         Converting to and from characters and strings.
 * Formatting Strings::        @code{format}: Emacs's analogue of @code{printf}.
 * Case Conversion::           Case conversion functions.

-* Case Tables::                      Customizing case conversion.
+* Case Tables::               Customizing case conversion.

 @end menu
 
 @node String Basics
 @end menu
 
 @node String Basics


@@ -39,7 +39,8 @@ keyboard character events.
 
   Characters are represented in Emacs Lisp as integers;
 whether an integer is a character or not is determined only by how it is
 
   Characters are represented in Emacs Lisp as integers;
 whether an integer is a character or not is determined only by how it is

-used.  Thus, strings really contain integers.
+used.  Thus, strings really contain integers.  @xref{Character Codes},
+for details about character representation in Emacs.

 
   The length of a string (like any array) is fixed, and cannot be
 altered once the string exists.  Strings in Lisp are @emph{not}
 
   The length of a string (like any array) is fixed, and cannot be
 altered once the string exists.  Strings in Lisp are @emph{not}


@@ -54,24 +55,19 @@ and @code{aset} (@pxref{Array Functions}).
 
   There are two text representations for non-@acronym{ASCII} characters in
 Emacs strings (and in buffers): unibyte and multibyte (@pxref{Text
 
   There are two text representations for non-@acronym{ASCII} characters in
 Emacs strings (and in buffers): unibyte and multibyte (@pxref{Text

-Representations}).  An @acronym{ASCII} character always occupies one byte in a
-string; in fact, when a string is all @acronym{ASCII}, there is no real
-difference between the unibyte and multibyte representations.
-For most Lisp programming, you don't need to be concerned with these two
-representations.
-
-  Sometimes key sequences are represented as strings.  When a string is
-a key sequence, string elements in the range 128 to 255 represent meta
-characters (which are large integers) rather than character
-codes in the range 128 to 255.
-
-  Strings cannot hold characters that have the hyper, super or alt
-modifiers; they can hold @acronym{ASCII} control characters, but no other
-control characters.  They do not distinguish case in @acronym{ASCII} control
-characters.  If you want to store such characters in a sequence, such as
-a key sequence, you must use a vector instead of a string.
-@xref{Character Type}, for more information about the representation of meta
-and other modifiers for keyboard input characters.
+Representations}).  For most Lisp programming, you don't need to be
+concerned with these two representations.
+
+  Sometimes key sequences are represented as unibyte strings.  When a
+unibyte string is a key sequence, string elements in the range 128 to
+255 represent meta characters (which are large integers) rather than
+character codes in the range 128 to 255.  Strings cannot hold
+characters that have the hyper, super or alt modifiers; they can hold
+@acronym{ASCII} control characters, but no other control characters.
+They do not distinguish case in @acronym{ASCII} control characters.
+If you want to store such characters in a sequence, such as a key
+sequence, you must use a vector instead of a string.  @xref{Character
+Type}, for more information about keyboard input characters.

 
   Strings are useful for holding regular expressions.  You can also
 match regular expressions against strings with @code{string-match}
 
   Strings are useful for holding regular expressions.  You can also
 match regular expressions against strings with @code{string-match}


@@ -103,8 +99,8 @@ otherwise.
 @end defun
 
 @defun string-or-null-p object
 @end defun
 
 @defun string-or-null-p object

-This function returns @code{t} if @var{object} is a string or nil,
-@code{nil} otherwise.
+This function returns @code{t} if @var{object} is a string or
+@code{nil}.  It returns @code{nil} otherwise.

 @end defun
 
 @defun char-or-string-p object
 @end defun
 
 @defun char-or-string-p object


@@ -129,9 +125,8 @@ This function returns a string made up of @var{count} repetitions of
      @result{} ""
 @end example
 
      @result{} ""
 @end example
 

-  Other functions to compare with this one include @code{char-to-string}
-(@pxref{String Conversion}), @code{make-vector} (@pxref{Vectors}), and
-@code{make-list} (@pxref{Building Lists}).
+  Other functions to compare with this one include @code{make-vector}
+(@pxref{Vectors}) and @code{make-list} (@pxref{Building Lists}).

 @end defun
 
 @defun string &rest characters
 @end defun
 
 @defun string &rest characters


@@ -157,11 +152,11 @@ index @var{start} up to (but excluding) the character at the index
 @end example
 
 @noindent
 @end example
 
 @noindent

-Here the index for @samp{a} is 0, the index for @samp{b} is 1, and the
-index for @samp{c} is 2.  Thus, three letters, @samp{abc}, are copied
-from the string @code{"abcdefg"}.  The index 3 marks the character
-position up to which the substring is copied.  The character whose index
-is 3 is actually the fourth character in the string.
+In the above example, the index for @samp{a} is 0, the index for
+@samp{b} is 1, and the index for @samp{c} is 2.  The index 3---which
+is the fourth character in the string---marks the character position
+up to which the substring is copied.  Thus, @samp{abc} is copied from
+the string @code{"abcdefg"}.

 
 A negative number counts from the end of the string, so that @minus{}1
 signifies the index of the last character of the string.  For example:
 
 A negative number counts from the end of the string, so that @minus{}1
 signifies the index of the last character of the string.  For example:


@@ -258,38 +253,32 @@ returns an empty string.
 @end example
 
 @noindent
 @end example
 
 @noindent

-The @code{concat} function always constructs a new string that is
-not @code{eq} to any existing string, except when the result is empty
-(since empty strings are canonicalized to save space).
-
-In Emacs versions before 21, when an argument was an integer (not a
-sequence of integers), it was converted to a string of digits making up
-the decimal printed representation of the integer.  This obsolete usage
-no longer works.  The proper way to convert an integer to its decimal
-printed form is with @code{format} (@pxref{Formatting Strings}) or
-@code{number-to-string} (@pxref{String Conversion}).
+This function always constructs a new string that is not @code{eq} to
+any existing string, except when the result is the empty string (to
+save space, Emacs makes only one empty multibyte string).

 
 For information about other concatenation functions, see the
 description of @code{mapconcat} in @ref{Mapping Functions},
 @code{vconcat} in @ref{Vector Functions}, and @code{append} in @ref{Building
 
 For information about other concatenation functions, see the
 description of @code{mapconcat} in @ref{Mapping Functions},
 @code{vconcat} in @ref{Vector Functions}, and @code{append} in @ref{Building

-Lists}.
+Lists}.  For concatenating individual command-line arguments into a
+string to be used as a shell command, see @ref{Shell Arguments,
+combine-and-quote-strings}.

 @end defun
 
 @defun split-string string &optional separators omit-nulls
 @end defun
 
 @defun split-string string &optional separators omit-nulls

-This function splits @var{string} into substrings at matches for the
-regular expression @var{separators}.  Each match for @var{separators}
-defines a splitting point; the substrings between the splitting points
-are made into a list, which is the value returned by
-@code{split-string}.
+This function splits @var{string} into substrings based on the regular
+expression @var{separators} (@pxref{Regular Expressions}).  Each match
+for @var{separators} defines a splitting point; the substrings between
+splitting points are made into a list, which is returned.

 
 

-If @var{omit-nulls} is @code{nil}, the result contains null strings
-whenever there are two consecutive matches for @var{separators}, or a
-match is adjacent to the beginning or end of @var{string}.  If
-@var{omit-nulls} is @code{t}, these null strings are omitted from the
-result.
+If @var{omit-nulls} is @code{nil} (or omitted), the result contains
+null strings whenever there are two consecutive matches for
+@var{separators}, or a match is adjacent to the beginning or end of
+@var{string}.  If @var{omit-nulls} is @code{t}, these null strings are
+omitted from the result.

 
 

-If @var{separators} is @code{nil} (or omitted),
-the default is the value of @code{split-string-default-separators}.
+If @var{separators} is @code{nil} (or omitted), the default is the
+value of @code{split-string-default-separators}.

 
 As a special case, when @var{separators} is @code{nil} (or omitted),
 null strings are always omitted from the result.  Thus:
 
 As a special case, when @var{separators} is @code{nil} (or omitted),
 null strings are always omitted from the result.  Thus:


@@ -357,6 +346,10 @@ practice:
 (split-string "ooo" "\\|o+" t)
      @result{} ("o" "o" "o")
 @end example
 (split-string "ooo" "\\|o+" t)
      @result{} ("o" "o" "o")
 @end example

+
+If you need to split a string into a list of individual command-line
+arguments suitable for @code{call-process} or @code{start-process},
+see @ref{Shell Arguments, split-string-and-unquote}.

 @end defun
 
 @defvar split-string-default-separators
 @end defun
 
 @defvar split-string-default-separators


@@ -437,9 +430,9 @@ For technical reasons, a unibyte and a multibyte string are
 @code{equal} if and only if they contain the same sequence of
 character codes and all these codes are either in the range 0 through
 127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}).
 @code{equal} if and only if they contain the same sequence of
 character codes and all these codes are either in the range 0 through
 127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}).

-However, when a unibyte string gets converted to a multibyte string,
-all characters with codes in the range 160 through 255 get converted
-to characters with higher codes, whereas @acronym{ASCII} characters
+However, when a unibyte string is converted to a multibyte string, all
+characters with codes in the range 160 through 255 are converted to
+characters with higher codes, whereas @acronym{ASCII} characters

 remain unchanged.  Thus, a unibyte string and its conversion to
 multibyte are only @code{equal} if the string is all @acronym{ASCII}.
 Character codes 160 through 255 are not entirely proper in multibyte
 remain unchanged.  Thus, a unibyte string and its conversion to
 multibyte are only @code{equal} if the string is all @acronym{ASCII}.
 Character codes 160 through 255 are not entirely proper in multibyte


@@ -545,7 +538,7 @@ be a list of strings or symbols rather than an actual alist.
 @xref{Association Lists}.
 @end defun
 
 @xref{Association Lists}.
 @end defun
 

-  See also the @code{compare-buffer-substrings} function in
+  See also the function @code{compare-buffer-substrings} in

 @ref{Comparing Text}, for a way to compare text in buffers.  The
 function @code{string-match}, which matches a regular expression
 against a string, can be used for a kind of string comparison; see
 @ref{Comparing Text}, for a way to compare text in buffers.  The
 function @code{string-match}, which matches a regular expression
 against a string, can be used for a kind of string comparison; see


@@ -556,52 +549,20 @@ against a string, can be used for a kind of string comparison; see
 @section Conversion of Characters and Strings
 @cindex conversion of strings
 
 @section Conversion of Characters and Strings
 @cindex conversion of strings
 

-  This section describes functions for conversions between characters,
-strings and integers.  @code{format} (@pxref{Formatting Strings})
-and @code{prin1-to-string}
-(@pxref{Output Functions}) can also convert Lisp objects into strings.
-@code{read-from-string} (@pxref{Input Functions}) can ``convert'' a
-string representation of a Lisp object into an object.  The functions
-@code{string-make-multibyte} and @code{string-make-unibyte} convert the
-text representation of a string (@pxref{Converting Representations}).
+  This section describes functions for converting between characters,
+strings and integers.  @code{format} (@pxref{Formatting Strings}) and
+@code{prin1-to-string} (@pxref{Output Functions}) can also convert
+Lisp objects into strings.  @code{read-from-string} (@pxref{Input
+Functions}) can ``convert'' a string representation of a Lisp object
+into an object.  The functions @code{string-to-multibyte} and
+@code{string-to-unibyte} convert the text representation of a string
+(@pxref{Converting Representations}).

 
   @xref{Documentation}, for functions that produce textual descriptions
 of text characters and general input events
 (@code{single-key-description} and @code{text-char-description}).  These
 are used primarily for making help messages.
 
 
   @xref{Documentation}, for functions that produce textual descriptions
 of text characters and general input events
 (@code{single-key-description} and @code{text-char-description}).  These
 are used primarily for making help messages.
 

-@defun char-to-string character
-@cindex character to string
-This function returns a new string containing one character,
-@var{character}.  This function is semi-obsolete because the function
-@code{string} is more general.  @xref{Creating Strings}.
-@end defun
-
-@defun string-to-char string
-@cindex string to character
-  This function returns the first character in @var{string}.  If the
-string is empty, the function returns 0.  The value is also 0 when the
-first character of @var{string} is the null character, @acronym{ASCII} code
-0.
-
-@example
-(string-to-char "ABC")
-     @result{} 65
-
-(string-to-char "xyz")
-     @result{} 120
-(string-to-char "")
-     @result{} 0
-@group
-(string-to-char "\000")
-     @result{} 0
-@end group
-@end example
-
-This function may be eliminated in the future if it does not seem useful
-enough to retain.
-@end defun
-

 @defun number-to-string number
 @cindex integer to string
 @cindex integer to decimal
 @defun number-to-string number
 @cindex integer to string
 @cindex integer to decimal


@@ -662,21 +623,41 @@ this function returns 0.
 
 @findex string-to-int
 @code{string-to-int} is an obsolete alias for this function.
 
 @findex string-to-int
 @code{string-to-int} is an obsolete alias for this function.

+@end defun
+
+@defun char-to-string character
+@cindex character to string
+This function returns a new string containing one character,
+@var{character}.  This function is semi-obsolete because the function
+@code{string} is more general.  @xref{Creating Strings}.
+@end defun
+
+@defun string-to-char string
+  This function returns the first character in @var{string}.  This
+mostly identical to @code{(aref string 0)}, except that it returns 0
+if the string is empty.  (The value is also 0 when the first character
+of @var{string} is the null character, @acronym{ASCII} code 0.)  This
+function may be eliminated in the future if it does not seem useful
+enough to retain.

 @end defun
 
   Here are some other functions that can convert to or from a string:
 
 @table @code
 @item concat
 @end defun
 
   Here are some other functions that can convert to or from a string:
 
 @table @code
 @item concat

-@code{concat} can convert a vector or a list into a string.
+This function converts a vector or a list into a string.

 @xref{Creating Strings}.
 
 @item vconcat
 @xref{Creating Strings}.
 
 @item vconcat

-@code{vconcat} can convert a string into a vector.  @xref{Vector
+This function converts a string into a vector.  @xref{Vector

 Functions}.
 
 @item append
 Functions}.
 
 @item append

-@code{append} can convert a string into a list.  @xref{Building Lists}.
+This function converts a string into a list.  @xref{Building Lists}.
+
+@item byte-to-string
+This function converts a byte of character data into a unibyte string.
+@xref{Converting Representations}.

 @end table
 
 @node Formatting Strings
 @end table
 
 @node Formatting Strings


@@ -685,10 +666,10 @@ Functions}.
 @cindex formatting strings
 @cindex strings, formatting them
 
 @cindex formatting strings
 @cindex strings, formatting them
 

-  @dfn{Formatting} means constructing a string by substitution of
-computed values at various places in a constant string.  This constant string
-controls how the other values are printed, as well as where they appear;
-it is called a @dfn{format string}.
+  @dfn{Formatting} means constructing a string by substituting
+computed values at various places in a constant string.  This constant
+string controls how the other values are printed, as well as where
+they appear; it is called a @dfn{format string}.

 
   Formatting is often useful for computing messages to be displayed.  In
 fact, the functions @code{message} and @code{error} provide the same
 
   Formatting is often useful for computing messages to be displayed.  In
 fact, the functions @code{message} and @code{error} provide the same


@@ -847,12 +828,12 @@ is not truncated.
 
 @example
 @group
 
 @example
 @group

-(format "The word `%7s' actually has %d letters in it."
+(format "The word `%7s' has %d letters in it."

         "foo" (length "foo"))
         "foo" (length "foo"))

-     @result{} "The word `    foo' actually has 3 letters in it."
-(format "The word `%7s' actually has %d letters in it."
+     @result{} "The word `    foo' has 3 letters in it."
+(format "The word `%7s' has %d letters in it."

         "specification" (length "specification"))
         "specification" (length "specification"))

-     @result{} "The word `specification' actually has 13 letters in it."
+     @result{} "The word `specification' has 13 letters in it."

 @end group
 @end example
 
 @end group
 @end example
 


@@ -932,15 +913,15 @@ arguments.
 @acronym{ASCII} codes 88 and 120 respectively.
 
 @defun downcase string-or-char
 @acronym{ASCII} codes 88 and 120 respectively.
 
 @defun downcase string-or-char

-This function converts a character or a string to lower case.
+This function converts @var{string-or-char}, which should be either a
+character or a string, to lower case.

 
 

-When the argument to @code{downcase} is a string, the function creates
-and returns a new string in which each letter in the argument that is
-upper case is converted to lower case.  When the argument to
-@code{downcase} is a character, @code{downcase} returns the
-corresponding lower case character.  This value is an integer.  If the
-original character is lower case, or is not a letter, then the value
-equals the original character.
+When @var{string-or-char} is a string, this function returns a new
+string in which each letter in the argument that is upper case is
+converted to lower case.  When @var{string-or-char} is a character,
+this function returns the corresponding lower case character (an
+integer); if the original character is lower case, or is not a letter,
+the return value is equal to the original character.

 
 @example
 (downcase "The cat in the hat")
 
 @example
 (downcase "The cat in the hat")


@@ -952,16 +933,15 @@ equals the original character.
 @end defun
 
 @defun upcase string-or-char
 @end defun
 
 @defun upcase string-or-char

-This function converts a character or a string to upper case.
+This function converts @var{string-or-char}, which should be either a
+character or a string, to upper case.

 
 

-When the argument to @code{upcase} is a string, the function creates
-and returns a new string in which each letter in the argument that is
-lower case is converted to upper case.
-
-When the argument to @code{upcase} is a character, @code{upcase}
-returns the corresponding upper case character.  This value is an integer.
-If the original character is upper case, or is not a letter, then the
-value returned equals the original character.
+When @var{string-or-char} is a string, this function returns a new
+string in which each letter in the argument that is lower case is
+converted to upper case.  When @var{string-or-char} is a character,
+this function returns the corresponding upper case character (an
+integer); if the original character is upper case, or is not a letter,
+the return value is equal to the original character.

 
 @example
 (upcase "The cat in the hat")
 
 @example
 (upcase "The cat in the hat")


@@ -975,9 +955,9 @@ value returned equals the original character.
 @defun capitalize string-or-char
 @cindex capitalization
 This function capitalizes strings or characters.  If
 @defun capitalize string-or-char
 @cindex capitalization
 This function capitalizes strings or characters.  If

-@var{string-or-char} is a string, the function creates and returns a new
-string, whose contents are a copy of @var{string-or-char} in which each
-word has been capitalized.  This means that the first character of each
+@var{string-or-char} is a string, the function returns a new string
+whose contents are a copy of @var{string-or-char} in which each word
+has been capitalized.  This means that the first character of each

 word is converted to upper case, and the rest are converted to lower
 case.
 
 word is converted to upper case, and the rest are converted to lower
 case.
 


@@ -985,8 +965,8 @@ The definition of a word is any sequence of consecutive characters that
 are assigned to the word constituent syntax class in the current syntax
 table (@pxref{Syntax Class Table}).
 
 are assigned to the word constituent syntax class in the current syntax
 table (@pxref{Syntax Class Table}).
 

-When the argument to @code{capitalize} is a character, @code{capitalize}
-has the same result as @code{upcase}.
+When @var{string-or-char} is a character, this function does the same
+thing as @code{upcase}.

 
 @example
 @group
 
 @example
 @group


@@ -1080,13 +1060,13 @@ equivalent).  (For ordinary @acronym{ASCII}, this would map @samp{a} into
 @samp{A} and @samp{A} into @samp{a}, and likewise for each set of
 equivalent characters.)
 
 @samp{A} and @samp{A} into @samp{a}, and likewise for each set of
 equivalent characters.)
 

-  When you construct a case table, you can provide @code{nil} for
+  When constructing a case table, you can provide @code{nil} for

 @var{canonicalize}; then Emacs fills in this slot from the lower case
 and upper case mappings.  You can also provide @code{nil} for
 @var{equivalences}; then Emacs fills in this slot from
 @var{canonicalize}.  In a case table that is actually in use, those
 @var{canonicalize}; then Emacs fills in this slot from the lower case
 and upper case mappings.  You can also provide @code{nil} for
 @var{equivalences}; then Emacs fills in this slot from
 @var{canonicalize}.  In a case table that is actually in use, those

-components are non-@code{nil}.  Do not try to specify @var{equivalences}
-without also specifying @var{canonicalize}.
+components are non-@code{nil}.  Do not try to specify
+@var{equivalences} without also specifying @var{canonicalize}.

 
   Here are the functions for working with case tables:
 
 
   Here are the functions for working with case tables:
 


@@ -1121,7 +1101,7 @@ of an abnormal exit via @code{throw} or error (@pxref{Nonlocal
 Exits}).
 @end defmac
 
 Exits}).
 @end defmac
 

-  Some language environments may modify the case conversions of
+  Some language environments modify the case conversions of

 @acronym{ASCII} characters; for example, in the Turkish language
 environment, the @acronym{ASCII} character @samp{I} is downcased into
 a Turkish ``dotless i''.  This can interfere with code that requires
 @acronym{ASCII} characters; for example, in the Turkish language
 environment, the @acronym{ASCII} character @samp{I} is downcased into
 a Turkish ``dotless i''.  This can interfere with code that requires


@@ -1161,7 +1141,3 @@ This function makes @var{char} case-invariant, with syntax
 This command displays a description of the contents of the current
 buffer's case table.
 @end deffn
 This command displays a description of the contents of the current
 buffer's case table.
 @end deffn

-
-@ignore
-   arch-tag: 700b8e95-7aa5-4b52-9eb3-8f2e1ea152b4
-@end ignore