diff options
Diffstat (limited to 'lispref')
| -rw-r--r-- | lispref/strings.texi | 810 |
1 files changed, 810 insertions, 0 deletions
diff --git a/lispref/strings.texi b/lispref/strings.texi new file mode 100644 index 00000000000..efca7aeea62 --- /dev/null +++ b/lispref/strings.texi @@ -0,0 +1,810 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/strings +@node Strings and Characters, Lists, Numbers, Top +@comment node-name, next, previous, up +@chapter Strings and Characters +@cindex strings +@cindex character arrays +@cindex characters +@cindex bytes + + A string in Emacs Lisp is an array that contains an ordered sequence +of characters. Strings are used as names of symbols, buffers, and +files, to send messages to users, to hold text being copied between +buffers, and for many other purposes. Because strings are so important, +Emacs Lisp has many functions expressly for manipulating them. Emacs +Lisp programs use strings more often than individual characters. + + @xref{Strings of Events}, for special considerations for strings of +keyboard character events. + +@menu +* Basics: 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. +* Text Comparison:: Comparing characters or strings. +* String Conversion:: Converting characters or strings and vice versa. +* Formatting Strings:: @code{format}: Emacs's analog of @code{printf}. +* Character Case:: Case conversion functions. +* Case Table:: Customizing case conversion. +@end menu + +@node String Basics +@section String and Character Basics + + Strings in Emacs Lisp are arrays that contain an ordered sequence of +characters. Characters are represented in Emacs Lisp as integers; +whether an integer was intended as a character or not is determined only +by how it is used. Thus, strings really contain integers. + + 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} +code 0), is a valid element of a string.@refill + + Since strings are considered arrays, you can operate on them with the +general array functions. (@xref{Sequences Arrays Vectors}.) For +example, you can access or change individual characters in a string +using the functions @code{aref} and @code{aset} (@pxref{Array +Functions}). + + Each character in a string is stored in a single byte. Therefore, +numbers not in the range 0 to 255 are truncated when stored into a +string. This means that a string takes up much less memory than a +vector of the same length. + + Sometimes key sequences are represented as strings. When a string is +a key sequence, string elements in the range 128 to 255 represent meta +characters (which are extremely large integers) rather than keyboard +events in the range 128 to 255. + + Strings cannot hold characters that have the hyper, super or alt +modifiers; they can hold @sc{ASCII} control characters, but no other +control characters. They do not distinguish case in @sc{ASCII} control +characters. @xref{Character Type}, for more information about +representation of meta and other modifiers for keyboard input +characters. + + Like a buffer, a string can contain text properties for the characters +in it, as well as the characters themselves. @xref{Text Properties}. + + @xref{Text}, for information about functions that display strings or +copy them into buffers. @xref{Character Type}, and @ref{String Type}, +for information about the syntax of characters and strings. + +@node Predicates for Strings +@section The Predicates for Strings + +For more information about general sequence and array predicates, +see @ref{Sequences Arrays Vectors}, and @ref{Arrays}. + +@defun stringp object + This function returns @code{t} if @var{object} is a string, @code{nil} +otherwise. +@end defun + +@defun char-or-string-p object + This function returns @code{t} if @var{object} is a string or a +character (i.e., an integer), @code{nil} otherwise. +@end defun + +@node Creating Strings +@section Creating Strings + + The following functions create strings, either from scratch, or by +putting strings together, or by taking them apart. + +@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. + +@example +(make-string 5 ?x) + @result{} "xxxxx" +(make-string 0 ?x) + @result{} "" +@end example + + Other functions to compare with this one include @code{char-to-string} +(@pxref{String Conversion}), @code{make-vector} (@pxref{Vectors}), and +@code{make-list} (@pxref{Building Lists}). +@end defun + +@defun substring string start &optional end + This function returns a new string which consists of those characters +from @var{string} in the range from (and including) the character at the +index @var{start} up to (but excluding) the character at the index +@var{end}. The first character is at index zero. + +@example +@group +(substring "abcdefg" 0 3) + @result{} "abc" +@end group +@end example + +@noindent +Here the index for @samp{a} is 0, the index for @samp{b} is 1, and the +index for @samp{c} is 2. Thus, three letters, @samp{abc}, are copied +from the string @code{"abcdefg"}. The index 3 marks the character +position up to which the substring is copied. The character whose index +is 3 is actually the fourth character in the string. + +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: + +@example +@group +(substring "abcdefg" -3 -1) + @result{} "ef" +@end group +@end example + +@noindent +In this example, the index for @samp{e} is @minus{}3, the index for +@samp{f} is @minus{}2, and the index for @samp{g} is @minus{}1. +Therefore, @samp{e} and @samp{f} are included, and @samp{g} is excluded. + +When @code{nil} is used as an index, it stands for the length of the +string. Thus, + +@example +@group +(substring "abcdefg" -3 nil) + @result{} "efg" +@end group +@end example + +Omitting the argument @var{end} is equivalent to specifying @code{nil}. +It follows that @code{(substring @var{string} 0)} returns a copy of all +of @var{string}. + +@example +@group +(substring "abcdefg" 0) + @result{} "abcdefg" +@end group +@end example + +@noindent +But we recommend @code{copy-sequence} for this purpose (@pxref{Sequence +Functions}). + +A @code{wrong-type-argument} error is signaled if either @var{start} or +@var{end} is not an integer or @code{nil}. An @code{args-out-of-range} +error is signaled if @var{start} indicates a character following +@var{end}, or if either integer is out of range for @var{string}. + +Contrast this function with @code{buffer-substring} (@pxref{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. +@end defun + +@defun concat &rest sequences +@cindex copying strings +@cindex concatenating strings +This function returns a new string consisting of the characters in the +arguments passed to it. The arguments may be strings, lists of numbers, +or vectors of numbers; they are not themselves changed. If +@code{concat} receives no arguments, it returns an empty string. + +@example +(concat "abc" "-def") + @result{} "abc-def" +(concat "abc" (list 120 (+ 256 121)) [122]) + @result{} "abcxyz" +;; @r{@code{nil} is an empty sequence.} +(concat "abc" nil "-def") + @result{} "abc-def" +(concat "The " "quick brown " "fox.") + @result{} "The quick brown fox." +(concat) + @result{} "" +@end example + +@noindent +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 @code{concat} function always constructs a new string that is +not @code{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. This special case exists for +compatibility with Mocklisp, and we don't recommend you take advantage +of it. If you want to convert an integer to digits in this way, use +@code{format} (@pxref{Formatting Strings}) or @code{number-to-string} +(@pxref{String Conversion}). + +@example +@group +(concat 137) + @result{} "137" +(concat 54 321) + @result{} "54321" +@end group +@end example + +For information about other concatenation functions, see the +description of @code{mapconcat} in @ref{Mapping Functions}, +@code{vconcat} in @ref{Vectors}, and @code{append} in @ref{Building +Lists}. +@end defun + +@node Text Comparison +@section Comparison of Characters and Strings +@cindex string equality + +@defun char-equal character1 character2 +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}. + +@example +(char-equal ?x ?x) + @result{} t +(char-to-string (+ 256 ?x)) + @result{} "x" +(char-equal ?x (+ 256 ?x)) + @result{} t +@end example +@end defun + +@defun string= string1 string2 +This function returns @code{t} if the characters of the two strings +match exactly; case is significant. + +@example +(string= "abc" "abc") + @result{} t +(string= "abc" "ABC") + @result{} nil +(string= "ab" "ABC") + @result{} nil +@end example +@end defun + +@defun string-equal string1 string2 +@code{string-equal} is another name for @code{string=}. +@end defun + +@cindex lexical comparison +@defun string< string1 string2 +@c (findex string< causes problems for permuted index!!) +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 @var{string1}, then @var{string1} is less, and this +function returns @code{t}. If the lesser character is the one from +@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 +mind that lower case letters have higher numeric values in the +@sc{ASCII} character set than their upper case counterparts; numbers and +many punctuation characters have a lower numeric value than upper case +letters. + +@example +@group +(string< "abc" "abd") + @result{} t +(string< "abd" "abc") + @result{} nil +(string< "123" "abc") + @result{} t +@end group +@end example + +When the strings have different lengths, and they match up to the +length of @var{string1}, then the result is @code{t}. If they match up +to the length of @var{string2}, the result is @code{nil}. A string of +no characters is less than any other string. + +@example +@group +(string< "" "abc") + @result{} t +(string< "ab" "abc") + @result{} t +(string< "abc" "") + @result{} nil +(string< "abc" "ab") + @result{} nil +(string< "" "") + @result{} nil +@end group +@end example +@end defun + +@defun string-lessp string1 string2 +@code{string-lessp} is another name for @code{string<}. +@end defun + + See also @code{compare-buffer-substrings} in @ref{Comparing Text}, for +a way to compare text in buffers. The function @code{string-match}, +which matches a regular expression against a string, can be used +for a kind of string comparison; see @ref{Regexp Search}. + +@node String Conversion +@comment node-name, next, previous, up +@section Conversion of Characters and Strings +@cindex conversion of strings + + This section describes functions for conversions between characters, +strings and integers. @code{format} and @code{prin1-to-string} +(@pxref{Output Functions}) can also convert Lisp objects into strings. +@code{read-from-string} (@pxref{Input Functions}) can ``convert'' a +string representation of a Lisp object into an object. + + @xref{Documentation}, for functions that produce textual descriptions +of text characters and general input events +(@code{single-key-description} and @code{text-char-description}). These +functions are used primarily for making help messages. + +@defun char-to-string character +@cindex character to string + This function returns a new string with a length of one character. +The value of @var{character}, modulo 256, is used to initialize the +element of the string. + +This function is similar to @code{make-string} with an integer argument +of 1. (@xref{Creating Strings}.) This conversion can also be done with +@code{format} using the @samp{%c} format specification. +(@xref{Formatting Strings}.) + +@example +(char-to-string ?x) + @result{} "x" +(char-to-string (+ 256 ?x)) + @result{} "x" +(make-string 1 ?x) + @result{} "x" +@end example +@end defun + +@defun string-to-char string +@cindex string to character + This function returns the first character in @var{string}. If the +string is empty, the function returns 0. The value is also 0 when the +first character of @var{string} is the null character, @sc{ASCII} code +0. + +@example +(string-to-char "ABC") + @result{} 65 +(string-to-char "xyz") + @result{} 120 +(string-to-char "") + @result{} 0 +(string-to-char "\000") + @result{} 0 +@end example + +This function may be eliminated in the future if it does not seem useful +enough to retain. +@end defun + +@defun number-to-string number +@cindex integer to string +@cindex integer to decimal +This function returns a string consisting of the printed +representation of @var{number}, which may be an integer or a floating +point number. The value starts with a sign if the argument is +negative. + +@example +(number-to-string 256) + @result{} "256" +(number-to-string -23) + @result{} "-23" +(number-to-string -23.5) + @result{} "-23.5" +@end example + +@cindex int-to-string +@code{int-to-string} is a semi-obsolete alias for this function. + +See also the function @code{format} in @ref{Formatting Strings}. +@end defun + +@defun string-to-number string +@cindex string to number +This function returns the numeric value of the characters in +@var{string}, read in base ten. 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. + +@example +(string-to-number "256") + @result{} 256 +(string-to-number "25 is a perfect square.") + @result{} 25 +(string-to-number "X256") + @result{} 0 +(string-to-number "-4.5") + @result{} -4.5 +@end example + +@findex string-to-int +@code{string-to-int} is an obsolete alias for this function. +@end defun + +@node Formatting Strings +@comment node-name, next, previous, up +@section Formatting Strings +@cindex formatting strings +@cindex strings, formatting them + + @dfn{Formatting} means constructing a string by substitution of +computed values at various places in a constant string. This string +controls how the other values are printed as well as where they appear; +it is called a @dfn{format string}. + + Formatting is often useful for computing messages to be displayed. In +fact, the functions @code{message} and @code{error} provide the same +formatting feature described here; they differ from @code{format} only +in how they use the result of formatting. + +@defun format string &rest objects + This function returns a new string that is made by copying +@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 + +@cindex @samp{%} in format +@cindex format specification + A format specification is a sequence of characters beginning with a +@samp{%}. Thus, if there is a @samp{%d} in @var{string}, the +@code{format} function replaces it with the printed representation of +one of the values to be formatted (one of the arguments @var{objects}). +For example: + +@example +@group +(format "The value of fill-column is %d." fill-column) + @result{} "The value of fill-column is 72." +@end group +@end example + + If @var{string} contains more than one format specification, the +format specifications correspond with successive values from +@var{objects}. Thus, the first format specification in @var{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: + +@table @samp +@item %s +Replace the specification with the printed representation of the object, +made without quoting. Thus, strings are represented by their contents +alone, with no @samp{"} characters, and symbols appear without @samp{\} +characters. + +If there is no corresponding object, the empty string is used. + +@item %S +Replace the specification with the printed representation of the object, +made with quoting. Thus, strings are enclosed in @samp{"} characters, +and @samp{\} characters appear where necessary before special characters. + +If there is no corresponding object, the empty string is used. + +@item %o +@cindex integer to octal +Replace the specification with the base-eight representation of an +integer. + +@item %d +Replace the specification with the base-ten representation of an +integer. + +@item %x +@cindex integer to hexadecimal +Replace the specification with the base-sixteen representation of an +integer. + +@item %c +Replace the specification with the character which is the value given. + +@item %e +Replace the specification with the exponential notation for a floating +point number. + +@item %f +Replace the specification with the decimal-point notation for a floating +point number. + +@item %g +Replace the specification with notation for a floating point number, +using either exponential notation or decimal-point notation whichever +is shorter. + +@item %% +A single @samp{%} is placed in the string. This format specification is +unusual in that it does not use a value. For example, @code{(format "%% +%d" 30)} returns @code{"% 30"}. +@end table + + Any other format character results in an @samp{Invalid format +operation} error. + + Here are several examples: + +@example +@group +(format "The name of this buffer is %s." (buffer-name)) + @result{} "The name of this buffer is strings.texi." + +(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, + and the hex value is %x." 18 18 18) + @result{} "The octal value of 18 is 22, + and the hex value is 12." +@end group +@end example + +@cindex numeric prefix +@cindex field width +@cindex padding + All the specification characters allow an optional numeric prefix +between the @samp{%} and the character. 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 on the left if the prefix is positive (or starts with +zero) and on the right if the prefix is negative. The padding character +is normally a space, but if the numeric prefix starts with a zero, zeros +are used for padding. + +@example +(format "%06d is padded on the left with zeros" 123) + @result{} "000123 is padded on the left with zeros" + +(format "%-6d is padded on the right" 123) + @result{} "123 is padded on the right" +@end example + + @code{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, @samp{%7s} specifies a minimum width +of 7. In the first case, the string inserted in place of @samp{%7s} has +only 3 letters, so 4 blank spaces are inserted for padding. In the +second case, the string @code{"specification"} is 13 letters wide but is +not truncated. In the third case, the padding is on the right. + +@smallexample +@group +(format "The word `%7s' actually has %d letters in it." + "foo" (length "foo")) + @result{} "The word ` foo' actually has 3 letters in it." +@end group + +@group +(format "The word `%7s' actually has %d letters in it." + "specification" (length "specification")) + @result{} "The word `specification' actually has 13 letters in it." +@end group + +@group +(format "The word `%-7s' actually has %d letters in it." + "foo" (length "foo")) + @result{} "The word `foo ' actually has 3 letters in it." +@end group +@end smallexample + +@node Character Case +@comment node-name, next, previous, up +@section 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 +characters (the letters @samp{A} through @samp{Z} and @samp{a} through +@samp{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 @samp{X} and @samp{x} which have +@sc{ASCII} codes 88 and 120 respectively. + +@defun downcase string-or-char +This function converts a character or a string to lower case. + +When the argument to @code{downcase} is a string, the function creates +and returns a new string in which each letter in the argument that is +upper case is converted to lower case. When the argument to +@code{downcase} is a character, @code{downcase} returns the +corresponding lower case character. This value is an integer. If the +original character is lower case, or is not a letter, then the value +equals the original character. + +@example +(downcase "The cat in the hat") + @result{} "the cat in the hat" + +(downcase ?X) + @result{} 120 +@end example +@end defun + +@defun upcase string-or-char +This function converts a character or a string to upper case. + +When the argument to @code{upcase} is a string, the function creates +and returns a new string in which each letter in the argument that is +lower case is converted to upper case. + +When the argument to @code{upcase} is a character, @code{upcase} +returns the corresponding upper case character. This value is an integer. +If the original character is upper case, or is not a letter, then the +value equals the original character. + +@example +(upcase "The cat in the hat") + @result{} "THE CAT IN THE HAT" + +(upcase ?x) + @result{} 88 +@end example +@end defun + +@defun capitalize string-or-char +@cindex capitalization +This function capitalizes strings or characters. If +@var{string-or-char} is a string, the function creates and returns a new +string, whose contents are a copy of @var{string-or-char} in which each +word has been capitalized. This means that the first character of each +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 (@xref{Syntax Class Table}). + +When the argument to @code{capitalize} is a character, @code{capitalize} +has the same result as @code{upcase}. + +@example +(capitalize "The cat in the hat") + @result{} "The Cat In The Hat" + +(capitalize "THE 77TH-HATTED CAT") + @result{} "The 77th-Hatted Cat" + +@group +(capitalize ?x) + @result{} 88 +@end group +@end example +@end defun + +@node Case Table +@section The Case Table + + You can customize case conversion by installing a special @dfn{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 (@pxref{Case Changes}). You need a case table if you are using a +language which has letters other than the standard @sc{ASCII} letters. + + A case table is a list of this form: + +@example +(@var{downcase} @var{upcase} @var{canonicalize} @var{equivalences}) +@end example + +@noindent +where each element is either @code{nil} or a string of length 256. The +element @var{downcase} says how to map each character to its lower-case +equivalent. The element @var{upcase} maps each character to its +upper-case equivalent. If lower and upper case characters are in +one-to-one correspondence, use @code{nil} for @var{upcase}; then Emacs +deduces the upcase table from @var{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 @var{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 @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 +@samp{A} into @samp{a}, and likewise for each set of equivalent +characters.) + + When you construct a case table, you can provide @code{nil} for both +@var{canonicalize} and @var{equivalences}. When you specify the case +table for use, Emacs fills in these strings, computing them from +@var{upcase} and @var{downcase}. In a case table that is actually in +use, those components are non-@code{nil}. Do not try to make just one +of these components @code{nil}; that is not meaningful. + + Each buffer has a case table. Emacs also has a @dfn{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: + +@defun case-table-p object +This predicate returns non-@code{nil} if @var{object} is a valid case +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. +@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. +@end defun + +@defun set-case-table table +This sets the current buffer's case table to @var{table}. +@end defun + + The following three functions are convenient subroutines for packages +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}. + +@defun set-case-syntax-pair uc lc downcase-table +This function specifies a pair of corresponding letters, one upper case +and one lower case. +@end defun + +@defun set-case-syntax-delims l r downcase-table +This function makes characters @var{l} and @var{r} a matching pair of +case-invariant delimiters. +@end defun + +@defun set-case-syntax char syntax downcase-table +This function makes @var{char} case-invariant, with syntax +@var{syntax}. +@end defun + +@deffn Command describe-buffer-case-table +This command displays a description of the contents of the current +buffer's case table. +@end deffn + +@cindex ISO Latin 1 +@pindex iso-syntax +You can load the library @file{iso-syntax} to set up the standard syntax +table and define a case table for the 256-bit ISO Latin 1 character set. |