|
428
|
1 @c -*-texinfo-*-
|
|
|
2 @c This is part of the XEmacs Lisp Reference Manual.
|
|
444
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
|
|
428
|
4 @c See the file lispref.texi for copying conditions.
|
|
|
5 @setfilename ../../info/strings.info
|
|
|
6 @node Strings and Characters, Lists, Numbers, Top
|
|
|
7 @chapter Strings and Characters
|
|
|
8 @cindex strings
|
|
|
9 @cindex character arrays
|
|
|
10 @cindex characters
|
|
|
11 @cindex bytes
|
|
|
12
|
|
|
13 A string in XEmacs Lisp is an array that contains an ordered sequence
|
|
|
14 of characters. Strings are used as names of symbols, buffers, and
|
|
|
15 files, to send messages to users, to hold text being copied between
|
|
|
16 buffers, and for many other purposes. Because strings are so important,
|
|
|
17 XEmacs Lisp has many functions expressly for manipulating them. XEmacs
|
|
|
18 Lisp programs use strings more often than individual characters.
|
|
|
19
|
|
|
20 @menu
|
|
440
|
21 * String Basics:: Basic properties of strings and characters.
|
|
428
|
22 * Predicates for Strings:: Testing whether an object is a string or char.
|
|
|
23 * Creating Strings:: Functions to allocate new strings.
|
|
|
24 * Predicates for Characters:: Testing whether an object is a character.
|
|
|
25 * Character Codes:: Each character has an equivalent integer.
|
|
|
26 * Text Comparison:: Comparing characters or strings.
|
|
|
27 * String Conversion:: Converting characters or strings and vice versa.
|
|
|
28 * Modifying Strings:: Changing characters in a string.
|
|
|
29 * String Properties:: Additional information attached to strings.
|
|
|
30 * Formatting Strings:: @code{format}: XEmacs's analog of @code{printf}.
|
|
|
31 * Character Case:: Case conversion functions.
|
|
|
32 * Case Tables:: Customizing case conversion.
|
|
|
33 * Char Tables:: Mapping from characters to Lisp objects.
|
|
|
34 @end menu
|
|
|
35
|
|
|
36 @node String Basics
|
|
|
37 @section String and Character Basics
|
|
|
38
|
|
|
39 Strings in XEmacs Lisp are arrays that contain an ordered sequence of
|
|
|
40 characters. Characters are their own primitive object type in XEmacs
|
|
|
41 20. However, in XEmacs 19, characters are represented in XEmacs Lisp as
|
|
|
42 integers; whether an integer was intended as a character or not is
|
|
|
43 determined only by how it is used. @xref{Character Type}.
|
|
|
44
|
|
|
45 The length of a string (like any array) is fixed and independent of
|
|
|
46 the string contents, and cannot be altered. Strings in Lisp are
|
|
|
47 @emph{not} terminated by a distinguished character code. (By contrast,
|
|
|
48 strings in C are terminated by a character with @sc{ascii} code 0.)
|
|
|
49 This means that any character, including the null character (@sc{ascii}
|
|
|
50 code 0), is a valid element of a string.@refill
|
|
|
51
|
|
|
52 Since strings are considered arrays, you can operate on them with the
|
|
|
53 general array functions. (@xref{Sequences Arrays Vectors}.) For
|
|
|
54 example, you can access or change individual characters in a string
|
|
|
55 using the functions @code{aref} and @code{aset} (@pxref{Array
|
|
|
56 Functions}).
|
|
|
57
|
|
|
58 Strings use an efficient representation for storing the characters
|
|
|
59 in them, and thus take up much less memory than a vector of the same
|
|
|
60 length.
|
|
|
61
|
|
|
62 Sometimes you will see strings used to hold key sequences. This
|
|
|
63 exists for backward compatibility with Emacs 18, but should @emph{not}
|
|
|
64 be used in new code, since many key chords can't be represented at
|
|
|
65 all and others (in particular meta key chords) are confused with
|
|
|
66 accented characters.
|
|
|
67
|
|
|
68 @ignore @c Not accurate any more
|
|
|
69 Each character in a string is stored in a single byte. Therefore,
|
|
|
70 numbers not in the range 0 to 255 are truncated when stored into a
|
|
|
71 string. This means that a string takes up much less memory than a
|
|
|
72 vector of the same length.
|
|
|
73
|
|
|
74 Sometimes key sequences are represented as strings. When a string is
|
|
|
75 a key sequence, string elements in the range 128 to 255 represent meta
|
|
|
76 characters (which are extremely large integers) rather than keyboard
|
|
|
77 events in the range 128 to 255.
|
|
|
78
|
|
|
79 Strings cannot hold characters that have the hyper, super or alt
|
|
|
80 modifiers; they can hold @sc{ASCII} control characters, but no other
|
|
|
81 control characters. They do not distinguish case in @sc{ASCII} control
|
|
|
82 characters. @xref{Character Type}, for more information about
|
|
|
83 representation of meta and other modifiers for keyboard input
|
|
|
84 characters.
|
|
|
85 @end ignore
|
|
|
86
|
|
|
87 Strings are useful for holding regular expressions. You can also
|
|
|
88 match regular expressions against strings (@pxref{Regexp Search}). The
|
|
|
89 functions @code{match-string} (@pxref{Simple Match Data}) and
|
|
|
90 @code{replace-match} (@pxref{Replacing Match}) are useful for
|
|
|
91 decomposing and modifying strings based on regular expression matching.
|
|
|
92
|
|
|
93 Like a buffer, a string can contain extents in it. These extents are
|
|
|
94 created when a function such as @code{buffer-substring} is called on a
|
|
|
95 region with duplicable extents in it. When the string is inserted into
|
|
|
96 a buffer, the extents are inserted along with it. @xref{Duplicable
|
|
|
97 Extents}.
|
|
|
98
|
|
|
99 @xref{Text}, for information about functions that display strings or
|
|
|
100 copy them into buffers. @xref{Character Type}, and @ref{String Type},
|
|
|
101 for information about the syntax of characters and strings.
|
|
|
102
|
|
|
103 @node Predicates for Strings
|
|
|
104 @section The Predicates for Strings
|
|
|
105
|
|
|
106 For more information about general sequence and array predicates,
|
|
|
107 see @ref{Sequences Arrays Vectors}, and @ref{Arrays}.
|
|
|
108
|
|
|
109 @defun stringp object
|
|
|
110 This function returns @code{t} if @var{object} is a string, @code{nil}
|
|
|
111 otherwise.
|
|
|
112 @end defun
|
|
|
113
|
|
|
114 @defun char-or-string-p object
|
|
|
115 This function returns @code{t} if @var{object} is a string or a
|
|
|
116 character, @code{nil} otherwise.
|
|
|
117
|
|
|
118 In XEmacs addition, this function also returns @code{t} if @var{object}
|
|
|
119 is an integer that can be represented as a character. This is because
|
|
|
120 of compatibility with previous XEmacs and should not be depended on.
|
|
|
121 @end defun
|
|
|
122
|
|
|
123 @node Creating Strings
|
|
|
124 @section Creating Strings
|
|
|
125
|
|
|
126 The following functions create strings, either from scratch, or by
|
|
|
127 putting strings together, or by taking them apart.
|
|
|
128
|
|
|
129 @defun string &rest characters
|
|
|
130 This function returns a new string made up of @var{characters}.
|
|
|
131
|
|
|
132 @example
|
|
|
133 (string ?X ?E ?m ?a ?c ?s)
|
|
|
134 @result{} "XEmacs"
|
|
|
135 (string)
|
|
|
136 @result{} ""
|
|
|
137 @end example
|
|
|
138
|
|
|
139 Analogous functions operating on other data types include @code{list},
|
|
|
140 @code{cons} (@pxref{Building Lists}), @code{vector} (@pxref{Vectors})
|
|
444
|
141 and @code{bit-vector} (@pxref{Bit Vectors}). This function has not been
|
|
428
|
142 available in XEmacs prior to 21.0 and FSF Emacs prior to 20.3.
|
|
|
143 @end defun
|
|
|
144
|
|
444
|
145 @defun make-string length character
|
|
|
146 This function returns a new string consisting entirely of @var{length}
|
|
|
147 successive copies of @var{character}. @var{length} must be a
|
|
|
148 non-negative integer.
|
|
428
|
149
|
|
|
150 @example
|
|
|
151 (make-string 5 ?x)
|
|
|
152 @result{} "xxxxx"
|
|
|
153 (make-string 0 ?x)
|
|
|
154 @result{} ""
|
|
|
155 @end example
|
|
|
156
|
|
|
157 Other functions to compare with this one include @code{char-to-string}
|
|
|
158 (@pxref{String Conversion}), @code{make-vector} (@pxref{Vectors}), and
|
|
|
159 @code{make-list} (@pxref{Building Lists}).
|
|
|
160 @end defun
|
|
|
161
|
|
|
162 @defun substring string start &optional end
|
|
|
163 This function returns a new string which consists of those characters
|
|
|
164 from @var{string} in the range from (and including) the character at the
|
|
|
165 index @var{start} up to (but excluding) the character at the index
|
|
|
166 @var{end}. The first character is at index zero.
|
|
|
167
|
|
|
168 @example
|
|
|
169 @group
|
|
|
170 (substring "abcdefg" 0 3)
|
|
|
171 @result{} "abc"
|
|
|
172 @end group
|
|
|
173 @end example
|
|
|
174
|
|
|
175 @noindent
|
|
|
176 Here the index for @samp{a} is 0, the index for @samp{b} is 1, and the
|
|
|
177 index for @samp{c} is 2. Thus, three letters, @samp{abc}, are copied
|
|
|
178 from the string @code{"abcdefg"}. The index 3 marks the character
|
|
|
179 position up to which the substring is copied. The character whose index
|
|
|
180 is 3 is actually the fourth character in the string.
|
|
|
181
|
|
|
182 A negative number counts from the end of the string, so that @minus{}1
|
|
444
|
183 signifies the index of the last character of the string. For example:
|
|
428
|
184
|
|
|
185 @example
|
|
|
186 @group
|
|
|
187 (substring "abcdefg" -3 -1)
|
|
|
188 @result{} "ef"
|
|
|
189 @end group
|
|
|
190 @end example
|
|
|
191
|
|
|
192 @noindent
|
|
|
193 In this example, the index for @samp{e} is @minus{}3, the index for
|
|
|
194 @samp{f} is @minus{}2, and the index for @samp{g} is @minus{}1.
|
|
|
195 Therefore, @samp{e} and @samp{f} are included, and @samp{g} is excluded.
|
|
|
196
|
|
|
197 When @code{nil} is used as an index, it stands for the length of the
|
|
|
198 string. Thus,
|
|
|
199
|
|
|
200 @example
|
|
|
201 @group
|
|
|
202 (substring "abcdefg" -3 nil)
|
|
|
203 @result{} "efg"
|
|
|
204 @end group
|
|
|
205 @end example
|
|
|
206
|
|
|
207 Omitting the argument @var{end} is equivalent to specifying @code{nil}.
|
|
|
208 It follows that @code{(substring @var{string} 0)} returns a copy of all
|
|
|
209 of @var{string}.
|
|
|
210
|
|
|
211 @example
|
|
|
212 @group
|
|
|
213 (substring "abcdefg" 0)
|
|
|
214 @result{} "abcdefg"
|
|
|
215 @end group
|
|
|
216 @end example
|
|
|
217
|
|
|
218 @noindent
|
|
|
219 But we recommend @code{copy-sequence} for this purpose (@pxref{Sequence
|
|
|
220 Functions}).
|
|
|
221
|
|
|
222 If the characters copied from @var{string} have duplicable extents or
|
|
|
223 text properties, those are copied into the new string also.
|
|
|
224 @xref{Duplicable Extents}.
|
|
|
225
|
|
|
226 A @code{wrong-type-argument} error is signaled if either @var{start} or
|
|
|
227 @var{end} is not an integer or @code{nil}. An @code{args-out-of-range}
|
|
|
228 error is signaled if @var{start} indicates a character following
|
|
|
229 @var{end}, or if either integer is out of range for @var{string}.
|
|
|
230
|
|
|
231 Contrast this function with @code{buffer-substring} (@pxref{Buffer
|
|
|
232 Contents}), which returns a string containing a portion of the text in
|
|
|
233 the current buffer. The beginning of a string is at index 0, but the
|
|
|
234 beginning of a buffer is at index 1.
|
|
|
235 @end defun
|
|
|
236
|
|
|
237 @defun concat &rest sequences
|
|
|
238 @cindex copying strings
|
|
|
239 @cindex concatenating strings
|
|
|
240 This function returns a new string consisting of the characters in the
|
|
|
241 arguments passed to it (along with their text properties, if any). The
|
|
|
242 arguments may be strings, lists of numbers, or vectors of numbers; they
|
|
|
243 are not themselves changed. If @code{concat} receives no arguments, it
|
|
|
244 returns an empty string.
|
|
|
245
|
|
|
246 @example
|
|
|
247 (concat "abc" "-def")
|
|
|
248 @result{} "abc-def"
|
|
|
249 (concat "abc" (list 120 (+ 256 121)) [122])
|
|
|
250 @result{} "abcxyz"
|
|
|
251 ;; @r{@code{nil} is an empty sequence.}
|
|
|
252 (concat "abc" nil "-def")
|
|
|
253 @result{} "abc-def"
|
|
|
254 (concat "The " "quick brown " "fox.")
|
|
|
255 @result{} "The quick brown fox."
|
|
|
256 (concat)
|
|
|
257 @result{} ""
|
|
|
258 @end example
|
|
|
259
|
|
|
260 @noindent
|
|
|
261 The second example above shows how characters stored in strings are
|
|
|
262 taken modulo 256. In other words, each character in the string is
|
|
|
263 stored in one byte.
|
|
|
264
|
|
|
265 The @code{concat} function always constructs a new string that is
|
|
|
266 not @code{eq} to any existing string.
|
|
|
267
|
|
|
268 When an argument is an integer (not a sequence of integers), it is
|
|
|
269 converted to a string of digits making up the decimal printed
|
|
|
270 representation of the integer. @strong{Don't use this feature; we plan
|
|
|
271 to eliminate it. If you already use this feature, change your programs
|
|
|
272 now!} The proper way to convert an integer to a decimal number in this
|
|
|
273 way is with @code{format} (@pxref{Formatting Strings}) or
|
|
|
274 @code{number-to-string} (@pxref{String Conversion}).
|
|
|
275
|
|
|
276 @example
|
|
|
277 @group
|
|
|
278 (concat 137)
|
|
|
279 @result{} "137"
|
|
|
280 (concat 54 321)
|
|
|
281 @result{} "54321"
|
|
|
282 @end group
|
|
|
283 @end example
|
|
|
284
|
|
|
285 For information about other concatenation functions, see the description
|
|
|
286 of @code{mapconcat} in @ref{Mapping Functions}, @code{vconcat} in
|
|
|
287 @ref{Vectors}, @code{bvconcat} in @ref{Bit Vectors}, and @code{append}
|
|
|
288 in @ref{Building Lists}.
|
|
|
289 @end defun
|
|
|
290
|
|
1495
|
291 The function @code{split-string}, in @ref{Regexp Search}, generates a
|
|
|
292 list of strings by splitting a string on occurances of a regular
|
|
|
293 expression.
|
|
|
294
|
|
428
|
295 @node Predicates for Characters
|
|
|
296 @section The Predicates for Characters
|
|
|
297
|
|
|
298 @defun characterp object
|
|
|
299 This function returns @code{t} if @var{object} is a character.
|
|
|
300
|
|
|
301 Some functions that work on integers (e.g. the comparison functions
|
|
|
302 <, <=, =, /=, etc. and the arithmetic functions +, -, *, etc.)
|
|
|
303 accept characters and implicitly convert them into integers. In
|
|
|
304 general, functions that work on characters also accept char-ints and
|
|
|
305 implicitly convert them into characters. WARNING: Neither of these
|
|
|
306 behaviors is very desirable, and they are maintained for backward
|
|
|
307 compatibility with old E-Lisp programs that confounded characters and
|
|
|
308 integers willy-nilly. These behaviors may change in the future; therefore,
|
|
|
309 do not rely on them. Instead, convert the characters explicitly
|
|
|
310 using @code{char-int}.
|
|
|
311 @end defun
|
|
|
312
|
|
|
313 @defun integer-or-char-p object
|
|
|
314 This function returns @code{t} if @var{object} is an integer or character.
|
|
|
315 @end defun
|
|
|
316
|
|
|
317 @node Character Codes
|
|
|
318 @section Character Codes
|
|
|
319
|
|
444
|
320 @defun char-int character
|
|
428
|
321 This function converts a character into an equivalent integer.
|
|
|
322 The resulting integer will always be non-negative. The integers in
|
|
|
323 the range 0 - 255 map to characters as follows:
|
|
|
324
|
|
|
325 @table @asis
|
|
|
326 @item 0 - 31
|
|
|
327 Control set 0
|
|
|
328 @item 32 - 127
|
|
|
329 @sc{ascii}
|
|
|
330 @item 128 - 159
|
|
|
331 Control set 1
|
|
|
332 @item 160 - 255
|
|
|
333 Right half of ISO-8859-1
|
|
|
334 @end table
|
|
|
335
|
|
|
336 If support for @sc{mule} does not exist, these are the only valid
|
|
|
337 character values. When @sc{mule} support exists, the values assigned to
|
|
|
338 other characters may vary depending on the particular version of XEmacs,
|
|
|
339 the order in which character sets were loaded, etc., and you should not
|
|
|
340 depend on them.
|
|
|
341 @end defun
|
|
|
342
|
|
|
343 @defun int-char integer
|
|
|
344 This function converts an integer into the equivalent character. Not
|
|
|
345 all integers correspond to valid characters; use @code{char-int-p} to
|
|
|
346 determine whether this is the case. If the integer cannot be converted,
|
|
|
347 @code{nil} is returned.
|
|
|
348 @end defun
|
|
|
349
|
|
|
350 @defun char-int-p object
|
|
|
351 This function returns @code{t} if @var{object} is an integer that can be
|
|
|
352 converted into a character.
|
|
|
353 @end defun
|
|
|
354
|
|
|
355 @defun char-or-char-int-p object
|
|
|
356 This function returns @code{t} if @var{object} is a character or an
|
|
|
357 integer that can be converted into one.
|
|
|
358 @end defun
|
|
|
359
|
|
|
360 @need 2000
|
|
|
361 @node Text Comparison
|
|
|
362 @section Comparison of Characters and Strings
|
|
|
363 @cindex string equality
|
|
|
364
|
|
444
|
365 @defun char-equal character1 character2 &optional buffer
|
|
428
|
366 This function returns @code{t} if the arguments represent the same
|
|
|
367 character, @code{nil} otherwise. This function ignores differences
|
|
444
|
368 in case if the value of @code{case-fold-search} is non-@code{nil} in
|
|
|
369 @var{buffer}, which defaults to the current buffer.
|
|
428
|
370
|
|
|
371 @example
|
|
|
372 (char-equal ?x ?x)
|
|
|
373 @result{} t
|
|
|
374 (let ((case-fold-search t))
|
|
|
375 (char-equal ?x ?X))
|
|
|
376 @result{} t
|
|
|
377 (let ((case-fold-search nil))
|
|
|
378 (char-equal ?x ?X))
|
|
|
379 @result{} nil
|
|
|
380 @end example
|
|
|
381 @end defun
|
|
|
382
|
|
|
383 @defun char= character1 character2
|
|
|
384 This function returns @code{t} if the arguments represent the same
|
|
|
385 character, @code{nil} otherwise. Case is significant.
|
|
|
386
|
|
|
387 @example
|
|
|
388 (char= ?x ?x)
|
|
|
389 @result{} t
|
|
|
390 (char= ?x ?X)
|
|
|
391 @result{} nil
|
|
|
392 (let ((case-fold-search t))
|
|
|
393 (char-equal ?x ?X))
|
|
|
394 @result{} nil
|
|
|
395 (let ((case-fold-search nil))
|
|
|
396 (char-equal ?x ?X))
|
|
|
397 @result{} nil
|
|
|
398 @end example
|
|
|
399 @end defun
|
|
|
400
|
|
|
401 @defun string= string1 string2
|
|
|
402 This function returns @code{t} if the characters of the two strings
|
|
|
403 match exactly; case is significant.
|
|
|
404
|
|
|
405 @example
|
|
|
406 (string= "abc" "abc")
|
|
|
407 @result{} t
|
|
|
408 (string= "abc" "ABC")
|
|
|
409 @result{} nil
|
|
|
410 (string= "ab" "ABC")
|
|
|
411 @result{} nil
|
|
|
412 @end example
|
|
|
413
|
|
|
414 @ignore @c `equal' in XEmacs does not compare text properties
|
|
|
415 The function @code{string=} ignores the text properties of the
|
|
|
416 two strings. To compare strings in a way that compares their text
|
|
|
417 properties also, use @code{equal} (@pxref{Equality Predicates}).
|
|
|
418 @end ignore
|
|
|
419 @end defun
|
|
|
420
|
|
|
421 @defun string-equal string1 string2
|
|
|
422 @code{string-equal} is another name for @code{string=}.
|
|
|
423 @end defun
|
|
|
424
|
|
|
425 @cindex lexical comparison
|
|
|
426 @defun string< string1 string2
|
|
|
427 @c (findex string< causes problems for permuted index!!)
|
|
|
428 This function compares two strings a character at a time. First it
|
|
|
429 scans both the strings at once to find the first pair of corresponding
|
|
|
430 characters that do not match. If the lesser character of those two is
|
|
|
431 the character from @var{string1}, then @var{string1} is less, and this
|
|
|
432 function returns @code{t}. If the lesser character is the one from
|
|
|
433 @var{string2}, then @var{string1} is greater, and this function returns
|
|
|
434 @code{nil}. If the two strings match entirely, the value is @code{nil}.
|
|
|
435
|
|
|
436 Pairs of characters are compared by their @sc{ascii} codes. Keep in
|
|
|
437 mind that lower case letters have higher numeric values in the
|
|
|
438 @sc{ascii} character set than their upper case counterparts; numbers and
|
|
|
439 many punctuation characters have a lower numeric value than upper case
|
|
|
440 letters.
|
|
|
441
|
|
|
442 @example
|
|
|
443 @group
|
|
|
444 (string< "abc" "abd")
|
|
|
445 @result{} t
|
|
|
446 (string< "abd" "abc")
|
|
|
447 @result{} nil
|
|
|
448 (string< "123" "abc")
|
|
|
449 @result{} t
|
|
|
450 @end group
|
|
|
451 @end example
|
|
|
452
|
|
|
453 When the strings have different lengths, and they match up to the
|
|
|
454 length of @var{string1}, then the result is @code{t}. If they match up
|
|
|
455 to the length of @var{string2}, the result is @code{nil}. A string of
|
|
|
456 no characters is less than any other string.
|
|
|
457
|
|
|
458 @example
|
|
|
459 @group
|
|
|
460 (string< "" "abc")
|
|
|
461 @result{} t
|
|
|
462 (string< "ab" "abc")
|
|
|
463 @result{} t
|
|
|
464 (string< "abc" "")
|
|
|
465 @result{} nil
|
|
|
466 (string< "abc" "ab")
|
|
|
467 @result{} nil
|
|
|
468 (string< "" "")
|
|
444
|
469 @result{} nil
|
|
428
|
470 @end group
|
|
|
471 @end example
|
|
|
472 @end defun
|
|
|
473
|
|
|
474 @defun string-lessp string1 string2
|
|
|
475 @code{string-lessp} is another name for @code{string<}.
|
|
|
476 @end defun
|
|
|
477
|
|
|
478 See also @code{compare-buffer-substrings} in @ref{Comparing Text}, for
|
|
|
479 a way to compare text in buffers. The function @code{string-match},
|
|
|
480 which matches a regular expression against a string, can be used
|
|
|
481 for a kind of string comparison; see @ref{Regexp Search}.
|
|
|
482
|
|
|
483 @node String Conversion
|
|
|
484 @section Conversion of Characters and Strings
|
|
|
485 @cindex conversion of strings
|
|
|
486
|
|
|
487 This section describes functions for conversions between characters,
|
|
|
488 strings and integers. @code{format} and @code{prin1-to-string}
|
|
|
489 (@pxref{Output Functions}) can also convert Lisp objects into strings.
|
|
|
490 @code{read-from-string} (@pxref{Input Functions}) can ``convert'' a
|
|
|
491 string representation of a Lisp object into an object.
|
|
|
492
|
|
|
493 @xref{Documentation}, for functions that produce textual descriptions
|
|
|
494 of text characters and general input events
|
|
|
495 (@code{single-key-description} and @code{text-char-description}). These
|
|
|
496 functions are used primarily for making help messages.
|
|
|
497
|
|
|
498 @defun char-to-string character
|
|
|
499 @cindex character to string
|
|
|
500 This function returns a new string with a length of one character.
|
|
|
501 The value of @var{character}, modulo 256, is used to initialize the
|
|
|
502 element of the string.
|
|
|
503
|
|
|
504 This function is similar to @code{make-string} with an integer argument
|
|
|
505 of 1. (@xref{Creating Strings}.) This conversion can also be done with
|
|
|
506 @code{format} using the @samp{%c} format specification.
|
|
|
507 (@xref{Formatting Strings}.)
|
|
|
508
|
|
|
509 @example
|
|
|
510 (char-to-string ?x)
|
|
|
511 @result{} "x"
|
|
|
512 (char-to-string (+ 256 ?x))
|
|
|
513 @result{} "x"
|
|
|
514 (make-string 1 ?x)
|
|
|
515 @result{} "x"
|
|
|
516 @end example
|
|
|
517 @end defun
|
|
|
518
|
|
|
519 @defun string-to-char string
|
|
|
520 @cindex string to character
|
|
|
521 This function returns the first character in @var{string}. If the
|
|
|
522 string is empty, the function returns 0. (Under XEmacs 19, the value is
|
|
|
523 also 0 when the first character of @var{string} is the null character,
|
|
|
524 @sc{ascii} code 0.)
|
|
|
525
|
|
|
526 @example
|
|
|
527 (string-to-char "ABC")
|
|
|
528 @result{} ?A ;; @r{Under XEmacs 20.}
|
|
|
529 @result{} 65 ;; @r{Under XEmacs 19.}
|
|
|
530 (string-to-char "xyz")
|
|
|
531 @result{} ?x ;; @r{Under XEmacs 20.}
|
|
|
532 @result{} 120 ;; @r{Under XEmacs 19.}
|
|
|
533 (string-to-char "")
|
|
|
534 @result{} 0
|
|
|
535 (string-to-char "\000")
|
|
|
536 @result{} ?\^@ ;; @r{Under XEmacs 20.}
|
|
|
537 @result{} 0 ;; @r{Under XEmacs 20.}
|
|
|
538 @end example
|
|
|
539
|
|
|
540 This function may be eliminated in the future if it does not seem useful
|
|
|
541 enough to retain.
|
|
|
542 @end defun
|
|
|
543
|
|
|
544 @defun number-to-string number
|
|
|
545 @cindex integer to string
|
|
|
546 @cindex integer to decimal
|
|
|
547 This function returns a string consisting of the printed
|
|
|
548 representation of @var{number}, which may be an integer or a floating
|
|
|
549 point number. The value starts with a sign if the argument is
|
|
|
550 negative.
|
|
|
551
|
|
|
552 @example
|
|
|
553 (number-to-string 256)
|
|
|
554 @result{} "256"
|
|
|
555 (number-to-string -23)
|
|
|
556 @result{} "-23"
|
|
|
557 (number-to-string -23.5)
|
|
|
558 @result{} "-23.5"
|
|
|
559 @end example
|
|
|
560
|
|
|
561 @cindex int-to-string
|
|
|
562 @code{int-to-string} is a semi-obsolete alias for this function.
|
|
|
563
|
|
|
564 See also the function @code{format} in @ref{Formatting Strings}.
|
|
|
565 @end defun
|
|
|
566
|
|
|
567 @defun string-to-number string &optional base
|
|
|
568 @cindex string to number
|
|
444
|
569 This function returns the numeric value represented by @var{string},
|
|
|
570 read in @var{base}. It skips spaces and tabs at the beginning of
|
|
|
571 @var{string}, then reads as much of @var{string} as it can interpret as
|
|
|
572 a number. (On some systems it ignores other whitespace at the
|
|
|
573 beginning, not just spaces and tabs.) If the first character after the
|
|
|
574 ignored whitespace is not a digit or a minus sign, this function returns
|
|
|
575 0.
|
|
428
|
576
|
|
|
577 If @var{base} is not specified, it defaults to ten. With @var{base}
|
|
|
578 other than ten, only integers can be read.
|
|
|
579
|
|
|
580 @example
|
|
|
581 (string-to-number "256")
|
|
|
582 @result{} 256
|
|
|
583 (string-to-number "25 is a perfect square.")
|
|
|
584 @result{} 25
|
|
|
585 (string-to-number "X256")
|
|
|
586 @result{} 0
|
|
|
587 (string-to-number "-4.5")
|
|
|
588 @result{} -4.5
|
|
|
589 (string-to-number "ffff" 16)
|
|
|
590 @result{} 65535
|
|
|
591 @end example
|
|
|
592
|
|
|
593 @findex string-to-int
|
|
|
594 @code{string-to-int} is an obsolete alias for this function.
|
|
|
595 @end defun
|
|
|
596
|
|
|
597 @node Modifying Strings
|
|
|
598 @section Modifying Strings
|
|
|
599 @cindex strings, modifying
|
|
|
600
|
|
|
601 You can modify a string using the general array-modifying primitives.
|
|
|
602 @xref{Arrays}. The function @code{aset} modifies a single character;
|
|
|
603 the function @code{fillarray} sets all characters in the string to
|
|
|
604 a specified character.
|
|
|
605
|
|
|
606 Each string has a tick counter that starts out at zero (when the string
|
|
|
607 is created) and is incremented each time a change is made to that
|
|
|
608 string.
|
|
|
609
|
|
|
610 @defun string-modified-tick string
|
|
|
611 This function returns the tick counter for @samp{string}.
|
|
|
612 @end defun
|
|
|
613
|
|
|
614 @node String Properties
|
|
|
615 @section String Properties
|
|
|
616 @cindex string properties
|
|
|
617 @cindex properties of strings
|
|
|
618
|
|
442
|
619 Just as with symbols, extents, faces, and glyphs, you can attach
|
|
428
|
620 additional information to strings in the form of @dfn{string
|
|
|
621 properties}. These differ from text properties, which are logically
|
|
|
622 attached to particular characters in the string.
|
|
|
623
|
|
|
624 To attach a property to a string, use @code{put}. To retrieve a property
|
|
|
625 from a string, use @code{get}. You can also use @code{remprop} to remove
|
|
442
|
626 a property from a string and @code{object-plist} to retrieve a list of
|
|
428
|
627 all the properties in a string.
|
|
|
628
|
|
|
629 @node Formatting Strings
|
|
|
630 @section Formatting Strings
|
|
|
631 @cindex formatting strings
|
|
|
632 @cindex strings, formatting them
|
|
|
633
|
|
|
634 @dfn{Formatting} means constructing a string by substitution of
|
|
|
635 computed values at various places in a constant string. This string
|
|
|
636 controls how the other values are printed as well as where they appear;
|
|
|
637 it is called a @dfn{format string}.
|
|
|
638
|
|
|
639 Formatting is often useful for computing messages to be displayed. In
|
|
|
640 fact, the functions @code{message} and @code{error} provide the same
|
|
|
641 formatting feature described here; they differ from @code{format} only
|
|
|
642 in how they use the result of formatting.
|
|
|
643
|
|
|
644 @defun format string &rest objects
|
|
|
645 This function returns a new string that is made by copying
|
|
444
|
646 @var{string} and then replacing any format specification
|
|
428
|
647 in the copy with encodings of the corresponding @var{objects}. The
|
|
|
648 arguments @var{objects} are the computed values to be formatted.
|
|
|
649 @end defun
|
|
|
650
|
|
|
651 @cindex @samp{%} in format
|
|
|
652 @cindex format specification
|
|
|
653 A format specification is a sequence of characters beginning with a
|
|
|
654 @samp{%}. Thus, if there is a @samp{%d} in @var{string}, the
|
|
|
655 @code{format} function replaces it with the printed representation of
|
|
|
656 one of the values to be formatted (one of the arguments @var{objects}).
|
|
|
657 For example:
|
|
|
658
|
|
|
659 @example
|
|
|
660 @group
|
|
|
661 (format "The value of fill-column is %d." fill-column)
|
|
|
662 @result{} "The value of fill-column is 72."
|
|
|
663 @end group
|
|
|
664 @end example
|
|
|
665
|
|
|
666 If @var{string} contains more than one format specification, the
|
|
|
667 format specifications correspond with successive values from
|
|
|
668 @var{objects}. Thus, the first format specification in @var{string}
|
|
|
669 uses the first such value, the second format specification uses the
|
|
|
670 second such value, and so on. Any extra format specifications (those
|
|
|
671 for which there are no corresponding values) cause unpredictable
|
|
|
672 behavior. Any extra values to be formatted are ignored.
|
|
|
673
|
|
|
674 Certain format specifications require values of particular types.
|
|
|
675 However, no error is signaled if the value actually supplied fails to
|
|
|
676 have the expected type. Instead, the output is likely to be
|
|
|
677 meaningless.
|
|
|
678
|
|
|
679 Here is a table of valid format specifications:
|
|
|
680
|
|
|
681 @table @samp
|
|
|
682 @item %s
|
|
|
683 Replace the specification with the printed representation of the object,
|
|
|
684 made without quoting. Thus, strings are represented by their contents
|
|
|
685 alone, with no @samp{"} characters, and symbols appear without @samp{\}
|
|
|
686 characters. This is equivalent to printing the object with @code{princ}.
|
|
|
687
|
|
|
688 If there is no corresponding object, the empty string is used.
|
|
|
689
|
|
|
690 @item %S
|
|
|
691 Replace the specification with the printed representation of the object,
|
|
|
692 made with quoting. Thus, strings are enclosed in @samp{"} characters,
|
|
|
693 and @samp{\} characters appear where necessary before special characters.
|
|
|
694 This is equivalent to printing the object with @code{prin1}.
|
|
|
695
|
|
|
696 If there is no corresponding object, the empty string is used.
|
|
|
697
|
|
|
698 @item %o
|
|
|
699 @cindex integer to octal
|
|
|
700 Replace the specification with the base-eight representation of an
|
|
|
701 integer.
|
|
|
702
|
|
|
703 @item %d
|
|
|
704 @itemx %i
|
|
|
705 Replace the specification with the base-ten representation of an
|
|
|
706 integer.
|
|
|
707
|
|
|
708 @item %x
|
|
|
709 @cindex integer to hexadecimal
|
|
|
710 Replace the specification with the base-sixteen representation of an
|
|
|
711 integer, using lowercase letters.
|
|
|
712
|
|
|
713 @item %X
|
|
|
714 @cindex integer to hexadecimal
|
|
|
715 Replace the specification with the base-sixteen representation of an
|
|
|
716 integer, using uppercase letters.
|
|
|
717
|
|
|
718 @item %c
|
|
|
719 Replace the specification with the character which is the value given.
|
|
|
720
|
|
|
721 @item %e
|
|
|
722 Replace the specification with the exponential notation for a floating
|
|
|
723 point number (e.g. @samp{7.85200e+03}).
|
|
|
724
|
|
|
725 @item %f
|
|
|
726 Replace the specification with the decimal-point notation for a floating
|
|
|
727 point number.
|
|
|
728
|
|
|
729 @item %g
|
|
|
730 Replace the specification with notation for a floating point number,
|
|
|
731 using a ``pretty format''. Either exponential notation or decimal-point
|
|
|
732 notation will be used (usually whichever is shorter), and trailing
|
|
|
733 zeroes are removed from the fractional part.
|
|
|
734
|
|
|
735 @item %%
|
|
|
736 A single @samp{%} is placed in the string. This format specification is
|
|
|
737 unusual in that it does not use a value. For example, @code{(format "%%
|
|
|
738 %d" 30)} returns @code{"% 30"}.
|
|
|
739 @end table
|
|
|
740
|
|
|
741 Any other format character results in an @samp{Invalid format
|
|
|
742 operation} error.
|
|
|
743
|
|
|
744 Here are several examples:
|
|
|
745
|
|
|
746 @example
|
|
|
747 @group
|
|
|
748 (format "The name of this buffer is %s." (buffer-name))
|
|
|
749 @result{} "The name of this buffer is strings.texi."
|
|
|
750
|
|
|
751 (format "The buffer object prints as %s." (current-buffer))
|
|
|
752 @result{} "The buffer object prints as #<buffer strings.texi>."
|
|
|
753
|
|
444
|
754 (format "The octal value of %d is %o,
|
|
428
|
755 and the hex value is %x." 18 18 18)
|
|
444
|
756 @result{} "The octal value of 18 is 22,
|
|
428
|
757 and the hex value is 12."
|
|
|
758 @end group
|
|
|
759 @end example
|
|
|
760
|
|
|
761 There are many additional flags and specifications that can occur
|
|
|
762 between the @samp{%} and the format character, in the following order:
|
|
|
763
|
|
|
764 @enumerate
|
|
|
765 @item
|
|
|
766 An optional repositioning specification, which is a positive
|
|
|
767 integer followed by a @samp{$}.
|
|
|
768
|
|
|
769 @item
|
|
|
770 Zero or more of the optional flag characters @samp{-}, @samp{+},
|
|
|
771 @samp{ }, @samp{0}, and @samp{#}.
|
|
|
772
|
|
|
773 @item
|
|
|
774 An asterisk (@samp{*}, meaning that the field width is now assumed to
|
|
|
775 have been specified as an argument.
|
|
|
776
|
|
|
777 @item
|
|
|
778 An optional minimum field width.
|
|
|
779
|
|
|
780 @item
|
|
|
781 An optional precision, preceded by a @samp{.} character.
|
|
|
782 @end enumerate
|
|
|
783
|
|
|
784 @cindex repositioning format arguments
|
|
|
785 @cindex multilingual string formatting
|
|
|
786 A @dfn{repositioning} specification changes which argument to
|
|
|
787 @code{format} is used by the current and all following format
|
|
|
788 specifications. Normally the first specification uses the first
|
|
|
789 argument, the second specification uses the second argument, etc. Using
|
|
|
790 a repositioning specification, you can change this. By placing a number
|
|
444
|
791 @var{n} followed by a @samp{$} between the @samp{%} and the format
|
|
|
792 character, you cause the specification to use the @var{n}th argument.
|
|
|
793 The next specification will use the @var{n}+1'th argument, etc.
|
|
428
|
794
|
|
|
795 For example:
|
|
|
796
|
|
|
797 @example
|
|
|
798 @group
|
|
|
799 (format "Can't find file `%s' in directory `%s'."
|
|
|
800 "ignatius.c" "loyola/")
|
|
|
801 @result{} "Can't find file `ignatius.c' in directory `loyola/'."
|
|
|
802
|
|
|
803 (format "In directory `%2$s', the file `%1$s' was not found."
|
|
|
804 "ignatius.c" "loyola/")
|
|
|
805 @result{} "In directory `loyola/', the file `ignatius.c' was not found."
|
|
|
806
|
|
|
807 (format
|
|
|
808 "The numbers %d and %d are %1$x and %x in hex and %1$o and %o in octal."
|
|
|
809 37 12)
|
|
|
810 @result{} "The numbers 37 and 12 are 25 and c in hex and 45 and 14 in octal."
|
|
|
811 @end group
|
|
|
812 @end example
|
|
|
813
|
|
|
814 As you can see, this lets you reprocess arguments more than once or
|
|
|
815 reword a format specification (thereby moving the arguments around)
|
|
|
816 without having to actually reorder the arguments. This is especially
|
|
|
817 useful in translating messages from one language to another: Different
|
|
|
818 languages use different word orders, and this sometimes entails changing
|
|
|
819 the order of the arguments. By using repositioning specifications,
|
|
|
820 this can be accomplished without having to embed knowledge of particular
|
|
|
821 languages into the location in the program's code where the message is
|
|
|
822 displayed.
|
|
|
823
|
|
|
824 @cindex numeric prefix
|
|
|
825 @cindex field width
|
|
|
826 @cindex padding
|
|
|
827 All the specification characters allow an optional numeric prefix
|
|
|
828 between the @samp{%} and the character, and following any repositioning
|
|
|
829 specification or flag. The optional numeric prefix defines the minimum
|
|
|
830 width for the object. If the printed representation of the object
|
|
|
831 contains fewer characters than this, then it is padded. The padding is
|
|
|
832 normally on the left, but will be on the right if the @samp{-} flag
|
|
|
833 character is given. The padding character is normally a space, but if
|
|
|
834 the @samp{0} flag character is given, zeros are used for padding.
|
|
|
835
|
|
|
836 @example
|
|
|
837 (format "%06d is padded on the left with zeros" 123)
|
|
|
838 @result{} "000123 is padded on the left with zeros"
|
|
|
839
|
|
|
840 (format "%-6d is padded on the right" 123)
|
|
|
841 @result{} "123 is padded on the right"
|
|
|
842 @end example
|
|
|
843
|
|
|
844 @code{format} never truncates an object's printed representation, no
|
|
|
845 matter what width you specify. Thus, you can use a numeric prefix to
|
|
|
846 specify a minimum spacing between columns with no risk of losing
|
|
|
847 information.
|
|
|
848
|
|
|
849 In the following three examples, @samp{%7s} specifies a minimum width
|
|
|
850 of 7. In the first case, the string inserted in place of @samp{%7s} has
|
|
|
851 only 3 letters, so 4 blank spaces are inserted for padding. In the
|
|
|
852 second case, the string @code{"specification"} is 13 letters wide but is
|
|
|
853 not truncated. In the third case, the padding is on the right.
|
|
|
854
|
|
444
|
855 @smallexample
|
|
428
|
856 @group
|
|
|
857 (format "The word `%7s' actually has %d letters in it."
|
|
|
858 "foo" (length "foo"))
|
|
444
|
859 @result{} "The word ` foo' actually has 3 letters in it."
|
|
428
|
860 @end group
|
|
|
861
|
|
|
862 @group
|
|
|
863 (format "The word `%7s' actually has %d letters in it."
|
|
444
|
864 "specification" (length "specification"))
|
|
|
865 @result{} "The word `specification' actually has 13 letters in it."
|
|
428
|
866 @end group
|
|
|
867
|
|
|
868 @group
|
|
|
869 (format "The word `%-7s' actually has %d letters in it."
|
|
|
870 "foo" (length "foo"))
|
|
444
|
871 @result{} "The word `foo ' actually has 3 letters in it."
|
|
428
|
872 @end group
|
|
|
873 @end smallexample
|
|
|
874
|
|
|
875 @cindex format precision
|
|
|
876 @cindex precision of formatted numbers
|
|
|
877 After any minimum field width, a precision may be specified by
|
|
|
878 preceding it with a @samp{.} character. The precision specifies the
|
|
|
879 minimum number of digits to appear in @samp{%d}, @samp{%i}, @samp{%o},
|
|
|
880 @samp{%x}, and @samp{%X} conversions (the number is padded on the left
|
|
|
881 with zeroes as necessary); the number of digits printed after the
|
|
|
882 decimal point for @samp{%f}, @samp{%e}, and @samp{%E} conversions; the
|
|
|
883 number of significant digits printed in @samp{%g} and @samp{%G}
|
|
|
884 conversions; and the maximum number of non-padding characters printed in
|
|
|
885 @samp{%s} and @samp{%S} conversions. The default precision for
|
|
|
886 floating-point conversions is six.
|
|
|
887
|
|
|
888 The other flag characters have the following meanings:
|
|
|
889
|
|
|
890 @itemize @bullet
|
|
|
891 @item
|
|
|
892 The @samp{ } flag means prefix non-negative numbers with a space.
|
|
|
893
|
|
|
894 @item
|
|
|
895 The @samp{+} flag means prefix non-negative numbers with a plus sign.
|
|
|
896
|
|
|
897 @item
|
|
|
898 The @samp{#} flag means print numbers in an alternate, more verbose
|
|
|
899 format: octal numbers begin with zero; hex numbers begin with a
|
|
|
900 @samp{0x} or @samp{0X}; a decimal point is printed in @samp{%f},
|
|
|
901 @samp{%e}, and @samp{%E} conversions even if no numbers are printed
|
|
|
902 after it; and trailing zeroes are not omitted in @samp{%g} and @samp{%G}
|
|
|
903 conversions.
|
|
|
904 @end itemize
|
|
|
905
|
|
|
906 @node Character Case
|
|
|
907 @section Character Case
|
|
444
|
908 @cindex upper case
|
|
|
909 @cindex lower case
|
|
|
910 @cindex character case
|
|
428
|
911
|
|
|
912 The character case functions change the case of single characters or
|
|
|
913 of the contents of strings. The functions convert only alphabetic
|
|
|
914 characters (the letters @samp{A} through @samp{Z} and @samp{a} through
|
|
|
915 @samp{z}); other characters are not altered. The functions do not
|
|
|
916 modify the strings that are passed to them as arguments.
|
|
|
917
|
|
|
918 The examples below use the characters @samp{X} and @samp{x} which have
|
|
|
919 @sc{ascii} codes 88 and 120 respectively.
|
|
|
920
|
|
444
|
921 @defun downcase string-or-char &optional buffer
|
|
428
|
922 This function converts a character or a string to lower case.
|
|
|
923
|
|
|
924 When the argument to @code{downcase} is a string, the function creates
|
|
|
925 and returns a new string in which each letter in the argument that is
|
|
|
926 upper case is converted to lower case. When the argument to
|
|
|
927 @code{downcase} is a character, @code{downcase} returns the
|
|
|
928 corresponding lower case character. (This value is actually an integer
|
|
|
929 under XEmacs 19.) If the original character is lower case, or is not a
|
|
|
930 letter, then the value equals the original character.
|
|
|
931
|
|
444
|
932 Optional second arg @var{buffer} specifies which buffer's case tables to
|
|
|
933 use, and defaults to the current buffer.
|
|
|
934
|
|
428
|
935 @example
|
|
|
936 (downcase "The cat in the hat")
|
|
|
937 @result{} "the cat in the hat"
|
|
|
938
|
|
|
939 (downcase ?X)
|
|
|
940 @result{} ?x ;; @r{Under XEmacs 20.}
|
|
|
941 @result{} 120 ;; @r{Under XEmacs 19.}
|
|
|
942
|
|
|
943 @end example
|
|
|
944 @end defun
|
|
|
945
|
|
444
|
946 @defun upcase string-or-char &optional buffer
|
|
428
|
947 This function converts a character or a string to upper case.
|
|
|
948
|
|
|
949 When the argument to @code{upcase} is a string, the function creates
|
|
|
950 and returns a new string in which each letter in the argument that is
|
|
|
951 lower case is converted to upper case.
|
|
|
952
|
|
|
953 When the argument to @code{upcase} is a character, @code{upcase} returns
|
|
|
954 the corresponding upper case character. (This value is actually an
|
|
|
955 integer under XEmacs 19.) If the original character is upper case, or
|
|
|
956 is not a letter, then the value equals the original character.
|
|
|
957
|
|
444
|
958 Optional second arg @var{buffer} specifies which buffer's case tables to
|
|
|
959 use, and defaults to the current buffer.
|
|
|
960
|
|
428
|
961 @example
|
|
|
962 (upcase "The cat in the hat")
|
|
|
963 @result{} "THE CAT IN THE HAT"
|
|
|
964
|
|
|
965 (upcase ?x)
|
|
|
966 @result{} ?X ;; @r{Under XEmacs 20.}
|
|
|
967 @result{} 88 ;; @r{Under XEmacs 19.}
|
|
|
968 @end example
|
|
|
969 @end defun
|
|
|
970
|
|
444
|
971 @defun capitalize string-or-char &optional buffer
|
|
428
|
972 @cindex capitalization
|
|
|
973 This function capitalizes strings or characters. If
|
|
|
974 @var{string-or-char} is a string, the function creates and returns a new
|
|
|
975 string, whose contents are a copy of @var{string-or-char} in which each
|
|
|
976 word has been capitalized. This means that the first character of each
|
|
|
977 word is converted to upper case, and the rest are converted to lower
|
|
|
978 case.
|
|
|
979
|
|
|
980 The definition of a word is any sequence of consecutive characters that
|
|
|
981 are assigned to the word constituent syntax class in the current syntax
|
|
|
982 table (@pxref{Syntax Class Table}).
|
|
|
983
|
|
|
984 When the argument to @code{capitalize} is a character, @code{capitalize}
|
|
|
985 has the same result as @code{upcase}.
|
|
|
986
|
|
444
|
987 Optional second arg @var{buffer} specifies which buffer's case tables to
|
|
|
988 use, and defaults to the current buffer.
|
|
|
989
|
|
428
|
990 @example
|
|
|
991 (capitalize "The cat in the hat")
|
|
|
992 @result{} "The Cat In The Hat"
|
|
|
993
|
|
|
994 (capitalize "THE 77TH-HATTED CAT")
|
|
|
995 @result{} "The 77th-Hatted Cat"
|
|
|
996
|
|
|
997 @group
|
|
|
998 (capitalize ?x)
|
|
|
999 @result{} ?X ;; @r{Under XEmacs 20.}
|
|
|
1000 @result{} 88 ;; @r{Under XEmacs 19.}
|
|
|
1001 @end group
|
|
|
1002 @end example
|
|
|
1003 @end defun
|
|
|
1004
|
|
|
1005 @node Case Tables
|
|
|
1006 @section The Case Table
|
|
|
1007
|
|
|
1008 You can customize case conversion by installing a special @dfn{case
|
|
|
1009 table}. A case table specifies the mapping between upper case and lower
|
|
|
1010 case letters. It affects both the string and character case conversion
|
|
|
1011 functions (see the previous section) and those that apply to text in the
|
|
|
1012 buffer (@pxref{Case Changes}). You need a case table if you are using a
|
|
|
1013 language which has letters other than the standard @sc{ascii} letters.
|
|
|
1014
|
|
|
1015 A case table is a list of this form:
|
|
|
1016
|
|
|
1017 @example
|
|
|
1018 (@var{downcase} @var{upcase} @var{canonicalize} @var{equivalences})
|
|
|
1019 @end example
|
|
|
1020
|
|
|
1021 @noindent
|
|
|
1022 where each element is either @code{nil} or a string of length 256. The
|
|
|
1023 element @var{downcase} says how to map each character to its lower-case
|
|
|
1024 equivalent. The element @var{upcase} maps each character to its
|
|
|
1025 upper-case equivalent. If lower and upper case characters are in
|
|
|
1026 one-to-one correspondence, use @code{nil} for @var{upcase}; then XEmacs
|
|
|
1027 deduces the upcase table from @var{downcase}.
|
|
|
1028
|
|
|
1029 For some languages, upper and lower case letters are not in one-to-one
|
|
|
1030 correspondence. There may be two different lower case letters with the
|
|
|
1031 same upper case equivalent. In these cases, you need to specify the
|
|
|
1032 maps for both directions.
|
|
|
1033
|
|
|
1034 The element @var{canonicalize} maps each character to a canonical
|
|
|
1035 equivalent; any two characters that are related by case-conversion have
|
|
|
1036 the same canonical equivalent character.
|
|
|
1037
|
|
|
1038 The element @var{equivalences} is a map that cyclicly permutes each
|
|
|
1039 equivalence class (of characters with the same canonical equivalent).
|
|
|
1040 (For ordinary @sc{ascii}, this would map @samp{a} into @samp{A} and
|
|
|
1041 @samp{A} into @samp{a}, and likewise for each set of equivalent
|
|
|
1042 characters.)
|
|
|
1043
|
|
|
1044 When you construct a case table, you can provide @code{nil} for
|
|
|
1045 @var{canonicalize}; then Emacs fills in this string from @var{upcase}
|
|
|
1046 and @var{downcase}. You can also provide @code{nil} for
|
|
|
1047 @var{equivalences}; then Emacs fills in this string from
|
|
|
1048 @var{canonicalize}. In a case table that is actually in use, those
|
|
|
1049 components are non-@code{nil}. Do not try to specify @var{equivalences}
|
|
|
1050 without also specifying @var{canonicalize}.
|
|
|
1051
|
|
|
1052 Each buffer has a case table. XEmacs also has a @dfn{standard case
|
|
|
1053 table} which is copied into each buffer when you create the buffer.
|
|
|
1054 Changing the standard case table doesn't affect any existing buffers.
|
|
|
1055
|
|
|
1056 Here are the functions for working with case tables:
|
|
|
1057
|
|
|
1058 @defun case-table-p object
|
|
|
1059 This predicate returns non-@code{nil} if @var{object} is a valid case
|
|
|
1060 table.
|
|
|
1061 @end defun
|
|
|
1062
|
|
444
|
1063 @defun set-standard-case-table case-table
|
|
|
1064 This function makes @var{case-table} the standard case table, so that it
|
|
|
1065 will apply to any buffers created subsequently.
|
|
428
|
1066 @end defun
|
|
|
1067
|
|
|
1068 @defun standard-case-table
|
|
|
1069 This returns the standard case table.
|
|
|
1070 @end defun
|
|
|
1071
|
|
444
|
1072 @defun current-case-table &optional buffer
|
|
|
1073 This function returns the case table of @var{buffer}, which defaults to
|
|
|
1074 the current buffer.
|
|
428
|
1075 @end defun
|
|
|
1076
|
|
444
|
1077 @defun set-case-table case-table
|
|
|
1078 This sets the current buffer's case table to @var{case-table}.
|
|
428
|
1079 @end defun
|
|
|
1080
|
|
|
1081 The following three functions are convenient subroutines for packages
|
|
|
1082 that define non-@sc{ascii} character sets. They modify a string
|
|
|
1083 @var{downcase-table} provided as an argument; this should be a string to
|
|
|
1084 be used as the @var{downcase} part of a case table. They also modify
|
|
|
1085 the standard syntax table. @xref{Syntax Tables}.
|
|
|
1086
|
|
|
1087 @defun set-case-syntax-pair uc lc downcase-table
|
|
|
1088 This function specifies a pair of corresponding letters, one upper case
|
|
|
1089 and one lower case.
|
|
|
1090 @end defun
|
|
|
1091
|
|
|
1092 @defun set-case-syntax-delims l r downcase-table
|
|
|
1093 This function makes characters @var{l} and @var{r} a matching pair of
|
|
|
1094 case-invariant delimiters.
|
|
|
1095 @end defun
|
|
|
1096
|
|
|
1097 @defun set-case-syntax char syntax downcase-table
|
|
|
1098 This function makes @var{char} case-invariant, with syntax
|
|
|
1099 @var{syntax}.
|
|
|
1100 @end defun
|
|
|
1101
|
|
|
1102 @deffn Command describe-buffer-case-table
|
|
|
1103 This command displays a description of the contents of the current
|
|
|
1104 buffer's case table.
|
|
|
1105 @end deffn
|
|
|
1106
|
|
|
1107 @cindex ISO Latin 1
|
|
|
1108 @pindex iso-syntax
|
|
|
1109 You can load the library @file{iso-syntax} to set up the standard syntax
|
|
|
1110 table and define a case table for the 8-bit ISO Latin 1 character set.
|
|
|
1111
|
|
|
1112 @node Char Tables
|
|
|
1113 @section The Char Table
|
|
|
1114
|
|
|
1115 A char table is a table that maps characters (or ranges of characters)
|
|
|
1116 to values. Char tables are specialized for characters, only allowing
|
|
|
1117 particular sorts of ranges to be assigned values. Although this
|
|
|
1118 loses in generality, it makes for extremely fast (constant-time)
|
|
|
1119 lookups, and thus is feasible for applications that do an extremely
|
|
|
1120 large number of lookups (e.g. scanning a buffer for a character in
|
|
|
1121 a particular syntax, where a lookup in the syntax table must occur
|
|
|
1122 once per character).
|
|
|
1123
|
|
|
1124 Note that char tables as a primitive type, and all of the functions in
|
|
|
1125 this section, exist only in XEmacs 20. In XEmacs 19, char tables are
|
|
|
1126 generally implemented using a vector of 256 elements.
|
|
|
1127
|
|
|
1128 When @sc{mule} support exists, the types of ranges that can be assigned
|
|
|
1129 values are
|
|
|
1130
|
|
|
1131 @itemize @bullet
|
|
|
1132 @item
|
|
|
1133 all characters
|
|
|
1134 @item
|
|
|
1135 an entire charset
|
|
|
1136 @item
|
|
|
1137 a single row in a two-octet charset
|
|
|
1138 @item
|
|
|
1139 a single character
|
|
|
1140 @end itemize
|
|
|
1141
|
|
|
1142 When @sc{mule} support is not present, the types of ranges that can be
|
|
|
1143 assigned values are
|
|
|
1144
|
|
|
1145 @itemize @bullet
|
|
|
1146 @item
|
|
|
1147 all characters
|
|
|
1148 @item
|
|
|
1149 a single character
|
|
|
1150 @end itemize
|
|
|
1151
|
|
|
1152 @defun char-table-p object
|
|
|
1153 This function returns non-@code{nil} if @var{object} is a char table.
|
|
|
1154 @end defun
|
|
|
1155
|
|
|
1156 @menu
|
|
|
1157 * Char Table Types:: Char tables have different uses.
|
|
|
1158 * Working With Char Tables:: Creating and working with char tables.
|
|
|
1159 @end menu
|
|
|
1160
|
|
|
1161 @node Char Table Types
|
|
|
1162 @subsection Char Table Types
|
|
|
1163
|
|
|
1164 Each char table type is used for a different purpose and allows different
|
|
|
1165 sorts of values. The different char table types are
|
|
|
1166
|
|
|
1167 @table @code
|
|
|
1168 @item category
|
|
|
1169 Used for category tables, which specify the regexp categories
|
|
|
1170 that a character is in. The valid values are @code{nil} or a
|
|
|
1171 bit vector of 95 elements. Higher-level Lisp functions are
|
|
|
1172 provided for working with category tables. Currently categories
|
|
|
1173 and category tables only exist when @sc{mule} support is present.
|
|
|
1174 @item char
|
|
|
1175 A generalized char table, for mapping from one character to
|
|
|
1176 another. Used for case tables, syntax matching tables,
|
|
|
1177 @code{keyboard-translate-table}, etc. The valid values are characters.
|
|
|
1178 @item generic
|
|
|
1179 An even more generalized char table, for mapping from a
|
|
|
1180 character to anything.
|
|
|
1181 @item display
|
|
|
1182 Used for display tables, which specify how a particular character
|
|
|
1183 is to appear when displayed. #### Not yet implemented.
|
|
|
1184 @item syntax
|
|
|
1185 Used for syntax tables, which specify the syntax of a particular
|
|
|
1186 character. Higher-level Lisp functions are provided for
|
|
|
1187 working with syntax tables. The valid values are integers.
|
|
|
1188 @end table
|
|
|
1189
|
|
444
|
1190 @defun char-table-type char-table
|
|
|
1191 This function returns the type of char table @var{char-table}.
|
|
428
|
1192 @end defun
|
|
|
1193
|
|
|
1194 @defun char-table-type-list
|
|
|
1195 This function returns a list of the recognized char table types.
|
|
|
1196 @end defun
|
|
|
1197
|
|
|
1198 @defun valid-char-table-type-p type
|
|
|
1199 This function returns @code{t} if @var{type} if a recognized char table type.
|
|
|
1200 @end defun
|
|
|
1201
|
|
|
1202 @node Working With Char Tables
|
|
|
1203 @subsection Working With Char Tables
|
|
|
1204
|
|
|
1205 @defun make-char-table type
|
|
|
1206 This function makes a new, empty char table of type @var{type}.
|
|
|
1207 @var{type} should be a symbol, one of @code{char}, @code{category},
|
|
|
1208 @code{display}, @code{generic}, or @code{syntax}.
|
|
|
1209 @end defun
|
|
|
1210
|
|
444
|
1211 @defun put-char-table range value char-table
|
|
|
1212 This function sets the value for chars in @var{range} to be @var{value} in
|
|
|
1213 @var{char-table}.
|
|
428
|
1214
|
|
|
1215 @var{range} specifies one or more characters to be affected and should be
|
|
|
1216 one of the following:
|
|
|
1217
|
|
|
1218 @itemize @bullet
|
|
|
1219 @item
|
|
|
1220 @code{t} (all characters are affected)
|
|
|
1221 @item
|
|
|
1222 A charset (only allowed when @sc{mule} support is present)
|
|
|
1223 @item
|
|
|
1224 A vector of two elements: a two-octet charset and a row number
|
|
|
1225 (only allowed when @sc{mule} support is present)
|
|
|
1226 @item
|
|
|
1227 A single character
|
|
|
1228 @end itemize
|
|
|
1229
|
|
444
|
1230 @var{value} must be a value appropriate for the type of @var{char-table}.
|
|
428
|
1231 @end defun
|
|
|
1232
|
|
444
|
1233 @defun get-char-table character char-table
|
|
|
1234 This function finds the value for @var{character} in @var{char-table}.
|
|
428
|
1235 @end defun
|
|
|
1236
|
|
444
|
1237 @defun get-range-char-table range char-table &optional multi
|
|
|
1238 This function finds the value for a range in @var{char-table}. If there is
|
|
428
|
1239 more than one value, @var{multi} is returned (defaults to @code{nil}).
|
|
|
1240 @end defun
|
|
|
1241
|
|
444
|
1242 @defun reset-char-table char-table
|
|
|
1243 This function resets @var{char-table} to its default state.
|
|
428
|
1244 @end defun
|
|
|
1245
|
|
444
|
1246 @defun map-char-table function char-table &optional range
|
|
|
1247 This function maps @var{function} over entries in @var{char-table}, calling
|
|
428
|
1248 it with two args, each key and value in the table.
|
|
|
1249
|
|
|
1250 @var{range} specifies a subrange to map over and is in the same format
|
|
|
1251 as the @var{range} argument to @code{put-range-table}. If omitted or
|
|
|
1252 @code{t}, it defaults to the entire table.
|
|
|
1253 @end defun
|
|
|
1254
|
|
|
1255 @defun valid-char-table-value-p value char-table-type
|
|
|
1256 This function returns non-@code{nil} if @var{value} is a valid value for
|
|
|
1257 @var{char-table-type}.
|
|
|
1258 @end defun
|
|
|
1259
|
|
|
1260 @defun check-valid-char-table-value value char-table-type
|
|
|
1261 This function signals an error if @var{value} is not a valid value for
|
|
|
1262 @var{char-table-type}.
|
|
|
1263 @end defun
|
