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 Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../../info/strings
7 @node Strings and Characters, Lists, Numbers, Top
8 @comment node-name, next, previous, up
9 @chapter Strings and Characters
11 @cindex character arrays
15 A string in Emacs Lisp is an array that contains an ordered sequence
16 of characters. Strings are used as names of symbols, buffers, and
17 files; to send messages to users; to hold text being copied between
18 buffers; and for many other purposes. Because strings are so important,
19 Emacs Lisp has many functions expressly for manipulating them. Emacs
20 Lisp programs use strings more often than individual characters.
22 @xref{Strings of Events}, for special considerations for strings of
23 keyboard character events.
26 * Basics: String Basics. Basic properties of strings and characters.
27 * Predicates for Strings:: Testing whether an object is a string or char.
28 * Creating Strings:: Functions to allocate new strings.
29 * Modifying Strings:: Altering the contents of an existing string.
30 * Text Comparison:: Comparing characters or strings.
31 * String Conversion:: Converting to and from characters and strings.
32 * Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}.
33 * Case Conversion:: Case conversion functions.
34 * Case Tables:: Customizing case conversion.
38 @section String and Character Basics
40 Characters are represented in Emacs Lisp as integers;
41 whether an integer is a character or not is determined only by how it is
42 used. Thus, strings really contain integers. @xref{Character Codes},
43 for details about character representation in Emacs.
45 The length of a string (like any array) is fixed, and cannot be
46 altered once the string exists. Strings in Lisp are @emph{not}
47 terminated by a distinguished character code. (By contrast, strings in
48 C are terminated by a character with @acronym{ASCII} code 0.)
50 Since strings are arrays, and therefore sequences as well, you can
51 operate on them with the general array and sequence functions.
52 (@xref{Sequences Arrays Vectors}.) For example, you can access or
53 change individual characters in a string using the functions @code{aref}
54 and @code{aset} (@pxref{Array Functions}).
56 There are two text representations for non-@acronym{ASCII} characters in
57 Emacs strings (and in buffers): unibyte and multibyte (@pxref{Text
58 Representations}). For most Lisp programming, you don't need to be
59 concerned with these two representations.
61 Sometimes key sequences are represented as unibyte strings. When a
62 unibyte string is a key sequence, string elements in the range 128 to
63 255 represent meta characters (which are large integers) rather than
64 character codes in the range 128 to 255. Strings cannot hold
65 characters that have the hyper, super or alt modifiers; they can hold
66 @acronym{ASCII} control characters, but no other control characters.
67 They do not distinguish case in @acronym{ASCII} control characters.
68 If you want to store such characters in a sequence, such as a key
69 sequence, you must use a vector instead of a string. @xref{Character
70 Type}, for more information about keyboard input characters.
72 Strings are useful for holding regular expressions. You can also
73 match regular expressions against strings with @code{string-match}
74 (@pxref{Regexp Search}). The functions @code{match-string}
75 (@pxref{Simple Match Data}) and @code{replace-match} (@pxref{Replacing
76 Match}) are useful for decomposing and modifying strings after
77 matching regular expressions against them.
79 Like a buffer, a string can contain text properties for the characters
80 in it, as well as the characters themselves. @xref{Text Properties}.
81 All the Lisp primitives that copy text from strings to buffers or other
82 strings also copy the properties of the characters being copied.
84 @xref{Text}, for information about functions that display strings or
85 copy them into buffers. @xref{Character Type}, and @ref{String Type},
86 for information about the syntax of characters and strings.
87 @xref{Non-ASCII Characters}, for functions to convert between text
88 representations and to encode and decode character codes.
90 @node Predicates for Strings
91 @section The Predicates for Strings
93 For more information about general sequence and array predicates,
94 see @ref{Sequences Arrays Vectors}, and @ref{Arrays}.
97 This function returns @code{t} if @var{object} is a string, @code{nil}
101 @defun string-or-null-p object
102 This function returns @code{t} if @var{object} is a string or
103 @code{nil}. It returns @code{nil} otherwise.
106 @defun char-or-string-p object
107 This function returns @code{t} if @var{object} is a string or a
108 character (i.e., an integer), @code{nil} otherwise.
111 @node Creating Strings
112 @section Creating Strings
114 The following functions create strings, either from scratch, or by
115 putting strings together, or by taking them apart.
117 @defun make-string count character
118 This function returns a string made up of @var{count} repetitions of
119 @var{character}. If @var{count} is negative, an error is signaled.
128 Other functions to compare with this one include @code{char-to-string}
129 (@pxref{String Conversion}), @code{make-vector} (@pxref{Vectors}), and
130 @code{make-list} (@pxref{Building Lists}).
133 @defun string &rest characters
134 This returns a string containing the characters @var{characters}.
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.
150 (substring "abcdefg" 0 3)
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:
167 (substring "abcdefg" -3 -1)
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
182 (substring "abcdefg" -3 nil)
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
193 (substring "abcdefg" 0)
199 But we recommend @code{copy-sequence} for this purpose (@pxref{Sequence
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.
209 (substring [a b (c) "d"] 1 3)
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
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.
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
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.
243 (concat "abc" "-def")
245 (concat "abc" (list 120 121) [122])
247 ;; @r{@code{nil} is an empty sequence.}
248 (concat "abc" nil "-def")
250 (concat "The " "quick brown " "fox.")
251 @result{} "The quick brown fox."
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}.
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:
288 (split-string " two words ")
289 @result{} ("two" "words")
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
297 (split-string " two words "
298 split-string-default-separators)
299 @result{} ("" "two" "words" "")
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")
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:
318 (split-string "aooob" "o*")
319 @result{} ("" "a" "" "b" "")
320 (split-string "ooaboo" "o*")
321 @result{} ("" "" "a" "b" "")
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:
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)
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
345 (split-string "ooo" "o*" t)
347 (split-string "ooo" "\\|o+" t)
348 @result{} ("o" "o" "o")
351 If you need to split a string that is a shell command, where
352 individual arguments could be quoted, see @ref{Shell Arguments,
353 split-string-and-unquote}.
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]+"}}.
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}.
384 To clear out a string that contained a password, use
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.
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}.
405 (let ((case-fold-search nil))
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}.
418 (string= "abc" "abc")
420 (string= "abc" "ABC")
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
447 @defun string-equal string1 string2
448 @code{string-equal} is another name for @code{string=}.
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}).
472 (string< "abc" "abd")
474 (string< "abd" "abc")
476 (string< "123" "abc")
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.
501 Symbols are also allowed as arguments, in which case their print names
505 @defun string-lessp string1 string2
506 @code{string-lessp} is another name for @code{string<}.
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
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
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}.
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
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 char-to-string character
568 @cindex character to string
569 This function returns a new string containing one character,
570 @var{character}. This function is semi-obsolete because the function
571 @code{string} is more general. @xref{Creating Strings}.
574 @defun string-to-char string
575 @cindex string to character
576 This function returns the first character in @var{string}. If the
577 string is empty, the function returns 0. The value is also 0 when the
578 first character of @var{string} is the null character, @acronym{ASCII} code
582 (string-to-char "ABC")
585 (string-to-char "xyz")
590 (string-to-char "\000")
595 This function may be eliminated in the future if it does not seem useful
599 @defun number-to-string number
600 @cindex integer to string
601 @cindex integer to decimal
602 This function returns a string consisting of the printed base-ten
603 representation of @var{number}, which may be an integer or a floating
604 point number. The returned value starts with a minus sign if the argument is
608 (number-to-string 256)
611 (number-to-string -23)
614 (number-to-string -23.5)
618 @cindex int-to-string
619 @code{int-to-string} is a semi-obsolete alias for this function.
621 See also the function @code{format} in @ref{Formatting Strings}.
624 @defun string-to-number string &optional base
625 @cindex string to number
626 This function returns the numeric value of the characters in
627 @var{string}. If @var{base} is non-@code{nil}, it must be an integer
628 between 2 and 16 (inclusive), and integers are converted in that base.
629 If @var{base} is @code{nil}, then base ten is used. Floating point
630 conversion only works in base ten; we have not implemented other
631 radices for floating point numbers, because that would be much more
632 work and does not seem useful. If @var{string} looks like an integer
633 but its value is too large to fit into a Lisp integer,
634 @code{string-to-number} returns a floating point result.
636 The parsing skips spaces and tabs at the beginning of @var{string},
637 then reads as much of @var{string} as it can interpret as a number in
638 the given base. (On some systems it ignores other whitespace at the
639 beginning, not just spaces and tabs.) If the first character after
640 the ignored whitespace is neither a digit in the given base, nor a
641 plus or minus sign, nor the leading dot of a floating point number,
642 this function returns 0.
645 (string-to-number "256")
647 (string-to-number "25 is a perfect square.")
649 (string-to-number "X256")
651 (string-to-number "-4.5")
653 (string-to-number "1e5")
657 @findex string-to-int
658 @code{string-to-int} is an obsolete alias for this function.
661 Here are some other functions that can convert to or from a string:
665 @code{concat} can convert a vector or a list into a string.
666 @xref{Creating Strings}.
669 @code{vconcat} can convert a string into a vector. @xref{Vector
673 @code{append} can convert a string into a list. @xref{Building Lists}.
676 @node Formatting Strings
677 @comment node-name, next, previous, up
678 @section Formatting Strings
679 @cindex formatting strings
680 @cindex strings, formatting them
682 @dfn{Formatting} means constructing a string by substituting
683 computed values at various places in a constant string. This constant
684 string controls how the other values are printed, as well as where
685 they appear; it is called a @dfn{format string}.
687 Formatting is often useful for computing messages to be displayed. In
688 fact, the functions @code{message} and @code{error} provide the same
689 formatting feature described here; they differ from @code{format} only
690 in how they use the result of formatting.
692 @defun format string &rest objects
693 This function returns a new string that is made by copying
694 @var{string} and then replacing any format specification
695 in the copy with encodings of the corresponding @var{objects}. The
696 arguments @var{objects} are the computed values to be formatted.
698 The characters in @var{string}, other than the format specifications,
699 are copied directly into the output, including their text properties,
703 @cindex @samp{%} in format
704 @cindex format specification
705 A format specification is a sequence of characters beginning with a
706 @samp{%}. Thus, if there is a @samp{%d} in @var{string}, the
707 @code{format} function replaces it with the printed representation of
708 one of the values to be formatted (one of the arguments @var{objects}).
713 (format "The value of fill-column is %d." fill-column)
714 @result{} "The value of fill-column is 72."
718 Since @code{format} interprets @samp{%} characters as format
719 specifications, you should @emph{never} pass an arbitrary string as
720 the first argument. This is particularly true when the string is
721 generated by some Lisp code. Unless the string is @emph{known} to
722 never include any @samp{%} characters, pass @code{"%s"}, described
723 below, as the first argument, and the string as the second, like this:
726 (format "%s" @var{arbitrary-string})
729 If @var{string} contains more than one format specification, the
730 format specifications correspond to successive values from
731 @var{objects}. Thus, the first format specification in @var{string}
732 uses the first such value, the second format specification uses the
733 second such value, and so on. Any extra format specifications (those
734 for which there are no corresponding values) cause an error. Any
735 extra values to be formatted are ignored.
737 Certain format specifications require values of particular types. If
738 you supply a value that doesn't fit the requirements, an error is
741 Here is a table of valid format specifications:
745 Replace the specification with the printed representation of the object,
746 made without quoting (that is, using @code{princ}, not
747 @code{prin1}---@pxref{Output Functions}). Thus, strings are represented
748 by their contents alone, with no @samp{"} characters, and symbols appear
749 without @samp{\} characters.
751 If the object is a string, its text properties are
752 copied into the output. The text properties of the @samp{%s} itself
753 are also copied, but those of the object take priority.
756 Replace the specification with the printed representation of the object,
757 made with quoting (that is, using @code{prin1}---@pxref{Output
758 Functions}). Thus, strings are enclosed in @samp{"} characters, and
759 @samp{\} characters appear where necessary before special characters.
762 @cindex integer to octal
763 Replace the specification with the base-eight representation of an
767 Replace the specification with the base-ten representation of an
772 @cindex integer to hexadecimal
773 Replace the specification with the base-sixteen representation of an
774 integer. @samp{%x} uses lower case and @samp{%X} uses upper case.
777 Replace the specification with the character which is the value given.
780 Replace the specification with the exponential notation for a floating
784 Replace the specification with the decimal-point notation for a floating
788 Replace the specification with notation for a floating point number,
789 using either exponential notation or decimal-point notation, whichever
793 Replace the specification with a single @samp{%}. This format
794 specification is unusual in that it does not use a value. For example,
795 @code{(format "%% %d" 30)} returns @code{"% 30"}.
798 Any other format character results in an @samp{Invalid format
801 Here are several examples:
805 (format "The name of this buffer is %s." (buffer-name))
806 @result{} "The name of this buffer is strings.texi."
808 (format "The buffer object prints as %s." (current-buffer))
809 @result{} "The buffer object prints as strings.texi."
811 (format "The octal value of %d is %o,
812 and the hex value is %x." 18 18 18)
813 @result{} "The octal value of 18 is 22,
814 and the hex value is 12."
820 A specification can have a @dfn{width}, which is a decimal number
821 between the @samp{%} and the specification character. If the printed
822 representation of the object contains fewer characters than this
823 width, @code{format} extends it with padding. The width specifier is
824 ignored for the @samp{%%} specification. Any padding introduced by
825 the width specifier normally consists of spaces inserted on the left:
828 (format "%5d is padded on the left with spaces" 123)
829 @result{} " 123 is padded on the left with spaces"
833 If the width is too small, @code{format} does not truncate the
834 object's printed representation. Thus, you can use a width to specify
835 a minimum spacing between columns with no risk of losing information.
836 In the following three examples, @samp{%7s} specifies a minimum width
837 of 7. In the first case, the string inserted in place of @samp{%7s}
838 has only 3 letters, and needs 4 blank spaces as padding. In the
839 second case, the string @code{"specification"} is 13 letters wide but
844 (format "The word `%7s' actually has %d letters in it."
845 "foo" (length "foo"))
846 @result{} "The word ` foo' actually has 3 letters in it."
847 (format "The word `%7s' actually has %d letters in it."
848 "specification" (length "specification"))
849 @result{} "The word `specification' actually has 13 letters in it."
853 @cindex flags in format specifications
854 Immediately after the @samp{%} and before the optional width
855 specifier, you can also put certain @dfn{flag characters}.
857 The flag @samp{+} inserts a plus sign before a positive number, so
858 that it always has a sign. A space character as flag inserts a space
859 before a positive number. (Otherwise, positive numbers start with the
860 first digit.) These flags are useful for ensuring that positive
861 numbers and negative numbers use the same number of columns. They are
862 ignored except for @samp{%d}, @samp{%e}, @samp{%f}, @samp{%g}, and if
863 both flags are used, @samp{+} takes precedence.
865 The flag @samp{#} specifies an ``alternate form'' which depends on
866 the format in use. For @samp{%o}, it ensures that the result begins
867 with a @samp{0}. For @samp{%x} and @samp{%X}, it prefixes the result
868 with @samp{0x} or @samp{0X}. For @samp{%e}, @samp{%f}, and @samp{%g},
869 the @samp{#} flag means include a decimal point even if the precision
872 The flag @samp{-} causes the padding inserted by the width
873 specifier, if any, to be inserted on the right rather than the left.
874 The flag @samp{0} ensures that the padding consists of @samp{0}
875 characters instead of spaces, inserted on the left. These flags are
876 ignored for specification characters for which they do not make sense:
877 @samp{%s}, @samp{%S} and @samp{%c} accept the @samp{0} flag, but still
878 pad with @emph{spaces} on the left. If both @samp{-} and @samp{0} are
879 present and valid, @samp{-} takes precedence.
883 (format "%06d is padded on the left with zeros" 123)
884 @result{} "000123 is padded on the left with zeros"
886 (format "%-6d is padded on the right" 123)
887 @result{} "123 is padded on the right"
889 (format "The word `%-7s' actually has %d letters in it."
890 "foo" (length "foo"))
891 @result{} "The word `foo ' actually has 3 letters in it."
895 @cindex precision in format specifications
896 All the specification characters allow an optional @dfn{precision}
897 before the character (after the width, if present). The precision is
898 a decimal-point @samp{.} followed by a digit-string. For the
899 floating-point specifications (@samp{%e}, @samp{%f}, @samp{%g}), the
900 precision specifies how many decimal places to show; if zero, the
901 decimal-point itself is also omitted. For @samp{%s} and @samp{%S},
902 the precision truncates the string to the given width, so @samp{%.3s}
903 shows only the first three characters of the representation for
904 @var{object}. Precision has no effect for other specification
907 @node Case Conversion
908 @comment node-name, next, previous, up
909 @section Case Conversion in Lisp
912 @cindex character case
913 @cindex case conversion in Lisp
915 The character case functions change the case of single characters or
916 of the contents of strings. The functions normally convert only
917 alphabetic characters (the letters @samp{A} through @samp{Z} and
918 @samp{a} through @samp{z}, as well as non-@acronym{ASCII} letters); other
919 characters are not altered. You can specify a different case
920 conversion mapping by specifying a case table (@pxref{Case Tables}).
922 These functions do not modify the strings that are passed to them as
925 The examples below use the characters @samp{X} and @samp{x} which have
926 @acronym{ASCII} codes 88 and 120 respectively.
928 @defun downcase string-or-char
929 This function converts @var{string-or-char}, which should be either a
930 character or a string, to lower case.
932 When @var{string-or-char} is a string, this function returns a new
933 string in which each letter in the argument that is upper case is
934 converted to lower case. When @var{string-or-char} is a character,
935 this function returns the corresponding lower case character (an
936 integer); if the original character is lower case, or is not a letter,
937 the return value is equal to the original character.
940 (downcase "The cat in the hat")
941 @result{} "the cat in the hat"
948 @defun upcase string-or-char
949 This function converts @var{string-or-char}, which should be either a
950 character or a string, to upper case.
952 When @var{string-or-char} is a string, this function returns a new
953 string in which each letter in the argument that is lower case is
954 converted to upper case. When @var{string-or-char} is a character,
955 this function returns the corresponding upper case character (an
956 integer); if the original character is upper case, or is not a letter,
957 the return value is equal to the original character.
960 (upcase "The cat in the hat")
961 @result{} "THE CAT IN THE HAT"
968 @defun capitalize string-or-char
969 @cindex capitalization
970 This function capitalizes strings or characters. If
971 @var{string-or-char} is a string, the function returns a new string
972 whose contents are a copy of @var{string-or-char} in which each word
973 has been capitalized. This means that the first character of each
974 word is converted to upper case, and the rest are converted to lower
977 The definition of a word is any sequence of consecutive characters that
978 are assigned to the word constituent syntax class in the current syntax
979 table (@pxref{Syntax Class Table}).
981 When @var{string-or-char} is a character, this function does the same
982 thing as @code{upcase}.
986 (capitalize "The cat in the hat")
987 @result{} "The Cat In The Hat"
991 (capitalize "THE 77TH-HATTED CAT")
992 @result{} "The 77th-Hatted Cat"
1002 @defun upcase-initials string-or-char
1003 If @var{string-or-char} is a string, this function capitalizes the
1004 initials of the words in @var{string-or-char}, without altering any
1005 letters other than the initials. It returns a new string whose
1006 contents are a copy of @var{string-or-char}, in which each word has
1007 had its initial letter converted to upper case.
1009 The definition of a word is any sequence of consecutive characters that
1010 are assigned to the word constituent syntax class in the current syntax
1011 table (@pxref{Syntax Class Table}).
1013 When the argument to @code{upcase-initials} is a character,
1014 @code{upcase-initials} has the same result as @code{upcase}.
1018 (upcase-initials "The CAT in the hAt")
1019 @result{} "The CAT In The HAt"
1024 @xref{Text Comparison}, for functions that compare strings; some of
1025 them ignore case differences, or can optionally ignore case differences.
1028 @section The Case Table
1030 You can customize case conversion by installing a special @dfn{case
1031 table}. A case table specifies the mapping between upper case and lower
1032 case letters. It affects both the case conversion functions for Lisp
1033 objects (see the previous section) and those that apply to text in the
1034 buffer (@pxref{Case Changes}). Each buffer has a case table; there is
1035 also a standard case table which is used to initialize the case table
1038 A case table is a char-table (@pxref{Char-Tables}) whose subtype is
1039 @code{case-table}. This char-table maps each character into the
1040 corresponding lower case character. It has three extra slots, which
1041 hold related tables:
1045 The upcase table maps each character into the corresponding upper
1048 The canonicalize table maps all of a set of case-related characters
1049 into a particular member of that set.
1051 The equivalences table maps each one of a set of case-related characters
1052 into the next character in that set.
1055 In simple cases, all you need to specify is the mapping to lower-case;
1056 the three related tables will be calculated automatically from that one.
1058 For some languages, upper and lower case letters are not in one-to-one
1059 correspondence. There may be two different lower case letters with the
1060 same upper case equivalent. In these cases, you need to specify the
1061 maps for both lower case and upper case.
1063 The extra table @var{canonicalize} maps each character to a canonical
1064 equivalent; any two characters that are related by case-conversion have
1065 the same canonical equivalent character. For example, since @samp{a}
1066 and @samp{A} are related by case-conversion, they should have the same
1067 canonical equivalent character (which should be either @samp{a} for both
1068 of them, or @samp{A} for both of them).
1070 The extra table @var{equivalences} is a map that cyclically permutes
1071 each equivalence class (of characters with the same canonical
1072 equivalent). (For ordinary @acronym{ASCII}, this would map @samp{a} into
1073 @samp{A} and @samp{A} into @samp{a}, and likewise for each set of
1074 equivalent characters.)
1076 When constructing a case table, you can provide @code{nil} for
1077 @var{canonicalize}; then Emacs fills in this slot from the lower case
1078 and upper case mappings. You can also provide @code{nil} for
1079 @var{equivalences}; then Emacs fills in this slot from
1080 @var{canonicalize}. In a case table that is actually in use, those
1081 components are non-@code{nil}. Do not try to specify
1082 @var{equivalences} without also specifying @var{canonicalize}.
1084 Here are the functions for working with case tables:
1086 @defun case-table-p object
1087 This predicate returns non-@code{nil} if @var{object} is a valid case
1091 @defun set-standard-case-table table
1092 This function makes @var{table} the standard case table, so that it will
1093 be used in any buffers created subsequently.
1096 @defun standard-case-table
1097 This returns the standard case table.
1100 @defun current-case-table
1101 This function returns the current buffer's case table.
1104 @defun set-case-table table
1105 This sets the current buffer's case table to @var{table}.
1108 @defmac with-case-table table body@dots{}
1109 The @code{with-case-table} macro saves the current case table, makes
1110 @var{table} the current case table, evaluates the @var{body} forms,
1111 and finally restores the case table. The return value is the value of
1112 the last form in @var{body}. The case table is restored even in case
1113 of an abnormal exit via @code{throw} or error (@pxref{Nonlocal
1117 Some language environments modify the case conversions of
1118 @acronym{ASCII} characters; for example, in the Turkish language
1119 environment, the @acronym{ASCII} character @samp{I} is downcased into
1120 a Turkish ``dotless i''. This can interfere with code that requires
1121 ordinary ASCII case conversion, such as implementations of
1122 @acronym{ASCII}-based network protocols. In that case, use the
1123 @code{with-case-table} macro with the variable @var{ascii-case-table},
1124 which stores the unmodified case table for the @acronym{ASCII}
1127 @defvar ascii-case-table
1128 The case table for the @acronym{ASCII} character set. This should not be
1129 modified by any language environment settings.
1132 The following three functions are convenient subroutines for packages
1133 that define non-@acronym{ASCII} character sets. They modify the specified
1134 case table @var{case-table}; they also modify the standard syntax table.
1135 @xref{Syntax Tables}. Normally you would use these functions to change
1136 the standard case table.
1138 @defun set-case-syntax-pair uc lc case-table
1139 This function specifies a pair of corresponding letters, one upper case
1143 @defun set-case-syntax-delims l r case-table
1144 This function makes characters @var{l} and @var{r} a matching pair of
1145 case-invariant delimiters.
1148 @defun set-case-syntax char syntax case-table
1149 This function makes @var{char} case-invariant, with syntax
1153 @deffn Command describe-buffer-case-table
1154 This command displays a description of the contents of the current
1155 buffer's case table.
1159 arch-tag: 700b8e95-7aa5-4b52-9eb3-8f2e1ea152b4