|
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
|
|
|
291 @node Predicates for Characters
|
|
|
292 @section The Predicates for Characters
|
|
|
293
|
|
|
294 @defun characterp object
|
|
|
295 This function returns @code{t} if @var{object} is a character.
|
|
|
296
|
|
|
297 Some functions that work on integers (e.g. the comparison functions
|
|
|
298 <, <=, =, /=, etc. and the arithmetic functions +, -, *, etc.)
|
|
|
299 accept characters and implicitly convert them into integers. In
|
|
|
300 general, functions that work on characters also accept char-ints and
|
|
|
301 implicitly convert them into characters. WARNING: Neither of these
|
|
|
302 behaviors is very desirable, and they are maintained for backward
|
|
|
303 compatibility with old E-Lisp programs that confounded characters and
|
|
|
304 integers willy-nilly. These behaviors may change in the future; therefore,
|
|
|
305 do not rely on them. Instead, convert the characters explicitly
|
|
|
306 using @code{char-int}.
|
|
|
307 @end defun
|
|
|
308
|
|
|
309 @defun integer-or-char-p object
|
|
|
310 This function returns @code{t} if @var{object} is an integer or character.
|
|
|
311 @end defun
|
|
|
312
|
|
|
313 @node Character Codes
|
|
|
314 @section Character Codes
|
|
|
315
|
|
444
|
316 @defun char-int character
|
|
428
|
317 This function converts a character into an equivalent integer.
|
|
|
318 The resulting integer will always be non-negative. The integers in
|
|
|
319 the range 0 - 255 map to characters as follows:
|
|
|
320
|
|
|
321 @table @asis
|
|
|
322 @item 0 - 31
|
|
|
323 Control set 0
|
|
|
324 @item 32 - 127
|
|
|
325 @sc{ascii}
|
|
|
326 @item 128 - 159
|
|
|
327 Control set 1
|
|
|
328 @item 160 - 255
|
|
|
329 Right half of ISO-8859-1
|
|
|
330 @end table
|
|
|
331
|
|
|
332 If support for @sc{mule} does not exist, these are the only valid
|
|
|
333 character values. When @sc{mule} support exists, the values assigned to
|
|
|
334 other characters may vary depending on the particular version of XEmacs,
|
|
|
335 the order in which character sets were loaded, etc., and you should not
|
|
|
336 depend on them.
|
|
|
337 @end defun
|
|
|
338
|
|
|
339 @defun int-char integer
|
|
|
340 This function converts an integer into the equivalent character. Not
|
|
|
341 all integers correspond to valid characters; use @code{char-int-p} to
|
|
|
342 determine whether this is the case. If the integer cannot be converted,
|
|
|
343 @code{nil} is returned.
|
|
|
344 @end defun
|
|
|
345
|
|
|
346 @defun char-int-p object
|
|
|
347 This function returns @code{t} if @var{object} is an integer that can be
|
|
|
348 converted into a character.
|
|
|
349 @end defun
|
|
|
350
|
|
|
351 @defun char-or-char-int-p object
|
|
|
352 This function returns @code{t} if @var{object} is a character or an
|
|
|
353 integer that can be converted into one.
|
|
|
354 @end defun
|
|
|
355
|
|
|
356 @need 2000
|
|
|
357 @node Text Comparison
|
|
|
358 @section Comparison of Characters and Strings
|
|
|
359 @cindex string equality
|
|
|
360
|
|
444
|
361 @defun char-equal character1 character2 &optional buffer
|
|
428
|
362 This function returns @code{t} if the arguments represent the same
|
|
|
363 character, @code{nil} otherwise. This function ignores differences
|
|
444
|
364 in case if the value of @code{case-fold-search} is non-@code{nil} in
|
|
|
365 @var{buffer}, which defaults to the current buffer.
|
|
428
|
366
|
|
|
367 @example
|
|
|
368 (char-equal ?x ?x)
|
|
|
369 @result{} t
|
|
|
370 (let ((case-fold-search t))
|
|
|
371 (char-equal ?x ?X))
|
|
|
372 @result{} t
|
|
|
373 (let ((case-fold-search nil))
|
|
|
374 (char-equal ?x ?X))
|
|
|
375 @result{} nil
|
|
|
376 @end example
|
|
|
377 @end defun
|
|
|
378
|
|
|
379 @defun char= character1 character2
|
|
|
380 This function returns @code{t} if the arguments represent the same
|
|
|
381 character, @code{nil} otherwise. Case is significant.
|
|
|
382
|
|
|
383 @example
|
|
|
384 (char= ?x ?x)
|
|
|
385 @result{} t
|
|
|
386 (char= ?x ?X)
|
|
|
387 @result{} nil
|
|
|
388 (let ((case-fold-search t))
|
|
|
389 (char-equal ?x ?X))
|
|
|
390 @result{} nil
|
|
|
391 (let ((case-fold-search nil))
|
|
|
392 (char-equal ?x ?X))
|
|
|
393 @result{} nil
|
|
|
394 @end example
|
|
|
395 @end defun
|
|
|
396
|
|
|
397 @defun string= string1 string2
|
|
|
398 This function returns @code{t} if the characters of the two strings
|
|
|
399 match exactly; case is significant.
|
|
|
400
|
|
|
401 @example
|
|
|
402 (string= "abc" "abc")
|
|
|
403 @result{} t
|
|
|
404 (string= "abc" "ABC")
|
|
|
405 @result{} nil
|
|
|
406 (string= "ab" "ABC")
|
|
|
407 @result{} nil
|
|
|
408 @end example
|
|
|
409
|
|
|
410 @ignore @c `equal' in XEmacs does not compare text properties
|
|
|
411 The function @code{string=} ignores the text properties of the
|
|
|
412 two strings. To compare strings in a way that compares their text
|
|
|
413 properties also, use @code{equal} (@pxref{Equality Predicates}).
|
|
|
414 @end ignore
|
|
|
415 @end defun
|
|
|
416
|
|
|
417 @defun string-equal string1 string2
|
|
|
418 @code{string-equal} is another name for @code{string=}.
|
|
|
419 @end defun
|
|
|
420
|
|
|
421 @cindex lexical comparison
|
|
|
422 @defun string< string1 string2
|
|
|
423 @c (findex string< causes problems for permuted index!!)
|
|
|
424 This function compares two strings a character at a time. First it
|
|
|
425 scans both the strings at once to find the first pair of corresponding
|
|
|
426 characters that do not match. If the lesser character of those two is
|
|
|
427 the character from @var{string1}, then @var{string1} is less, and this
|
|
|
428 function returns @code{t}. If the lesser character is the one from
|
|
|
429 @var{string2}, then @var{string1} is greater, and this function returns
|
|
|
430 @code{nil}. If the two strings match entirely, the value is @code{nil}.
|
|
|
431
|
|
|
432 Pairs of characters are compared by their @sc{ascii} codes. Keep in
|
|
|
433 mind that lower case letters have higher numeric values in the
|
|
|
434 @sc{ascii} character set than their upper case counterparts; numbers and
|
|
|
435 many punctuation characters have a lower numeric value than upper case
|
|
|
436 letters.
|
|
|
437
|
|
|
438 @example
|
|
|
439 @group
|
|
|
440 (string< "abc" "abd")
|
|
|
441 @result{} t
|
|
|
442 (string< "abd" "abc")
|
|
|
443 @result{} nil
|
|
|
444 (string< "123" "abc")
|
|
|
445 @result{} t
|
|
|
446 @end group
|
|
|
447 @end example
|
|
|
448
|
|
|
449 When the strings have different lengths, and they match up to the
|
|
|
450 length of @var{string1}, then the result is @code{t}. If they match up
|
|
|
451 to the length of @var{string2}, the result is @code{nil}. A string of
|
|
|
452 no characters is less than any other string.
|
|
|
453
|
|
|
454 @example
|
|
|
455 @group
|
|
|
456 (string< "" "abc")
|
|
|
457 @result{} t
|
|
|
458 (string< "ab" "abc")
|
|
|
459 @result{} t
|
|
|
460 (string< "abc" "")
|
|
|
461 @result{} nil
|
|
|
462 (string< "abc" "ab")
|
|
|
463 @result{} nil
|
|
|
464 (string< "" "")
|
|
444
|
465 @result{} nil
|
|
428
|
466 @end group
|
|
|
467 @end example
|
|
|
468 @end defun
|
|
|
469
|
|
|
470 @defun string-lessp string1 string2
|
|
|
471 @code{string-lessp} is another name for @code{string<}.
|
|
|
472 @end defun
|
|
|
473
|
|
|
474 See also @code{compare-buffer-substrings} in @ref{Comparing Text}, for
|
|
|
475 a way to compare text in buffers. The function @code{string-match},
|
|
|
476 which matches a regular expression against a string, can be used
|
|
|
477 for a kind of string comparison; see @ref{Regexp Search}.
|
|
|
478
|
|
|
479 @node String Conversion
|
|
|
480 @section Conversion of Characters and Strings
|
|
|
481 @cindex conversion of strings
|
|
|
482
|
|
|
483 This section describes functions for conversions between characters,
|
|
|
484 strings and integers. @code{format} and @code{prin1-to-string}
|
|
|
485 (@pxref{Output Functions}) can also convert Lisp objects into strings.
|
|
|
486 @code{read-from-string} (@pxref{Input Functions}) can ``convert'' a
|
|
|
487 string representation of a Lisp object into an object.
|
|
|
488
|
|
|
489 @xref{Documentation}, for functions that produce textual descriptions
|
|
|
490 of text characters and general input events
|
|
|
491 (@code{single-key-description} and @code{text-char-description}). These
|
|
|
492 functions are used primarily for making help messages.
|
|
|
493
|
|
|
494 @defun char-to-string character
|
|
|
495 @cindex character to string
|
|
|
496 This function returns a new string with a length of one character.
|
|
|
497 The value of @var{character}, modulo 256, is used to initialize the
|
|
|
498 element of the string.
|
|
|
499
|
|
|
500 This function is similar to @code{make-string} with an integer argument
|
|
|
501 of 1. (@xref{Creating Strings}.) This conversion can also be done with
|
|
|
502 @code{format} using the @samp{%c} format specification.
|
|
|
503 (@xref{Formatting Strings}.)
|
|
|
504
|
|
|
505 @example
|
|
|
506 (char-to-string ?x)
|
|
|
507 @result{} "x"
|
|
|
508 (char-to-string (+ 256 ?x))
|
|
|
509 @result{} "x"
|
|
|
510 (make-string 1 ?x)
|
|
|
511 @result{} "x"
|
|
|
512 @end example
|
|
|
513 @end defun
|
|
|
514
|
|
|
515 @defun string-to-char string
|
|
|
516 @cindex string to character
|
|
|
517 This function returns the first character in @var{string}. If the
|
|
|
518 string is empty, the function returns 0. (Under XEmacs 19, the value is
|
|
|
519 also 0 when the first character of @var{string} is the null character,
|
|
|
520 @sc{ascii} code 0.)
|
|
|
521
|
|
|
522 @example
|
|
|
523 (string-to-char "ABC")
|
|
|
524 @result{} ?A ;; @r{Under XEmacs 20.}
|
|
|
525 @result{} 65 ;; @r{Under XEmacs 19.}
|
|
|
526 (string-to-char "xyz")
|
|
|
527 @result{} ?x ;; @r{Under XEmacs 20.}
|
|
|
528 @result{} 120 ;; @r{Under XEmacs 19.}
|
|
|
529 (string-to-char "")
|
|
|
530 @result{} 0
|
|
|
531 (string-to-char "\000")
|
|
|
532 @result{} ?\^@ ;; @r{Under XEmacs 20.}
|
|
|
533 @result{} 0 ;; @r{Under XEmacs 20.}
|
|
|
534 @end example
|
|
|
535
|
|
|
536 This function may be eliminated in the future if it does not seem useful
|
|
|
537 enough to retain.
|
|
|
538 @end defun
|
|
|
539
|
|
|
540 @defun number-to-string number
|
|
|
541 @cindex integer to string
|
|
|
542 @cindex integer to decimal
|
|
|
543 This function returns a string consisting of the printed
|
|
|
544 representation of @var{number}, which may be an integer or a floating
|
|
|
545 point number. The value starts with a sign if the argument is
|
|
|
546 negative.
|
|
|
547
|
|
|
548 @example
|
|
|
549 (number-to-string 256)
|
|
|
550 @result{} "256"
|
|
|
551 (number-to-string -23)
|
|
|
552 @result{} "-23"
|
|
|
553 (number-to-string -23.5)
|
|
|
554 @result{} "-23.5"
|
|
|
555 @end example
|
|
|
556
|
|
|
557 @cindex int-to-string
|
|
|
558 @code{int-to-string} is a semi-obsolete alias for this function.
|
|
|
559
|
|
|
560 See also the function @code{format} in @ref{Formatting Strings}.
|
|
|
561 @end defun
|
|
|
562
|
|
|
563 @defun string-to-number string &optional base
|
|
|
564 @cindex string to number
|
|
444
|
565 This function returns the numeric value represented by @var{string},
|
|
|
566 read in @var{base}. It skips spaces and tabs at the beginning of
|
|
|
567 @var{string}, then reads as much of @var{string} as it can interpret as
|
|
|
568 a number. (On some systems it ignores other whitespace at the
|
|
|
569 beginning, not just spaces and tabs.) If the first character after the
|
|
|
570 ignored whitespace is not a digit or a minus sign, this function returns
|
|
|
571 0.
|
|
428
|
572
|
|
|
573 If @var{base} is not specified, it defaults to ten. With @var{base}
|
|
|
574 other than ten, only integers can be read.
|
|
|
575
|
|
|
576 @example
|
|
|
577 (string-to-number "256")
|
|
|
578 @result{} 256
|
|
|
579 (string-to-number "25 is a perfect square.")
|
|
|
580 @result{} 25
|
|
|
581 (string-to-number "X256")
|
|
|
582 @result{} 0
|
|
|
583 (string-to-number "-4.5")
|
|
|
584 @result{} -4.5
|
|
|
585 (string-to-number "ffff" 16)
|
|
|
586 @result{} 65535
|
|
|
587 @end example
|
|
|
588
|
|
|
589 @findex string-to-int
|
|
|
590 @code{string-to-int} is an obsolete alias for this function.
|
|
|
591 @end defun
|
|
|
592
|
|
|
593 @node Modifying Strings
|
|
|
594 @section Modifying Strings
|
|
|
595 @cindex strings, modifying
|
|
|
596
|
|
|
597 You can modify a string using the general array-modifying primitives.
|
|
|
598 @xref{Arrays}. The function @code{aset} modifies a single character;
|
|
|
599 the function @code{fillarray} sets all characters in the string to
|
|
|
600 a specified character.
|
|
|
601
|
|
|
602 Each string has a tick counter that starts out at zero (when the string
|
|
|
603 is created) and is incremented each time a change is made to that
|
|
|
604 string.
|
|
|
605
|
|
|
606 @defun string-modified-tick string
|
|
|
607 This function returns the tick counter for @samp{string}.
|
|
|
608 @end defun
|
|
|
609
|
|
|
610 @node String Properties
|
|
|
611 @section String Properties
|
|
|
612 @cindex string properties
|
|
|
613 @cindex properties of strings
|
|
|
614
|
|
442
|
615 Just as with symbols, extents, faces, and glyphs, you can attach
|
|
428
|
616 additional information to strings in the form of @dfn{string
|
|
|
617 properties}. These differ from text properties, which are logically
|
|
|
618 attached to particular characters in the string.
|
|
|
619
|
|
|
620 To attach a property to a string, use @code{put}. To retrieve a property
|
|
|
621 from a string, use @code{get}. You can also use @code{remprop} to remove
|
|
442
|
622 a property from a string and @code{object-plist} to retrieve a list of
|
|
428
|
623 all the properties in a string.
|
|
|
624
|
|
|
625 @node Formatting Strings
|
|
|
626 @section Formatting Strings
|
|
|
627 @cindex formatting strings
|
|
|
628 @cindex strings, formatting them
|
|
|
629
|
|
|
630 @dfn{Formatting} means constructing a string by substitution of
|
|
|
631 computed values at various places in a constant string. This string
|
|
|
632 controls how the other values are printed as well as where they appear;
|
|
|
633 it is called a @dfn{format string}.
|
|
|
634
|
|
|
635 Formatting is often useful for computing messages to be displayed. In
|
|
|
636 fact, the functions @code{message} and @code{error} provide the same
|
|
|
637 formatting feature described here; they differ from @code{format} only
|
|
|
638 in how they use the result of formatting.
|
|
|
639
|
|
|
640 @defun format string &rest objects
|
|
|
641 This function returns a new string that is made by copying
|
|
444
|
642 @var{string} and then replacing any format specification
|
|
428
|
643 in the copy with encodings of the corresponding @var{objects}. The
|
|
|
644 arguments @var{objects} are the computed values to be formatted.
|
|
|
645 @end defun
|
|
|
646
|
|
|
647 @cindex @samp{%} in format
|
|
|
648 @cindex format specification
|
|
|
649 A format specification is a sequence of characters beginning with a
|
|
|
650 @samp{%}. Thus, if there is a @samp{%d} in @var{string}, the
|
|
|
651 @code{format} function replaces it with the printed representation of
|
|
|
652 one of the values to be formatted (one of the arguments @var{objects}).
|
|
|
653 For example:
|
|
|
654
|
|
|
655 @example
|
|
|
656 @group
|
|
|
657 (format "The value of fill-column is %d." fill-column)
|
|
|
658 @result{} "The value of fill-column is 72."
|
|
|
659 @end group
|
|
|
660 @end example
|
|
|
661
|
|
|
662 If @var{string} contains more than one format specification, the
|
|
|
663 format specifications correspond with successive values from
|
|
|
664 @var{objects}. Thus, the first format specification in @var{string}
|
|
|
665 uses the first such value, the second format specification uses the
|
|
|
666 second such value, and so on. Any extra format specifications (those
|
|
|
667 for which there are no corresponding values) cause unpredictable
|
|
|
668 behavior. Any extra values to be formatted are ignored.
|
|
|
669
|
|
|
670 Certain format specifications require values of particular types.
|
|
|
671 However, no error is signaled if the value actually supplied fails to
|
|
|
672 have the expected type. Instead, the output is likely to be
|
|
|
673 meaningless.
|
|
|
674
|
|
|
675 Here is a table of valid format specifications:
|
|
|
676
|
|
|
677 @table @samp
|
|
|
678 @item %s
|
|
|
679 Replace the specification with the printed representation of the object,
|
|
|
680 made without quoting. Thus, strings are represented by their contents
|
|
|
681 alone, with no @samp{"} characters, and symbols appear without @samp{\}
|
|
|
682 characters. This is equivalent to printing the object with @code{princ}.
|
|
|
683
|
|
|
684 If there is no corresponding object, the empty string is used.
|
|
|
685
|
|
|
686 @item %S
|
|
|
687 Replace the specification with the printed representation of the object,
|
|
|
688 made with quoting. Thus, strings are enclosed in @samp{"} characters,
|
|
|
689 and @samp{\} characters appear where necessary before special characters.
|
|
|
690 This is equivalent to printing the object with @code{prin1}.
|
|
|
691
|
|
|
692 If there is no corresponding object, the empty string is used.
|
|
|
693
|
|
|
694 @item %o
|
|
|
695 @cindex integer to octal
|
|
|
696 Replace the specification with the base-eight representation of an
|
|
|
697 integer.
|
|
|
698
|
|
|
699 @item %d
|
|
|
700 @itemx %i
|
|
|
701 Replace the specification with the base-ten representation of an
|
|
|
702 integer.
|
|
|
703
|
|
|
704 @item %x
|
|
|
705 @cindex integer to hexadecimal
|
|
|
706 Replace the specification with the base-sixteen representation of an
|
|
|
707 integer, using lowercase letters.
|
|
|
708
|
|
|
709 @item %X
|
|
|
710 @cindex integer to hexadecimal
|
|
|
711 Replace the specification with the base-sixteen representation of an
|
|
|
712 integer, using uppercase letters.
|
|
|
713
|
|
|
714 @item %c
|
|
|
715 Replace the specification with the character which is the value given.
|
|
|
716
|
|
|
717 @item %e
|
|
|
718 Replace the specification with the exponential notation for a floating
|
|
|
719 point number (e.g. @samp{7.85200e+03}).
|
|
|
720
|
|
|
721 @item %f
|
|
|
722 Replace the specification with the decimal-point notation for a floating
|
|
|
723 point number.
|
|
|
724
|
|
|
725 @item %g
|
|
|
726 Replace the specification with notation for a floating point number,
|
|
|
727 using a ``pretty format''. Either exponential notation or decimal-point
|
|
|
728 notation will be used (usually whichever is shorter), and trailing
|
|
|
729 zeroes are removed from the fractional part.
|
|
|
730
|
|
|
731 @item %%
|
|
|
732 A single @samp{%} is placed in the string. This format specification is
|
|
|
733 unusual in that it does not use a value. For example, @code{(format "%%
|
|
|
734 %d" 30)} returns @code{"% 30"}.
|
|
|
735 @end table
|
|
|
736
|
|
|
737 Any other format character results in an @samp{Invalid format
|
|
|
738 operation} error.
|
|
|
739
|
|
|
740 Here are several examples:
|
|
|
741
|
|
|
742 @example
|
|
|
743 @group
|
|
|
744 (format "The name of this buffer is %s." (buffer-name))
|
|
|
745 @result{} "The name of this buffer is strings.texi."
|
|
|
746
|
|
|
747 (format "The buffer object prints as %s." (current-buffer))
|
|
|
748 @result{} "The buffer object prints as #<buffer strings.texi>."
|
|
|
749
|
|
444
|
750 (format "The octal value of %d is %o,
|
|
428
|
751 and the hex value is %x." 18 18 18)
|
|
444
|
752 @result{} "The octal value of 18 is 22,
|
|
428
|
753 and the hex value is 12."
|
|
|
754 @end group
|
|
|
755 @end example
|
|
|
756
|
|
|
757 There are many additional flags and specifications that can occur
|
|
|
758 between the @samp{%} and the format character, in the following order:
|
|
|
759
|
|
|
760 @enumerate
|
|
|
761 @item
|
|
|
762 An optional repositioning specification, which is a positive
|
|
|
763 integer followed by a @samp{$}.
|
|
|
764
|
|
|
765 @item
|
|
|
766 Zero or more of the optional flag characters @samp{-}, @samp{+},
|
|
|
767 @samp{ }, @samp{0}, and @samp{#}.
|
|
|
768
|
|
|
769 @item
|
|
|
770 An asterisk (@samp{*}, meaning that the field width is now assumed to
|
|
|
771 have been specified as an argument.
|
|
|
772
|
|
|
773 @item
|
|
|
774 An optional minimum field width.
|
|
|
775
|
|
|
776 @item
|
|
|
777 An optional precision, preceded by a @samp{.} character.
|
|
|
778 @end enumerate
|
|
|
779
|
|
|
780 @cindex repositioning format arguments
|
|
|
781 @cindex multilingual string formatting
|
|
|
782 A @dfn{repositioning} specification changes which argument to
|
|
|
783 @code{format} is used by the current and all following format
|
|
|
784 specifications. Normally the first specification uses the first
|
|
|
785 argument, the second specification uses the second argument, etc. Using
|
|
|
786 a repositioning specification, you can change this. By placing a number
|
|
444
|
787 @var{n} followed by a @samp{$} between the @samp{%} and the format
|
|
|
788 character, you cause the specification to use the @var{n}th argument.
|
|
|
789 The next specification will use the @var{n}+1'th argument, etc.
|
|
428
|
790
|
|
|
791 For example:
|
|
|
792
|
|
|
793 @example
|
|
|
794 @group
|
|
|
795 (format "Can't find file `%s' in directory `%s'."
|
|
|
796 "ignatius.c" "loyola/")
|
|
|
797 @result{} "Can't find file `ignatius.c' in directory `loyola/'."
|
|
|
798
|
|
|
799 (format "In directory `%2$s', the file `%1$s' was not found."
|
|
|
800 "ignatius.c" "loyola/")
|
|
|
801 @result{} "In directory `loyola/', the file `ignatius.c' was not found."
|
|
|
802
|
|
|
803 (format
|
|
|
804 "The numbers %d and %d are %1$x and %x in hex and %1$o and %o in octal."
|
|
|
805 37 12)
|
|
|
806 @result{} "The numbers 37 and 12 are 25 and c in hex and 45 and 14 in octal."
|
|
|
807 @end group
|
|
|
808 @end example
|
|
|
809
|
|
|
810 As you can see, this lets you reprocess arguments more than once or
|
|
|
811 reword a format specification (thereby moving the arguments around)
|
|
|
812 without having to actually reorder the arguments. This is especially
|
|
|
813 useful in translating messages from one language to another: Different
|
|
|
814 languages use different word orders, and this sometimes entails changing
|
|
|
815 the order of the arguments. By using repositioning specifications,
|
|
|
816 this can be accomplished without having to embed knowledge of particular
|
|
|
817 languages into the location in the program's code where the message is
|
|
|
818 displayed.
|
|
|
819
|
|
|
820 @cindex numeric prefix
|
|
|
821 @cindex field width
|
|
|
822 @cindex padding
|
|
|
823 All the specification characters allow an optional numeric prefix
|
|
|
824 between the @samp{%} and the character, and following any repositioning
|
|
|
825 specification or flag. The optional numeric prefix defines the minimum
|
|
|
826 width for the object. If the printed representation of the object
|
|
|
827 contains fewer characters than this, then it is padded. The padding is
|
|
|
828 normally on the left, but will be on the right if the @samp{-} flag
|
|
|
829 character is given. The padding character is normally a space, but if
|
|
|
830 the @samp{0} flag character is given, zeros are used for padding.
|
|
|
831
|
|
|
832 @example
|
|
|
833 (format "%06d is padded on the left with zeros" 123)
|
|
|
834 @result{} "000123 is padded on the left with zeros"
|
|
|
835
|
|
|
836 (format "%-6d is padded on the right" 123)
|
|
|
837 @result{} "123 is padded on the right"
|
|
|
838 @end example
|
|
|
839
|
|
|
840 @code{format} never truncates an object's printed representation, no
|
|
|
841 matter what width you specify. Thus, you can use a numeric prefix to
|
|
|
842 specify a minimum spacing between columns with no risk of losing
|
|
|
843 information.
|
|
|
844
|
|
|
845 In the following three examples, @samp{%7s} specifies a minimum width
|
|
|
846 of 7. In the first case, the string inserted in place of @samp{%7s} has
|
|
|
847 only 3 letters, so 4 blank spaces are inserted for padding. In the
|
|
|
848 second case, the string @code{"specification"} is 13 letters wide but is
|
|
|
849 not truncated. In the third case, the padding is on the right.
|
|
|
850
|
|
444
|
851 @smallexample
|
|
428
|
852 @group
|
|
|
853 (format "The word `%7s' actually has %d letters in it."
|
|
|
854 "foo" (length "foo"))
|
|
444
|
855 @result{} "The word ` foo' actually has 3 letters in it."
|
|
428
|
856 @end group
|
|
|
857
|
|
|
858 @group
|
|
|
859 (format "The word `%7s' actually has %d letters in it."
|
|
444
|
860 "specification" (length "specification"))
|
|
|
861 @result{} "The word `specification' actually has 13 letters in it."
|
|
428
|
862 @end group
|
|
|
863
|
|
|
864 @group
|
|
|
865 (format "The word `%-7s' actually has %d letters in it."
|
|
|
866 "foo" (length "foo"))
|
|
444
|
867 @result{} "The word `foo ' actually has 3 letters in it."
|
|
428
|
868 @end group
|
|
|
869 @end smallexample
|
|
|
870
|
|
|
871 @cindex format precision
|
|
|
872 @cindex precision of formatted numbers
|
|
|
873 After any minimum field width, a precision may be specified by
|
|
|
874 preceding it with a @samp{.} character. The precision specifies the
|
|
|
875 minimum number of digits to appear in @samp{%d}, @samp{%i}, @samp{%o},
|
|
|
876 @samp{%x}, and @samp{%X} conversions (the number is padded on the left
|
|
|
877 with zeroes as necessary); the number of digits printed after the
|
|
|
878 decimal point for @samp{%f}, @samp{%e}, and @samp{%E} conversions; the
|
|
|
879 number of significant digits printed in @samp{%g} and @samp{%G}
|
|
|
880 conversions; and the maximum number of non-padding characters printed in
|
|
|
881 @samp{%s} and @samp{%S} conversions. The default precision for
|
|
|
882 floating-point conversions is six.
|
|
|
883
|
|
|
884 The other flag characters have the following meanings:
|
|
|
885
|
|
|
886 @itemize @bullet
|
|
|
887 @item
|
|
|
888 The @samp{ } flag means prefix non-negative numbers with a space.
|
|
|
889
|
|
|
890 @item
|
|
|
891 The @samp{+} flag means prefix non-negative numbers with a plus sign.
|
|
|
892
|
|
|
893 @item
|
|
|
894 The @samp{#} flag means print numbers in an alternate, more verbose
|
|
|
895 format: octal numbers begin with zero; hex numbers begin with a
|
|
|
896 @samp{0x} or @samp{0X}; a decimal point is printed in @samp{%f},
|
|
|
897 @samp{%e}, and @samp{%E} conversions even if no numbers are printed
|
|
|
898 after it; and trailing zeroes are not omitted in @samp{%g} and @samp{%G}
|
|
|
899 conversions.
|
|
|
900 @end itemize
|
|
|
901
|
|
|
902 @node Character Case
|
|
|
903 @section Character Case
|
|
444
|
904 @cindex upper case
|
|
|
905 @cindex lower case
|
|
|
906 @cindex character case
|
|
428
|
907
|
|
|
908 The character case functions change the case of single characters or
|
|
|
909 of the contents of strings. The functions convert only alphabetic
|
|
|
910 characters (the letters @samp{A} through @samp{Z} and @samp{a} through
|
|
|
911 @samp{z}); other characters are not altered. The functions do not
|
|
|
912 modify the strings that are passed to them as arguments.
|
|
|
913
|
|
|
914 The examples below use the characters @samp{X} and @samp{x} which have
|
|
|
915 @sc{ascii} codes 88 and 120 respectively.
|
|
|
916
|
|
444
|
917 @defun downcase string-or-char &optional buffer
|
|
428
|
918 This function converts a character or a string to lower case.
|
|
|
919
|
|
|
920 When the argument to @code{downcase} is a string, the function creates
|
|
|
921 and returns a new string in which each letter in the argument that is
|
|
|
922 upper case is converted to lower case. When the argument to
|
|
|
923 @code{downcase} is a character, @code{downcase} returns the
|
|
|
924 corresponding lower case character. (This value is actually an integer
|
|
|
925 under XEmacs 19.) If the original character is lower case, or is not a
|
|
|
926 letter, then the value equals the original character.
|
|
|
927
|
|
444
|
928 Optional second arg @var{buffer} specifies which buffer's case tables to
|
|
|
929 use, and defaults to the current buffer.
|
|
|
930
|
|
428
|
931 @example
|
|
|
932 (downcase "The cat in the hat")
|
|
|
933 @result{} "the cat in the hat"
|
|
|
934
|
|
|
935 (downcase ?X)
|
|
|
936 @result{} ?x ;; @r{Under XEmacs 20.}
|
|
|
937 @result{} 120 ;; @r{Under XEmacs 19.}
|
|
|
938
|
|
|
939 @end example
|
|
|
940 @end defun
|
|
|
941
|
|
444
|
942 @defun upcase string-or-char &optional buffer
|
|
428
|
943 This function converts a character or a string to upper case.
|
|
|
944
|
|
|
945 When the argument to @code{upcase} is a string, the function creates
|
|
|
946 and returns a new string in which each letter in the argument that is
|
|
|
947 lower case is converted to upper case.
|
|
|
948
|
|
|
949 When the argument to @code{upcase} is a character, @code{upcase} returns
|
|
|
950 the corresponding upper case character. (This value is actually an
|
|
|
951 integer under XEmacs 19.) If the original character is upper case, or
|
|
|
952 is not a letter, then the value equals the original character.
|
|
|
953
|
|
444
|
954 Optional second arg @var{buffer} specifies which buffer's case tables to
|
|
|
955 use, and defaults to the current buffer.
|
|
|
956
|
|
428
|
957 @example
|
|
|
958 (upcase "The cat in the hat")
|
|
|
959 @result{} "THE CAT IN THE HAT"
|
|
|
960
|
|
|
961 (upcase ?x)
|
|
|
962 @result{} ?X ;; @r{Under XEmacs 20.}
|
|
|
963 @result{} 88 ;; @r{Under XEmacs 19.}
|
|
|
964 @end example
|
|
|
965 @end defun
|
|
|
966
|
|
444
|
967 @defun capitalize string-or-char &optional buffer
|
|
428
|
968 @cindex capitalization
|
|
|
969 This function capitalizes strings or characters. If
|
|
|
970 @var{string-or-char} is a string, the function creates and returns a new
|
|
|
971 string, whose contents are a copy of @var{string-or-char} in which each
|
|
|
972 word has been capitalized. This means that the first character of each
|
|
|
973 word is converted to upper case, and the rest are converted to lower
|
|
|
974 case.
|
|
|
975
|
|
|
976 The definition of a word is any sequence of consecutive characters that
|
|
|
977 are assigned to the word constituent syntax class in the current syntax
|
|
|
978 table (@pxref{Syntax Class Table}).
|
|
|
979
|
|
|
980 When the argument to @code{capitalize} is a character, @code{capitalize}
|
|
|
981 has the same result as @code{upcase}.
|
|
|
982
|
|
444
|
983 Optional second arg @var{buffer} specifies which buffer's case tables to
|
|
|
984 use, and defaults to the current buffer.
|
|
|
985
|
|
428
|
986 @example
|
|
|
987 (capitalize "The cat in the hat")
|
|
|
988 @result{} "The Cat In The Hat"
|
|
|
989
|
|
|
990 (capitalize "THE 77TH-HATTED CAT")
|
|
|
991 @result{} "The 77th-Hatted Cat"
|
|
|
992
|
|
|
993 @group
|
|
|
994 (capitalize ?x)
|
|
|
995 @result{} ?X ;; @r{Under XEmacs 20.}
|
|
|
996 @result{} 88 ;; @r{Under XEmacs 19.}
|
|
|
997 @end group
|
|
|
998 @end example
|
|
|
999 @end defun
|
|
|
1000
|
|
|
1001 @node Case Tables
|
|
|
1002 @section The Case Table
|
|
|
1003
|
|
|
1004 You can customize case conversion by installing a special @dfn{case
|
|
|
1005 table}. A case table specifies the mapping between upper case and lower
|
|
|
1006 case letters. It affects both the string and character case conversion
|
|
|
1007 functions (see the previous section) and those that apply to text in the
|
|
|
1008 buffer (@pxref{Case Changes}). You need a case table if you are using a
|
|
|
1009 language which has letters other than the standard @sc{ascii} letters.
|
|
|
1010
|
|
|
1011 A case table is a list of this form:
|
|
|
1012
|
|
|
1013 @example
|
|
|
1014 (@var{downcase} @var{upcase} @var{canonicalize} @var{equivalences})
|
|
|
1015 @end example
|
|
|
1016
|
|
|
1017 @noindent
|
|
|
1018 where each element is either @code{nil} or a string of length 256. The
|
|
|
1019 element @var{downcase} says how to map each character to its lower-case
|
|
|
1020 equivalent. The element @var{upcase} maps each character to its
|
|
|
1021 upper-case equivalent. If lower and upper case characters are in
|
|
|
1022 one-to-one correspondence, use @code{nil} for @var{upcase}; then XEmacs
|
|
|
1023 deduces the upcase table from @var{downcase}.
|
|
|
1024
|
|
|
1025 For some languages, upper and lower case letters are not in one-to-one
|
|
|
1026 correspondence. There may be two different lower case letters with the
|
|
|
1027 same upper case equivalent. In these cases, you need to specify the
|
|
|
1028 maps for both directions.
|
|
|
1029
|
|
|
1030 The element @var{canonicalize} maps each character to a canonical
|
|
|
1031 equivalent; any two characters that are related by case-conversion have
|
|
|
1032 the same canonical equivalent character.
|
|
|
1033
|
|
|
1034 The element @var{equivalences} is a map that cyclicly permutes each
|
|
|
1035 equivalence class (of characters with the same canonical equivalent).
|
|
|
1036 (For ordinary @sc{ascii}, this would map @samp{a} into @samp{A} and
|
|
|
1037 @samp{A} into @samp{a}, and likewise for each set of equivalent
|
|
|
1038 characters.)
|
|
|
1039
|
|
|
1040 When you construct a case table, you can provide @code{nil} for
|
|
|
1041 @var{canonicalize}; then Emacs fills in this string from @var{upcase}
|
|
|
1042 and @var{downcase}. You can also provide @code{nil} for
|
|
|
1043 @var{equivalences}; then Emacs fills in this string from
|
|
|
1044 @var{canonicalize}. In a case table that is actually in use, those
|
|
|
1045 components are non-@code{nil}. Do not try to specify @var{equivalences}
|
|
|
1046 without also specifying @var{canonicalize}.
|
|
|
1047
|
|
|
1048 Each buffer has a case table. XEmacs also has a @dfn{standard case
|
|
|
1049 table} which is copied into each buffer when you create the buffer.
|
|
|
1050 Changing the standard case table doesn't affect any existing buffers.
|
|
|
1051
|
|
|
1052 Here are the functions for working with case tables:
|
|
|
1053
|
|
|
1054 @defun case-table-p object
|
|
|
1055 This predicate returns non-@code{nil} if @var{object} is a valid case
|
|
|
1056 table.
|
|
|
1057 @end defun
|
|
|
1058
|
|
444
|
1059 @defun set-standard-case-table case-table
|
|
|
1060 This function makes @var{case-table} the standard case table, so that it
|
|
|
1061 will apply to any buffers created subsequently.
|
|
428
|
1062 @end defun
|
|
|
1063
|
|
|
1064 @defun standard-case-table
|
|
|
1065 This returns the standard case table.
|
|
|
1066 @end defun
|
|
|
1067
|
|
444
|
1068 @defun current-case-table &optional buffer
|
|
|
1069 This function returns the case table of @var{buffer}, which defaults to
|
|
|
1070 the current buffer.
|
|
428
|
1071 @end defun
|
|
|
1072
|
|
444
|
1073 @defun set-case-table case-table
|
|
|
1074 This sets the current buffer's case table to @var{case-table}.
|
|
428
|
1075 @end defun
|
|
|
1076
|
|
|
1077 The following three functions are convenient subroutines for packages
|
|
|
1078 that define non-@sc{ascii} character sets. They modify a string
|
|
|
1079 @var{downcase-table} provided as an argument; this should be a string to
|
|
|
1080 be used as the @var{downcase} part of a case table. They also modify
|
|
|
1081 the standard syntax table. @xref{Syntax Tables}.
|
|
|
1082
|
|
|
1083 @defun set-case-syntax-pair uc lc downcase-table
|
|
|
1084 This function specifies a pair of corresponding letters, one upper case
|
|
|
1085 and one lower case.
|
|
|
1086 @end defun
|
|
|
1087
|
|
|
1088 @defun set-case-syntax-delims l r downcase-table
|
|
|
1089 This function makes characters @var{l} and @var{r} a matching pair of
|
|
|
1090 case-invariant delimiters.
|
|
|
1091 @end defun
|
|
|
1092
|
|
|
1093 @defun set-case-syntax char syntax downcase-table
|
|
|
1094 This function makes @var{char} case-invariant, with syntax
|
|
|
1095 @var{syntax}.
|
|
|
1096 @end defun
|
|
|
1097
|
|
|
1098 @deffn Command describe-buffer-case-table
|
|
|
1099 This command displays a description of the contents of the current
|
|
|
1100 buffer's case table.
|
|
|
1101 @end deffn
|
|
|
1102
|
|
|
1103 @cindex ISO Latin 1
|
|
|
1104 @pindex iso-syntax
|
|
|
1105 You can load the library @file{iso-syntax} to set up the standard syntax
|
|
|
1106 table and define a case table for the 8-bit ISO Latin 1 character set.
|
|
|
1107
|
|
|
1108 @node Char Tables
|
|
|
1109 @section The Char Table
|
|
|
1110
|
|
|
1111 A char table is a table that maps characters (or ranges of characters)
|
|
|
1112 to values. Char tables are specialized for characters, only allowing
|
|
|
1113 particular sorts of ranges to be assigned values. Although this
|
|
|
1114 loses in generality, it makes for extremely fast (constant-time)
|
|
|
1115 lookups, and thus is feasible for applications that do an extremely
|
|
|
1116 large number of lookups (e.g. scanning a buffer for a character in
|
|
|
1117 a particular syntax, where a lookup in the syntax table must occur
|
|
|
1118 once per character).
|
|
|
1119
|
|
|
1120 Note that char tables as a primitive type, and all of the functions in
|
|
|
1121 this section, exist only in XEmacs 20. In XEmacs 19, char tables are
|
|
|
1122 generally implemented using a vector of 256 elements.
|
|
|
1123
|
|
|
1124 When @sc{mule} support exists, the types of ranges that can be assigned
|
|
|
1125 values are
|
|
|
1126
|
|
|
1127 @itemize @bullet
|
|
|
1128 @item
|
|
|
1129 all characters
|
|
|
1130 @item
|
|
|
1131 an entire charset
|
|
|
1132 @item
|
|
|
1133 a single row in a two-octet charset
|
|
|
1134 @item
|
|
|
1135 a single character
|
|
|
1136 @end itemize
|
|
|
1137
|
|
|
1138 When @sc{mule} support is not present, the types of ranges that can be
|
|
|
1139 assigned values are
|
|
|
1140
|
|
|
1141 @itemize @bullet
|
|
|
1142 @item
|
|
|
1143 all characters
|
|
|
1144 @item
|
|
|
1145 a single character
|
|
|
1146 @end itemize
|
|
|
1147
|
|
|
1148 @defun char-table-p object
|
|
|
1149 This function returns non-@code{nil} if @var{object} is a char table.
|
|
|
1150 @end defun
|
|
|
1151
|
|
|
1152 @menu
|
|
|
1153 * Char Table Types:: Char tables have different uses.
|
|
|
1154 * Working With Char Tables:: Creating and working with char tables.
|
|
|
1155 @end menu
|
|
|
1156
|
|
|
1157 @node Char Table Types
|
|
|
1158 @subsection Char Table Types
|
|
|
1159
|
|
|
1160 Each char table type is used for a different purpose and allows different
|
|
|
1161 sorts of values. The different char table types are
|
|
|
1162
|
|
|
1163 @table @code
|
|
|
1164 @item category
|
|
|
1165 Used for category tables, which specify the regexp categories
|
|
|
1166 that a character is in. The valid values are @code{nil} or a
|
|
|
1167 bit vector of 95 elements. Higher-level Lisp functions are
|
|
|
1168 provided for working with category tables. Currently categories
|
|
|
1169 and category tables only exist when @sc{mule} support is present.
|
|
|
1170 @item char
|
|
|
1171 A generalized char table, for mapping from one character to
|
|
|
1172 another. Used for case tables, syntax matching tables,
|
|
|
1173 @code{keyboard-translate-table}, etc. The valid values are characters.
|
|
|
1174 @item generic
|
|
|
1175 An even more generalized char table, for mapping from a
|
|
|
1176 character to anything.
|
|
|
1177 @item display
|
|
|
1178 Used for display tables, which specify how a particular character
|
|
|
1179 is to appear when displayed. #### Not yet implemented.
|
|
|
1180 @item syntax
|
|
|
1181 Used for syntax tables, which specify the syntax of a particular
|
|
|
1182 character. Higher-level Lisp functions are provided for
|
|
|
1183 working with syntax tables. The valid values are integers.
|
|
|
1184 @end table
|
|
|
1185
|
|
444
|
1186 @defun char-table-type char-table
|
|
|
1187 This function returns the type of char table @var{char-table}.
|
|
428
|
1188 @end defun
|
|
|
1189
|
|
|
1190 @defun char-table-type-list
|
|
|
1191 This function returns a list of the recognized char table types.
|
|
|
1192 @end defun
|
|
|
1193
|
|
|
1194 @defun valid-char-table-type-p type
|
|
|
1195 This function returns @code{t} if @var{type} if a recognized char table type.
|
|
|
1196 @end defun
|
|
|
1197
|
|
|
1198 @node Working With Char Tables
|
|
|
1199 @subsection Working With Char Tables
|
|
|
1200
|
|
|
1201 @defun make-char-table type
|
|
|
1202 This function makes a new, empty char table of type @var{type}.
|
|
|
1203 @var{type} should be a symbol, one of @code{char}, @code{category},
|
|
|
1204 @code{display}, @code{generic}, or @code{syntax}.
|
|
|
1205 @end defun
|
|
|
1206
|
|
444
|
1207 @defun put-char-table range value char-table
|
|
|
1208 This function sets the value for chars in @var{range} to be @var{value} in
|
|
|
1209 @var{char-table}.
|
|
428
|
1210
|
|
|
1211 @var{range} specifies one or more characters to be affected and should be
|
|
|
1212 one of the following:
|
|
|
1213
|
|
|
1214 @itemize @bullet
|
|
|
1215 @item
|
|
|
1216 @code{t} (all characters are affected)
|
|
|
1217 @item
|
|
|
1218 A charset (only allowed when @sc{mule} support is present)
|
|
|
1219 @item
|
|
|
1220 A vector of two elements: a two-octet charset and a row number
|
|
|
1221 (only allowed when @sc{mule} support is present)
|
|
|
1222 @item
|
|
|
1223 A single character
|
|
|
1224 @end itemize
|
|
|
1225
|
|
444
|
1226 @var{value} must be a value appropriate for the type of @var{char-table}.
|
|
428
|
1227 @end defun
|
|
|
1228
|
|
444
|
1229 @defun get-char-table character char-table
|
|
|
1230 This function finds the value for @var{character} in @var{char-table}.
|
|
428
|
1231 @end defun
|
|
|
1232
|
|
444
|
1233 @defun get-range-char-table range char-table &optional multi
|
|
|
1234 This function finds the value for a range in @var{char-table}. If there is
|
|
428
|
1235 more than one value, @var{multi} is returned (defaults to @code{nil}).
|
|
|
1236 @end defun
|
|
|
1237
|
|
444
|
1238 @defun reset-char-table char-table
|
|
|
1239 This function resets @var{char-table} to its default state.
|
|
428
|
1240 @end defun
|
|
|
1241
|
|
444
|
1242 @defun map-char-table function char-table &optional range
|
|
|
1243 This function maps @var{function} over entries in @var{char-table}, calling
|
|
428
|
1244 it with two args, each key and value in the table.
|
|
|
1245
|
|
|
1246 @var{range} specifies a subrange to map over and is in the same format
|
|
|
1247 as the @var{range} argument to @code{put-range-table}. If omitted or
|
|
|
1248 @code{t}, it defaults to the entire table.
|
|
|
1249 @end defun
|
|
|
1250
|
|
|
1251 @defun valid-char-table-value-p value char-table-type
|
|
|
1252 This function returns non-@code{nil} if @var{value} is a valid value for
|
|
|
1253 @var{char-table-type}.
|
|
|
1254 @end defun
|
|
|
1255
|
|
|
1256 @defun check-valid-char-table-value value char-table-type
|
|
|
1257 This function signals an error if @var{value} is not a valid value for
|
|
|
1258 @var{char-table-type}.
|
|
|
1259 @end defun
|
