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