@c -*-texinfo-*-
@c This is part of the XEmacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c See the file lispref.texi for copying conditions.
@setfilename ../../info/strings.info
@node Strings and Characters, Lists, Numbers, Top
Lisp programs use strings more often than individual characters.
@menu
-* Basics: String Basics. Basic properties of strings and characters.
+* String Basics:: Basic properties of strings and characters.
* Predicates for Strings:: Testing whether an object is a string or char.
* Creating Strings:: Functions to allocate new strings.
* Predicates for Characters:: Testing whether an object is a character.
The length of a string (like any array) is fixed and independent of
the string contents, and cannot be altered. Strings in Lisp are
@emph{not} terminated by a distinguished character code. (By contrast,
-strings in C are terminated by a character with @sc{ASCII} code 0.)
-This means that any character, including the null character (@sc{ASCII}
+strings in C are terminated by a character with @sc{ascii} code 0.)
+This means that any character, including the null character (@sc{ascii}
code 0), is a valid element of a string.@refill
Since strings are considered arrays, you can operate on them with the
Analogous functions operating on other data types include @code{list},
@code{cons} (@pxref{Building Lists}), @code{vector} (@pxref{Vectors})
-and @code{bit-vector} (@pxref{Bit Vectors}). This function has not been
+and @code{bit-vector} (@pxref{Bit Vectors}). This function has not been
available in XEmacs prior to 21.0 and FSF Emacs prior to 20.3.
@end defun
-@defun make-string count character
- This function returns a string made up of @var{count} repetitions of
-@var{character}. If @var{count} is negative, an error is signaled.
+@defun make-string length character
+This function returns a new string consisting entirely of @var{length}
+successive copies of @var{character}. @var{length} must be a
+non-negative integer.
@example
(make-string 5 ?x)
is 3 is actually the fourth character in the string.
A negative number counts from the end of the string, so that @minus{}1
-signifies the index of the last character of the string. For example:
+signifies the index of the last character of the string. For example:
@example
@group
@node Character Codes
@section Character Codes
-@defun char-int ch
+@defun char-int character
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:
@item 0 - 31
Control set 0
@item 32 - 127
-@sc{ASCII}
+@sc{ascii}
@item 128 - 159
Control set 1
@item 160 - 255
Right half of ISO-8859-1
@end table
-If support for @sc{MULE} does not exist, these are the only valid
-character values. When @sc{MULE} support exists, the values assigned to
+If support for @sc{mule} does not exist, these are the only valid
+character values. When @sc{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.
@section Comparison of Characters and Strings
@cindex string equality
-@defun char-equal character1 character2
+@defun char-equal character1 character2 &optional buffer
This function returns @code{t} if the arguments represent the same
character, @code{nil} otherwise. This function ignores differences
-in case if @code{case-fold-search} is non-@code{nil}.
+in case if the value of @code{case-fold-search} is non-@code{nil} in
+@var{buffer}, which defaults to the current buffer.
@example
(char-equal ?x ?x)
@var{string2}, then @var{string1} is greater, and this function returns
@code{nil}. If the two strings match entirely, the value is @code{nil}.
-Pairs of characters are compared by their @sc{ASCII} codes. Keep in
+Pairs of characters are compared by their @sc{ascii} codes. Keep in
mind that lower case letters have higher numeric values in the
-@sc{ASCII} character set than their upper case counterparts; numbers and
+@sc{ascii} character set than their upper case counterparts; numbers and
many punctuation characters have a lower numeric value than upper case
letters.
(string< "abc" "ab")
@result{} nil
(string< "" "")
- @result{} nil
+ @result{} nil
@end group
@end example
@end defun
This function returns the first character in @var{string}. If the
string is empty, the function returns 0. (Under XEmacs 19, the value is
also 0 when the first character of @var{string} is the null character,
-@sc{ASCII} code 0.)
+@sc{ascii} code 0.)
@example
(string-to-char "ABC")
@defun string-to-number string &optional base
@cindex string to number
-This function returns the numeric value of the characters in
-@var{string}, read in @var{base}. It skips spaces and tabs at the
-beginning of @var{string}, then reads as much of @var{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.
+This function returns the numeric value represented by @var{string},
+read in @var{base}. It skips spaces and tabs at the beginning of
+@var{string}, then reads as much of @var{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 @var{base} is not specified, it defaults to ten. With @var{base}
other than ten, only integers can be read.
@cindex string properties
@cindex properties of strings
-Similar to symbols, extents, faces, and glyphs, you can attach
+Just as with symbols, extents, faces, and glyphs, you can attach
additional information to strings in the form of @dfn{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 @code{put}. To retrieve a property
from a string, use @code{get}. You can also use @code{remprop} to remove
-a property from a string and @code{object-props} to retrieve a list of
+a property from a string and @code{object-plist} to retrieve a list of
all the properties in a string.
@node Formatting Strings
@defun format string &rest objects
This function returns a new string that is made by copying
-@var{string} and then replacing any format specification
+@var{string} and then replacing any format specification
in the copy with encodings of the corresponding @var{objects}. The
arguments @var{objects} are the computed values to be formatted.
@end defun
(format "The buffer object prints as %s." (current-buffer))
@result{} "The buffer object prints as #<buffer strings.texi>."
-(format "The octal value of %d is %o,
+(format "The octal value of %d is %o,
and the hex value is %x." 18 18 18)
- @result{} "The octal value of 18 is 22,
+ @result{} "The octal value of 18 is 22,
and the hex value is 12."
@end group
@end example
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
-@var{N} followed by a @samp{$} between the @samp{%} and the format
-character, you cause the specification to use the @var{N}th argument.
-The next specification will use the @var{N}+1'th argument, etc.
+@var{n} followed by a @samp{$} between the @samp{%} and the format
+character, you cause the specification to use the @var{n}th argument.
+The next specification will use the @var{n}+1'th argument, etc.
For example:
second case, the string @code{"specification"} is 13 letters wide but is
not truncated. In the third case, the padding is on the right.
-@smallexample
+@smallexample
@group
(format "The word `%7s' actually has %d letters in it."
"foo" (length "foo"))
- @result{} "The word ` foo' actually has 3 letters in it."
+ @result{} "The word ` foo' actually has 3 letters in it."
@end group
@group
(format "The word `%7s' actually has %d letters in it."
- "specification" (length "specification"))
- @result{} "The word `specification' actually has 13 letters in it."
+ "specification" (length "specification"))
+ @result{} "The word `specification' actually has 13 letters in it."
@end group
@group
(format "The word `%-7s' actually has %d letters in it."
"foo" (length "foo"))
- @result{} "The word `foo ' actually has 3 letters in it."
+ @result{} "The word `foo ' actually has 3 letters in it."
@end group
@end smallexample
@node Character Case
@section Character Case
-@cindex upper case
-@cindex lower case
-@cindex character case
+@cindex upper case
+@cindex lower case
+@cindex character case
The character case functions change the case of single characters or
of the contents of strings. The functions convert only alphabetic
modify the strings that are passed to them as arguments.
The examples below use the characters @samp{X} and @samp{x} which have
-@sc{ASCII} codes 88 and 120 respectively.
+@sc{ascii} codes 88 and 120 respectively.
-@defun downcase string-or-char
+@defun downcase string-or-char &optional buffer
This function converts a character or a string to lower case.
When the argument to @code{downcase} is a string, the function creates
under XEmacs 19.) If the original character is lower case, or is not a
letter, then the value equals the original character.
+Optional second arg @var{buffer} specifies which buffer's case tables to
+use, and defaults to the current buffer.
+
@example
(downcase "The cat in the hat")
@result{} "the cat in the hat"
@end example
@end defun
-@defun upcase string-or-char
+@defun upcase string-or-char &optional buffer
This function converts a character or a string to upper case.
When the argument to @code{upcase} is a string, the function creates
integer under XEmacs 19.) If the original character is upper case, or
is not a letter, then the value equals the original character.
+Optional second arg @var{buffer} specifies which buffer's case tables to
+use, and defaults to the current buffer.
+
@example
(upcase "The cat in the hat")
@result{} "THE CAT IN THE HAT"
@end example
@end defun
-@defun capitalize string-or-char
+@defun capitalize string-or-char &optional buffer
@cindex capitalization
This function capitalizes strings or characters. If
@var{string-or-char} is a string, the function creates and returns a new
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 (@xref{Syntax Class Table}).
+table (@pxref{Syntax Class Table}).
When the argument to @code{capitalize} is a character, @code{capitalize}
has the same result as @code{upcase}.
+Optional second arg @var{buffer} specifies which buffer's case tables to
+use, and defaults to the current buffer.
+
@example
(capitalize "The cat in the hat")
@result{} "The Cat In The Hat"
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 (@pxref{Case Changes}). You need a case table if you are using a
-language which has letters other than the standard @sc{ASCII} letters.
+language which has letters other than the standard @sc{ascii} letters.
A case table is a list of this form:
The element @var{equivalences} is a map that cyclicly permutes each
equivalence class (of characters with the same canonical equivalent).
-(For ordinary @sc{ASCII}, this would map @samp{a} into @samp{A} and
+(For ordinary @sc{ascii}, this would map @samp{a} into @samp{A} and
@samp{A} into @samp{a}, and likewise for each set of equivalent
characters.)
table.
@end defun
-@defun set-standard-case-table table
-This function makes @var{table} the standard case table, so that it will
-apply to any buffers created subsequently.
+@defun set-standard-case-table case-table
+This function makes @var{case-table} the standard case table, so that it
+will apply to any buffers created subsequently.
@end defun
@defun standard-case-table
This returns the standard case table.
@end defun
-@defun current-case-table
-This function returns the current buffer's case table.
+@defun current-case-table &optional buffer
+This function returns the case table of @var{buffer}, which defaults to
+the current buffer.
@end defun
-@defun set-case-table table
-This sets the current buffer's case table to @var{table}.
+@defun set-case-table case-table
+This sets the current buffer's case table to @var{case-table}.
@end defun
The following three functions are convenient subroutines for packages
-that define non-@sc{ASCII} character sets. They modify a string
+that define non-@sc{ascii} character sets. They modify a string
@var{downcase-table} provided as an argument; this should be a string to
be used as the @var{downcase} part of a case table. They also modify
the standard syntax table. @xref{Syntax Tables}.
this section, exist only in XEmacs 20. In XEmacs 19, char tables are
generally implemented using a vector of 256 elements.
-When @sc{MULE} support exists, the types of ranges that can be assigned
+When @sc{mule} support exists, the types of ranges that can be assigned
values are
@itemize @bullet
a single character
@end itemize
-When @sc{MULE} support is not present, the types of ranges that can be
+When @sc{mule} support is not present, the types of ranges that can be
assigned values are
@itemize @bullet
that a character is in. The valid values are @code{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 @sc{MULE} support is present.
+and category tables only exist when @sc{mule} support is present.
@item char
A generalized char table, for mapping from one character to
another. Used for case tables, syntax matching tables,
working with syntax tables. The valid values are integers.
@end table
-@defun char-table-type table
-This function returns the type of char table @var{table}.
+@defun char-table-type char-table
+This function returns the type of char table @var{char-table}.
@end defun
@defun char-table-type-list
@code{display}, @code{generic}, or @code{syntax}.
@end defun
-@defun put-char-table range val table
-This function sets the value for chars in @var{range} to be @var{val} in
-@var{table}.
+@defun put-char-table range value char-table
+This function sets the value for chars in @var{range} to be @var{value} in
+@var{char-table}.
@var{range} specifies one or more characters to be affected and should be
one of the following:
@item
@code{t} (all characters are affected)
@item
-A charset (only allowed when @sc{MULE} support is present)
+A charset (only allowed when @sc{mule} support is present)
@item
A vector of two elements: a two-octet charset and a row number
-(only allowed when @sc{MULE} support is present)
+(only allowed when @sc{mule} support is present)
@item
A single character
@end itemize
-@var{val} must be a value appropriate for the type of @var{table}.
+@var{value} must be a value appropriate for the type of @var{char-table}.
@end defun
-@defun get-char-table ch table
-This function finds the value for char @var{ch} in @var{table}.
+@defun get-char-table character char-table
+This function finds the value for @var{character} in @var{char-table}.
@end defun
-@defun get-range-char-table range table &optional multi
-This function finds the value for a range in @var{table}. If there is
+@defun get-range-char-table range char-table &optional multi
+This function finds the value for a range in @var{char-table}. If there is
more than one value, @var{multi} is returned (defaults to @code{nil}).
@end defun
-@defun reset-char-table table
-This function resets a char table to its default state.
+@defun reset-char-table char-table
+This function resets @var{char-table} to its default state.
@end defun
-@defun map-char-table function table &optional range
-This function maps @var{function} over entries in @var{table}, calling
+@defun map-char-table function char-table &optional range
+This function maps @var{function} over entries in @var{char-table}, calling
it with two args, each key and value in the table.
@var{range} specifies a subrange to map over and is in the same format
projects / chise / xemacs-chise.git.1 / blobdiff