This commit was generated by cvs2svn to compensate for changes in r6453,

[chise/xemacs-chise.git.1] / info / lispref.info-5

This is Info file ../../info/lispref.info, produced by Makeinfo version
1.68 from the input file lispref.texi.

INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
* Lispref: (lispref).           XEmacs Lisp Reference Manual.
END-INFO-DIR-ENTRY

   Edition History:

   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998

   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
Copyright (C) 1995, 1996 Ben Wing.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the section entitled "GNU General Public License"
may be included in a translation approved by the Free Software
Foundation instead of in the original English.

\1f
File: lispref.info,  Node: String Basics,  Next: Predicates for Strings,  Up: Strings and Characters

String and Character Basics
===========================

   Strings in XEmacs Lisp are arrays that contain an ordered sequence of
characters.  Characters are their own primitive object type in XEmacs
20.  However, in XEmacs 19, characters are represented in XEmacs Lisp as
integers; whether an integer was intended as a character or not is
determined only by how it is used.  *Note Character Type::.

   The length of a string (like any array) is fixed and independent of
the string contents, and cannot be altered.  Strings in Lisp are *not*
terminated by a distinguished character code.  (By contrast, strings in
C are terminated by a character with ASCII code 0.)  This means that
any character, including the null character (ASCII code 0), is a valid
element of a string.

   Since strings are considered arrays, you can operate on them with the
general array functions.  (*Note Sequences Arrays Vectors::.)  For
example, you can access or change individual characters in a string
using the functions `aref' and `aset' (*note Array Functions::.).

   Strings use an efficient representation for storing the characters
in them, and thus take up much less memory than a vector of the same
length.

   Sometimes you will see strings used to hold key sequences.  This
exists for backward compatibility with Emacs 18, but should *not* be
used in new code, since many key chords can't be represented at all and
others (in particular meta key chords) are confused with accented
characters.

   Strings are useful for holding regular expressions.  You can also
match regular expressions against strings (*note Regexp Search::.).  The
functions `match-string' (*note Simple Match Data::.) and
`replace-match' (*note Replacing Match::.) are useful for decomposing
and modifying strings based on regular expression matching.

   Like a buffer, a string can contain extents in it.  These extents are
created when a function such as `buffer-substring' is called on a
region with duplicable extents in it.  When the string is inserted into
a buffer, the extents are inserted along with it.  *Note Duplicable
Extents::.

   *Note Text::, for information about functions that display strings or
copy them into buffers.  *Note Character Type::, and *Note String
Type::, for information about the syntax of characters and strings.

\1f
File: lispref.info,  Node: Predicates for Strings,  Next: Creating Strings,  Prev: String Basics,  Up: Strings and Characters

The Predicates for Strings
==========================

   For more information about general sequence and array predicates,
see *Note Sequences Arrays Vectors::, and *Note Arrays::.

 - Function: stringp OBJECT
     This function returns `t' if OBJECT is a string, `nil' otherwise.

 - Function: char-or-string-p OBJECT
     This function returns `t' if OBJECT is a string or a character,
     `nil' otherwise.

     In XEmacs addition, this function also returns `t' if OBJECT is an
     integer that can be represented as a character.  This is because
     of compatibility with previous XEmacs and should not be depended
     on.

\1f
File: lispref.info,  Node: Creating Strings,  Next: Predicates for Characters,  Prev: Predicates for Strings,  Up: Strings and Characters

Creating Strings
================

   The following functions create strings, either from scratch, or by
putting strings together, or by taking them apart.

 - Function: string &rest CHARACTERS
     This function returns a new string made up of CHARACTERS.

          (string ?X ?E ?m ?a ?c ?s)
               => "XEmacs"
          (string)
               => ""

     Analogous functions operating on other data types include `list',
     `cons' (*note Building Lists::.), `vector' (*note Vectors::.)  and
     `bit-vector' (*note Bit Vectors::.).  This function has not been
     available in XEmacs prior to 21.0 and FSF Emacs prior to 20.3.

 - Function: make-string COUNT CHARACTER
     This function returns a string made up of COUNT repetitions of
     CHARACTER.  If COUNT is negative, an error is signaled.

          (make-string 5 ?x)
               => "xxxxx"
          (make-string 0 ?x)
               => ""

     Other functions to compare with this one include `char-to-string'
     (*note String Conversion::.), `make-vector' (*note Vectors::.), and
     `make-list' (*note Building Lists::.).

 - Function: substring STRING START &optional END
     This function returns a new string which consists of those
     characters from STRING in the range from (and including) the
     character at the index START up to (but excluding) the character
     at the index END.  The first character is at index zero.

          (substring "abcdefg" 0 3)
               => "abc"

     Here the index for `a' is 0, the index for `b' is 1, and the index
     for `c' is 2.  Thus, three letters, `abc', are copied from the
     string `"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.

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

          (substring "abcdefg" -3 -1)
               => "ef"

     In this example, the index for `e' is -3, the index for `f' is -2,
     and the index for `g' is -1.  Therefore, `e' and `f' are included,
     and `g' is excluded.

     When `nil' is used as an index, it stands for the length of the
     string.  Thus,

          (substring "abcdefg" -3 nil)
               => "efg"

     Omitting the argument END is equivalent to specifying `nil'.  It
     follows that `(substring STRING 0)' returns a copy of all of
     STRING.

          (substring "abcdefg" 0)
               => "abcdefg"

     But we recommend `copy-sequence' for this purpose (*note Sequence
     Functions::.).

     If the characters copied from STRING have duplicable extents or
     text properties, those are copied into the new string also.  *Note
     Duplicable Extents::.

     A `wrong-type-argument' error is signaled if either START or END
     is not an integer or `nil'.  An `args-out-of-range' error is
     signaled if START indicates a character following END, or if
     either integer is out of range for STRING.

     Contrast this function with `buffer-substring' (*note Buffer
     Contents::.), which returns a string containing a portion of the
     text in the current buffer.  The beginning of a string is at index
     0, but the beginning of a buffer is at index 1.

 - Function: concat &rest SEQUENCES
     This function returns a new string consisting of the characters in
     the arguments passed to it (along with their text properties, if
     any).  The arguments may be strings, lists of numbers, or vectors
     of numbers; they are not themselves changed.  If `concat' receives
     no arguments, it returns an empty string.

          (concat "abc" "-def")
               => "abc-def"
          (concat "abc" (list 120 (+ 256 121)) [122])
               => "abcxyz"
          ;; `nil' is an empty sequence.
          (concat "abc" nil "-def")
               => "abc-def"
          (concat "The " "quick brown " "fox.")
               => "The quick brown fox."
          (concat)
               => ""

     The second example above shows how characters stored in strings are
     taken modulo 256.  In other words, each character in the string is
     stored in one byte.

     The `concat' function always constructs a new string that is not
     `eq' to any existing string.

     When an argument is an integer (not a sequence of integers), it is
     converted to a string of digits making up the decimal printed
     representation of the integer.  *Don't use this feature; we plan
     to eliminate it.  If you already use this feature, change your
     programs now!*  The proper way to convert an integer to a decimal
     number in this way is with `format' (*note Formatting Strings::.)
     or `number-to-string' (*note String Conversion::.).

          (concat 137)
               => "137"
          (concat 54 321)
               => "54321"

     For information about other concatenation functions, see the
     description of `mapconcat' in *Note Mapping Functions::, `vconcat'
     in *Note Vectors::, `bvconcat' in *Note Bit Vectors::, and `append'
     in *Note Building Lists::.

\1f
File: lispref.info,  Node: Predicates for Characters,  Next: Character Codes,  Prev: Creating Strings,  Up: Strings and Characters

The Predicates for Characters
=============================

 - Function: characterp OBJECT
     This function returns `t' if OBJECT is a character.

     Some functions that work on integers (e.g. the comparison functions
     <, <=, =, /=, etc. and the arithmetic functions +, -, *, etc.)
     accept characters and implicitly convert them into integers.  In
     general, functions that work on characters also accept char-ints
     and implicitly convert them into characters.  WARNING: Neither of
     these behaviors is very desirable, and they are maintained for
     backward compatibility with old E-Lisp programs that confounded
     characters and integers willy-nilly.  These behaviors may change
     in the future; therefore, do not rely on them.  Instead, convert
     the characters explicitly using `char-int'.

 - Function: integer-or-char-p OBJECT
     This function returns `t' if OBJECT is an integer or character.

\1f
File: lispref.info,  Node: Character Codes,  Next: Text Comparison,  Prev: Predicates for Characters,  Up: Strings and Characters

Character Codes
===============

 - Function: char-int CH
     This function converts a character into an equivalent integer.
     The resulting integer will always be non-negative.  The integers in
     the range 0 - 255 map to characters as follows:

    0 - 31
          Control set 0

    32 - 127
          ASCII

    128 - 159
          Control set 1

    160 - 255
          Right half of ISO-8859-1

     If support for MULE does not exist, these are the only valid
     character values.  When MULE support exists, the values assigned to
     other characters may vary depending on the particular version of
     XEmacs, the order in which character sets were loaded, etc., and
     you should not depend on them.

 - Function: int-char INTEGER
     This function converts an integer into the equivalent character.
     Not all integers correspond to valid characters; use `char-int-p'
     to determine whether this is the case.  If the integer cannot be
     converted, `nil' is returned.

 - Function: char-int-p OBJECT
     This function returns `t' if OBJECT is an integer that can be
     converted into a character.

 - Function: char-or-char-int-p OBJECT
     This function returns `t' if OBJECT is a character or an integer
     that can be converted into one.

\1f
File: lispref.info,  Node: Text Comparison,  Next: String Conversion,  Prev: Character Codes,  Up: Strings and Characters

Comparison of Characters and Strings
====================================

 - Function: char-equal CHARACTER1 CHARACTER2
     This function returns `t' if the arguments represent the same
     character, `nil' otherwise.  This function ignores differences in
     case if `case-fold-search' is non-`nil'.

          (char-equal ?x ?x)
               => t
          (let ((case-fold-search t))
            (char-equal ?x ?X))
               => t
          (let ((case-fold-search nil))
            (char-equal ?x ?X))
               => nil

 - Function: char= CHARACTER1 CHARACTER2
     This function returns `t' if the arguments represent the same
     character, `nil' otherwise.  Case is significant.

          (char= ?x ?x)
               => t
          (char= ?x ?X)
               => nil
          (let ((case-fold-search t))
            (char-equal ?x ?X))
               => nil
          (let ((case-fold-search nil))
            (char-equal ?x ?X))
               => nil

 - Function: string= STRING1 STRING2
     This function returns `t' if the characters of the two strings
     match exactly; case is significant.

          (string= "abc" "abc")
               => t
          (string= "abc" "ABC")
               => nil
          (string= "ab" "ABC")
               => nil


 - Function: string-equal STRING1 STRING2
     `string-equal' is another name for `string='.

 - Function: string< STRING1 STRING2
     This function compares two strings a character at a time.  First it
     scans both the strings at once to find the first pair of
     corresponding characters that do not match.  If the lesser
     character of those two is the character from STRING1, then STRING1
     is less, and this function returns `t'.  If the lesser character
     is the one from STRING2, then STRING1 is greater, and this
     function returns `nil'.  If the two strings match entirely, the
     value is `nil'.

     Pairs of characters are compared by their ASCII codes.  Keep in
     mind that lower case letters have higher numeric values in the
     ASCII character set than their upper case counterparts; numbers and
     many punctuation characters have a lower numeric value than upper
     case letters.

          (string< "abc" "abd")
               => t
          (string< "abd" "abc")
               => nil
          (string< "123" "abc")
               => t

     When the strings have different lengths, and they match up to the
     length of STRING1, then the result is `t'.  If they match up to
     the length of STRING2, the result is `nil'.  A string of no
     characters is less than any other string.

          (string< "" "abc")
               => t
          (string< "ab" "abc")
               => t
          (string< "abc" "")
               => nil
          (string< "abc" "ab")
               => nil
          (string< "" "")
               => nil

 - Function: string-lessp STRING1 STRING2
     `string-lessp' is another name for `string<'.

   See also `compare-buffer-substrings' in *Note Comparing Text::, for
a way to compare text in buffers.  The function `string-match', which
matches a regular expression against a string, can be used for a kind
of string comparison; see *Note Regexp Search::.

\1f
File: lispref.info,  Node: String Conversion,  Next: Modifying Strings,  Prev: Text Comparison,  Up: Strings and Characters

Conversion of Characters and Strings
====================================

   This section describes functions for conversions between characters,
strings and integers.  `format' and `prin1-to-string' (*note Output
Functions::.) can also convert Lisp objects into strings.
`read-from-string' (*note Input Functions::.) can "convert" a string
representation of a Lisp object into an object.

   *Note Documentation::, for functions that produce textual
descriptions of text characters and general input events
(`single-key-description' and `text-char-description').  These
functions are used primarily for making help messages.

 - Function: char-to-string CHARACTER
     This function returns a new string with a length of one character.
     The value of CHARACTER, modulo 256, is used to initialize the
     element of the string.

     This function is similar to `make-string' with an integer argument
     of 1.  (*Note Creating Strings::.)  This conversion can also be
     done with `format' using the `%c' format specification.  (*Note
     Formatting Strings::.)

          (char-to-string ?x)
               => "x"
          (char-to-string (+ 256 ?x))
               => "x"
          (make-string 1 ?x)
               => "x"

 - Function: string-to-char STRING
     This function returns the first character in STRING.  If the
     string is empty, the function returns 0. (Under XEmacs 19, the
     value is also 0 when the first character of STRING is the null
     character, ASCII code 0.)

          (string-to-char "ABC")
               => ?A   ;; Under XEmacs 20.
               => 65   ;; Under XEmacs 19.
          (string-to-char "xyz")
               => ?x   ;; Under XEmacs 20.
               => 120  ;; Under XEmacs 19.
          (string-to-char "")
               => 0
          (string-to-char "\000")
               => ?\^ ;; Under XEmacs 20.
               => 0    ;; Under XEmacs 20.

     This function may be eliminated in the future if it does not seem
     useful enough to retain.

 - Function: number-to-string NUMBER
     This function returns a string consisting of the printed
     representation of NUMBER, which may be an integer or a floating
     point number.  The value starts with a sign if the argument is
     negative.

          (number-to-string 256)
               => "256"
          (number-to-string -23)
               => "-23"
          (number-to-string -23.5)
               => "-23.5"

     `int-to-string' is a semi-obsolete alias for this function.

     See also the function `format' in *Note Formatting Strings::.

 - Function: string-to-number STRING &optional BASE
     This function returns the numeric value of the characters in
     STRING, read in BASE.  It skips spaces and tabs at the beginning
     of STRING, then reads as much of STRING as it can interpret as a
     number.  (On some systems it ignores other whitespace at the
     beginning, not just spaces and tabs.)  If the first character after
     the ignored whitespace is not a digit or a minus sign, this
     function returns 0.

     If BASE is not specified, it defaults to ten.  With BASE other
     than ten, only integers can be read.

          (string-to-number "256")
               => 256
          (string-to-number "25 is a perfect square.")
               => 25
          (string-to-number "X256")
               => 0
          (string-to-number "-4.5")
               => -4.5
          (string-to-number "ffff" 16)
               => 65535

     `string-to-int' is an obsolete alias for this function.

\1f
File: lispref.info,  Node: Modifying Strings,  Next: String Properties,  Prev: String Conversion,  Up: Strings and Characters

Modifying Strings
=================

   You can modify a string using the general array-modifying primitives.
*Note Arrays::.  The function `aset' modifies a single character; the
function `fillarray' sets all characters in the string to a specified
character.

   Each string has a tick counter that starts out at zero (when the
string is created) and is incremented each time a change is made to that
string.

 - Function: string-modified-tick STRING
     This function returns the tick counter for `string'.

\1f
File: lispref.info,  Node: String Properties,  Next: Formatting Strings,  Prev: Modifying Strings,  Up: Strings and Characters

String Properties
=================

   Similar to symbols, extents, faces, and glyphs, you can attach
additional information to strings in the form of "string properties".
These differ from text properties, which are logically attached to
particular characters in the string.

   To attach a property to a string, use `put'.  To retrieve a property
from a string, use `get'.  You can also use `remprop' to remove a
property from a string and `object-props' to retrieve a list of all the
properties in a string.

\1f
File: lispref.info,  Node: Formatting Strings,  Next: Character Case,  Prev: String Properties,  Up: Strings and Characters

Formatting Strings
==================

   "Formatting" means constructing a string by substitution of computed
values at various places in a constant string.  This string controls
how the other values are printed as well as where they appear; it is
called a "format string".

   Formatting is often useful for computing messages to be displayed.
In fact, the functions `message' and `error' provide the same
formatting feature described here; they differ from `format' only in
how they use the result of formatting.

 - Function: format STRING &rest OBJECTS
     This function returns a new string that is made by copying STRING
     and then replacing any format specification in the copy with
     encodings of the corresponding OBJECTS.  The arguments OBJECTS are
     the computed values to be formatted.

   A format specification is a sequence of characters beginning with a
`%'.  Thus, if there is a `%d' in STRING, the `format' function
replaces it with the printed representation of one of the values to be
formatted (one of the arguments OBJECTS).  For example:

     (format "The value of fill-column is %d." fill-column)
          => "The value of fill-column is 72."

   If STRING contains more than one format specification, the format
specifications correspond with successive values from OBJECTS.  Thus,
the first format specification in STRING uses the first such value, the
second format specification uses the second such value, and so on.  Any
extra format specifications (those for which there are no corresponding
values) cause unpredictable behavior.  Any extra values to be formatted
are ignored.

   Certain format specifications require values of particular types.
However, no error is signaled if the value actually supplied fails to
have the expected type.  Instead, the output is likely to be
meaningless.

   Here is a table of valid format specifications:

`%s'
     Replace the specification with the printed representation of the
     object, made without quoting.  Thus, strings are represented by
     their contents alone, with no `"' characters, and symbols appear
     without `\' characters.  This is equivalent to printing the object
     with `princ'.

     If there is no corresponding object, the empty string is used.

`%S'
     Replace the specification with the printed representation of the
     object, made with quoting.  Thus, strings are enclosed in `"'
     characters, and `\' characters appear where necessary before
     special characters.  This is equivalent to printing the object
     with `prin1'.

     If there is no corresponding object, the empty string is used.

`%o'
     Replace the specification with the base-eight representation of an
     integer.

`%d'
`%i'
     Replace the specification with the base-ten representation of an
     integer.

`%x'
     Replace the specification with the base-sixteen representation of
     an integer, using lowercase letters.

`%X'
     Replace the specification with the base-sixteen representation of
     an integer, using uppercase letters.

`%c'
     Replace the specification with the character which is the value
     given.

`%e'
     Replace the specification with the exponential notation for a
     floating point number (e.g. `7.85200e+03').

`%f'
     Replace the specification with the decimal-point notation for a
     floating point number.

`%g'
     Replace the specification with notation for a floating point
     number, using a "pretty format".  Either exponential notation or
     decimal-point notation will be used (usually whichever is
     shorter), and trailing zeroes are removed from the fractional part.

`%%'
     A single `%' is placed in the string.  This format specification is
     unusual in that it does not use a value.  For example, `(format "%%
     %d" 30)' returns `"% 30"'.

   Any other format character results in an `Invalid format operation'
error.

   Here are several examples:

     (format "The name of this buffer is %s." (buffer-name))
          => "The name of this buffer is strings.texi."
     
     (format "The buffer object prints as %s." (current-buffer))
          => "The buffer object prints as #<buffer strings.texi>."
     
     (format "The octal value of %d is %o,
              and the hex value is %x." 18 18 18)
          => "The octal value of 18 is 22,
              and the hex value is 12."

   There are many additional flags and specifications that can occur
between the `%' and the format character, in the following order:

  1. An optional repositioning specification, which is a positive
     integer followed by a `$'.

  2. Zero or more of the optional flag characters `-', `+', ` ', `0',
     and `#'.

  3. An asterisk (`*', meaning that the field width is now assumed to
     have been specified as an argument.

  4. An optional minimum field width.

  5. An optional precision, preceded by a `.' character.

   A "repositioning" specification changes which argument to `format'
is used by the current and all following format specifications.
Normally the first specification uses the first argument, the second
specification uses the second argument, etc.  Using a repositioning
specification, you can change this.  By placing a number N followed by
a `$' between the `%' and the format character, you cause the
specification to use the Nth argument.  The next specification will use
the N+1'th argument, etc.

   For example:

     (format "Can't find file `%s' in directory `%s'."
             "ignatius.c" "loyola/")
          => "Can't find file `ignatius.c' in directory `loyola/'."
     
     (format "In directory `%2$s', the file `%1$s' was not found."
             "ignatius.c" "loyola/")
          => "In directory `loyola/', the file `ignatius.c' was not found."
     
     (format
         "The numbers %d and %d are %1$x and %x in hex and %1$o and %o in octal."
         37 12)
     => "The numbers 37 and 12 are 25 and c in hex and 45 and 14 in octal."

   As you can see, this lets you reprocess arguments more than once or
reword a format specification (thereby moving the arguments around)
without having to actually reorder the arguments.  This is especially
useful in translating messages from one language to another: Different
languages use different word orders, and this sometimes entails changing
the order of the arguments.  By using repositioning specifications,
this can be accomplished without having to embed knowledge of particular
languages into the location in the program's code where the message is
displayed.

   All the specification characters allow an optional numeric prefix
between the `%' and the character, and following any repositioning
specification or flag.  The optional numeric prefix defines the minimum
width for the object.  If the printed representation of the object
contains fewer characters than this, then it is padded.  The padding is
normally on the left, but will be on the right if the `-' flag
character is given.  The padding character is normally a space, but if
the `0' flag character is given, zeros are used for padding.

     (format "%06d is padded on the left with zeros" 123)
          => "000123 is padded on the left with zeros"
     
     (format "%-6d is padded on the right" 123)
          => "123    is padded on the right"

   `format' never truncates an object's printed representation, no
matter what width you specify.  Thus, you can use a numeric prefix to
specify a minimum spacing between columns with no risk of losing
information.

   In the following three examples, `%7s' specifies a minimum width of
7.  In the first case, the string inserted in place of `%7s' has only 3
letters, so 4 blank spaces are inserted for padding.  In the second
case, the string `"specification"' is 13 letters wide but is not
truncated.  In the third case, the padding is on the right.

     (format "The word `%7s' actually has %d letters in it."
             "foo" (length "foo"))
          => "The word `    foo' actually has 3 letters in it."

     (format "The word `%7s' actually has %d letters in it."
             "specification" (length "specification"))
          => "The word `specification' actually has 13 letters in it."

     (format "The word `%-7s' actually has %d letters in it."
             "foo" (length "foo"))
          => "The word `foo    ' actually has 3 letters in it."

   After any minimum field width, a precision may be specified by
preceding it with a `.' character.  The precision specifies the minimum
number of digits to appear in `%d', `%i', `%o', `%x', and `%X'
conversions (the number is padded on the left with zeroes as
necessary); the number of digits printed after the decimal point for
`%f', `%e', and `%E' conversions; the number of significant digits
printed in `%g' and `%G' conversions; and the maximum number of
non-padding characters printed in `%s' and `%S' conversions.  The
default precision for floating-point conversions is six.

   The other flag characters have the following meanings:

   * The ` ' flag means prefix non-negative numbers with a space.

   * The `+' flag means prefix non-negative numbers with a plus sign.

   * The `#' flag means print numbers in an alternate, more verbose
     format: octal numbers begin with zero; hex numbers begin with a
     `0x' or `0X'; a decimal point is printed in `%f', `%e', and `%E'
     conversions even if no numbers are printed after it; and trailing
     zeroes are not omitted in `%g' and `%G' conversions.

\1f
File: lispref.info,  Node: Character Case,  Next: Case Tables,  Prev: Formatting Strings,  Up: Strings and Characters

Character Case
==============

   The character case functions change the case of single characters or
of the contents of strings.  The functions convert only alphabetic
characters (the letters `A' through `Z' and `a' through `z'); other
characters are not altered.  The functions do not modify the strings
that are passed to them as arguments.

   The examples below use the characters `X' and `x' which have ASCII
codes 88 and 120 respectively.

 - Function: downcase STRING-OR-CHAR
     This function converts a character or a string to lower case.

     When the argument to `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
     `downcase' is a character, `downcase' returns the corresponding
     lower case character. (This value is actually an integer under
     XEmacs 19.) If the original character is lower case, or is not a
     letter, then the value equals the original character.

          (downcase "The cat in the hat")
               => "the cat in the hat"
          
          (downcase ?X)
               => ?x   ;; Under XEmacs 20.
               => 120  ;; Under XEmacs 19.

 - Function: upcase STRING-OR-CHAR
     This function converts a character or a string to upper case.

     When the argument to `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 `upcase' is a character, `upcase' returns the
     corresponding upper case character. (This value is actually an
     integer under XEmacs 19.)  If the original character is upper
     case, or is not a letter, then the value equals the original
     character.

          (upcase "The cat in the hat")
               => "THE CAT IN THE HAT"
          
          (upcase ?x)
               => ?X   ;; Under XEmacs 20.
               => 88   ;; Under XEmacs 19.

 - Function: capitalize STRING-OR-CHAR
     This function capitalizes strings or characters.  If
     STRING-OR-CHAR is a string, the function creates and returns a new
     string, whose contents are a copy of 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.

     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 (*note Syntax Class Table::.).

     When the argument to `capitalize' is a character, `capitalize' has
     the same result as `upcase'.

          (capitalize "The cat in the hat")
               => "The Cat In The Hat"
          
          (capitalize "THE 77TH-HATTED CAT")
               => "The 77th-Hatted Cat"
          
          (capitalize ?x)
               => ?X   ;; Under XEmacs 20.
               => 88   ;; Under XEmacs 19.

\1f
File: lispref.info,  Node: Case Tables,  Next: Char Tables,  Prev: Character Case,  Up: Strings and Characters

The Case Table
==============

   You can customize case conversion by installing a special "case
table".  A case table specifies the mapping between upper case and lower
case letters.  It affects both the string and character case conversion
functions (see the previous section) and those that apply to text in the
buffer (*note Case Changes::.).  You need a case table if you are using
a language which has letters other than the standard ASCII letters.

   A case table is a list of this form:

     (DOWNCASE UPCASE CANONICALIZE EQUIVALENCES)

where each element is either `nil' or a string of length 256.  The
element DOWNCASE says how to map each character to its lower-case
equivalent.  The element UPCASE maps each character to its upper-case
equivalent.  If lower and upper case characters are in one-to-one
correspondence, use `nil' for UPCASE; then XEmacs deduces the upcase
table from DOWNCASE.

   For some languages, upper and lower case letters are not in
one-to-one correspondence.  There may be two different lower case
letters with the same upper case equivalent.  In these cases, you need
to specify the maps for both directions.

   The element CANONICALIZE maps each character to a canonical
equivalent; any two characters that are related by case-conversion have
the same canonical equivalent character.

   The element EQUIVALENCES is a map that cyclicly permutes each
equivalence class (of characters with the same canonical equivalent).
(For ordinary ASCII, this would map `a' into `A' and `A' into `a', and
likewise for each set of equivalent characters.)

   When you construct a case table, you can provide `nil' for
CANONICALIZE; then Emacs fills in this string from UPCASE and DOWNCASE.
You can also provide `nil' for EQUIVALENCES; then Emacs fills in this
string from CANONICALIZE.  In a case table that is actually in use,
those components are non-`nil'.  Do not try to specify EQUIVALENCES
without also specifying CANONICALIZE.

   Each buffer has a case table.  XEmacs also has a "standard case
table" which is copied into each buffer when you create the buffer.
Changing the standard case table doesn't affect any existing buffers.

   Here are the functions for working with case tables:

 - Function: case-table-p OBJECT
     This predicate returns non-`nil' if OBJECT is a valid case table.

 - Function: set-standard-case-table TABLE
     This function makes TABLE the standard case table, so that it will
     apply to any buffers created subsequently.

 - Function: standard-case-table
     This returns the standard case table.

 - Function: current-case-table
     This function returns the current buffer's case table.

 - Function: set-case-table TABLE
     This sets the current buffer's case table to TABLE.

   The following three functions are convenient subroutines for packages
that define non-ASCII character sets.  They modify a string
DOWNCASE-TABLE provided as an argument; this should be a string to be
used as the DOWNCASE part of a case table.  They also modify the
standard syntax table.  *Note Syntax Tables::.

 - Function: set-case-syntax-pair UC LC DOWNCASE-TABLE
     This function specifies a pair of corresponding letters, one upper
     case and one lower case.

 - Function: set-case-syntax-delims L R DOWNCASE-TABLE
     This function makes characters L and R a matching pair of
     case-invariant delimiters.

 - Function: set-case-syntax CHAR SYNTAX DOWNCASE-TABLE
     This function makes CHAR case-invariant, with syntax SYNTAX.

 - Command: describe-buffer-case-table
     This command displays a description of the contents of the current
     buffer's case table.

   You can load the library `iso-syntax' to set up the standard syntax
table and define a case table for the 8-bit ISO Latin 1 character set.

\1f
File: lispref.info,  Node: Char Tables,  Prev: Case Tables,  Up: Strings and Characters

The Char Table
==============

   A char table is a table that maps characters (or ranges of
characters) to values.  Char tables are specialized for characters,
only allowing particular sorts of ranges to be assigned values.
Although this loses in generality, it makes for extremely fast
(constant-time) lookups, and thus is feasible for applications that do
an extremely large number of lookups (e.g. scanning a buffer for a
character in a particular syntax, where a lookup in the syntax table
must occur once per character).

   Note that char tables as a primitive type, and all of the functions
in this section, exist only in XEmacs 20.  In XEmacs 19, char tables are
generally implemented using a vector of 256 elements.

   When MULE support exists, the types of ranges that can be assigned
values are

   * all characters

   * an entire charset

   * a single row in a two-octet charset

   * a single character

   When MULE support is not present, the types of ranges that can be
assigned values are

   * all characters

   * a single character

 - Function: char-table-p OBJECT
     This function returns non-`nil' if OBJECT is a char table.

* Menu:

* Char Table Types::            Char tables have different uses.
* Working With Char Tables::    Creating and working with char tables.

\1f
File: lispref.info,  Node: Char Table Types,  Next: Working With Char Tables,  Up: Char Tables

Char Table Types
----------------

   Each char table type is used for a different purpose and allows
different sorts of values.  The different char table types are

`category'
     Used for category tables, which specify the regexp categories that
     a character is in.  The valid values are `nil' or a bit vector of
     95 elements.  Higher-level Lisp functions are provided for working
     with category tables.  Currently categories and category tables
     only exist when MULE support is present.

`char'
     A generalized char table, for mapping from one character to
     another.  Used for case tables, syntax matching tables,
     `keyboard-translate-table', etc.  The valid values are characters.

`generic'
     An even more generalized char table, for mapping from a character
     to anything.

`display'
     Used for display tables, which specify how a particular character
     is to appear when displayed.  #### Not yet implemented.

`syntax'
     Used for syntax tables, which specify the syntax of a particular
     character.  Higher-level Lisp functions are provided for working
     with syntax tables.  The valid values are integers.

 - Function: char-table-type TABLE
     This function returns the type of char table TABLE.

 - Function: char-table-type-list
     This function returns a list of the recognized char table types.

 - Function: valid-char-table-type-p TYPE
     This function returns `t' if TYPE if a recognized char table type.

\1f
File: lispref.info,  Node: Working With Char Tables,  Prev: Char Table Types,  Up: Char Tables

Working With Char Tables
------------------------

 - Function: make-char-table TYPE
     This function makes a new, empty char table of type TYPE.  TYPE
     should be a symbol, one of `char', `category', `display',
     `generic', or `syntax'.

 - Function: put-char-table RANGE VAL TABLE
     This function sets the value for chars in RANGE to be VAL in TABLE.

     RANGE specifies one or more characters to be affected and should be
     one of the following:

        * `t' (all characters are affected)

        * A charset (only allowed when MULE support is present)

        * A vector of two elements: a two-octet charset and a row number
          (only allowed when MULE support is present)

        * A single character

     VAL must be a value appropriate for the type of TABLE.

 - Function: get-char-table CH TABLE
     This function finds the value for char CH in TABLE.

 - Function: get-range-char-table RANGE TABLE &optional MULTI
     This function finds the value for a range in TABLE.  If there is
     more than one value, MULTI is returned (defaults to `nil').

 - Function: reset-char-table TABLE
     This function resets a char table to its default state.

 - Function: map-char-table FUNCTION TABLE &optional RANGE
     This function maps FUNCTION over entries in TABLE, calling it with
     two args, each key and value in the table.

     RANGE specifies a subrange to map over and is in the same format
     as the RANGE argument to `put-range-table'.  If omitted or `t', it
     defaults to the entire table.

 - Function: valid-char-table-value-p VALUE CHAR-TABLE-TYPE
     This function returns non-`nil' if VALUE is a valid value for
     CHAR-TABLE-TYPE.

 - Function: check-valid-char-table-value VALUE CHAR-TABLE-TYPE
     This function signals an error if VALUE is not a valid value for
     CHAR-TABLE-TYPE.

\1f
File: lispref.info,  Node: Lists,  Next: Sequences Arrays Vectors,  Prev: Strings and Characters,  Up: Top

Lists
*****

   A "list" represents a sequence of zero or more elements (which may
be any Lisp objects).  The important difference between lists and
vectors is that two or more lists can share part of their structure; in
addition, you can insert or delete elements in a list without copying
the whole list.

* Menu:

* Cons Cells::              How lists are made out of cons cells.
* Lists as Boxes::          Graphical notation to explain lists.
* List-related Predicates:: Is this object a list?  Comparing two lists.
* List Elements::           Extracting the pieces of a list.
* Building Lists::          Creating list structure.
* Modifying Lists::         Storing new pieces into an existing list.
* Sets And Lists::          A list can represent a finite mathematical set.
* Association Lists::       A list can represent a finite relation or mapping.
* Property Lists::          A different way to represent a finite mapping.
* Weak Lists::              A list with special garbage-collection behavior.

\1f
File: lispref.info,  Node: Cons Cells,  Next: Lists as Boxes,  Up: Lists

Lists and Cons Cells
====================

   Lists in Lisp are not a primitive data type; they are built up from
"cons cells".  A cons cell is a data object that represents an ordered
pair.  It records two Lisp objects, one labeled as the CAR, and the
other labeled as the CDR.  These names are traditional; see *Note Cons
Cell Type::.  CDR is pronounced "could-er."

   A list is a series of cons cells chained together, one cons cell per
element of the list.  By convention, the CARs of the cons cells are the
elements of the list, and the CDRs are used to chain the list: the CDR
of each cons cell is the following cons cell.  The CDR of the last cons
cell is `nil'.  This asymmetry between the CAR and the CDR is entirely
a matter of convention; at the level of cons cells, the CAR and CDR
slots have the same characteristics.

   Because most cons cells are used as part of lists, the phrase "list
structure" has come to mean any structure made out of cons cells.

   The symbol `nil' is considered a list as well as a symbol; it is the
list with no elements.  For convenience, the symbol `nil' is considered
to have `nil' as its CDR (and also as its CAR).

   The CDR of any nonempty list L is a list containing all the elements
of L except the first.

\1f
File: lispref.info,  Node: Lists as Boxes,  Next: List-related Predicates,  Prev: Cons Cells,  Up: Lists

Lists as Linked Pairs of Boxes
==============================

   A cons cell can be illustrated as a pair of boxes.  The first box
represents the CAR and the second box represents the CDR.  Here is an
illustration of the two-element list, `(tulip lily)', made from two
cons cells:

      ---------------         ---------------
     | car   | cdr   |       | car   | cdr   |
     | tulip |   o---------->| lily  |  nil  |
     |       |       |       |       |       |
      ---------------         ---------------

   Each pair of boxes represents a cons cell.  Each box "refers to",
"points to" or "contains" a Lisp object.  (These terms are synonymous.)
The first box, which is the CAR of the first cons cell, contains the
symbol `tulip'.  The arrow from the CDR of the first cons cell to the
second cons cell indicates that the CDR of the first cons cell points
to the second cons cell.

   The same list can be illustrated in a different sort of box notation
like this:

         ___ ___      ___ ___
        |___|___|--> |___|___|--> nil
          |            |
          |            |
           --> tulip    --> lily

   Here is a more complex illustration, showing the three-element list,
`((pine needles) oak maple)', the first element of which is a
two-element list:

         ___ ___      ___ ___      ___ ___
        |___|___|--> |___|___|--> |___|___|--> nil
          |            |            |
          |            |            |
          |             --> oak      --> maple
          |
          |     ___ ___      ___ ___
           --> |___|___|--> |___|___|--> nil
                 |            |
                 |            |
                  --> pine     --> needles

   The same list represented in the first box notation looks like this:

      --------------       --------------       --------------
     | car   | cdr  |     | car   | cdr  |     | car   | cdr  |
     |   o   |   o------->| oak   |   o------->| maple |  nil |
     |   |   |      |     |       |      |     |       |      |
      -- | ---------       --------------       --------------
         |
         |
         |        --------------       ----------------
         |       | car   | cdr  |     | car     | cdr  |
          ------>| pine  |   o------->| needles |  nil |
                 |       |      |     |         |      |
                  --------------       ----------------

   *Note Cons Cell Type::, for the read and print syntax of cons cells
and lists, and for more "box and arrow" illustrations of lists.

\1f
File: lispref.info,  Node: List-related Predicates,  Next: List Elements,  Prev: Lists as Boxes,  Up: Lists

Predicates on Lists
===================

   The following predicates test whether a Lisp object is an atom, is a
cons cell or is a list, or whether it is the distinguished object
`nil'.  (Many of these predicates can be defined in terms of the
others, but they are used so often that it is worth having all of them.)

 - Function: consp OBJECT
     This function returns `t' if OBJECT is a cons cell, `nil'
     otherwise.  `nil' is not a cons cell, although it *is* a list.

 - Function: atom OBJECT
     This function returns `t' if OBJECT is an atom, `nil' otherwise.
     All objects except cons cells are atoms.  The symbol `nil' is an
     atom and is also a list; it is the only Lisp object that is both.

          (atom OBJECT) == (not (consp OBJECT))

 - Function: listp OBJECT
     This function returns `t' if OBJECT is a cons cell or `nil'.
     Otherwise, it returns `nil'.

          (listp '(1))
               => t
          (listp '())
               => t

 - Function: nlistp OBJECT
     This function is the opposite of `listp': it returns `t' if OBJECT
     is not a list.  Otherwise, it returns `nil'.

          (listp OBJECT) == (not (nlistp OBJECT))

 - Function: null OBJECT
     This function returns `t' if OBJECT is `nil', and returns `nil'
     otherwise.  This function is identical to `not', but as a matter
     of clarity we use `null' when OBJECT is considered a list and
     `not' when it is considered a truth value (see `not' in *Note
     Combining Conditions::).

          (null '(1))
               => nil
          (null '())
               => t