* configure.in: Make gameuser configurable (Bug#7717).
[emacs.git] / doc / lispref / strings.texi
blobcc74c2cbf8ad15ef39f79d14fd71bb823ec174ad
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
4 @c   2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
5 @c   Free Software Foundation, Inc.
6 @c See the file elisp.texi for copying conditions.
7 @setfilename ../../info/strings
8 @node Strings and Characters, Lists, Numbers, Top
9 @comment  node-name,  next,  previous,  up
10 @chapter Strings and Characters
11 @cindex strings
12 @cindex character arrays
13 @cindex characters
14 @cindex bytes
16   A string in Emacs Lisp is an array that contains an ordered sequence
17 of characters.  Strings are used as names of symbols, buffers, and
18 files; to send messages to users; to hold text being copied between
19 buffers; and for many other purposes.  Because strings are so important,
20 Emacs Lisp has many functions expressly for manipulating them.  Emacs
21 Lisp programs use strings more often than individual characters.
23   @xref{Strings of Events}, for special considerations for strings of
24 keyboard character events.
26 @menu
27 * Basics: String Basics.      Basic properties of strings and characters.
28 * Predicates for Strings::    Testing whether an object is a string or char.
29 * Creating Strings::          Functions to allocate new strings.
30 * Modifying Strings::         Altering the contents of an existing string.
31 * Text Comparison::           Comparing characters or strings.
32 * String Conversion::         Converting to and from characters and strings.
33 * Formatting Strings::        @code{format}: Emacs's analogue of @code{printf}.
34 * Case Conversion::           Case conversion functions.
35 * Case Tables::               Customizing case conversion.
36 @end menu
38 @node String Basics
39 @section String and Character Basics
41   Characters are represented in Emacs Lisp as integers;
42 whether an integer is a character or not is determined only by how it is
43 used.  Thus, strings really contain integers.  @xref{Character Codes},
44 for details about character representation in Emacs.
46   The length of a string (like any array) is fixed, and cannot be
47 altered once the string exists.  Strings in Lisp are @emph{not}
48 terminated by a distinguished character code.  (By contrast, strings in
49 C are terminated by a character with @acronym{ASCII} code 0.)
51   Since strings are arrays, and therefore sequences as well, you can
52 operate on them with the general array and sequence functions.
53 (@xref{Sequences Arrays Vectors}.)  For example, you can access or
54 change individual characters in a string using the functions @code{aref}
55 and @code{aset} (@pxref{Array Functions}).
57   There are two text representations for non-@acronym{ASCII} characters in
58 Emacs strings (and in buffers): unibyte and multibyte (@pxref{Text
59 Representations}).  For most Lisp programming, you don't need to be
60 concerned with these two representations.
62   Sometimes key sequences are represented as unibyte strings.  When a
63 unibyte string is a key sequence, string elements in the range 128 to
64 255 represent meta characters (which are large integers) rather than
65 character codes in the range 128 to 255.  Strings cannot hold
66 characters that have the hyper, super or alt modifiers; they can hold
67 @acronym{ASCII} control characters, but no other control characters.
68 They do not distinguish case in @acronym{ASCII} control characters.
69 If you want to store such characters in a sequence, such as a key
70 sequence, you must use a vector instead of a string.  @xref{Character
71 Type}, for more information about keyboard input characters.
73   Strings are useful for holding regular expressions.  You can also
74 match regular expressions against strings with @code{string-match}
75 (@pxref{Regexp Search}).  The functions @code{match-string}
76 (@pxref{Simple Match Data}) and @code{replace-match} (@pxref{Replacing
77 Match}) are useful for decomposing and modifying strings after
78 matching regular expressions against them.
80   Like a buffer, a string can contain text properties for the characters
81 in it, as well as the characters themselves.  @xref{Text Properties}.
82 All the Lisp primitives that copy text from strings to buffers or other
83 strings also copy the properties of the characters being copied.
85   @xref{Text}, for information about functions that display strings or
86 copy them into buffers.  @xref{Character Type}, and @ref{String Type},
87 for information about the syntax of characters and strings.
88 @xref{Non-ASCII Characters}, for functions to convert between text
89 representations and to encode and decode character codes.
91 @node Predicates for Strings
92 @section The Predicates for Strings
94 For more information about general sequence and array predicates,
95 see @ref{Sequences Arrays Vectors}, and @ref{Arrays}.
97 @defun stringp object
98 This function returns @code{t} if @var{object} is a string, @code{nil}
99 otherwise.
100 @end defun
102 @defun string-or-null-p object
103 This function returns @code{t} if @var{object} is a string or
104 @code{nil}.  It returns @code{nil} otherwise.
105 @end defun
107 @defun char-or-string-p object
108 This function returns @code{t} if @var{object} is a string or a
109 character (i.e., an integer), @code{nil} otherwise.
110 @end defun
112 @node Creating Strings
113 @section Creating Strings
115   The following functions create strings, either from scratch, or by
116 putting strings together, or by taking them apart.
118 @defun make-string count character
119 This function returns a string made up of @var{count} repetitions of
120 @var{character}.  If @var{count} is negative, an error is signaled.
122 @example
123 (make-string 5 ?x)
124      @result{} "xxxxx"
125 (make-string 0 ?x)
126      @result{} ""
127 @end example
129   Other functions to compare with this one include @code{make-vector}
130 (@pxref{Vectors}) and @code{make-list} (@pxref{Building Lists}).
131 @end defun
133 @defun string &rest characters
134 This returns a string containing the characters @var{characters}.
136 @example
137 (string ?a ?b ?c)
138      @result{} "abc"
139 @end example
140 @end defun
142 @defun substring string start &optional end
143 This function returns a new string which consists of those characters
144 from @var{string} in the range from (and including) the character at the
145 index @var{start} up to (but excluding) the character at the index
146 @var{end}.  The first character is at index zero.
148 @example
149 @group
150 (substring "abcdefg" 0 3)
151      @result{} "abc"
152 @end group
153 @end example
155 @noindent
156 In the above example, the index for @samp{a} is 0, the index for
157 @samp{b} is 1, and the index for @samp{c} is 2.  The index 3---which
158 is the fourth character in the string---marks the character position
159 up to which the substring is copied.  Thus, @samp{abc} is copied from
160 the string @code{"abcdefg"}.
162 A negative number counts from the end of the string, so that @minus{}1
163 signifies the index of the last character of the string.  For example:
165 @example
166 @group
167 (substring "abcdefg" -3 -1)
168      @result{} "ef"
169 @end group
170 @end example
172 @noindent
173 In this example, the index for @samp{e} is @minus{}3, the index for
174 @samp{f} is @minus{}2, and the index for @samp{g} is @minus{}1.
175 Therefore, @samp{e} and @samp{f} are included, and @samp{g} is excluded.
177 When @code{nil} is used for @var{end}, it stands for the length of the
178 string.  Thus,
180 @example
181 @group
182 (substring "abcdefg" -3 nil)
183      @result{} "efg"
184 @end group
185 @end example
187 Omitting the argument @var{end} is equivalent to specifying @code{nil}.
188 It follows that @code{(substring @var{string} 0)} returns a copy of all
189 of @var{string}.
191 @example
192 @group
193 (substring "abcdefg" 0)
194      @result{} "abcdefg"
195 @end group
196 @end example
198 @noindent
199 But we recommend @code{copy-sequence} for this purpose (@pxref{Sequence
200 Functions}).
202 If the characters copied from @var{string} have text properties, the
203 properties are copied into the new string also.  @xref{Text Properties}.
205 @code{substring} also accepts a vector for the first argument.
206 For example:
208 @example
209 (substring [a b (c) "d"] 1 3)
210      @result{} [b (c)]
211 @end example
213 A @code{wrong-type-argument} error is signaled if @var{start} is not
214 an integer or if @var{end} is neither an integer nor @code{nil}.  An
215 @code{args-out-of-range} error is signaled if @var{start} indicates a
216 character following @var{end}, or if either integer is out of range
217 for @var{string}.
219 Contrast this function with @code{buffer-substring} (@pxref{Buffer
220 Contents}), which returns a string containing a portion of the text in
221 the current buffer.  The beginning of a string is at index 0, but the
222 beginning of a buffer is at index 1.
223 @end defun
225 @defun substring-no-properties string &optional start end
226 This works like @code{substring} but discards all text properties from
227 the value.  Also, @var{start} may be omitted or @code{nil}, which is
228 equivalent to 0.  Thus, @w{@code{(substring-no-properties
229 @var{string})}} returns a copy of @var{string}, with all text
230 properties removed.
231 @end defun
233 @defun concat &rest sequences
234 @cindex copying strings
235 @cindex concatenating strings
236 This function returns a new string consisting of the characters in the
237 arguments passed to it (along with their text properties, if any).  The
238 arguments may be strings, lists of numbers, or vectors of numbers; they
239 are not themselves changed.  If @code{concat} receives no arguments, it
240 returns an empty string.
242 @example
243 (concat "abc" "-def")
244      @result{} "abc-def"
245 (concat "abc" (list 120 121) [122])
246      @result{} "abcxyz"
247 ;; @r{@code{nil} is an empty sequence.}
248 (concat "abc" nil "-def")
249      @result{} "abc-def"
250 (concat "The " "quick brown " "fox.")
251      @result{} "The quick brown fox."
252 (concat)
253      @result{} ""
254 @end example
256 @noindent
257 This function always constructs a new string that is not @code{eq} to
258 any existing string, except when the result is the empty string (to
259 save space, Emacs makes only one empty multibyte string).
261 For information about other concatenation functions, see the
262 description of @code{mapconcat} in @ref{Mapping Functions},
263 @code{vconcat} in @ref{Vector Functions}, and @code{append} in @ref{Building
264 Lists}.  For concatenating individual command-line arguments into a
265 string to be used as a shell command, see @ref{Shell Arguments,
266 combine-and-quote-strings}.
267 @end defun
269 @defun split-string string &optional separators omit-nulls
270 This function splits @var{string} into substrings based on the regular
271 expression @var{separators} (@pxref{Regular Expressions}).  Each match
272 for @var{separators} defines a splitting point; the substrings between
273 splitting points are made into a list, which is returned.
275 If @var{omit-nulls} is @code{nil} (or omitted), the result contains
276 null strings whenever there are two consecutive matches for
277 @var{separators}, or a match is adjacent to the beginning or end of
278 @var{string}.  If @var{omit-nulls} is @code{t}, these null strings are
279 omitted from the result.
281 If @var{separators} is @code{nil} (or omitted), the default is the
282 value of @code{split-string-default-separators}.
284 As a special case, when @var{separators} is @code{nil} (or omitted),
285 null strings are always omitted from the result.  Thus:
287 @example
288 (split-string "  two words ")
289      @result{} ("two" "words")
290 @end example
292 The result is not @code{("" "two" "words" "")}, which would rarely be
293 useful.  If you need such a result, use an explicit value for
294 @var{separators}:
296 @example
297 (split-string "  two words "
298               split-string-default-separators)
299      @result{} ("" "two" "words" "")
300 @end example
302 More examples:
304 @example
305 (split-string "Soup is good food" "o")
306      @result{} ("S" "up is g" "" "d f" "" "d")
307 (split-string "Soup is good food" "o" t)
308      @result{} ("S" "up is g" "d f" "d")
309 (split-string "Soup is good food" "o+")
310      @result{} ("S" "up is g" "d f" "d")
311 @end example
313 Empty matches do count, except that @code{split-string} will not look
314 for a final empty match when it already reached the end of the string
315 using a non-empty match or when @var{string} is empty:
317 @example
318 (split-string "aooob" "o*")
319      @result{} ("" "a" "" "b" "")
320 (split-string "ooaboo" "o*")
321      @result{} ("" "" "a" "b" "")
322 (split-string "" "")
323      @result{} ("")
324 @end example
326 However, when @var{separators} can match the empty string,
327 @var{omit-nulls} is usually @code{t}, so that the subtleties in the
328 three previous examples are rarely relevant:
330 @example
331 (split-string "Soup is good food" "o*" t)
332      @result{} ("S" "u" "p" " " "i" "s" " " "g" "d" " " "f" "d")
333 (split-string "Nice doggy!" "" t)
334      @result{} ("N" "i" "c" "e" " " "d" "o" "g" "g" "y" "!")
335 (split-string "" "" t)
336      @result{} nil
337 @end example
339 Somewhat odd, but predictable, behavior can occur for certain
340 ``non-greedy'' values of @var{separators} that can prefer empty
341 matches over non-empty matches.  Again, such values rarely occur in
342 practice:
344 @example
345 (split-string "ooo" "o*" t)
346      @result{} nil
347 (split-string "ooo" "\\|o+" t)
348      @result{} ("o" "o" "o")
349 @end example
351 If you need to split a string into a list of individual command-line
352 arguments suitable for @code{call-process} or @code{start-process},
353 see @ref{Shell Arguments, split-string-and-unquote}.
354 @end defun
356 @defvar split-string-default-separators
357 The default value of @var{separators} for @code{split-string}.  Its
358 usual value is @w{@code{"[ \f\t\n\r\v]+"}}.
359 @end defvar
361 @node Modifying Strings
362 @section Modifying Strings
364   The most basic way to alter the contents of an existing string is with
365 @code{aset} (@pxref{Array Functions}).  @code{(aset @var{string}
366 @var{idx} @var{char})} stores @var{char} into @var{string} at index
367 @var{idx}.  Each character occupies one or more bytes, and if @var{char}
368 needs a different number of bytes from the character already present at
369 that index, @code{aset} signals an error.
371   A more powerful function is @code{store-substring}:
373 @defun store-substring string idx obj
374 This function alters part of the contents of the string @var{string}, by
375 storing @var{obj} starting at index @var{idx}.  The argument @var{obj}
376 may be either a character or a (smaller) string.
378 Since it is impossible to change the length of an existing string, it is
379 an error if @var{obj} doesn't fit within @var{string}'s actual length,
380 or if any new character requires a different number of bytes from the
381 character currently present at that point in @var{string}.
382 @end defun
384   To clear out a string that contained a password, use
385 @code{clear-string}:
387 @defun clear-string string
388 This makes @var{string} a unibyte string and clears its contents to
389 zeros.  It may also change @var{string}'s length.
390 @end defun
392 @need 2000
393 @node Text Comparison
394 @section Comparison of Characters and Strings
395 @cindex string equality
397 @defun char-equal character1 character2
398 This function returns @code{t} if the arguments represent the same
399 character, @code{nil} otherwise.  This function ignores differences
400 in case if @code{case-fold-search} is non-@code{nil}.
402 @example
403 (char-equal ?x ?x)
404      @result{} t
405 (let ((case-fold-search nil))
406   (char-equal ?x ?X))
407      @result{} nil
408 @end example
409 @end defun
411 @defun string= string1 string2
412 This function returns @code{t} if the characters of the two strings
413 match exactly.  Symbols are also allowed as arguments, in which case
414 their print names are used.
415 Case is always significant, regardless of @code{case-fold-search}.
417 @example
418 (string= "abc" "abc")
419      @result{} t
420 (string= "abc" "ABC")
421      @result{} nil
422 (string= "ab" "ABC")
423      @result{} nil
424 @end example
426 The function @code{string=} ignores the text properties of the two
427 strings.  When @code{equal} (@pxref{Equality Predicates}) compares two
428 strings, it uses @code{string=}.
430 For technical reasons, a unibyte and a multibyte string are
431 @code{equal} if and only if they contain the same sequence of
432 character codes and all these codes are either in the range 0 through
433 127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}).
434 However, when a unibyte string is converted to a multibyte string, all
435 characters with codes in the range 160 through 255 are converted to
436 characters with higher codes, whereas @acronym{ASCII} characters
437 remain unchanged.  Thus, a unibyte string and its conversion to
438 multibyte are only @code{equal} if the string is all @acronym{ASCII}.
439 Character codes 160 through 255 are not entirely proper in multibyte
440 text, even though they can occur.  As a consequence, the situation
441 where a unibyte and a multibyte string are @code{equal} without both
442 being all @acronym{ASCII} is a technical oddity that very few Emacs
443 Lisp programmers ever get confronted with.  @xref{Text
444 Representations}.
445 @end defun
447 @defun string-equal string1 string2
448 @code{string-equal} is another name for @code{string=}.
449 @end defun
451 @cindex lexical comparison
452 @defun string< string1 string2
453 @c (findex string< causes problems for permuted index!!)
454 This function compares two strings a character at a time.  It
455 scans both the strings at the same time to find the first pair of corresponding
456 characters that do not match.  If the lesser character of these two is
457 the character from @var{string1}, then @var{string1} is less, and this
458 function returns @code{t}.  If the lesser character is the one from
459 @var{string2}, then @var{string1} is greater, and this function returns
460 @code{nil}.  If the two strings match entirely, the value is @code{nil}.
462 Pairs of characters are compared according to their character codes.
463 Keep in mind that lower case letters have higher numeric values in the
464 @acronym{ASCII} character set than their upper case counterparts; digits and
465 many punctuation characters have a lower numeric value than upper case
466 letters.  An @acronym{ASCII} character is less than any non-@acronym{ASCII}
467 character; a unibyte non-@acronym{ASCII} character is always less than any
468 multibyte non-@acronym{ASCII} character (@pxref{Text Representations}).
470 @example
471 @group
472 (string< "abc" "abd")
473      @result{} t
474 (string< "abd" "abc")
475      @result{} nil
476 (string< "123" "abc")
477      @result{} t
478 @end group
479 @end example
481 When the strings have different lengths, and they match up to the
482 length of @var{string1}, then the result is @code{t}.  If they match up
483 to the length of @var{string2}, the result is @code{nil}.  A string of
484 no characters is less than any other string.
486 @example
487 @group
488 (string< "" "abc")
489      @result{} t
490 (string< "ab" "abc")
491      @result{} t
492 (string< "abc" "")
493      @result{} nil
494 (string< "abc" "ab")
495      @result{} nil
496 (string< "" "")
497      @result{} nil
498 @end group
499 @end example
501 Symbols are also allowed as arguments, in which case their print names
502 are used.
503 @end defun
505 @defun string-lessp string1 string2
506 @code{string-lessp} is another name for @code{string<}.
507 @end defun
509 @defun compare-strings string1 start1 end1 string2 start2 end2 &optional ignore-case
510 This function compares the specified part of @var{string1} with the
511 specified part of @var{string2}.  The specified part of @var{string1}
512 runs from index @var{start1} up to index @var{end1} (@code{nil} means
513 the end of the string).  The specified part of @var{string2} runs from
514 index @var{start2} up to index @var{end2} (@code{nil} means the end of
515 the string).
517 The strings are both converted to multibyte for the comparison
518 (@pxref{Text Representations}) so that a unibyte string and its
519 conversion to multibyte are always regarded as equal.  If
520 @var{ignore-case} is non-@code{nil}, then case is ignored, so that
521 upper case letters can be equal to lower case letters.
523 If the specified portions of the two strings match, the value is
524 @code{t}.  Otherwise, the value is an integer which indicates how many
525 leading characters agree, and which string is less.  Its absolute value
526 is one plus the number of characters that agree at the beginning of the
527 two strings.  The sign is negative if @var{string1} (or its specified
528 portion) is less.
529 @end defun
531 @defun assoc-string key alist &optional case-fold
532 This function works like @code{assoc}, except that @var{key} must be a
533 string or symbol, and comparison is done using @code{compare-strings}.
534 Symbols are converted to strings before testing.
535 If @var{case-fold} is non-@code{nil}, it ignores case differences.
536 Unlike @code{assoc}, this function can also match elements of the alist
537 that are strings or symbols rather than conses.  In particular, @var{alist} can
538 be a list of strings or symbols rather than an actual alist.
539 @xref{Association Lists}.
540 @end defun
542   See also the function @code{compare-buffer-substrings} in
543 @ref{Comparing Text}, for a way to compare text in buffers.  The
544 function @code{string-match}, which matches a regular expression
545 against a string, can be used for a kind of string comparison; see
546 @ref{Regexp Search}.
548 @node String Conversion
549 @comment  node-name,  next,  previous,  up
550 @section Conversion of Characters and Strings
551 @cindex conversion of strings
553   This section describes functions for converting between characters,
554 strings and integers.  @code{format} (@pxref{Formatting Strings}) and
555 @code{prin1-to-string} (@pxref{Output Functions}) can also convert
556 Lisp objects into strings.  @code{read-from-string} (@pxref{Input
557 Functions}) can ``convert'' a string representation of a Lisp object
558 into an object.  The functions @code{string-make-multibyte} and
559 @code{string-make-unibyte} convert the text representation of a string
560 (@pxref{Converting Representations}).
562   @xref{Documentation}, for functions that produce textual descriptions
563 of text characters and general input events
564 (@code{single-key-description} and @code{text-char-description}).  These
565 are used primarily for making help messages.
567 @defun number-to-string number
568 @cindex integer to string
569 @cindex integer to decimal
570 This function returns a string consisting of the printed base-ten
571 representation of @var{number}, which may be an integer or a floating
572 point number.  The returned value starts with a minus sign if the argument is
573 negative.
575 @example
576 (number-to-string 256)
577      @result{} "256"
578 @group
579 (number-to-string -23)
580      @result{} "-23"
581 @end group
582 (number-to-string -23.5)
583      @result{} "-23.5"
584 @end example
586 @cindex int-to-string
587 @code{int-to-string} is a semi-obsolete alias for this function.
589 See also the function @code{format} in @ref{Formatting Strings}.
590 @end defun
592 @defun string-to-number string &optional base
593 @cindex string to number
594 This function returns the numeric value of the characters in
595 @var{string}.  If @var{base} is non-@code{nil}, it must be an integer
596 between 2 and 16 (inclusive), and integers are converted in that base.
597 If @var{base} is @code{nil}, then base ten is used.  Floating point
598 conversion only works in base ten; we have not implemented other
599 radices for floating point numbers, because that would be much more
600 work and does not seem useful.  If @var{string} looks like an integer
601 but its value is too large to fit into a Lisp integer,
602 @code{string-to-number} returns a floating point result.
604 The parsing skips spaces and tabs at the beginning of @var{string},
605 then reads as much of @var{string} as it can interpret as a number in
606 the given base.  (On some systems it ignores other whitespace at the
607 beginning, not just spaces and tabs.)  If the first character after
608 the ignored whitespace is neither a digit in the given base, nor a
609 plus or minus sign, nor the leading dot of a floating point number,
610 this function returns 0.
612 @example
613 (string-to-number "256")
614      @result{} 256
615 (string-to-number "25 is a perfect square.")
616      @result{} 25
617 (string-to-number "X256")
618      @result{} 0
619 (string-to-number "-4.5")
620      @result{} -4.5
621 (string-to-number "1e5")
622      @result{} 100000.0
623 @end example
625 @findex string-to-int
626 @code{string-to-int} is an obsolete alias for this function.
627 @end defun
629 @defun char-to-string character
630 @cindex character to string
631 This function returns a new string containing one character,
632 @var{character}.  This function is semi-obsolete because the function
633 @code{string} is more general.  @xref{Creating Strings}.
634 @end defun
636 @defun string-to-char string
637   This function returns the first character in @var{string}.  This
638 mostly identical to @code{(aref string 0)}, except that it returns 0
639 if the string is empty.  (The value is also 0 when the first character
640 of @var{string} is the null character, @acronym{ASCII} code 0.)  This
641 function may be eliminated in the future if it does not seem useful
642 enough to retain.
643 @end defun
645   Here are some other functions that can convert to or from a string:
647 @table @code
648 @item concat
649 This function converts a vector or a list into a string.
650 @xref{Creating Strings}.
652 @item vconcat
653 This function converts a string into a vector.  @xref{Vector
654 Functions}.
656 @item append
657 This function converts a string into a list.  @xref{Building Lists}.
659 @item byte-to-string
660 This function converts a byte of character data into a unibyte string.
661 @xref{Converting Representations}.
662 @end table
664 @node Formatting Strings
665 @comment  node-name,  next,  previous,  up
666 @section Formatting Strings
667 @cindex formatting strings
668 @cindex strings, formatting them
670   @dfn{Formatting} means constructing a string by substituting
671 computed values at various places in a constant string.  This constant
672 string controls how the other values are printed, as well as where
673 they appear; it is called a @dfn{format string}.
675   Formatting is often useful for computing messages to be displayed.  In
676 fact, the functions @code{message} and @code{error} provide the same
677 formatting feature described here; they differ from @code{format} only
678 in how they use the result of formatting.
680 @defun format string &rest objects
681 This function returns a new string that is made by copying
682 @var{string} and then replacing any format specification
683 in the copy with encodings of the corresponding @var{objects}.  The
684 arguments @var{objects} are the computed values to be formatted.
686 The characters in @var{string}, other than the format specifications,
687 are copied directly into the output, including their text properties,
688 if any.
689 @end defun
691 @cindex @samp{%} in format
692 @cindex format specification
693   A format specification is a sequence of characters beginning with a
694 @samp{%}.  Thus, if there is a @samp{%d} in @var{string}, the
695 @code{format} function replaces it with the printed representation of
696 one of the values to be formatted (one of the arguments @var{objects}).
697 For example:
699 @example
700 @group
701 (format "The value of fill-column is %d." fill-column)
702      @result{} "The value of fill-column is 72."
703 @end group
704 @end example
706   Since @code{format} interprets @samp{%} characters as format
707 specifications, you should @emph{never} pass an arbitrary string as
708 the first argument.  This is particularly true when the string is
709 generated by some Lisp code.  Unless the string is @emph{known} to
710 never include any @samp{%} characters, pass @code{"%s"}, described
711 below, as the first argument, and the string as the second, like this:
713 @example
714   (format "%s" @var{arbitrary-string})
715 @end example
717   If @var{string} contains more than one format specification, the
718 format specifications correspond to successive values from
719 @var{objects}.  Thus, the first format specification in @var{string}
720 uses the first such value, the second format specification uses the
721 second such value, and so on.  Any extra format specifications (those
722 for which there are no corresponding values) cause an error.  Any
723 extra values to be formatted are ignored.
725   Certain format specifications require values of particular types.  If
726 you supply a value that doesn't fit the requirements, an error is
727 signaled.
729   Here is a table of valid format specifications:
731 @table @samp
732 @item %s
733 Replace the specification with the printed representation of the object,
734 made without quoting (that is, using @code{princ}, not
735 @code{prin1}---@pxref{Output Functions}).  Thus, strings are represented
736 by their contents alone, with no @samp{"} characters, and symbols appear
737 without @samp{\} characters.
739 If the object is a string, its text properties are
740 copied into the output.  The text properties of the @samp{%s} itself
741 are also copied, but those of the object take priority.
743 @item %S
744 Replace the specification with the printed representation of the object,
745 made with quoting (that is, using @code{prin1}---@pxref{Output
746 Functions}).  Thus, strings are enclosed in @samp{"} characters, and
747 @samp{\} characters appear where necessary before special characters.
749 @item %o
750 @cindex integer to octal
751 Replace the specification with the base-eight representation of an
752 integer.
754 @item %d
755 Replace the specification with the base-ten representation of an
756 integer.
758 @item %x
759 @itemx %X
760 @cindex integer to hexadecimal
761 Replace the specification with the base-sixteen representation of an
762 integer.  @samp{%x} uses lower case and @samp{%X} uses upper case.
764 @item %c
765 Replace the specification with the character which is the value given.
767 @item %e
768 Replace the specification with the exponential notation for a floating
769 point number.
771 @item %f
772 Replace the specification with the decimal-point notation for a floating
773 point number.
775 @item %g
776 Replace the specification with notation for a floating point number,
777 using either exponential notation or decimal-point notation, whichever
778 is shorter.
780 @item %%
781 Replace the specification with a single @samp{%}.  This format
782 specification is unusual in that it does not use a value.  For example,
783 @code{(format "%% %d" 30)} returns @code{"% 30"}.
784 @end table
786   Any other format character results in an @samp{Invalid format
787 operation} error.
789   Here are several examples:
791 @example
792 @group
793 (format "The name of this buffer is %s." (buffer-name))
794      @result{} "The name of this buffer is strings.texi."
796 (format "The buffer object prints as %s." (current-buffer))
797      @result{} "The buffer object prints as strings.texi."
799 (format "The octal value of %d is %o,
800          and the hex value is %x." 18 18 18)
801      @result{} "The octal value of 18 is 22,
802          and the hex value is 12."
803 @end group
804 @end example
806 @cindex field width
807 @cindex padding
808   A specification can have a @dfn{width}, which is a decimal number
809 between the @samp{%} and the specification character.  If the printed
810 representation of the object contains fewer characters than this
811 width, @code{format} extends it with padding.  The width specifier is
812 ignored for the @samp{%%} specification.  Any padding introduced by
813 the width specifier normally consists of spaces inserted on the left:
815 @example
816 (format "%5d is padded on the left with spaces" 123)
817      @result{} "  123 is padded on the left with spaces"
818 @end example
820 @noindent
821 If the width is too small, @code{format} does not truncate the
822 object's printed representation.  Thus, you can use a width to specify
823 a minimum spacing between columns with no risk of losing information.
824 In the following three examples, @samp{%7s} specifies a minimum width
825 of 7.  In the first case, the string inserted in place of @samp{%7s}
826 has only 3 letters, and needs 4 blank spaces as padding.  In the
827 second case, the string @code{"specification"} is 13 letters wide but
828 is not truncated.
830 @example
831 @group
832 (format "The word `%7s' actually has %d letters in it."
833         "foo" (length "foo"))
834      @result{} "The word `    foo' actually has 3 letters in it."
835 (format "The word `%7s' actually has %d letters in it."
836         "specification" (length "specification"))
837      @result{} "The word `specification' actually has 13 letters in it."
838 @end group
839 @end example
841 @cindex flags in format specifications
842   Immediately after the @samp{%} and before the optional width
843 specifier, you can also put certain @dfn{flag characters}.
845   The flag @samp{+} inserts a plus sign before a positive number, so
846 that it always has a sign.  A space character as flag inserts a space
847 before a positive number.  (Otherwise, positive numbers start with the
848 first digit.)  These flags are useful for ensuring that positive
849 numbers and negative numbers use the same number of columns.  They are
850 ignored except for @samp{%d}, @samp{%e}, @samp{%f}, @samp{%g}, and if
851 both flags are used, @samp{+} takes precedence.
853   The flag @samp{#} specifies an ``alternate form'' which depends on
854 the format in use.  For @samp{%o}, it ensures that the result begins
855 with a @samp{0}.  For @samp{%x} and @samp{%X}, it prefixes the result
856 with @samp{0x} or @samp{0X}.  For @samp{%e}, @samp{%f}, and @samp{%g},
857 the @samp{#} flag means include a decimal point even if the precision
858 is zero.
860   The flag @samp{-} causes the padding inserted by the width
861 specifier, if any, to be inserted on the right rather than the left.
862 The flag @samp{0} ensures that the padding consists of @samp{0}
863 characters instead of spaces, inserted on the left.  These flags are
864 ignored for specification characters for which they do not make sense:
865 @samp{%s}, @samp{%S} and @samp{%c} accept the @samp{0} flag, but still
866 pad with @emph{spaces} on the left.  If both @samp{-} and @samp{0} are
867 present and valid, @samp{-} takes precedence.
869 @example
870 @group
871 (format "%06d is padded on the left with zeros" 123)
872      @result{} "000123 is padded on the left with zeros"
874 (format "%-6d is padded on the right" 123)
875      @result{} "123    is padded on the right"
877 (format "The word `%-7s' actually has %d letters in it."
878         "foo" (length "foo"))
879      @result{} "The word `foo    ' actually has 3 letters in it."
880 @end group
881 @end example
883 @cindex precision in format specifications
884   All the specification characters allow an optional @dfn{precision}
885 before the character (after the width, if present).  The precision is
886 a decimal-point @samp{.} followed by a digit-string.  For the
887 floating-point specifications (@samp{%e}, @samp{%f}, @samp{%g}), the
888 precision specifies how many decimal places to show; if zero, the
889 decimal-point itself is also omitted.  For @samp{%s} and @samp{%S},
890 the precision truncates the string to the given width, so @samp{%.3s}
891 shows only the first three characters of the representation for
892 @var{object}.  Precision has no effect for other specification
893 characters.
895 @node Case Conversion
896 @comment node-name, next, previous, up
897 @section Case Conversion in Lisp
898 @cindex upper case
899 @cindex lower case
900 @cindex character case
901 @cindex case conversion in Lisp
903   The character case functions change the case of single characters or
904 of the contents of strings.  The functions normally convert only
905 alphabetic characters (the letters @samp{A} through @samp{Z} and
906 @samp{a} through @samp{z}, as well as non-@acronym{ASCII} letters); other
907 characters are not altered.  You can specify a different case
908 conversion mapping by specifying a case table (@pxref{Case Tables}).
910   These functions do not modify the strings that are passed to them as
911 arguments.
913   The examples below use the characters @samp{X} and @samp{x} which have
914 @acronym{ASCII} codes 88 and 120 respectively.
916 @defun downcase string-or-char
917 This function converts @var{string-or-char}, which should be either a
918 character or a string, to lower case.
920 When @var{string-or-char} is a string, this function returns a new
921 string in which each letter in the argument that is upper case is
922 converted to lower case.  When @var{string-or-char} is a character,
923 this function returns the corresponding lower case character (an
924 integer); if the original character is lower case, or is not a letter,
925 the return value is equal to the original character.
927 @example
928 (downcase "The cat in the hat")
929      @result{} "the cat in the hat"
931 (downcase ?X)
932      @result{} 120
933 @end example
934 @end defun
936 @defun upcase string-or-char
937 This function converts @var{string-or-char}, which should be either a
938 character or a string, to upper case.
940 When @var{string-or-char} is a string, this function returns a new
941 string in which each letter in the argument that is lower case is
942 converted to upper case.  When @var{string-or-char} is a character,
943 this function returns the corresponding upper case character (an
944 integer); if the original character is upper case, or is not a letter,
945 the return value is equal to the original character.
947 @example
948 (upcase "The cat in the hat")
949      @result{} "THE CAT IN THE HAT"
951 (upcase ?x)
952      @result{} 88
953 @end example
954 @end defun
956 @defun capitalize string-or-char
957 @cindex capitalization
958 This function capitalizes strings or characters.  If
959 @var{string-or-char} is a string, the function returns a new string
960 whose contents are a copy of @var{string-or-char} in which each word
961 has been capitalized.  This means that the first character of each
962 word is converted to upper case, and the rest are converted to lower
963 case.
965 The definition of a word is any sequence of consecutive characters that
966 are assigned to the word constituent syntax class in the current syntax
967 table (@pxref{Syntax Class Table}).
969 When @var{string-or-char} is a character, this function does the same
970 thing as @code{upcase}.
972 @example
973 @group
974 (capitalize "The cat in the hat")
975      @result{} "The Cat In The Hat"
976 @end group
978 @group
979 (capitalize "THE 77TH-HATTED CAT")
980      @result{} "The 77th-Hatted Cat"
981 @end group
983 @group
984 (capitalize ?x)
985      @result{} 88
986 @end group
987 @end example
988 @end defun
990 @defun upcase-initials string-or-char
991 If @var{string-or-char} is a string, this function capitalizes the
992 initials of the words in @var{string-or-char}, without altering any
993 letters other than the initials.  It returns a new string whose
994 contents are a copy of @var{string-or-char}, in which each word has
995 had its initial letter converted to upper case.
997 The definition of a word is any sequence of consecutive characters that
998 are assigned to the word constituent syntax class in the current syntax
999 table (@pxref{Syntax Class Table}).
1001 When the argument to @code{upcase-initials} is a character,
1002 @code{upcase-initials} has the same result as @code{upcase}.
1004 @example
1005 @group
1006 (upcase-initials "The CAT in the hAt")
1007      @result{} "The CAT In The HAt"
1008 @end group
1009 @end example
1010 @end defun
1012   @xref{Text Comparison}, for functions that compare strings; some of
1013 them ignore case differences, or can optionally ignore case differences.
1015 @node Case Tables
1016 @section The Case Table
1018   You can customize case conversion by installing a special @dfn{case
1019 table}.  A case table specifies the mapping between upper case and lower
1020 case letters.  It affects both the case conversion functions for Lisp
1021 objects (see the previous section) and those that apply to text in the
1022 buffer (@pxref{Case Changes}).  Each buffer has a case table; there is
1023 also a standard case table which is used to initialize the case table
1024 of new buffers.
1026   A case table is a char-table (@pxref{Char-Tables}) whose subtype is
1027 @code{case-table}.  This char-table maps each character into the
1028 corresponding lower case character.  It has three extra slots, which
1029 hold related tables:
1031 @table @var
1032 @item upcase
1033 The upcase table maps each character into the corresponding upper
1034 case character.
1035 @item canonicalize
1036 The canonicalize table maps all of a set of case-related characters
1037 into a particular member of that set.
1038 @item equivalences
1039 The equivalences table maps each one of a set of case-related characters
1040 into the next character in that set.
1041 @end table
1043   In simple cases, all you need to specify is the mapping to lower-case;
1044 the three related tables will be calculated automatically from that one.
1046   For some languages, upper and lower case letters are not in one-to-one
1047 correspondence.  There may be two different lower case letters with the
1048 same upper case equivalent.  In these cases, you need to specify the
1049 maps for both lower case and upper case.
1051   The extra table @var{canonicalize} maps each character to a canonical
1052 equivalent; any two characters that are related by case-conversion have
1053 the same canonical equivalent character.  For example, since @samp{a}
1054 and @samp{A} are related by case-conversion, they should have the same
1055 canonical equivalent character (which should be either @samp{a} for both
1056 of them, or @samp{A} for both of them).
1058   The extra table @var{equivalences} is a map that cyclically permutes
1059 each equivalence class (of characters with the same canonical
1060 equivalent).  (For ordinary @acronym{ASCII}, this would map @samp{a} into
1061 @samp{A} and @samp{A} into @samp{a}, and likewise for each set of
1062 equivalent characters.)
1064   When constructing a case table, you can provide @code{nil} for
1065 @var{canonicalize}; then Emacs fills in this slot from the lower case
1066 and upper case mappings.  You can also provide @code{nil} for
1067 @var{equivalences}; then Emacs fills in this slot from
1068 @var{canonicalize}.  In a case table that is actually in use, those
1069 components are non-@code{nil}.  Do not try to specify
1070 @var{equivalences} without also specifying @var{canonicalize}.
1072   Here are the functions for working with case tables:
1074 @defun case-table-p object
1075 This predicate returns non-@code{nil} if @var{object} is a valid case
1076 table.
1077 @end defun
1079 @defun set-standard-case-table table
1080 This function makes @var{table} the standard case table, so that it will
1081 be used in any buffers created subsequently.
1082 @end defun
1084 @defun standard-case-table
1085 This returns the standard case table.
1086 @end defun
1088 @defun current-case-table
1089 This function returns the current buffer's case table.
1090 @end defun
1092 @defun set-case-table table
1093 This sets the current buffer's case table to @var{table}.
1094 @end defun
1096 @defmac with-case-table table body@dots{}
1097 The @code{with-case-table} macro saves the current case table, makes
1098 @var{table} the current case table, evaluates the @var{body} forms,
1099 and finally restores the case table.  The return value is the value of
1100 the last form in @var{body}.  The case table is restored even in case
1101 of an abnormal exit via @code{throw} or error (@pxref{Nonlocal
1102 Exits}).
1103 @end defmac
1105   Some language environments modify the case conversions of
1106 @acronym{ASCII} characters; for example, in the Turkish language
1107 environment, the @acronym{ASCII} character @samp{I} is downcased into
1108 a Turkish ``dotless i''.  This can interfere with code that requires
1109 ordinary ASCII case conversion, such as implementations of
1110 @acronym{ASCII}-based network protocols.  In that case, use the
1111 @code{with-case-table} macro with the variable @var{ascii-case-table},
1112 which stores the unmodified case table for the @acronym{ASCII}
1113 character set.
1115 @defvar ascii-case-table
1116 The case table for the @acronym{ASCII} character set.  This should not be
1117 modified by any language environment settings.
1118 @end defvar
1120   The following three functions are convenient subroutines for packages
1121 that define non-@acronym{ASCII} character sets.  They modify the specified
1122 case table @var{case-table}; they also modify the standard syntax table.
1123 @xref{Syntax Tables}.  Normally you would use these functions to change
1124 the standard case table.
1126 @defun set-case-syntax-pair uc lc case-table
1127 This function specifies a pair of corresponding letters, one upper case
1128 and one lower case.
1129 @end defun
1131 @defun set-case-syntax-delims l r case-table
1132 This function makes characters @var{l} and @var{r} a matching pair of
1133 case-invariant delimiters.
1134 @end defun
1136 @defun set-case-syntax char syntax case-table
1137 This function makes @var{char} case-invariant, with syntax
1138 @var{syntax}.
1139 @end defun
1141 @deffn Command describe-buffer-case-table
1142 This command displays a description of the contents of the current
1143 buffer's case table.
1144 @end deffn
1146 @ignore
1147    arch-tag: 700b8e95-7aa5-4b52-9eb3-8f2e1ea152b4
1148 @end ignore