+++ /dev/null
-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
-
projects / chise / xemacs-chise.git.1 / blobdiff