@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc. 
@c See the file elisp.texi for copying conditions.
@setfilename ../info/strings
@node Strings and Characters, Lists, Numbers, Top
@comment  node-name,  next,  previous,  up
@c @chapter Strings and Characters
@chapter $BJ8;zNs$HJ8;z(B
@c @cindex strings
@c @cindex character arrays
@c @cindex characters
@c @cindex bytes
@cindex $BJ8;zNs(B
@cindex $BJ8;zG[Ns(B
@cindex $BJ8;z(B
@cindex $B%P%$%H(B

@c   A string in Emacs Lisp is an array that contains an ordered sequence
@c of characters.  Strings are used as names of symbols, buffers, and
@c files, to send messages to users, to hold text being copied between
@c buffers, and for many other purposes.  Because strings are so important,
@c Emacs Lisp has many functions expressly for manipulating them.  Emacs
@c Lisp programs use strings more often than individual characters.
Emacs Lisp$B$NJ8;zNs$OJ8;z$N=g=xNs$rJ];}$7$F$$$kG[Ns$G$9!#(B
$BJ8;zNs$O!"%7%s%\%k!"%P%C%U%!!"%U%!%$%k$N$=$l$>$l$NL>A0$H$7$F!"(B
$B%f!<%6!<$X%a%C%;!<%8$rAw$k$?$a!"(B
$B%P%C%U%!4V$G%3%T!<$9$k%F%-%9%H$rJ];}$9$k$?$a!"(B
$B$=$NB>$5$^$6$^$JL\E*$K;H$o$l$^$9!#(B
$BJ8;zNs$O$H$F$b=EMW$J$N$G!"(B
Emacs Lisp$B$K$OJ8;zNs$rA`:n$9$k4X?t$,?tB?$/$"$j$^$9!#(B
Emacs Lisp$B$N%W%m%0%i%`$G$O!"8D!9$NJ8;z$h$j$bJ8;zNs$rB?MQ$7$^$9!#(B

@c   @xref{Strings of Events}, for special considerations for strings of
@c keyboard character events.
$B%-!<%\!<%IJ8;z%$%Y%s%H$rI=$9J8;zNs$K4X$9$kFCJL$JG[N8$K$D$$$F$O!"(B
@xref{Strings of Events}$B!#(B

@menu
* Basics: String Basics.      Basic properties of strings and characters.
* Predicates for Strings::    Testing whether an object is a string or char.
* Creating Strings::          Functions to allocate new strings.
* Modifying Strings::         Altering the contents of an existing string.
* Text Comparison::           Comparing characters or strings.
* String Conversion::         Converting characters or strings and vice versa.
* Formatting Strings::        @code{format}: Emacs's analogue of @code{printf}.
* Case Conversion::           Case conversion functions.
* Case Tables::		      Customizing case conversion.
@end menu

@node String Basics
@c @section String and Character Basics
@section $BJ8;zNs$HJ8;z$N4pK\(B

@c   Strings in Emacs Lisp are arrays that contain an ordered sequence of
@c characters.  Characters are represented in Emacs Lisp as integers;
@c whether an integer is a character or not is determined only by how it is
@c used.  Thus, strings really contain integers.
Emacs Lisp$B$NJ8;zNs$OJ8;z$N=g=xNs$rJ];}$7$F$$$kG[Ns$G$9!#(B
Emacs Lisp$B$G$OJ8;z$r@0?t$GI=8=$7$^$9!#(B
$B@0?t$,J8;z$G$"$k$+$I$&$+$O!"$=$N;H$o$lJ}$+$i$7$+H=CG$G$-$^$;$s!#(B
$B$7$?$,$C$F!"J8;zNs$O!"<B:]$K$O!"@0?t72$rJ];}$7$F$$$k$N$G$9!#(B

@c   The length of a string (like any array) is fixed, and cannot be
@c altered once the string exists.  Strings in Lisp are @emph{not}
@c terminated by a distinguished character code.  (By contrast, strings in
@c C are terminated by a character with @sc{ASCII} code 0.)
$B!JG$0U$NG[Ns$HF1MM$K!KJ8;zNs$ND9$5$O8GDj$5$l$F$$$F!"(B
$BJ8;zNs$r$$$C$?$s:n@.$9$k$HJQ99$G$-$^$;$s!#(B
Lisp$B$NJ8;zNs$OFCJL$JJ8;z%3!<%I$G=*C<$5$l$k$N$G$O(B@emph{$B$"$j$^$;$s(B}$B!#(B
$B!JBP>HE*$K!"(BC$B8@8l$NJ8;zNs$O(B@sc{ASCII}$B%3!<%I(B0$B$G=*C<$5$l$k!#!K(B

@c   Since strings are arrays, and therefore sequences as well, you can
@c operate on them with the general array and sequence functions.
@c (@xref{Sequences Arrays Vectors}.)  For example, you can access or
@c change individual characters in a string using the functions @code{aref}
@c and @code{aset} (@pxref{Array Functions}).
$BJ8;zNs$OG[Ns$G$9$+$i%7!<%1%s%9$G$b$"$j!"(B
$B0lHL$NG[Ns4X?t$d%7!<%1%s%94X?t$GJ8;zNs$rA`:n$G$-$^$9!#(B
$B!J(B@pxref{Sequences Arrays Vectors}$B!#!K(B
$B$?$H$($P!"4X?t(B@code{aref}$B$H(B@code{aset}$B!J(B@pxref{Array Functions}$B!K$r(B
$BMQ$$$F!"J8;zNsFb$N8D!9$NJ8;z$r;2>H$7$?$jJQ99$G$-$^$9!#(B

@c   There are two text representations for non-@sc{ASCII} characters in
@c Emacs strings (and in buffers): unibyte and multibyte (@pxref{Text
@c Representations}).  @sc{ASCII} characters always occupy one byte in a
@c string; in fact, there is no real difference between the two
@c representation for a string which is all @sc{ASCII}.  For most Lisp
@c programming, you don't need to be concerned with these two
@c representations.
Emacs$BJ8;zNs!J$*$h$S%P%C%U%!!KFb$NHs(B@sc{ASCII}$BJ8;z$N%F%-%9%HI=8=$O(B
2$B<oN`$"$j$^$9!#(B
$B%f%K%P%$%H$H%^%k%A%P%$%H$G$9!J(B@pxref{Text Representations}$B!K!#(B
@sc{ASCII}$BJ8;z$O!"J8;zNsFb$G$O$D$M$K(B1$B%P%$%H$r@j$a$^$9!#(B
$B<B:]!"$9$Y$F$,(B@sc{ASCII}$BJ8;z$G$"$kJ8;zNs$G$O!"(B2$B$D$NI=8=$K0c$$$O$"$j$^$;$s!#(B
$B$[$H$s$I$N(BLisp$B%W%m%0%i%`$G$O!"(B
$BFI<T$O$3$l$i$N(B2$B$D$NI=8=$r9MN8$9$kI,MW$O$J$$$G$7$g$&!#(B

@c   Sometimes key sequences are represented as strings.  When a string is
@c a key sequence, string elements in the range 128 to 255 represent meta
@c characters (which are extremely large integers) rather than character
@c codes in the range 128 to 255.
$B%-!<Ns$rJ8;zNs$H$7$FI=8=$9$k$3$H$,$"$j$^$9!#(B
$BJ8;zNs$,%-!<Ns$rI=$9>l9g!"(B128$B$+$i(B255$B$NHO0O$K$"$kJ8;zNs$NMWAG$O!"(B
$B$=$NHO0O$NJ8;z%3!<%I$H$7$F$G$O$J$/!"(B
$B!JHs>o$KBg$-$J@0?t$K$J$k!K%a%?J8;z$rI=8=$7$^$9!#(B

@c   Strings cannot hold characters that have the hyper, super or alt
@c modifiers; they can hold @sc{ASCII} control characters, but no other
@c control characters.  They do not distinguish case in @sc{ASCII} control
@c characters.  If you want to store such characters in a sequence, such as
@c a key sequence, you must use a vector instead of a string.
@c @xref{Character Type}, for more information about representation of meta
@c and other modifiers for keyboard input characters.
$BJ8;zNs$O!"%O%$%Q!<!"%9!<%Q!<!"%"%k%H$N=$>~;R$r;}$DJ8;z$rJ];}$G$-$^$;$s!#(B
$BJ8;zNs$O(B@sc{ASCII}$B%3%s%H%m!<%kJ8;z$rJ];}$G$-$^$9$,!"(B
$B$=$l0J30$N%3%s%H%m!<%kJ8;z$rJ];}$G$-$^$;$s!#(B
$BJ8;zNs$G$O!"(B@sc{ASCII}$B%3%s%H%m!<%kJ8;z$NBgJ8;z>.J8;z$r6hJL$G$-$^$;$s!#(B
$B%-!<Ns$J$I$N$=$N$h$&$JJ8;z$r%7!<%1%s%9$K<}$a$k$K$O!"(B
$BJ8;zNs$N$+$o$j$K%Y%/%H%k$r;H$&I,MW$,$"$j$^$9!#(B
$B%-!<%\!<%IF~NOJ8;z$KBP$9$k%a%?$J$I$N=$>~;R$NI=8=$K$D$$$F$O!"(B
@xref{Character Type}$B!#(B

@c   Strings are useful for holding regular expressions.  You can also
@c match regular expressions against strings (@pxref{Regexp Search}).  The
@c functions @code{match-string} (@pxref{Simple Match Data}) and
@c @code{replace-match} (@pxref{Replacing Match}) are useful for
@c decomposing and modifying strings based on regular expression matching.
$BJ8;zNs$O@55,I=8=$rJ];}$9$k$N$K$bJXMx$G$9!#(B
$BJ8;zNs$KBP$7$F@55,I=8=$N0lCW$r<h$k$3$H$b$G$-$^$9!J(B@pxref{Regexp Search}$B!K!#(B
$B4X?t(B@code{match-string}$B!J(B@pxref{Simple Match Data}$B!K$H(B
@code{replace-match}$B!J(B@pxref{Replacing Match}$B!K$O!"(B
$B@55,I=8=$N0lCW$K4p$E$$$FJ8;zNs$rJ,2r$7$?$jJQ99$9$k$N$KJXMx$G$9!#(B

@c   Like a buffer, a string can contain text properties for the characters
@c in it, as well as the characters themselves.  @xref{Text Properties}.
@c All the Lisp primitives that copy text from strings to buffers or other
@c strings also copy the properties of the characters being copied.
$B%P%C%U%!$HF1MM$K!"J8;zNs$O!"(B
$BJ8;z$=$N$b$N$K2C$($FJ8;zNsFb$NJ8;z$KBP$9$k%F%-%9%HB0@-$rJ];}$G$-$^$9!#(B
@xref{Text Properties}$B!#(B
$BJ8;zNs$+$i%P%C%U%!$dB>$NJ8;zNs$X%F%-%9%H$r%3%T!<$9$k$9$Y$F$N(BLisp$B4pK\4X?t$O!"(B
$B%3%T!<$9$kJ8;z$NB0@-$b%3%T!<$7$^$9!#(B

@c   @xref{Text}, for information about functions that display strings or
@c copy them into buffers.  @xref{Character Type}, and @ref{String Type},
@c for information about the syntax of characters and strings.
@c @xref{Non-ASCII Characters}, for functions to convert between text
@c representations and encode and decode character codes.
$BJ8;zNs$rI=<($7$?$j%P%C%U%!$X%3%T!<$9$k4X?t$K$D$$$F$O!"(B@xref{Text}$B!#(B
$BJ8;z$HJ8;zNs$N9=J8$K$D$$$F$O!"(B@ref{Character Type}$B$H(B@xref{String Type}$B!#(B
$B%F%-%9%HI=8=$rJQ49$7$?$j!"J8;z%3!<%I$rId9f2=!?I|9f2=$9$k4X?t$K$D$$$F$O!"(B
@xref{Non-ASCII Characters}$B!#(B

@node Predicates for Strings
@c @section The Predicates for Strings
@section $BJ8;zNs8~$1$N=R8l(B

@c For more information about general sequence and array predicates,
@c see @ref{Sequences Arrays Vectors}, and @ref{Arrays}.
$B0lHL$N%7!<%1%s%9$dG[Ns$KBP$9$k=R8l$K$D$$$F>\$7$/$O!"(B
@ref{Sequences Arrays Vectors}$B$H(B@xref{Arrays}$B!#(B

@defun stringp object
@c This function returns @code{t} if @var{object} is a string, @code{nil}
@c otherwise.
$B$3$N4X?t$O!"(B@var{object}$B$,J8;zNs$J$i$P(B@code{t}$B$rJV$7!"(B
$B$5$b$J$1$l$P(B@code{nil}$B$rJV$9!#(B
@end defun

@defun char-or-string-p object
@c This function returns @code{t} if @var{object} is a string or a
@c character (i.e., an integer), @code{nil} otherwise.
$B$3$N4X?t$O!"(B@var{object}$B$,J8;zNs$+J8;z!J$D$^$j!"@0?t!K$J$i$P(B
@code{t}$B$rJV$7!"$5$b$J$1$l$P(B@code{nil}$B$rJV$9!#(B
@end defun

@node Creating Strings
@c @section Creating Strings
@section $BJ8;zNs$N:n@.(B

@c   The following functions create strings, either from scratch, or by
@c putting strings together, or by taking them apart.
$B0J2<$N4X?t$O!"?7$?$KJ8;zNs$r:n@.$7$?$j!"(B
$BJ8;zNs$rO"7k$7$?$jJ,2r$7$FJ8;zNs$r:n@.$7$^$9!#(B

@defun make-string count character
@c This function returns a string made up of @var{count} repetitions of
@c @var{character}.  If @var{count} is negative, an error is signaled.
$B$3$N4X?t$O!"J8;z(B@var{character}$B$r(B@var{count}$B2s7+$jJV$7$F:n@.$7$?J8;zNs$rJV$9!#(B
@var{count}$B$,Ii$G$"$k$H%(%i!<$rDLCN$9$k!#(B

@example
(make-string 5 ?x)
     @result{} "xxxxx"
(make-string 0 ?x)
     @result{} ""
@end example

@c   Other functions to compare with this one include @code{char-to-string}
@c (@pxref{String Conversion}), @code{make-vector} (@pxref{Vectors}), and
@c @code{make-list} (@pxref{Building Lists}).
$B$3$N4X?t$KBPHf$9$k$b$N$K!"(B
@code{char-to-string}$B!J(B@pxref{String Conversion}$B!K!"(B
@code{make-vector}$B!J(B@pxref{Vectors}$B!K!"(B
@code{make-list}$B!J(B@pxref{Building Lists}$B!K$J$I$,$"$k!#(B
@end defun

@defun string &rest characters
@tindex string
@c This returns a string containing the characters @var{characters}.
$B$3$l$O!"J#?t8D$NJ8;z72(B@var{characters}$B$,F~$C$?J8;zNs$rJV$9!#(B

@example
(string ?a ?b ?c)
     @result{} "abc"
@end example
@end defun

@defun substring string start &optional end
@c This function returns a new string which consists of those characters
@c from @var{string} in the range from (and including) the character at the
@c index @var{start} up to (but excluding) the character at the index
@c @var{end}.  The first character is at index zero.
$B$3$N4X?t$O!"(B@var{string}$B$N(B@var{start}$B$+$i(B
@var{end}$B!J$ND>A0!K$^$G$NHO0O$K$"$kJ8;z$+$i@.$k?7$?$JJ8;zNs$rJV$9!#(B
$B@hF,$NJ8;z$r(B0$B$GE:;zIU$1$9$k!#(B

@example
@group
(substring "abcdefg" 0 3)
     @result{} "abc"
@end group
@end example

@noindent
@c Here the index for @samp{a} is 0, the index for @samp{b} is 1, and the
@c index for @samp{c} is 2.  Thus, three letters, @samp{abc}, are copied
@c from the string @code{"abcdefg"}.  The index 3 marks the character
@c position up to which the substring is copied.  The character whose index
@c is 3 is actually the fourth character in the string.
$B$3$3$G!"(B@samp{a}$B$NE:;z$O(B0$B!"(B@samp{b}$B$NE:;z$O(B1$B!"(B@samp{c}$B$NE:;z$O(B2$B$G$"$k!#(B
$B$7$?$,$C$F!"J8;zNs(B@code{"abcdefg"}$B$+$i(B3$BJ8;z(B@samp{abc}$B$r%3%T!<$9$k!#(B
$BE:;z(B3$B$O%3%T!<$9$kItJ,J8;zNs$N6-3&$NJ8;z0LCV$rI=$9!#(B
$BE:;z$,(B3$B$G$"$kJ8;z$O!"<B:]$K$OJ8;zNsFb$N(B4$BHVL\$NJ8;z$G$"$k!#(B

@c A negative number counts from the end of the string, so that @minus{}1
@c signifies the index of the last character of the string.  For example: 
$BIi$N?t$OJ8;zNs$NKvHx$+$i?t$($k!#(B
$B$7$?$,$C$F!"(B@minus{}1$B$OJ8;zNs$N:G8e$NJ8;z$NE:;z$G$"$k!#(B
$B$?$H$($P!"(B

@example
@group
(substring "abcdefg" -3 -1)
     @result{} "ef"
@end group
@end example

@noindent
@c In this example, the index for @samp{e} is @minus{}3, the index for
@c @samp{f} is @minus{}2, and the index for @samp{g} is @minus{}1.
@c Therefore, @samp{e} and @samp{f} are included, and @samp{g} is excluded.
$B$3$NNc$G$O!"(B@samp{e}$B$NE:;z$O(B@minus{}3$B!"(B@samp{f}$B$NE:;z$O(B@minus{}2$B!"(B
@samp{g}$B$NE:;z$O(B@minus{}1$B$G$"$k!#(B
$B$7$?$,$C$F!"(B@samp{e}$B$H(B@samp{f}$B$r4^$`$,(B@samp{g}$B$O4^$^$J$$!#(B

@c When @code{nil} is used as an index, it stands for the length of the
@c string.  Thus,
$BE:;z$K(B@code{nil}$B$r;H$&$H!"J8;zNs$ND9$5$r0UL#$9$k!#(B
$B$7$?$,$C$F!"$D$.$N$h$&$K$J$k!#(B

@example
@group
(substring "abcdefg" -3 nil)
     @result{} "efg"
@end group
@end example

@c Omitting the argument @var{end} is equivalent to specifying @code{nil}.
@c It follows that @code{(substring @var{string} 0)} returns a copy of all
@c of @var{string}.
$B0z?t(B@var{end}$B$r>JN,$9$k$3$H$O!"(B@code{nil}$B$r;XDj$9$k$3$H$HEy2A$G$"$k!#(B
$B$=$N$?$a!"(B@code{(substring @var{string} 0)}$B$O!"(B
@var{string}$BA4BN$r%3%T!<$7$?$b$N$rJV$9!#(B

@example
@group
(substring "abcdefg" 0)
     @result{} "abcdefg"
@end group
@end example

@noindent
@c But we recommend @code{copy-sequence} for this purpose (@pxref{Sequence
@c Functions}).
$B$7$+$7!"$3$N$h$&$JL\E*$K$O(B@code{copy-sequence}$B$r4+$a$k(B
$B!J(B@pxref{Sequence Functions}$B!K!#(B

@c If the characters copied from @var{string} have text properties, the
@c properties are copied into the new string also.  @xref{Text Properties}.
@var{string}$B$+$i%3%T!<$7$?J8;z$K%F%-%9%HB0@-$,$"$l$P!"(B
$B?7$?$JJ8;zNs$K$b$=$N%F%-%9%HB0@-$r%3%T!<$9$k!#(B
@pxref{Text Properties}$B!#(B

@c @code{substring} also allows vectors for the first argument.
@c For example:
@code{substring}$B$OBh(B1$B0z?t$H$7$F%Y%/%H%k$b<u$1IU$1$k!#(B
$B$?$H$($P!"$D$.$N$H$*$j!#(B

@example
(substring [a b (c) "d"] 1 3)
     @result{} [b (c)]
@end example

@c A @code{wrong-type-argument} error is signaled if either @var{start} or
@c @var{end} is not an integer or @code{nil}.  An @code{args-out-of-range}
@c error is signaled if @var{start} indicates a character following
@c @var{end}, or if either integer is out of range for @var{string}.
@var{start}$B$d(B@var{end}$B$,@0?t$G$b(B@code{nil}$B$G$b$J$$$H!"(B
$B%(%i!<(B@code{wrong-type-argument}$B$rDLCN$9$k!#(B
@var{start}$B$,(B@var{end}$B$h$j$&$7$m$NJ8;z$r;X$7$F$$$?$j!"(B
$B$$$:$l$+$N@0?t$,(B@var{string}$B$NHO0O30$G$"$k$H(B
$B%(%i!<(B@code{args-out-of-range}$B$rDLCN$9$k!#(B

@c Contrast this function with @code{buffer-substring} (@pxref{Buffer
@c Contents}), which returns a string containing a portion of the text in
@c the current buffer.  The beginning of a string is at index 0, but the
@c beginning of a buffer is at index 1.
$B$3$N4X?t$HBP>HE*$J$N$,(B@code{buffer-substring}
$B!J(B@pxref{Buffer Contents}$B!K$G$"$j!"(B
$B%+%l%s%H%P%C%U%!Fb$N%F%-%9%H$N0lIt$r<}$a$?J8;zNs$rJV$9!#(B
$BJ8;zNs$N@hF,$O(B0$B$GE:;zIU$1$9$k$,!"%P%C%U%!$N@hF,$O(B1$B$GE:;zIU$1$9$k!#(B
@end defun

@defun concat &rest sequences
@c @cindex copying strings
@c @cindex concatenating strings
@cindex $BJ8;zNs$N%3%T!<(B
@cindex $B%3%T!<!"J8;zNs(B
@cindex $BJ8;zNs$NO"7k(B
@cindex $BO"7k!"J8;zNs(B
@c This function returns a new string consisting of the characters in the
@c arguments passed to it (along with their text properties, if any).  The
@c arguments may be strings, lists of numbers, or vectors of numbers; they
@c are not themselves changed.  If @code{concat} receives no arguments, it
@c returns an empty string.
$B$3$N4X?t$O!"EO$7$?0z?t$NJ8;z$+$i@.$k(B
$B!J%F%-%9%HB0@-$,$"$l$P$=$l$b4^$a$F!K?7$?$JJ8;zNs$rJV$9!#(B
$B0z?t$O!"J8;zNs!"?t$N%j%9%H!"?t$N%Y%/%H%k$G$"$k!#(B
$B0z?t<+?H$OJQ99$7$J$$!#(B
@code{concat}$B$K0z?t$r;XDj$7$J$$$H6uJ8;zNs$rJV$9!#(B

@example
(concat "abc" "-def")
     @result{} "abc-def"
(concat "abc" (list 120 121) [122])
     @result{} "abcxyz"
@c ;; @r{@code{nil} is an empty sequence.}
;; @r{@code{nil}$B$O6u%7!<%1%s%9(B}
(concat "abc" nil "-def")
     @result{} "abc-def"
(concat "The " "quick brown " "fox.")
     @result{} "The quick brown fox."
(concat)
     @result{} ""
@end example

@noindent
@c The @code{concat} function always constructs a new string that is
@c not @code{eq} to any existing string.
$B4X?t(B@code{concat}$B$O!"(B
$B4{B8$NJ8;zNs$H(B@code{eq}$B$G$O$J$$?7$?$JJ8;zNs$r$D$M$K:n$j=P$9!#(B

@c When an argument is an integer (not a sequence of integers), it is
@c converted to a string of digits making up the decimal printed
@c representation of the integer.  @strong{Don't use this feature; we plan
@c to eliminate it.  If you already use this feature, change your programs
@c now!}  The proper way to convert an integer to a decimal number in this
@c way is with @code{format} (@pxref{Formatting Strings}) or
@c @code{number-to-string} (@pxref{String Conversion}).
$B0z?t$,!J@0?t$N%7!<%1%s%9$G$O$J$/!K@0?t$G$"$k$H!"(B
$B$=$N@0?t$NI=<(I=8=$r9=@.$9$kJ8;zNs$KJQ49$9$k!#(B
@strong{$B$3$N5!G=$r;H$o$J$$$G$[$7$$!#(B
$B:o=|$9$kM=Dj$G$"$k!#(B
$BFI<T$,$3$N5!G=$r;H$C$F$$$?$i!":#$9$0%W%m%0%i%`$rD>$9$3$H!*(B}@code{ }
$B@0?t$r$3$N$h$&$J(B10$B?J?t$KJQ49$9$k@5$7$$J}K!$O!"(B
@code{format}$B!J(B@pxref{Formatting Strings}$B!K$d(B
@code{number-to-string}$B!J(B@pxref{String Conversion}$B!K$r;H$&$3$H$G$"$k!#(B

@example
@group
(concat 137)
     @result{} "137"
(concat 54 321)
     @result{} "54321"
@end group
@end example

@c For information about other concatenation functions, see the
@c description of @code{mapconcat} in @ref{Mapping Functions},
@c @code{vconcat} in @ref{Vectors}, and @code{append} in @ref{Building
@c Lists}.
$BB>$NO"7k4X?t$K$D$$$F$O!"(B
@ref{Mapping Functions}$B$N(B@code{mapconcat}$B!"(B
@ref{Vectors}$B$N(B@code{vconcat}$B!"(B
@ref{Building Lists}$B$N(B@code{append}$B$r;2>H!#(B
@end defun

@defun split-string string separators
@tindex split-string
@c Split @var{string} into substrings in between matches for the regular
@c expression @var{separators}.  Each match for @var{separators} defines a
@c splitting point; the substrings between the splitting points are made
@c into a list, which is the value.  If @var{separators} is @code{nil} (or
@c omitted), the default is @code{"[ \f\t\n\r\v]+"}.
@var{string}$B$r@55,I=8=(B@var{separators}$B$N0lCW2U=j$G6h@Z$C$F(B
$BItJ,J8;zNs$KJ,2r$9$k!#(B
@var{separators}$B$K0lCW$9$k$=$l$>$l$NItJ,$,J,3d2U=j$rDj5A$9$k!#(B
$BJ,3d2U=j$N$"$$$@$K$"$kItJ,J8;zNs$r%j%9%H$K$^$H$a!"$3$l$rCM$H$9$k!#(B
@var{separators}$B$,(B@code{nil}$B$G$"$k!J$D$^$j!">JN,$9$k!K$H!"(B
$B%G%U%)%k%H$O(B@code{"[ \f\t\n\r\v]+"}$B$G$"$k!#(B

@c For example,
$B$?$H$($P!"$D$.$N$h$&$K$J$k!#(B

@example
(split-string "Soup is good food" "o")
@result{} ("S" "up is g" "" "d f" "" "d")
(split-string "Soup is good food" "o+")
@result{} ("S" "up is g" "d f" "d")
@end example

@c When there is a match adjacent to the beginning or end of the string,
@c this does not cause a null string to appear at the beginning or end
@c of the list:
$BJ8;zNs$N@hF,$dKvHx$G0lCW$7$?>l9g$K$O!"(B
$B%j%9%H$N@hF,$dKvHx$K6uJ8;zNs$O8=$l$J$$!#(B

@example
(split-string "out to moo" "o+")
@result{} ("ut t" " m")
@end example

@c Empty matches do count, when not adjacent to another match:
$B6u$N0lCW2U=j$O!"$=$l$i$,O"B3$7$F$$$J$$8B$jJ,3dE@$K$J$k!#(B

@example
(split-string "Soup is good food" "o*")
@result{}("S" "u" "p" " " "i" "s" " " "g" "d" " " "f" "d")
(split-string "Nice doggy!" "")
@result{}("N" "i" "c" "e" " " "d" "o" "g" "g" "y" "!")
@end example
@end defun

@node Modifying Strings
@c @section Modifying Strings
@section $BJ8;zNs$NJQ99(B

@c   The most basic way to alter the contents of an existing string is with
@c @code{aset} (@pxref{Array Functions}).  @code{(aset @var{string}
@c @var{idx} @var{char})} stores @var{char} into @var{string} at index
@c @var{idx}.  Each character occupies one or more bytes, and if @var{char}
@c needs a different number of bytes from the character already present at
@c that index, @code{aset} signals an error.
$B4{B8$NJ8;zNs$NFbMF$rJQ99$9$k$b$C$H$b4pK\E*$JJ}K!$O!"(B
@code{aset}$B!J(B@pxref{Array Functions}$B!K$r;H$&$3$H$G$9!#(B
@code{(aset @var{string} @var{idx} @var{char})}$B$O!"(B
@var{string}$B$NE:;z(B@var{idx}$B0LCV$K(B@var{char}$B$r3JG<$7$^$9!#(B
$B3FJ8;z$O(B1$B%P%$%H0J>e$r@j$a$^$9!#(B
@var{char}$B$,I,MW$H$9$k%P%$%H?t$,;XDj$7$?E:;z0LCV$NJ8;z$,@j$a$k%P%$%H?t$H(B
$B0[$J$k>l9g$K$O!"(B@code{aset}$B$O%(%i!<$rDLCN$7$^$9!#(B

@c   A more powerful function is @code{store-substring}:
$B$h$j6/NO$J4X?t$O(B@code{store-substring}$B$G$9!#(B

@defun store-substring string idx obj
@tindex store-substring
@c This function alters part of the contents of the string @var{string}, by
@c storing @var{obj} starting at index @var{idx}.  The argument @var{obj}
@c may be either a character or a (smaller) string.
$B$3$N4X?t$O!"J8;zNs(B@var{string}$B$NE:;z(B@var{idx}$B0LCV$+$i;O$^$kItJ,$K(B@var{obj}$B$r(B
$B3JG<$9$k$3$H$G!"J8;zNs(B@var{string}$B$NFbMF$N0lItJ,$rJQ99$9$k!#(B
$B0z?t(B@var{obj}$B$OJ8;z$G$"$k$+!J$h$j>.$5$J!KJ8;zNs!#(B

@c Since it is impossible to change the length of an existing string, it is
@c an error if @var{obj} doesn't fit within @var{string}'s actual length,
@c of if any new character requires a different number of bytes from the
@c character currently present at that point in @var{string}.
$B4{B8$NJ8;zNs$ND9$5$rJQ99$9$k$3$H$OIT2DG=$J$N$G!"(B
$B?7$?$JJ8;z$KI,MW$J%P%$%H?t$,(B@var{string}$B$NEv3:2U=j$NJ8;z$N%P%$%H?t$H(B
$B0[$J$k$J$I$7$F!"(B
@var{obj}$B$,(B@var{string}$B$N<B:]$ND9$5$K<}$^$i$J$$$H$-$K$O%(%i!<$G$"$k!#(B
@end defun

@need 2000
@node Text Comparison
@c @section Comparison of Characters and Strings
@section $BJ8;z$HJ8;zNs$NHf3S(B
@c @cindex string equality
@cindex $BJ8;zNs$NF1CM@-(B
@cindex $BF1CM@-!"J8;zNs(B

@defun char-equal character1 character2
@c This function returns @code{t} if the arguments represent the same
@c character, @code{nil} otherwise.  This function ignores differences
@c in case if @code{case-fold-search} is non-@code{nil}.
$B$3$N4X?t$O!"0z?t$,F1$8J8;z$rI=$7$F$$$l$P(B@code{t}$B$rJV$7!"(B
$B$5$b$J$1$l$P(B@code{nil}$B$rJV$9!#(B
@code{case-fold-search}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B$3$N4X?t$OBgJ8;z>.J8;z$N0c$$$r6hJL$7$J$$!#(B

@example
(char-equal ?x ?x)
     @result{} t
(let ((case-fold-search nil))
  (char-equal ?x ?X))
     @result{} nil
@end example
@end defun

@defun string= string1 string2
@c This function returns @code{t} if the characters of the two strings
@c match exactly; case is significant.
$B$3$N4X?t$O!"(B2$B$D$NJ8;zNs$N3FJ8;z$,@53N$K0lCW$9$l$P(B@code{t}$B$rJV$9!#(B
$BBgJ8;z>.J8;z$r6hJL$9$k!#(B

@example
(string= "abc" "abc")
     @result{} t
(string= "abc" "ABC")
     @result{} nil
(string= "ab" "ABC")
     @result{} nil
@end example

@c The function @code{string=} ignores the text properties of the two
@c strings.  When @code{equal} (@pxref{Equality Predicates}) compares two
@c strings, it uses @code{string=}.
$B4X?t(B@code{string=}$B$O(B2$B$D$NJ8;zNs$N%F%-%9%HB0@-$rL5;k$9$k!#(B
@code{equal}$B!J(B@pxref{Equality Predicates}$B!K$,(B2$B$D$NJ8;zNs$rHf3S$9$k:]$K$O!"(B
@code{string=}$B$r;H$&!#(B

@c If the strings contain non-@sc{ASCII} characters, and one is unibyte
@c while the other is multibyte, then they cannot be equal.  @xref{Text
@c Representations}.
$BJ8;zNs$KHs(B@sc{ASCII}$BJ8;z$,4^$^$l!"(B
$B0lJ}$,%f%K%P%$%H$G$"$jB>J}$,%^%k%A%P%$%H$G$"$k>l9g!"(B
$B$=$l$i$,Ey$7$$$3$H$O$J$$!#(B
@pxref{Text Representations}$B!#(B
@end defun

@defun string-equal string1 string2
@c @code{string-equal} is another name for @code{string=}.
@code{string-equal}$B$O(B@code{string=}$B$NJLL>!#(B
@end defun

@c @cindex lexical comparison
@cindex $B<-=q<0=g$NHf3S(B
@cindex $BHf3S!"<-=q<0=g(B
@defun string< string1 string2
@c @c (findex string< causes problems for permuted index!!)
@c This function compares two strings a character at a time.  First it
@c scans both the strings at once to find the first pair of corresponding
@c characters that do not match.  If the lesser character of those two is
@c the character from @var{string1}, then @var{string1} is less, and this
@c function returns @code{t}.  If the lesser character is the one from
@c @var{string2}, then @var{string1} is greater, and this function returns
@c @code{nil}.  If the two strings match entirely, the value is @code{nil}.
$B$3$N4X?t$O(B2$B$D$NJ8;zNs$r(B1$BJ8;z$:$DHf3S$9$k!#(B
$B$^$:!"J8;zNs$rAv::$7!"BP1~$9$kJ8;zF1;N$NBP$G0lCW$7$J$$$b$N$rC5$9!#(B
$B$=$N$h$&$JBP$NJ8;z$N>.$5$$$[$&$,(B@var{string1}$B$NJ8;z$G$"$k$J$i$P!"(B
@var{string1}$B$,>.$5$/!"$3$N4X?t$O(B@code{t}$B$rJV$9!#(B
$BJ8;z$N>.$5$$$[$&$,(B@var{string2}$B$NJ8;z$G$"$k$J$i$P!"(B
@var{string1}$B$,Bg$-$/!"$3$N4X?t$O(B@code{nil}$B$rJV$9!#(B
2$B$D$NJ8;zNs$,40A4$K0lCW$9$k>l9g!"CM$O(B@code{nil}$B$G$"$k!#(B

@c Pairs of characters are compared according to their character codes.
@c Keep in mind that lower case letters have higher numeric values in the
@c @sc{ASCII} character set than their upper case counterparts; digits and
@c many punctuation characters have a lower numeric value than upper case
@c letters.  An @sc{ASCII} character is less than any non-@sc{ASCII}
@c character; a unibyte non-@sc{ASCII} character is always less than any
@c multibyte non-@sc{ASCII} character (@pxref{Text Representations}).
$BJ8;z$NBP$O!"$=$l$i$NJ8;z%3!<%I$GHf3S$9$k!#(B
@sc{ASCII}$BJ8;z=89g$G$O!">.J8;z$OBgJ8;z$h$jBg$-$J?tCM$G$"$j!"(B
$B?t;zJ8;z$dB?$/$N6gFIE@J8;z$OBgJ8;z$h$j>.$5$J?tCM$G$"$k$3$H$KCm0U!#(B
@sc{ASCII}$BJ8;z$O$I$s$JHs(B@sc{ASCII}$BJ8;z$h$j$b>.$5$$!#(B
$B%f%K%P%$%HHs(B@sc{ASCII}$BJ8;z$O%^%k%A%P%$%HHs(B@sc{ASCII}$BJ8;z$h$j$b$D$M$K>.$5$$!#(B
$B!J(B@pxref{Text Representations}$B!K!#(B

@example
@group
(string< "abc" "abd")
     @result{} t
(string< "abd" "abc")
     @result{} nil
(string< "123" "abc")
     @result{} t
@end group
@end example

@c When the strings have different lengths, and they match up to the
@c length of @var{string1}, then the result is @code{t}.  If they match up
@c to the length of @var{string2}, the result is @code{nil}.  A string of
@c no characters is less than any other string.
$BJ8;zNs$ND9$5$,0[$J$j(B@var{string1}$B$ND9$5$^$G0lCW$9$k>l9g!"(B
$B7k2L$O(B@code{t}$B$G$"$k!#(B
@var{string2}$B$ND9$5$^$G0lCW$9$k>l9g!"7k2L$O(B@code{nil}$B$G$"$k!#(B
$B6uJ8;zNs$OB>$N$I$s$JJ8;zNs$h$j$b>.$5$$!#(B

@example
@group
(string< "" "abc")
     @result{} t
(string< "ab" "abc")
     @result{} t
(string< "abc" "")
     @result{} nil
(string< "abc" "ab")
     @result{} nil
(string< "" "")
     @result{} nil 
@end group
@end example
@end defun

@defun string-lessp string1 string2
@c @code{string-lessp} is another name for @code{string<}.
@code{string-lessp}$B$O(B@code{string<}$B$NJLL>!#(B
@end defun

@defun compare-strings string1 start1 end1 string2 start2 end2 &optional ignore-case
@tindex compare-strings
@c This function compares a specified part of @var{string1} with a
@c specified part of @var{string2}.  The specified part of @var{string1}
@c runs from index @var{start1} up to index @var{end1} (default, the end of
@c the string).  The specified part of @var{string2} runs from index
@c @var{start2} up to index @var{end2} (default, the end of the string).
$B$3$N4X?t$O!"(B@var{string1}$B$N;XDjItJ,$H(B@var{string2}$B$N;XDjItJ,$rHf3S$9$k!#(B
@var{string1}$B$N;XDjItJ,$O!"(B
$BE:;z(B@var{start1}$B0LCV$+$i;O$^$jE:;z(B@var{end1}$B0LCV$^$G$G$"$k(B
$B!J%G%U%)%k%H$OJ8;zNs$NKvHx!K!#(B
@var{string2}$B$N;XDjItJ,$O!"(B
$BE:;z(B@var{start2}$B0LCV$+$i;O$^$jE:;z(B@var{end2}$B0LCV$^$G$G$"$k(B
$B!J%G%U%)%k%H$OJ8;zNs$NKvHx!K!#(B

@c The strings are both converted to multibyte for the comparison
@c (@pxref{Text Representations}) so that a unibyte string can be equal to
@c a multibyte string.  If @var{ignore-case} is non-@code{nil}, then case
@c is ignored, so that upper case letters can be equal to lower case letters.
$B$I$A$i$NJ8;zNs$bHf3S$N$?$a$K%^%k%A%P%$%H$KJQ49$9$k$N$G(B
$B!J(B@pxref{Text Representations}$B!K!"(B
$B%f%K%P%$%HJ8;zNs$H%^%k%A%P%$%H$,Ey$7$/$J$k>l9g$b$"$k!#(B
@var{ignore-case}$B$,(B@code{nil}$B$G$J$1$l$P!"BgJ8;z>.J8;z$r6hJL$7$J$$$N$G!"(B
$BBgJ8;z$O>.J8;z$KEy$7$/$J$k(B

@c If the specified portions of the two strings match, the value is
@c @code{t}.  Otherwise, the value is an integer which indicates how many
@c leading characters agree, and which string is less.  Its absolute value
@c is one plus the number of characters that agree at the beginning of the
@c two strings.  The sign is negative if @var{string1} (or its specified
@c portion) is less.
2$B$D$NJ8;zNs$N;XDjItJ,$,0lCW$9$l$P!"CM$O(B@code{t}$B!#(B
$B$5$b$J$1$l$P!"CM$O2?J8;zL\$^$G$,0lCW$7$F$I$A$i$NJ8;zNs$,>.$5$$$+$r<($9!#(B
$B$=$N@dBPCM$O!"(B2$B$D$NJ8;zNs$N;O$a$+$i0lCW$7$?J8;z$N8D?t$K(B1$B$r2C$($?$b$N!#(B
@var{string1}$B!J$N;XDjItJ,!K$,>.$5$$$J$i$PId9f$OIi$K$J$k!#(B
@end defun

@defun assoc-ignore-case key alist
@tindex assoc-ignore-case
@c This function works like @code{assoc}, except that @var{key} must be a
@c string, and comparison is done using @code{compare-strings}.
@c Case differences are ignored in this comparison.
$B$3$N4X?t$O!"(B@code{assoc}$B$HF1MM$KF0:n$9$k$,!"(B
@var{key}$B$OJ8;zNs$G$"$kI,MW$,$"$j!"(B
@code{compare-strings}$B$rMQ$$$FHf3S$9$kE@$,0[$J$k!#(B
$BBgJ8;z>.J8;z$r6hJL$7$J$$$GHf3S$9$k!#(B
@end defun

@defun assoc-ignore-representation key alist
@tindex assoc-ignore-representation
@c This function works like @code{assoc}, except that @var{key} must be a
@c string, and comparison is done using @code{compare-strings}.
@c Case differences are significant.
$B$3$N4X?t$O!"(B@code{assoc}$B$HF1MM$KF0:n$9$k$,!"(B
@var{key}$B$OJ8;zNs$G$"$kI,MW$,$"$j!"(B
@code{compare-strings}$B$rMQ$$$FHf3S$9$kE@$,0[$J$k!#(B
$BBgJ8;z>.J8;z$r6hJL$7$FHf3S$9$k!#(B
@end defun

@c   See also @code{compare-buffer-substrings} in @ref{Comparing Text}, for
@c a way to compare text in buffers.  The function @code{string-match},
@c which matches a regular expression against a string, can be used
@c for a kind of string comparison; see @ref{Regexp Search}.
$B%P%C%U%!Fb$N%F%-%9%H$rHf3S$9$k(B
@ref{Comparing Text}$B$N(B@code{compare-buffer-substrings}$B$b;2>H$7$F$/$@$5$$!#(B
$BJ8;zNs$KBP$7$F@55,I=8=$N0lCW$r<h$k4X?t(B@code{string-match}$B$O!"(B
$B$"$k<o$NJ8;zNsHf3S$K;H$($^$9!#(B
@xref{Regexp Search}$B!#(B

@node String Conversion
@comment  node-name,  next,  previous,  up
@c @section Conversion of Characters and Strings
@section $BJ8;z$HJ8;zNs$NJQ49(B
@c @cindex conversion of strings
@cindex $BJ8;z$HJ8;zNs$NJQ49(B
@cindex $BJQ49!"J8;z$HJ8;zNs(B

@c   This section describes functions for conversions between characters,
@c strings and integers.  @code{format} and @code{prin1-to-string}
@c (@pxref{Output Functions}) can also convert Lisp objects into strings.
@c @code{read-from-string} (@pxref{Input Functions}) can ``convert'' a
@c string representation of a Lisp object into an object.  The functions
@c @code{string-make-multibyte} and @code{string-make-unibyte} convert the
@c text representation of a string (@pxref{Converting Representations}).
$BK\@a$G$O!"J8;z$dJ8;zNs$H@0?t$N$"$$$@$NJQ494X?t$K$D$$$F@bL@$7$^$9!#(B
@code{format}$B$H(B@code{prin1-to-string}$B!J(B@pxref{Output Functions}$B!K$O!"(B
Lisp$B%*%V%8%'%/%H$rJ8;zNs$KJQ49$9$k$?$a$K;H$($^$9!#(B
@code{read-from-string}$B!J(B@pxref{Input Functions}$B!K$O!"(B
Lisp$B%*%V%8%'%/%H$NJ8;zNsI=8=$r%*%V%8%'%/%H$K!XJQ49!Y$G$-$^$9!#(B
$B4X?t(B@code{string-make-multibyte}$B$H(B@code{string-make-unibyte}$B$O!"(B
$BJ8;zNs$N%F%-%9%HI=8=$rJQ49$7$^$9!J(B@pxref{Converting Representations}$B!K!#(B

@c   @xref{Documentation}, for functions that produce textual descriptions
@c of text characters and general input events
@c (@code{single-key-description} and @code{text-char-description}).  These
@c functions are used primarily for making help messages.
$B%F%-%9%HJ8;z$H0lHL$NF~NO%$%Y%s%H$N%F%-%9%HI=8=$r@8@.$9$k4X?t(B
$B!J(B@code{single-key-description}$B$H(B@code{text-char-description}$B!K$K$D$$$F$O!"(B
@xref{Documentation}$B!#(B
$B$3$l$i$N4X?t$O!"<g$K!"%X%k%W%a%C%;!<%8$N:n@.$K;H$$$^$9!#(B

@defun char-to-string character
@c @cindex character to string
@cindex $BJ8;z$+$iJ8;zNs$X(B
@c This function returns a new string containing one character,
@c @var{character}.  This function is semi-obsolete because the function
@c @code{string} is more general.  @xref{Creating Strings}.
$B$3$N4X?t$O!"(B1$B$D$NJ8;z(B@var{character}$B$@$1$r4^$`?7$?$JJ8;zNs$rJV$9!#(B
$B4X?t(B@code{string}$B$N$[$&$,$h$jHFMQ$G$"$k$N$G!"(B
$B$3$N4X?t$O$[$\GQ$l$F$$$k!#(B
@pxref{Creating Strings}$B!#(B
@end defun

@defun string-to-char string
@c @cindex string to character
@cindex $BJ8;zNs$+$iJ8;z$X(B
@c   This function returns the first character in @var{string}.  If the
@c string is empty, the function returns 0.  The value is also 0 when the
@c first character of @var{string} is the null character, @sc{ASCII} code
@c 0.
$B$3$N4X?t$O!"(B@var{string}$B$N@hF,J8;z$rJV$9!#(B
$BJ8;zNs$,6u$G$"$k$H4X?t$O(B0$B$rJV$9!#(B
$BJ8;zNs(B@var{string}$B$N@hF,J8;z$,!"(B@sc{ASCII}$B%3!<%I$,(B0$B$N%J%kJ8;z$G$"$k$H$-$b!"(B
$BCM$O(B0$B$G$"$k!#(B

@example
(string-to-char "ABC")
     @result{} 65
(string-to-char "xyz")
     @result{} 120
(string-to-char "")
     @result{} 0
(string-to-char "\000")
     @result{} 0
@end example

@c This function may be eliminated in the future if it does not seem useful
@c enough to retain.
$B$3$N4X?t$O!"B8B3$5$;$k$[$IM-MQ$G$J$1$l$P!">-Mh!"<h$j=|$/$+$b$7$l$J$$!#(B
@end defun

@defun number-to-string number
@c @cindex integer to string
@c @cindex integer to decimal
@cindex $B@0?t$+$iJ8;zNs$X(B
@cindex $B@0?t$N(B10$B?JI=5-(B
@c This function returns a string consisting of the printed
@c representation of @var{number}, which may be an integer or a floating
@c point number.  The value starts with a sign if the argument is
@c negative.
$B$3$N4X?t$O!"(B@var{number}$B$NI=<(I=8=$G$"$kJ8;zNs$rJV$9!#(B
@var{number}$B$O@0?t$+IbF0>.?tE@?t!#(B
$B0z?t$,Ii$G$"$l$PCM$NJ8;zNs$OId9f$G;O$^$k!#(B

@example
(number-to-string 256)
     @result{} "256"
(number-to-string -23)
     @result{} "-23"
(number-to-string -23.5)
     @result{} "-23.5"
@end example

@c @cindex int-to-string
@c = $B%?%$%]!)(B
@findex int-to-string
@c @code{int-to-string} is a semi-obsolete alias for this function.
@code{int-to-string}$B$O!"$3$N4X?t$N$[$\GQ$l$F$$$kJLL>!#(B

@c See also the function @code{format} in @ref{Formatting Strings}.
@ref{Formatting Strings}$B$N(B@code{format}$B$b;2>H!#(B
@end defun

@defun string-to-number string &optional base
@c @cindex string to number
@cindex $BJ8;zNs$+$i?t$X(B
@c This function returns the numeric value of the characters in
@c @var{string}.  If @var{base} is non-@code{nil}, integers are converted
@c in that base.  If @var{base} is @code{nil}, then base ten is used.
@c Floating point conversion always uses base ten; we have not implemented
@c other radices for floating point numbers, because that would be much
@c more work and does not seem useful.
$B$3$N4X?t$O!"(B@var{string}$BFb$NJ8;z72$,I=$9?tCM$rJV$9!#(B
@var{base}$B$,(B@code{nil}$B0J30$J$i$P!"$3$l$r4p?t$H$7$F@0?t$KJQ49$9$k!#(B
@var{base}$B$,(B@code{nil}$B$J$i$P(B10$B$r4p?t$H$9$k!#(B
$BIbF0>.?tE@?t$NJQ49$O$D$M$K(B10$B$r4p?t$H$9$k!#(B
$BIbF0>.?tE@?t$KBP$7$F$OJL$N4p?t$r<BAu$7$F$$$J$$!#(B
$B:n6HNL$bB?$/$=$N$o$j$K$OM-MQ$H$b;W$($J$$$+$i$G$"$k!#(B

@c The parsing skips spaces and tabs at the beginning of @var{string}, then
@c reads as much of @var{string} as it can interpret as a number.  (On some
@c systems it ignores other whitespace at the beginning, not just spaces
@c and tabs.)  If the first character after the ignored whitespace is not a
@c digit or a plus or minus sign, this function returns 0.
$B2r@O$9$k$H$-!"(B@var{string}$B$N@hF,$K$"$k6uGr$d%?%V$OL5;k$7!"(B
$B?t$H2r<a$G$-$k8B$j$r(B@var{string}$B$+$iFI$_<h$k!#(B
$B!J@hF,$N6uGr$d%?%V0J30$NB>$NGrJ8;z$rL5;k$9$k%7%9%F%`$b$"$k!#!K(B
$BL5;k$7$?GrJ8;z$N$"$H$N:G=i$NJ8;z$,!"?t;zJ8;z!"%W%i%95-9f!"(B
$B%^%$%J%95-9f$G$J$1$l$P!"$3$N4X?t$O(B0$B$rJV$9!#(B

@example
(string-to-number "256")
     @result{} 256
(string-to-number "25 is a perfect square.")
     @result{} 25
(string-to-number "X256")
     @result{} 0
(string-to-number "-4.5")
     @result{} -4.5
@end example

@findex string-to-int
@c @code{string-to-int} is an obsolete alias for this function.
@code{string-to-int}$B$O$3$N4X?t$NGQ$l$?JLL>!#(B
@end defun

@c   Here are some other functions that can convert to or from a string:
$BJ8;zNs$X!?$+$iJQ49$9$k$=$NB>$N4X?t$r0J2<$K$"$2$F$*$-$^$9!#(B

@table @code
@item concat
@c @code{concat} can convert a vector or a list into a string.
@c @xref{Creating Strings}.
@code{concat}$B$O!"%Y%/%H%k$d%j%9%H$rJ8;zNs$XJQ49$9$k!#(B
@pxref{Creating Strings}$B!#(B

@item vconcat
@c @code{vconcat} can convert a string into a vector.  @xref{Vector
@c Functions}.
@code{vconcat}$B$O!"J8;zNs$r%Y%/%H%k$XJQ49$9$k!#(B
@pxref{Vector Functions}$B!#(B

@item append
@c @code{append} can convert a string into a list.  @xref{Building Lists}.
@code{append}$B$O!"J8;zNs$r%j%9%H$XJQ49$9$k!#(B
@pxref{Building Lists}$B!#(B
@end table

@node Formatting Strings
@comment  node-name,  next,  previous,  up
@c @section Formatting Strings
@section $BJ8;zNs$N=q<0IU$1(B
@c @cindex formatting strings
@c @cindex strings, formatting them
@cindex $BJ8;zNs$N=q<0IU$1(B
@cindex $B=q<0IU$1!"J8;zNs(B

@c   @dfn{Formatting} means constructing a string by substitution of
@c computed values at various places in a constant string.  This string
@c controls how the other values are printed as well as where they appear;
@c it is called a @dfn{format string}.
@dfn{$B=q<0IU$1(B}$B!J(Bformatting$B!K$H$O!"(B
$BDj?tJ8;zNsFb$N$5$^$6$^ItJ,$r7W;;CM$GCV$-49$($?J8;zNs$r:n$k$3$H$G$9!#(B
$B$3$NJ8;zNs$O!"J8;zNs<+BN$K2C$($F!"(B
$BB>$NCM$r$I$N$h$&$KI=<($9$k$+$b@)8f$7$^$9!#(B
$B$3$NJ8;zNs$r(B@dfn{$B=q<0IU$1J8;zNs(B}$B!J(Bformat string$B!K$H8F$S$^$9!#(B

@c   Formatting is often useful for computing messages to be displayed.  In
@c fact, the functions @code{message} and @code{error} provide the same
@c formatting feature described here; they differ from @code{format} only
@c in how they use the result of formatting.
$B=q<0IU$1$O!"I=<($9$k%a%C%;!<%8$r7W;;$9$k>l9g$KJXMx$G$9!#(B
$B<B:]!"4X?t(B@code{message}$B$H4X?t(B@code{error}$B$K$O!"(B
$B$3$3$G@bL@$9$k$N$HF1$8=q<0IU$15!G=$,$"$j$^$9!#(B
$B$=$l$i$H(B@code{format}$B$H$N0c$$$O!"(B
$B=q<0IU$1$7$?7k2L$r$I$N$h$&$KMxMQ$9$k$+$G$9!#(B

@defun format string &rest objects
@c This function returns a new string that is made by copying
@c @var{string} and then replacing any format specification 
@c in the copy with encodings of the corresponding @var{objects}.  The
@c arguments @var{objects} are the computed values to be formatted.
$B$3$N4X?t$O!"(B@var{string}$B$r%3%T!<$7!"(B
$B%3%T!<Fb$N=q<0IU$1;XDj$rBP1~$9$k(B@var{objects}$B$NI=8=$GCV$-49$($?(B
$B?7$?$JJ8;zNs$rJV$9!#(B
$B0z?t(B@var{objects}$B$O=q<0IU$1$9$Y$-7W;;CM$G$"$k!#(B
@end defun

@c @cindex @samp{%} in format
@c @cindex format specification
@cindex @samp{%}$B!"=q<0IU$1(B
@cindex $B=q<0IU$1;XDj(B
@c   A format specification is a sequence of characters beginning with a
@c @samp{%}.  Thus, if there is a @samp{%d} in @var{string}, the
@c @code{format} function replaces it with the printed representation of
@c one of the values to be formatted (one of the arguments @var{objects}).
@c For example:
$B=q<0IU$1;XDj$O(B@samp{%}$B$G;O$^$kJ8;z$NNs$G$9!#(B
$B$7$?$,$C$F!"(B@var{string}$BFb$K(B@samp{%d}$B$,$"$k$H!"(B
$B4X?t(B@code{format}$B$O$=$l$r=q<0IU$1$9$Y$-CM$N(B1$B$D(B
$B!J0z?t(B@var{objects}$B$N(B1$B$D!K$NI=<(I=8=$GCV$-49$($^$9!#(B
$B$?$H$($P!"$D$.$N$H$*$j$G$9!#(B

@example
@group
(format "The value of fill-column is %d." fill-column)
     @result{} "The value of fill-column is 72."
@end group
@end example

@c   If @var{string} contains more than one format specification, the
@c format specifications correspond with successive values from
@c @var{objects}.  Thus, the first format specification in @var{string}
@c uses the first such value, the second format specification uses the
@c second such value, and so on.  Any extra format specifications (those
@c for which there are no corresponding values) cause unpredictable
@c behavior.  Any extra values to be formatted are ignored.
@var{string}$B$K(B2$B8D0J>e$N=q<0IU$1;XDj$,$"$k>l9g!"(B
$B=q<0IU$1;XDj$O(B@var{objects}$B$N8eB3$NCM$KBP1~$7$^$9!#(B
$B$D$^$j!"(B@var{string}$B$N:G=i$N=q<0IU$1;XDj$O:G=i$NCM$r;H$$!"(B
2$BHVL\$N=q<0IU$1;XDj$O(B2$BHVL\$NCM$r;H$$!"$H$$$C$?6q9g$G$9!#(B
$B!JCM$,BP1~$7$J$$!KM>7W$J=q<0IU$1;XDj$O!"(B
$BM=B,IT2DG=$J$U$k$^$$$r0z$-5/$3$7$^$9!#(B
$BM>7W$JCM$OL5;k$7$^$9!#(B

@c   Certain format specifications require values of particular types.  If
@c you supply a value that doesn't fit the requirements, an error is
@c signaled.
$BFCDj$N=q<0IU$1;XDj$O!"FCDj$N7?$NCM$rI,MW$H$7$^$9!#(B
$BMW5a$KE,9g$7$J$$CM$rFI<T$,;XDj$9$k$H%(%i!<$rDLCN$7$^$9!#(B

@c   Here is a table of valid format specifications:
$BM-8z$J=q<0IU$1;XDj$r$D$.$K<($7$^$9!#(B

@table @samp
@item %s
@c Replace the specification with the printed representation of the object,
@c made without quoting (that is, using @code{princ}, not
@c @code{prin1}---@pxref{Output Functions}).  Thus, strings are represented
@c by their contents alone, with no @samp{"} characters, and symbols appear
@c without @samp{\} characters.
$B=q<0IU$1;XDj$r%*%V%8%'%/%H$N%/%)!<%H$7$J$$(B
$B!J$D$^$j!"(B@code{prin1}$B$G$O$J$/(B@code{princ}$B$rMQ$$$k!#(B@pxref{Output Functions}$B!K(B
$BI=<(I=8=$GCV$-49$($k!#(B
$B$7$?$,$C$F!"J8;zNs$O(B@samp{"}$BJ8;z$J$7$G$=$NFbMF$rI=<($7!"(B
$B%7%s%\%k$O(B@samp{\}$BJ8;z$J$7$GI=<($9$k!#(B

@c If there is no corresponding object, the empty string is used.
$BBP1~$9$k%*%V%8%'%/%H$,$J$1$l$P6uJ8;zNs$r;H$&!#(B

@item %S
@c Replace the specification with the printed representation of the object,
@c made with quoting (that is, using @code{prin1}---@pxref{Output
@c Functions}).  Thus, strings are enclosed in @samp{"} characters, and
@c @samp{\} characters appear where necessary before special characters.
$B=q<0IU$1;XDj$r%*%V%8%'%/%H$N%/%)!<%H$7$?(B
$B!J$D$^$j!"(B@code{prin1}$B$rMQ$$$k!#(B@pxref{Output Functions}$B!K(B
$BI=<(I=8=$GCV$-49$($k!#(B
$B$7$?$,$C$F!"J8;zNs$O(B@samp{"}$BJ8;z$G0O$s$GI=<($7!"(B
$B%7%s%\%k$OFCJL$JJ8;z$N$^$($K$O(B@samp{\}$BJ8;z$rIU$1$FI=<($9$k!#(B

@c If there is no corresponding object, the empty string is used.
$BBP1~$9$k%*%V%8%'%/%H$,$J$1$l$P6uJ8;zNs$r;H$&!#(B

@item %o
@c @cindex integer to octal
@cindex $B@0?t$N(B8$B?JI=5-(B
@c Replace the specification with the base-eight representation of an
@c integer.
$B=q<0IU$1;XDj$r@0?t$N4p?t(B8$B$NI=<(I=8=$GCV$-49$($k!#(B

@item %d
@c Replace the specification with the base-ten representation of an
@c integer.
$B=q<0IU$1;XDj$r@0?t$N4p?t(B10$B$NI=<(I=8=$GCV$-49$($k!#(B

@item %x
@c @cindex integer to hexadecimal
@cindex $B@0?t$N(B16$B?JI=5-(B
@c Replace the specification with the base-sixteen representation of an
@c integer.
$B=q<0IU$1;XDj$r@0?t$N4p?t(B16$B$NI=<(I=8=$GCV$-49$($k!#(B

@item %c
@c Replace the specification with the character which is the value given.
$B=q<0IU$1;XDj$r;XDjCM$NJ8;z$GCV$-49$($k!#(B

@item %e
@c Replace the specification with the exponential notation for a floating
@c point number.
$B=q<0IU$1;XDj$rIbF0>.?tE@?t$N;X?tI=5-$GCV$-49$($k!#(B

@item %f
@c Replace the specification with the decimal-point notation for a floating
@c point number.
$B=q<0IU$1;XDj$rIbF0>.?tE@?t$N>.?tE@I=5-$GCV$-49$($k!#(B

@item %g
@c Replace the specification with notation for a floating point number,
@c using either exponential notation or decimal-point notation, whichever
@c is shorter.
$B=q<0IU$1;XDj$rIbF0>.?tE@?t$N;X?tI=5-$+>.?tE@I=5-$N$I$A$i$+C;$$$[$&$G(B
$BCV$-49$($k!#(B

@item %%
@c A single @samp{%} is placed in the string.  This format specification is
@c unusual in that it does not use a value.  For example, @code{(format "%%
@c %d" 30)} returns @code{"% 30"}.
$BJ8;zNs$K(B1$B8D$N(B@samp{%}$B$rF~$l$k!#(B
$B$3$N=q<0IU$1;XDj$O!"CM$r;H$o$J$$E@$GFCJL$G$"$k!#(B
$B$?$H$($P!"(B@code{(format "%% %d" 30)}$B$O(B@code{"% 30"}$B$rJV$9!#(B
@end table

@c   Any other format character results in an @samp{Invalid format
@c operation} error.
$B>e5-0J30$N=q<0IU$1J8;z$O!"%(%i!<(B@samp{Invalid format operation}$B$K$J$j$^$9!#(B

@c   Here are several examples:
$BNc$r$$$/$D$+<($7$^$9!#(B

@example
@group
(format "The name of this buffer is %s." (buffer-name))
     @result{} "The name of this buffer is strings.texi."

(format "The buffer object prints as %s." (current-buffer))
     @result{} "The buffer object prints as strings.texi."

(format "The octal value of %d is %o, 
         and the hex value is %x." 18 18 18)
     @result{} "The octal value of 18 is 22, 
         and the hex value is 12."
@end group
@end example

@c @cindex numeric prefix
@c @cindex field width
@c @cindex padding
@cindex $B?tA0CV;R(B
@cindex $B%U%#!<%k%II}(B
@cindex $B%Q%G%#%s%0(B
@c   All the specification characters allow an optional numeric prefix
@c between the @samp{%} and the character.  The optional numeric prefix
@c defines the minimum width for the object.  If the printed representation
@c of the object contains fewer characters than this, then it is padded.
@c The padding is on the left if the prefix is positive (or starts with
@c zero) and on the right if the prefix is negative.  The padding character
@c is normally a space, but if the numeric prefix starts with a zero, zeros
@c are used for padding.  Here are some examples of padding:
$B$9$Y$F$N=q<0IU$1J8;z$K$O!"(B@samp{%}$B$H$=$NJ8;z$N$"$$$@$K!"(B
$B?tA0CV;R$r;XDj$G$-$^$9!#(B
$B>JN,2DG=$J?tA0CV;R$O%*%V%8%'%/%H$N:G>.I}$r;XDj$7$^$9!#(B
$B%*%V%8%'%/%H$NI=<(I=8=$,$3$NI}$h$j>.$5$$>l9g!"%Q%G%#%s%0$7$^$9!#(B
$B?tA0CV;R$,@5$J$i$P!J$"$k$$$O%<%m$G;O$^$l$P!K:8B&$K%Q%G%#%s%0$7!"(B
$B?tA0CV;R$,Ii$J$i$P1&B&$K%Q%G%#%s%0$7$^$9!#(B
$B%Q%G%#%s%0J8;z$O!"DL>o!"6uGr$G$9$,!"(B
$B?tA0CV;R$,%<%m$G;O$^$l$P!"%<%m$G%Q%G%#%s%0$7$^$9!#(B
$B%Q%G%#%s%0$NNc$r<($7$^$9!#(B

@example
(format "%06d is padded on the left with zeros" 123)
     @result{} "000123 is padded on the left with zeros"

(format "%-6d is padded on the right" 123)
     @result{} "123    is padded on the right"
@end example

@c   @code{format} never truncates an object's printed representation, no
@c matter what width you specify.  Thus, you can use a numeric prefix to
@c specify a minimum spacing between columns with no risk of losing
@c information.
@code{format}$B$O!"$I$s$JI}$r;XDj$7$F$b!"(B
$B%*%V%8%'%/%H$NI=<(I=8=$r@Z$j5M$a$k$3$H$O$"$j$^$;$s!#(B
$B$D$^$j!">pJs$r<:$&$3$H$J$/!"?tA0CV;R$r;H$C$F:G>.$N7eI}$r;XDj$G$-$^$9!#(B

@c   In the following three examples, @samp{%7s} specifies a minimum width
@c of 7.  In the first case, the string inserted in place of @samp{%7s} has
@c only 3 letters, so 4 blank spaces are inserted for padding.  In the
@c second case, the string @code{"specification"} is 13 letters wide but is
@c not truncated.  In the third case, the padding is on the right.
$B$D$.$N(B3$B$D$NNc$K$*$$$F!"(B@samp{%7s}$B$O:G>.I}(B7$B$r;XDj$7$^$9!#(B
$B:G=i$NNc$G$O!"(B@samp{%7s}$B$KCV$-49$o$kJ8;zNs$O(B3$BJ8;z$G$9$+$i!"(B
$B%Q%G%#%s%0$H$7$F6uGr(B4$B8D$rA^F~$7$^$9!#(B
2$BHVL\$NNc$G$O!"J8;zNs(B@code{"specification"}$B$O(B13$BJ8;zI}$G$9$,@Z$j5M$a$^$;$s!#(B
3$BHVL\$NNc$G$O!"1&B&$K%Q%G%#%s%0$7$^$9!#(B

@smallexample 
@group
(format "The word `%7s' actually has %d letters in it."
        "foo" (length "foo"))
     @result{} "The word `    foo' actually has 3 letters in it."  
@end group

@group
(format "The word `%7s' actually has %d letters in it."
        "specification" (length "specification")) 
     @result{} "The word `specification' actually has 13 letters in it."  
@end group

@group
(format "The word `%-7s' actually has %d letters in it."
        "foo" (length "foo"))
     @result{} "The word `foo    ' actually has 3 letters in it."  
@end group
@end smallexample

@node Case Conversion
@comment node-name, next, previous, up 
@c @section Case Conversion in Lisp
@section Lisp$B$NBgJ8;z>.J8;zJQ49(B
@c @cindex upper case 
@c @cindex lower case 
@c @cindex character case 
@c @cindex case conversion in Lisp
@cindex $BBgJ8;z(B
@cindex $B>.J8;z(B
@cindex $BBgJ8;z>.J8;z(B
@cindex Lisp$B$NBgJ8;z>.J8;zJQ49(B

@c   The character case functions change the case of single characters or
@c of the contents of strings.  The functions normally convert only
@c alphabetic characters (the letters @samp{A} through @samp{Z} and
@c @samp{a} through @samp{z}, as well as non-ASCII letters); other
@c characters are not altered.  (You can specify a different case
@c conversion mapping by specifying a case table---@pxref{Case Tables}.)
$BBgJ8;z>.J8;zJQ494X?t$O!"(B1$BJ8;z$dJ8;zNsFb$NBgJ8;z>.J8;z$rJQ99$7$^$9!#(B
$B4X?t$O!"DL>o!"%"%k%U%!%Y%C%HJ8;z(B
$B!JHs(BASCII$BJ8;z$N%"%k%U%!%Y%C%H$K2C$($F!"(B
@samp{A}$B$+$i(B@samp{Z}$B$H(B@samp{a}$B$+$i(B@samp{z}$B!K$@$1$rJQ49$7$^$9!#(B
$B$=$l0J30$NJ8;z$OJQ$o$j$^$;$s!#(B
$B!JBgJ8;z>.J8;z%F!<%V%k$r;XDj$7$F0[$J$kBgJ8;z>.J8;zJQ49$r;XDj$G$-$k!#(B
@pxref{Case Tables}$B!K(B

@c   These functions do not modify the strings that are passed to them as
@c arguments.
$B$3$l$i$N4X?t$O!"0z?t$H$7$FEO$7$?J8;zNs$OJQ99$7$^$;$s!#(B

@c   The examples below use the characters @samp{X} and @samp{x} which have
@c @sc{ASCII} codes 88 and 120 respectively.
$B0J2<$NNc$G$O!"J8;z(B@samp{X}$B$H(B@samp{x}$B$r;H$$$^$9!#(B
@sc{ASCII}$B%3!<%I$O!"$=$l$>$l!"(B88$B$H(B120$B$G$9!#(B

@defun downcase string-or-char
@c This function converts a character or a string to lower case.
$B$3$N4X?t$O!"J8;z$dJ8;zNs$r>.J8;z$KJQ49$9$k!#(B

@c When the argument to @code{downcase} is a string, the function creates
@c and returns a new string in which each letter in the argument that is
@c upper case is converted to lower case.  When the argument to
@c @code{downcase} is a character, @code{downcase} returns the
@c corresponding lower case character.  This value is an integer.  If the
@c original character is lower case, or is not a letter, then the value
@c equals the original character.
@code{downcase}$B$N0z?t$,J8;zNs$G$"$k$H!"(B
$B$3$N4X?t$O!"0z?t$N3FJ8;z$NBgJ8;z$r>.J8;z$KJQ49$7$??7$?$JJ8;zNs$r:n@.$9$k!#(B
@code{downcase}$B$N0z?t$,J8;z$G$"$k$H!"(B
@code{downcase}$B$OBP1~$9$k>.J8;z$rJV$9!#(B
$B$3$NCM$O@0?t$G$"$k!#(B
$B$b$H$NJ8;z$,>.J8;z$G$"$C$?$j%"%k%U%!%Y%C%HJ8;z$G$J$1$l$P!"(B
$BCM$O$b$H$NJ8;z$KEy$7$$!#(B

@example
(downcase "The cat in the hat")
     @result{} "the cat in the hat"

(downcase ?X)
     @result{} 120
@end example
@end defun

@defun upcase string-or-char
@c This function converts a character or a string to upper case.
$B$3$N4X?t$O!"J8;z$dJ8;zNs$rBgJ8;z$KJQ49$9$k!#(B

@c When the argument to @code{upcase} is a string, the function creates
@c and returns a new string in which each letter in the argument that is
@c lower case is converted to upper case.
@code{upcase}$B$N0z?t$,J8;zNs$G$"$k$H!"(B
$B$3$N4X?t$O!"0z?t$N3FJ8;z$N>.J8;z$rBgJ8;z$KJQ49$7$??7$?$JJ8;zNs$r:n@.$9$k!#(B

@c When the argument to @code{upcase} is a character, @code{upcase}
@c returns the corresponding upper case character.  This value is an integer.
@c If the original character is upper case, or is not a letter, then the
@c value equals the original character.
@code{upcase}$B$N0z?t$,J8;z$G$"$k$H!"(B
@code{upcase}$B$OBP1~$9$kBgJ8;z$rJV$9!#(B
$B$3$NCM$O@0?t$G$"$k!#(B
$B$b$H$NJ8;z$,BgJ8;z$G$"$C$?$j%"%k%U%!%Y%C%HJ8;z$G$J$1$l$P!"(B
$BCM$O$b$H$NJ8;z$KEy$7$$!#(B

@example
(upcase "The cat in the hat")
     @result{} "THE CAT IN THE HAT"

(upcase ?x)
     @result{} 88
@end example
@end defun

@defun capitalize string-or-char
@c @cindex capitalization
@cindex $B%-%c%T%?%i%$%:!J@hF,J8;z$@$1$rBgJ8;z$K$9$k!K(B
@c This function capitalizes strings or characters.  If
@c @var{string-or-char} is a string, the function creates and returns a new
@c string, whose contents are a copy of @var{string-or-char} in which each
@c word has been capitalized.  This means that the first character of each
@c word is converted to upper case, and the rest are converted to lower
@c case.
$B$3$N4X?t$O!"J8;zNs$dJ8;z$r%-%c%T%?%i%$%:!J@hF,J8;z$@$1$rBgJ8;z$K!K$9$k!#(B
@var{string-or-char}$B$,J8;zNs$J$i$P!"(B
$B$3$N4X?t$O!"(B@var{string-or-char}$B$N%3%T!<$N3FC18l$r%-%c%T%?%i%$%:$7$?$b$N$r(B
$BFbMF$H$9$k?7$?$JJ8;zNs$r:n@.$7$FJV$9!#(B
$B$D$^$j!"3FC18l$N@hF,J8;z$@$1$rBgJ8;z$K$7$F;D$j$r>.J8;z$K$9$k!#(B

@c The definition of a word is any sequence of consecutive characters that
@c are assigned to the word constituent syntax class in the current syntax
@c table (@xref{Syntax Class Table}).
$BC18l$NDj5A$O!"8=:_$N9=J8%F!<%V%k!J(B@xref{Syntax Class Table}$B!K$K$*$$$F(B
$BC18l9=@.J8;z$KJ,N`$5$l$?J8;z$,O"B3$7$?Ns$G$"$k!#(B

@c When the argument to @code{capitalize} is a character, @code{capitalize}
@c has the same result as @code{upcase}.
@code{capitalize}$B$N0z?t$,J8;z$N>l9g$K$O!"(B
@code{capitalize}$B$O(B@code{upcase}$B$N7k2L$HF1$8$G$"$k!#(B

@example
(capitalize "The cat in the hat")
     @result{} "The Cat In The Hat"

(capitalize "THE 77TH-HATTED CAT")
     @result{} "The 77th-Hatted Cat"

@group
(capitalize ?x)
     @result{} 88
@end group
@end example
@end defun

@defun upcase-initials string
@c This function capitalizes the initials of the words in @var{string}.
@c without altering any letters other than the initials.  It returns a new
@c string whose contents are a copy of @var{string}, in which each word has
@c been converted to upper case.
$B$3$N4X?t$O!"(B@var{string}$BFb$NC18l$N@hF,J8;z$@$1$rBgJ8;z$K$7!"(B
$B@hF,J8;z0J30$NJ8;z$OJQ99$7$J$$!#(B
$B$3$N4X?t$O!"(B@var{string}$B$N%3%T!<$N3FC18l$N@hF,J8;z$rBgJ8;z$KJQ49$7$?$b$N$r(B
$BFbMF$H$9$k?7$?$JJ8;zNs$rJV$9!#(B

@c The definition of a word is any sequence of consecutive characters that
@c are assigned to the word constituent syntax class in the current syntax
@c table (@xref{Syntax Class Table}).
$BC18l$NDj5A$O!"8=:_$N9=J8%F!<%V%k!J(B@xref{Syntax Class Table}$B!K$K$*$$$F(B
$BC18l9=@.J8;z$KJ,N`$5$l$?J8;z$,O"B3$7$?Ns$G$"$k!#(B

@example
@group
(upcase-initials "The CAT in the hAt")
     @result{} "The CAT In The HAt"
@end group
@end example
@end defun

@c   @xref{Text Comparison}, for functions that compare strings; some of
@c them ignore case differences, or can optionally ignore case differences.
$BJ8;zNs$rHf3S$9$k4X?t$K$D$$$F$O!"(B@xref{Text Comparison}$B!#(B
$B$3$l$i$O!"BgJ8;z>.J8;z$r6hJL$7$J$$$b$N$b$"$l$P!"(B
$B>l9g$K$h$C$FBgJ8;z>.J8;z$r6hJL$7$J$$$b$N$b$"$k!#(B

@node Case Tables
@c @section The Case Table
@section $BBgJ8;z>.J8;z%F!<%V%k(B

@c   You can customize case conversion by installing a special @dfn{case
@c table}.  A case table specifies the mapping between upper case and lower
@c case letters.  It affects both the case conversion functions for Lisp
@c objects (see the previous section) and those that apply to text in the
@c buffer (@pxref{Case Changes}).  Each buffer has a case table; there is
@c also a standard case table which is used to initialize the case table
@c of new buffers.
$BFCJL$J(B@dfn{$BBgJ8;z>.J8;z%F!<%V%k(B}$B!J(Bcase table$B!K$r%$%s%9%H!<%k$9$l$P!"(B
$BBgJ8;z>.J8;zJQ49$r%+%9%?%^%$%:$G$-$^$9!#(B
$BBgJ8;z>.J8;z%F!<%V%k$O!"BgJ8;z$H>.J8;z$NBP1~4X78$r;XDj$7$^$9!#(B
$B$3$N%F!<%V%k$O!"(BLisp$B%*%V%8%'%/%H$NBgJ8;z>.J8;zJQ494X?t!JA0@a;2>H!K$H(B
$B%P%C%U%!Fb$N%F%-%9%H$K:nMQ$9$kBgJ8;z>.J8;zJQ494X?t!J(B@pxref{Case Changes}$B!K$N(B
$BN>J}$K1F6A$7$^$9!#(B
$B3F%P%C%U%!$4$H$KBgJ8;z>.J8;z%F!<%V%k$,$"$j$^$9!#(B
$B?7$?$J%P%C%U%!$NBgJ8;z>.J8;z%F!<%V%k$r=i4|2=$9$k$?$a$K;H$&(B
$BI8=`$NBgJ8;z>.J8;z%F!<%V%k$b$"$j$^$9!#(B

@c   A case table is a char-table (@pxref{Char-Tables}) whose subtype is
@c @code{case-table}.  This char-table maps each character into the
@c corresponding lower case character.  It has three extra slots, which
@c hold related tables:
$BBgJ8;z>.J8;z%F!<%V%k$O!"%5%V%?%$%W$,(B@code{case-table}$B$G$"$k(B
$BJ8;z%F!<%V%k!J(B@pxref{Char-Tables}$B!K$G$9!#(B
$B$3$NJ8;z%F!<%V%k$O!"3FJ8;z$rBP1~$9$k>.J8;z$KBP1~IU$1$^$9!#(B
$B$3$l$K$O(B3$B$D$NDI2C%9%m%C%H$,$"$j!"4XO"$9$k%F!<%V%k$rJ];}$7$^$9!#(B

@table @var
@item upcase
@c The upcase table maps each character into the corresponding upper
@c case character.
upcase$B!JBgJ8;z!K%F!<%V%k$O!"3FJ8;z$rBP1~$9$kBgJ8;z$KBP1~IU$1$k!#(B
@item canonicalize
@c The canonicalize table maps all of a set of case-related characters
@c into a particular member of that set.
canonicalize$B!J@5B'!K%F!<%V%k$OBgJ8;z>.J8;z$K4XO"$9$k(B1$BAH$NJ8;z72$r(B
$B$=$NJ8;z72$NFCDj$N%a%s%P$KBP1~IU$1$k!#(B
@item equivalences
@c The equivalences table maps each one of a set of case-related characters
@c into the next character in that set.
equivalences$B!JF1CM!K%F!<%V%k$O!"BgJ8;z>.J8;z$K4XO"$9$k(B1$BAH$NJ8;z72$N3FMWAG$r(B
$B$=$NJ8;z72Fb$N$D$.$NJ8;z$KBP1~IU$1$k!#(B
@end table

@c   In simple cases, all you need to specify is the mapping to lower-case;
@c the three related tables will be calculated automatically from that one.
$BC1=c$J>l9g!"I,MW$J$3$H$O!">.J8;z$X$NBP1~IU$1$r;XDj$9$k$@$1$G$9!#(B
$B4XO"$9$k(B3$B$D$N%F!<%V%k$O$3$NBP1~IU$1$+$i<+F0E*$K7W;;$5$l$^$9!#(B

@c   For some languages, upper and lower case letters are not in one-to-one
@c correspondence.  There may be two different lower case letters with the
@c same upper case equivalent.  In these cases, you need to specify the
@c maps for both lower case and upper case.
$B8@8l$K$h$C$F$O!"BgJ8;z$H>.J8;z$NBP1~4X78$,(B1$BBP(B1$B$G$J$$$3$H$,$"$j$^$9!#(B
2$B$D$N0[$J$k>.J8;z$,F1$8BgJ8;z$KBP1~$9$k$3$H$,$"$j$^$9!#(B
$B$3$N$h$&$J>l9g!"BgJ8;z$+$i>.J8;z$X$NBP1~IU$1$H!"(B
$B>.J8;z$+$iBgJ8;z$X$NBP1~IU$1$NN>J}$r;XDj$9$kI,MW$,$"$j$^$9!#(B

@c   The extra table @var{canonicalize} maps each character to a canonical
@c equivalent; any two characters that are related by case-conversion have
@c the same canonical equivalent character.  For example, since @samp{a}
@c and @samp{A} are related by case-conversion, they should have the same
@c canonical equivalent character (which should be either @samp{a} for both
@c of them, or @samp{A} for both of them).
$BDI2C$N%F!<%V%k(B@var{canonicalize}$B!J@5B'!K$O!"3FJ8;z$r@5B'J8;z$KBP1~IU$1$^$9!#(B
2$B$D$NG$0U$NJ8;z$,BgJ8;z>.J8;zJQ49$G4XO"IU$1$i$l$F$$$k>l9g!"(B
$B$=$N(B2$B$D$NJ8;z$OF10l$N@5B'J8;z$r;}$A$^$9!#(B
$B$?$H$($P!"(B@samp{a}$B$H(B@samp{A}$B$O!"BgJ8;z>.J8;zJQ49$G4XO"IU$1$i$l$F$$$k$N$G!"(B
$B$3$l$i$OF10l$N@5B'J8;z$r;}$D$O$:$G$9(B
$B!JN>J}$NJ8;z$KBP$7$F(B@samp{a}$B$G$"$k$+!"N>J}$NJ8;z$KBP$7$F(B@samp{A}$B$G$"$k!K!#(B

@c   The extra table @var{equivalences} is a map that cyclicly permutes
@c each equivalence class (of characters with the same canonical
@c equivalent).  (For ordinary @sc{ASCII}, this would map @samp{a} into
@c @samp{A} and @samp{A} into @samp{a}, and likewise for each set of
@c equivalent characters.)
$BDI2C$N%F!<%V%k(B@var{equivalences}$B!JF1CM!K$O!"(B
$BF1$8@5B'%/%i%9!JF10l$N@5B'J8;z$r;}$DJ8;z72!K$NJ8;z$r=d2s$7$FBP1~IU$1$^$9!#(B
$B!JIaDL$N(B@sc{ASCII}$B$G$O!"(B@samp{a}$B$r(B@samp{A}$B$KBP1~IU$1!"(B
@samp{A}$B$r(B@samp{a}$B$KBP1~IU$1$k!#(B
$B3F@5B'%/%i%9$K$D$$$F$bF1MM!#!K(B

@c   When you construct a case table, you can provide @code{nil} for
@c @var{canonicalize}; then Emacs fills in this slot from the lower case
@c and upper case mappings.  You can also provide @code{nil} for
@c @var{equivalences}; then Emacs fills in this slot from
@c @var{canonicalize}.  In a case table that is actually in use, those
@c components are non-@code{nil}.  Do not try to specify @var{equivalences}
@c without also specifying @var{canonicalize}.
$BBgJ8;z>.J8;z%F!<%V%k$r:n@.$9$k$H$-$K$O!"(B
@var{canonicalize}$B!J@5B'!K$K$O(B@code{nil}$B$r;XDj$G$-$^$9!#(B
$B$=$&$9$k$H!"(BEmacs$B$O$3$N%9%m%C%H$r>.J8;z$HBgJ8;z$NBP1~IU$1$+$iKd$a$^$9!#(B
@var{equivalences}$B!JF1CM!K$K$b(B@code{nil}$B$r;XDj$G$-$^$9!#(B
$B$=$&$9$k$H!"(BEmacs$B$O$3$N%9%m%C%H$r(B@var{canonicalize}$B!J@5B'!K$+$iKd$a$^$9!#(B
$B<B:]$K;HMQ$7$F$$$kBgJ8;z>.J8;z%F!<%V%k$G$O!"(B
$B$3$l$i$NMWAG$O(B@code{nil}$B0J30$G$9!#(B
@var{canonicalize}$B!J@5B'!K$r;XDj$;$:$K(B
@var{equivalences}$B!JF1CM!K$r;XDj$7$J$$$G$/$@$5$$!"(B

@c   Here are the functions for working with case tables:
$B$D$.$K!"BgJ8;z>.J8;z%F!<%V%k$rA`:n$9$k4X?t$r<($7$^$9!#(B

@defun case-table-p object
@c This predicate returns non-@code{nil} if @var{object} is a valid case
@c table.
$B$3$N=R8l$O!"(B@var{object}$B$,@5$7$$(B
$BBgJ8;z>.J8;z%F!<%V%k$J$i$P(B@code{nil}$B0J30$rJV$9!#(B
@end defun

@defun set-standard-case-table table
@c This function makes @var{table} the standard case table, so that it will
@c be used in any buffers created subsequently.
$B$3$N4X?t$O!"(B@var{table}$B$rI8=`$NBgJ8;z>.J8;z%F!<%V%k$H$7!"(B
$B$3$l0J9_$K:n@.$9$kG$0U$N%P%C%U%!$K;HMQ$G$-$k$h$&$K$9$k!#(B
@end defun

@defun standard-case-table
@c This returns the standard case table.
$B$3$l$O!"I8=`$NBgJ8;z>.J8;z%F!<%V%k$rJV$9!#(B
@end defun

@defun current-case-table
@c This function returns the current buffer's case table.
$B$3$N4X?t$O!"%+%l%s%H%P%C%U%!$NBgJ8;z>.J8;z%F!<%V%k$rJV$9!#(B
@end defun

@defun set-case-table table
@c This sets the current buffer's case table to @var{table}.
$B$3$l$O!"%+%l%s%H%P%C%U%!$NBgJ8;z>.J8;z%F!<%V%k$r(B@var{table}$B$H$9$k!#(B
@end defun

@c   The following three functions are convenient subroutines for packages
@c that define non-@sc{ASCII} character sets.  They modify the specified
@c case table @var{case-table}; they also modify the standard syntax table.
@c @xref{Syntax Tables}.  Normally you would use these functions to change
@c the standard case table.
$B0J2<$N(B3$B$D4X?t$O!"Hs(B@sc{ASCII}$BJ8;z=89g$rDj5A$9$k%Q%C%1!<%88~$1$N(B
$BJXMx$J%5%V%k!<%F%#%s$G$9!#(B
$B$3$l$i$O!";XDj$7$?BgJ8;z>.J8;z%F!<%V%k(B@var{case-table}$B$rJQ99$7$^$9!#(B
$B$5$i$K!"I8=`$N9=J8%F!<%V%k$bJQ99$7$^$9!#(B
@xref{Syntax Tables}$B!#(B
$BIaDL!"I8=`$NBgJ8;z>.J8;z%F!<%V%k$rJQ99$9$k$?$a$K$3$l$i$N4X?t$r;H$$$^$9!#(B

@defun set-case-syntax-pair uc lc case-table
@c This function specifies a pair of corresponding letters, one upper case
@c and one lower case.
$B$3$N4X?t$OBP1~$9$kBgJ8;z$H>.J8;z$r;XDj$9$k!#(B
@end defun

@defun set-case-syntax-delims l r case-table
@c This function makes characters @var{l} and @var{r} a matching pair of
@c case-invariant delimiters.
$B$3$N4X?t$O!"J8;z(B@var{l}$B$H(B@var{r}$B$r(B
$BBgJ8;z>.J8;zITJQ6h@Z$j$NBP1~$9$kBP$K$9$k!#(B
@end defun

@defun set-case-syntax char syntax case-table
@c This function makes @var{char} case-invariant, with syntax
@c @var{syntax}.
$B$3$N4X?t$O!"(B@var{char}$B$r9=J8(B@var{syntax}$B$NBgJ8;z>.J8;zITJQ$K$9$k!#(B
@end defun

@c @deffn Command describe-buffer-case-table
@deffn $B%3%^%s%I(B describe-buffer-case-table
@c This command displays a description of the contents of the current
@c buffer's case table.
$B$3$N%3%^%s%I$O!"%+%l%s%H%P%C%U%!$NBgJ8;z>.J8;z%F!<%V%k$NFbMF$r5-=R$9$k!#(B
@end deffn