@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 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/strings
@node Strings and Characters, Lists, Numbers, Top
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}
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.
+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.
+ 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
@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
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
(split-string "ooo" "\\|o+" t)
@result{} ("o" "o" "o")
@end example
+
+If you need to split a string that is a shell command, where
+individual arguments could be quoted, see @ref{Shell Arguments,
+split-string-and-unquote}.
@end defun
@defvar split-string-default-separators
@cindex field width
@cindex padding
- A specification can have a @dfn{width}, which is a signed decimal
-number between the @samp{%} and the specification character. If the
-printed representation of the object contains fewer characters than
-this width, @code{format} extends it with padding. The padding goes
-on the left if the width is positive (or starts with zero) and on the
-right if the width is negative. The padding character is normally a
-space, but it's @samp{0} if the width starts with a zero.
-
- Some of these conventions are ignored for specification characters
-for which they do not make sense. That is, @samp{%s}, @samp{%S} and
-@samp{%c} accept a width starting with 0, but still pad with
-@emph{spaces} on the left. Also, @samp{%%} accepts a width, but
-ignores it. Here are some examples of padding:
+ A specification can have a @dfn{width}, which is a decimal number
+between the @samp{%} and the specification character. If the printed
+representation of the object contains fewer characters than this
+width, @code{format} extends it with padding. The width specifier is
+ignored for the @samp{%%} specification. Any padding introduced by
+the width specifier normally consists of spaces inserted on the left:
@example
-(format "%06d is padded on the left with zeros" 123)
- @result{} "000123 is padded on the left with zeros"
-
-(format "%-6d is padded on the right" 123)
- @result{} "123 is padded on the right"
+(format "%5d is padded on the left with spaces" 123)
+ @result{} " 123 is padded on the left with spaces"
@end example
@noindent
If the width is too small, @code{format} does not truncate the
object's printed representation. Thus, you can use a width to specify
a minimum spacing between columns with no risk of losing information.
+In the following three examples, @samp{%7s} specifies a minimum width
+of 7. In the first case, the string inserted in place of @samp{%7s}
+has only 3 letters, and needs 4 blank spaces as padding. In the
+second case, the string @code{"specification"} is 13 letters wide but
+is not truncated.
- In the following three examples, @samp{%7s} specifies a minimum
-width of 7. In the first case, the string inserted in place of
-@samp{%7s} has only 3 letters, it needs 4 blank spaces as padding. In
-the second case, the string @code{"specification"} is 13 letters wide
-but is not truncated. In the third case, the padding is on the right.
-
-@smallexample
+@example
@group
(format "The word `%7s' actually has %d letters in it."
"foo" (length "foo"))
@result{} "The word ` foo' actually has 3 letters in it."
-@end group
-
-@group
(format "The word `%7s' actually has %d letters in it."
"specification" (length "specification"))
@result{} "The word `specification' actually has 13 letters in it."
@end group
+@end example
+@cindex flags in format specifications
+ Immediately after the @samp{%} and before the optional width
+specifier, you can also put certain @dfn{flag characters}.
+
+ The flag @samp{+} inserts a plus sign before a positive number, so
+that it always has a sign. A space character as flag inserts a space
+before a positive number. (Otherwise, positive numbers start with the
+first digit.) These flags are useful for ensuring that positive
+numbers and negative numbers use the same number of columns. They are
+ignored except for @samp{%d}, @samp{%e}, @samp{%f}, @samp{%g}, and if
+both flags are used, @samp{+} takes precedence.
+
+ The flag @samp{#} specifies an ``alternate form'' which depends on
+the format in use. For @samp{%o}, it ensures that the result begins
+with a @samp{0}. For @samp{%x} and @samp{%X}, it prefixes the result
+with @samp{0x} or @samp{0X}. For @samp{%e}, @samp{%f}, and @samp{%g},
+the @samp{#} flag means include a decimal point even if the precision
+is zero.
+
+ The flag @samp{-} causes the padding inserted by the width
+specifier, if any, to be inserted on the right rather than the left.
+The flag @samp{0} ensures that the padding consists of @samp{0}
+characters instead of spaces, inserted on the left. These flags are
+ignored for specification characters for which they do not make sense:
+@samp{%s}, @samp{%S} and @samp{%c} accept the @samp{0} flag, but still
+pad with @emph{spaces} on the left. If both @samp{-} and @samp{0} are
+present and valid, @samp{-} takes precedence.
+
+@example
@group
+(format "%06d is padded on the left with zeros" 123)
+ @result{} "000123 is padded on the left with zeros"
+
+(format "%-6d is padded on the right" 123)
+ @result{} "123 is padded on the right"
+
(format "The word `%-7s' actually has %d letters in it."
"foo" (length "foo"))
@result{} "The word `foo ' actually has 3 letters in it."
@end group
-@end smallexample
+@end example
@cindex precision in format specifications
All the specification characters allow an optional @dfn{precision}
@var{object}. Precision has no effect for other specification
characters.
-@cindex flags in format specifications
- Immediately after the @samp{%} and before the optional width and
-precision, you can put certain ``flag'' characters.
-
- @samp{+} as a flag inserts a plus sign before a positive number, so
-that it always has a sign. A space character as flag inserts a space
-before a positive number. (Otherwise, positive numbers start with the
-first digit.) Either of these two flags ensures that positive numbers
-and negative numbers use the same number of columns. These flags are
-ignored except for @samp{%d}, @samp{%e}, @samp{%f}, @samp{%g}, and if
-both flags are used, the @samp{+} takes precedence.
-
- The flag @samp{#} specifies an ``alternate form'' which depends on
-the format in use. For @samp{%o} it ensures that the result begins
-with a @samp{0}. For @samp{%x} and @samp{%X}, it prefixes the result
-with @samp{0x} or @samp{0X}. For @samp{%e}, @samp{%f}, and @samp{%g},
-the @samp{#} flag means include a decimal point even if the precision
-is zero.
-
@node Case Conversion
@comment node-name, next, previous, up
@section Case Conversion in Lisp
HCoop / bpt / emacs.git / blobdiff