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