dotfiles/gcl-info/chap-16.texi

@node Strings, Sequences, Arrays, Top
@chapter Strings

@menu
* String Concepts::		
* Strings Dictionary::		
@end menu

@node String Concepts, Strings Dictionary, Strings, Strings
@section String Concepts

@c including concept-strings

@menu
* Implications of Strings Being Arrays::  
* Subtypes of STRING::		
@end menu

@node Implications of Strings Being Arrays, Subtypes of STRING, String Concepts, String Concepts
@subsection Implications of Strings Being Arrays

Since all @i{strings} are @i{arrays}, all rules which apply
generally to @i{arrays} also apply to @i{strings}.
See @ref{Array Concepts}.

For example,
     @i{strings} can have @i{fill pointers},
 and @i{strings} are also subject to the rules of @i{element type} @i{upgrading}
        that apply to @i{arrays}.

@node Subtypes of STRING,  , Implications of Strings Being Arrays, String Concepts
@subsection Subtypes of STRING

All functions that operate on @i{strings} 
will operate on @i{subtypes} of @i{string} as well.

However,
the consequences are undefined if a @i{character} is inserted into a @i{string}
for which the @i{element type} of the @i{string} does not include that @i{character}.

@c end of including concept-strings

@node Strings Dictionary,  , String Concepts, Strings
@section Strings Dictionary

@c including dict-strings

@menu
* string (System Class)::	
* base-string::			
* simple-string::		
* simple-base-string::		
* simple-string-p::		
* char::			
* string::			
* string-upcase::		
* string-trim::			
* string=::			
* stringp::			
* make-string::			
@end menu

@node string (System Class), base-string, Strings Dictionary, Strings Dictionary
@subsection string                                                       [System Class]

@subsubheading  Class Precedence List::
@b{string},
@b{vector},
@b{array},
@b{sequence},
@b{t}

@subsubheading  Description::

A @i{string} is a @i{specialized} @i{vector} 
whose @i{elements} are of @i{type} @b{character} or a @i{subtype} of @i{type} @b{character}.  
When used as a @i{type specifier} for object creation,
@b{string} means @t{(vector character)}.

@subsubheading  Compound Type Specifier Kind::

Abbreviating.

@subsubheading  Compound Type Specifier Syntax::

(@code{string}@{@i{@t{[}size@t{]}}@})

@subsubheading  Compound Type Specifier Arguments::

@i{size}---a non-negative @i{fixnum},
	    or the @i{symbol} @b{*}.

@subsubheading  Compound Type Specifier Description::

This denotes the union of all @i{types}
@t{(array @i{c} (@i{size}))}
for all @i{subtypes} @i{c} of @b{character};
that is, the set of @i{strings} of size @i{size}.

@subsubheading  See Also::

@ref{String Concepts},
@ref{Double-Quote},
@ref{Printing Strings}

@node base-string, simple-string, string (System Class), Strings Dictionary
@subsection base-string                                                          [Type]

@subsubheading  Supertypes::

@b{base-string},
@b{string},
@b{vector},
@b{array},
@b{sequence},
@b{t}

@subsubheading  Description::

The @i{type} @b{base-string} is equivalent to 

@t{(vector base-char)}.

The @i{base string} representation is the most efficient @i{string} representation
that can hold an arbitrary sequence of @i{standard characters}.

@subsubheading  Compound Type Specifier Kind::

Abbreviating.

@subsubheading  Compound Type Specifier Syntax::

(@code{base-string}@{@i{@t{[}size@t{]}}@})

@subsubheading  Compound Type Specifier Arguments::

@i{size}---a non-negative @i{fixnum},
	    or the @i{symbol} @b{*}.

@subsubheading  Compound Type Specifier Description::

This is equivalent to the type @t{(vector base-char @i{size})};
that is, the set of @i{base strings} of size @i{size}.

@node simple-string, simple-base-string, base-string, Strings Dictionary
@subsection simple-string                                                        [Type]

@subsubheading  Supertypes:: 

@b{simple-string},
@b{string},
@b{vector},
@b{simple-array},
@b{array},
@b{sequence},
@b{t}

@subsubheading  Description::

A @i{simple string} is a specialized one-dimensional
@i{simple array} whose @i{elements} are of @i{type} @b{character} or a @i{subtype} of @i{type} @b{character}.
When used as a @i{type specifier} for object creation,
@b{simple-string} means @t{(simple-array character (@i{size}))}.

@subsubheading  Compound Type Specifier Kind::

Abbreviating.

@subsubheading  Compound Type Specifier Syntax::

(@code{simple-string}@{@i{@t{[}size@t{]}}@})

@subsubheading  Compound Type Specifier Arguments::

@i{size}---a non-negative @i{fixnum},
	    or the @i{symbol} @b{*}.

@subsubheading  Compound Type Specifier Description::

This denotes the union of all @i{types}
@t{(simple-array @i{c} (@i{size}))} for all @i{subtypes} @i{c} of
@b{character}; that is, the set of @i{simple strings} of size @i{size}.

@node simple-base-string, simple-string-p, simple-string, Strings Dictionary
@subsection simple-base-string                                                   [Type]

@subsubheading  Supertypes::

@b{simple-base-string},
@b{base-string},
@b{simple-string},
@b{string},
@b{vector},
@b{simple-array},
@b{array},
@b{sequence},
@b{t}

@subsubheading  Description::

The @i{type} @b{simple-base-string} is equivalent to 

@t{(simple-array base-char (*))}.

@subsubheading  Compound Type Specifier Kind::

Abbreviating.

@subsubheading  Compound Type Specifier Syntax::

(@code{simple-base-string}@{@i{@t{[}size@t{]}}@})

@subsubheading  Compound Type Specifier Arguments::

@i{size}---a non-negative @i{fixnum},
	    or the @i{symbol} @b{*}.

@subsubheading  Compound Type Specifier Description::

This is equivalent to the type @t{(simple-array base-char (@i{size}))};
that is, the set of @i{simple base strings} of size @i{size}.

@node simple-string-p, char, simple-base-string, Strings Dictionary
@subsection simple-string-p                                                  [Function]

@code{simple-string-p}  @i{object} @result{}  @i{generalized-boolean}

@subsubheading  Arguments and Values::

@i{object}---an @i{object}.

@i{generalized-boolean}---a @i{generalized boolean}.

@subsubheading  Description::

Returns @i{true} if @i{object} is of @i{type} @b{simple-string};
otherwise, returns @i{false}.

@subsubheading  Examples::
@example
 (simple-string-p "aaaaaa") @result{}  @i{true}
 (simple-string-p (make-array 6 
                              :element-type 'character 
                              :fill-pointer t)) @result{}  @i{false}
@end example

@subsubheading  Notes::
@example
 (simple-string-p @i{object}) @equiv{} (typep @i{object} 'simple-string)
@end example

@node char, string, simple-string-p, Strings Dictionary
@subsection char, schar                                                      [Accessor]

@code{char}  @i{string index} @result{}  @i{character}

@code{schar}  @i{string index} @result{}  @i{character}

(setf (@code{char} @i{string index}) new-character)@*(setf (@code{schar} @i{string index}) new-character)@*

@subsubheading  Arguments and Values:: 

@i{string}---for @b{char},  a @i{string};
		 for @b{schar}, a @i{simple string}.

@i{index}---a @i{valid array index} for the @i{string}.

@i{character}, @i{new-character}---a @i{character}.

@subsubheading  Description::

@b{char} and @b{schar} @i{access} the @i{element} of @i{string}
specified by @i{index}.

@b{char} ignores @i{fill pointers} when @i{accessing} @i{elements}.

@subsubheading  Examples::

@example
 (setq my-simple-string (make-string 6 :initial-element #\A)) @result{}  "AAAAAA"
 (schar my-simple-string 4) @result{}  #\A
 (setf (schar my-simple-string 4) #\B) @result{}  #\B
 my-simple-string @result{}  "AAAABA"
 (setq my-filled-string
       (make-array 6 :element-type 'character
                     :fill-pointer 5
                     :initial-contents my-simple-string))
@result{}  "AAAAB"
 (char my-filled-string 4) @result{}  #\B
 (char my-filled-string 5) @result{}  #\A
 (setf (char my-filled-string 3) #\C) @result{}  #\C
 (setf (char my-filled-string 5) #\D) @result{}  #\D
 (setf (fill-pointer my-filled-string) 6) @result{}  6
 my-filled-string @result{}  "AAACBD"
@end example

@subsubheading  See Also::

@ref{aref}
,
@ref{elt}
,

@ref{Compiler Terminology}

@subsubheading  Notes::

@example
 (char s j) @equiv{} (aref (the string s) j)
@end example

@node string, string-upcase, char, Strings Dictionary
@subsection string                                                           [Function]

@code{string}  @i{x} @result{}  @i{string}

@subsubheading  Arguments and Values::

@i{x}---a @i{string}, a @i{symbol}, or a @i{character}.

@i{string}---a @i{string}.

@subsubheading  Description::

Returns a @i{string} described by @i{x}; specifically:

@table @asis

@item @t{*}  
If @i{x} is a @i{string}, it is returned.
@item @t{*}  
If @i{x} is a @i{symbol}, its @i{name} is returned.
@item @t{*}  

If @i{x} is a @i{character},

then a @i{string} containing that one @i{character} is returned.
@item @t{*}  

@b{string} might perform additional, @i{implementation-defined} conversions.

@end table

@subsubheading  Examples::

@example
 (string "already a string") @result{}  "already a string"
 (string 'elm) @result{}  "ELM"
 (string #\c) @result{}  "c"
@end example

@subsubheading  Exceptional Situations::

In the case where a conversion is defined neither by this specification nor
by the @i{implementation}, an error of @i{type} @b{type-error} is signaled.

@subsubheading  See Also::

@ref{coerce}
,
@b{string} (@i{type}).

@subsubheading  Notes::

@b{coerce} can be used to convert a @i{sequence} of @i{characters}
to a @i{string}.

@b{prin1-to-string}, @b{princ-to-string}, @b{write-to-string},
or @b{format} (with a first argument of @b{nil}) can be used to get a
@i{string} representation of a @i{number} or any other @i{object}.

@node string-upcase, string-trim, string, Strings Dictionary
@subsection string-upcase, string-downcase, string-capitalize, 
@subheading nstring-upcase, nstring-downcase, nstring-capitalize
@flushright
@i{[Function]}
@end flushright

@code{string-upcase}  @i{string {&key} start end} @result{}  @i{cased-string}

@code{string-downcase}  @i{string {&key} start end} @result{}  @i{cased-string}

@code{string-capitalize}  @i{string {&key} start end} @result{}  @i{cased-string}

@code{nstring-upcase}  @i{string {&key} start end} @result{}  @i{string}

@code{nstring-downcase}  @i{string {&key} start end} @result{}  @i{string}

@code{nstring-capitalize}  @i{string {&key} start end} @result{}  @i{string}

@subsubheading  Arguments and Values:: 

@i{string}---a @i{string designator}.
  For @b{nstring-upcase},
      @b{nstring-downcase},
  and @b{nstring-capitalize},
  the @i{string} @i{designator} must be a @i{string}.

@i{start}, @i{end}---@i{bounding index designators} of @i{string}.
 The defaults for @i{start} and @i{end} are @t{0} and @b{nil}, respectively.

@i{cased-string}---a @i{string}.

@subsubheading  Description::

@b{string-upcase},  @b{string-downcase},  @b{string-capitalize},
@b{nstring-upcase}, @b{nstring-downcase}, @b{nstring-capitalize}
change the case of the subsequence of @i{string} 
@i{bounded} by @i{start} and @i{end} 
as follows:

@table @asis

@item string-upcase  
@b{string-upcase} returns a @i{string} just like @i{string} 
with all lowercase characters replaced by the corresponding uppercase 
characters.  More precisely, each character of the result @i{string} 
is produced by applying the @i{function} @b{char-upcase} to the corresponding
character of @i{string}.

@item string-downcase  
@b{string-downcase} is like @b{string-upcase} 
except that all uppercase characters are replaced by the corresponding 
lowercase characters (using @b{char-downcase}).

@item string-capitalize  
@b{string-capitalize} produces a copy of @i{string} such that,
for every word in the copy, the first @i{character} of the ``word,''
if it has @i{case}, is @i{uppercase} and
any other @i{characters} with @i{case} in the word are @i{lowercase}.
For the purposes of @b{string-capitalize},
a ``word'' is defined to be a
consecutive subsequence consisting of @i{alphanumeric} @i{characters},
delimited at each end either by a non-@i{alphanumeric} @i{character}
or by an end of the @i{string}.

@item nstring-upcase, nstring-downcase, nstring-capitalize   
@b{nstring-upcase}, @b{nstring-downcase},
and @b{nstring-capitalize} are identical to @b{string-upcase}, 
@b{string-downcase}, and @b{string-capitalize}
respectively except that they  modify @i{string}.
@end table

For @b{string-upcase}, @b{string-downcase}, and @b{string-capitalize},
@i{string} is not modified.  However, if no characters in @i{string} 
require conversion, the result may be either @i{string} or a copy of it,
at the implementation's discretion.

@subsubheading  Examples::
@example
 (string-upcase "abcde") @result{}  "ABCDE"
 (string-upcase "Dr. Livingston, I presume?")
@result{}  "DR. LIVINGSTON, I PRESUME?"
 (string-upcase "Dr. Livingston, I presume?" :start 6 :end 10)
@result{}  "Dr. LiVINGston, I presume?"
 (string-downcase "Dr. Livingston, I presume?")
@result{}  "dr. livingston, i presume?"

 (string-capitalize "elm 13c arthur;fig don't") @result{}  "Elm 13c Arthur;Fig Don'T"
 (string-capitalize " hello ") @result{}  " Hello "
 (string-capitalize "occlUDeD cASEmenTs FOreSTAll iNADVertent DEFenestraTION")
@result{}   "Occluded Casements Forestall Inadvertent Defenestration"
 (string-capitalize 'kludgy-hash-search) @result{}  "Kludgy-Hash-Search"
 (string-capitalize "DON'T!") @result{}  "Don'T!"    ;not "Don't!"
 (string-capitalize "pipe 13a, foo16c") @result{}  "Pipe 13a, Foo16c"

 (setq str (copy-seq "0123ABCD890a")) @result{}  "0123ABCD890a"
 (nstring-downcase str :start 5 :end 7) @result{}  "0123AbcD890a"
 str @result{}  "0123AbcD890a"
@end example

@subsubheading  Side Effects::

    @b{nstring-upcase},
    @b{nstring-downcase}, 
and @b{nstring-capitalize} modify @i{string} as appropriate
rather than constructing a new @i{string}.

@subsubheading  See Also::

@ref{char-upcase; char-downcase}
, @b{char-downcase}

@subsubheading  Notes::
The result is always of the same length
as @i{string}.

@node string-trim, string=, string-upcase, Strings Dictionary
@subsection string-trim, string-left-trim, string-right-trim                 [Function]

@code{string-trim}  @i{character-bag string} @result{}  @i{trimmed-string}

@code{string-left-trim}  @i{character-bag string} @result{}  @i{trimmed-string}

@code{string-right-trim}  @i{character-bag string} @result{}  @i{trimmed-string}

@subsubheading  Arguments and Values::

@i{character-bag}---a @i{sequence} containing @i{characters}.

@i{string}---a @i{string designator}.

@i{trimmed-string}---a @i{string}.

@subsubheading  Description::

@b{string-trim} returns a substring of @i{string}, 
with all characters in @i{character-bag} stripped off the beginning and end.
@b{string-left-trim} is similar but strips characters off only the beginning; 
@b{string-right-trim} strips off only the end.

If no @i{characters} need to be trimmed from the @i{string},
then either @i{string} itself or a copy of it may be returned,
at the discretion of the implementation.

All of these @i{functions} observe the @i{fill pointer}.

@subsubheading  Examples::
@example
 (string-trim "abc" "abcaakaaakabcaaa") @result{}  "kaaak"
 (string-trim '(#\Space #\Tab #\Newline) " garbanzo beans
        ") @result{}  "garbanzo beans"
 (string-trim " (*)" " ( *three (silly) words* ) ")
@result{}  "three (silly) words"

 (string-left-trim "abc" "labcabcabc") @result{}  "labcabcabc"
 (string-left-trim " (*)" " ( *three (silly) words* ) ")
@result{}  "three (silly) words* ) "

 (string-right-trim " (*)" " ( *three (silly) words* ) ") 
@result{}  " ( *three (silly) words"
@end example

@subsubheading  Affected By::

The @i{implementation}.

@node string=, stringp, string-trim, Strings Dictionary
@subsection string=, string/=, string<, string>, string<=, string>=, 
@subheading string-equal, string-not-equal, string-lessp, 
@subheading string-greaterp, string-not-greaterp, string-not-lessp
@flushright
@i{[Function]}
@end flushright

@code{string=}  @i{string1 string2 {&key} start1 end1 start2 end2} @result{}  @i{generalized-boolean}

@code{string/=}  @i{string1 string2 {&key} start1 end1 start2 end2} @result{}  @i{mismatch-index}

@code{string<}  @i{string1 string2 {&key} start1 end1 start2 end2} @result{}  @i{mismatch-index}

@code{string>}  @i{string1 string2 {&key} start1 end1 start2 end2} @result{}  @i{mismatch-index}

@code{string<=}  @i{string1 string2 {&key} start1 end1 start2 end2} @result{}  @i{mismatch-index}

@code{string>=}  @i{string1 string2 {&key} start1 end1 start2 end2} @result{}  @i{mismatch-index}

@code{string-equal}  @i{string1 string2 {&key} start1 end1 start2 end2} @result{}  @i{generalized-boolean}

@code{string-not-equal}  @i{string1 string2 {&key} start1 end1 start2 end2} @result{}  @i{mismatch-index}

@code{string-lessp}  @i{string1 string2 {&key} start1 end1 start2 end2} @result{}  @i{mismatch-index}

@code{string-greaterp}  @i{string1 string2 {&key} start1 end1 start2 end2} @result{}  @i{mismatch-index}

@code{string-not-greaterp}  @i{string1 string2 {&key} start1 end1 start2 end2} @result{}  @i{mismatch-index}

@code{string-not-lessp}  @i{string1 string2 {&key} start1 end1 start2 end2} @result{}  @i{mismatch-index}

@subsubheading  Arguments and Values::

@i{string1}---a @i{string designator}.

@i{string2}---a @i{string designator}.

@i{start1}, @i{end1}---@i{bounding index designators} of @i{string1}.
 The defaults for @i{start} and @i{end} are @t{0} and @b{nil}, respectively.

@i{start2}, @i{end2}---@i{bounding index designators} of @i{string2}.
 The defaults for @i{start} and @i{end} are @t{0} and @b{nil}, respectively.

@i{generalized-boolean}---a @i{generalized boolean}.

@i{mismatch-index}---a @i{bounding index} of @i{string1}, or @b{nil}.

@subsubheading  Description::

These functions perform lexicographic comparisons on @i{string1} and @i{string2}.
@b{string=} and @b{string-equal} are called equality functions;
the others are called inequality functions.
The comparison operations these @i{functions} perform are restricted
     to the subsequence of @i{string1} @i{bounded} by @i{start1} and @i{end1}
 and to the subsequence of @i{string2} @i{bounded} by @i{start2} and @i{end2}.

A string @i{a} is equal to a string @i{b} if it contains the same number
of characters, and the corresponding characters are the @i{same}
under @b{char=} or @b{char-equal}, as appropriate.

A string @i{a} is less than a string @i{b} if in the first position in
which they differ the character of @i{a} is less than the corresponding
character of @i{b} according to @b{char<} or @b{char-lessp} 
as appropriate, or if string @i{a} is a proper prefix of string @i{b}
(of shorter length and matching in all the characters of @i{a}).

The equality functions return a @i{generalized boolean} 
that is @i{true} if the strings are equal, 
or @i{false} otherwise.

The inequality functions return a @i{mismatch-index}
that is @i{true} if the strings are not equal,
or @i{false} otherwise.
When the @i{mismatch-index} is @i{true},
it is an @i{integer} representing the first character position at which the 
two substrings differ, as an offset from the beginning of @i{string1}.

The comparison has one of the following results:

@table @asis

@item @b{string=}  
@b{string=} is @i{true} if the supplied substrings are of
the same length and contain the @i{same} characters in corresponding
positions; otherwise it is @i{false}.

@item @b{string/=}  
@b{string/=} is @i{true} if the supplied substrings are 
different; otherwise it is @i{false}.

@item @b{string-equal}  
@b{string-equal} is just like @b{string=} 
except that differences in case are ignored; 
two characters are considered to be the same if @b{char-equal} is @i{true} of them.

@item @b{string<}  
@b{string<} is @i{true} if substring1 is less than substring2;
otherwise it is @i{false}.

@item @b{string>}  
@b{string>} is @i{true} if substring1 is greater than substring2;
otherwise it is @i{false}.

@item @b{string-lessp}, @b{string-greaterp}  
@b{string-lessp} and @b{string-greaterp} 
are exactly like @b{string<} and @b{string>}, respectively,
except that distinctions between uppercase and lowercase letters are ignored.
It is as if @b{char-lessp} were used instead of @b{char<}
for comparing characters.

@item @b{string<=}  
@b{string<=} is @i{true} if substring1 is less than or equal to substring2;
otherwise it is @i{false}.

@item @b{string>=}  
@b{string>=} is @i{true} if substring1 is greater than or equal to substring2;
otherwise it is @i{false}.

@item @b{string-not-greaterp}, @b{string-not-lessp}  
@b{string-not-greaterp} and @b{string-not-lessp}
are exactly like @b{string<=} and @b{string>=}, respectively, 
except that distinctions between uppercase and lowercase letters are ignored.
It is as if @b{char-lessp} were used instead of @b{char<}
for comparing characters.

@end table

@subsubheading  Examples::

@example
 (string= "foo" "foo") @result{}  @i{true}
 (string= "foo" "Foo") @result{}  @i{false}
 (string= "foo" "bar") @result{}  @i{false}
 (string= "together" "frog" :start1 1 :end1 3 :start2 2) @result{}  @i{true}
 (string-equal "foo" "Foo") @result{}  @i{true}
 (string= "abcd" "01234abcd9012" :start2 5 :end2 9) @result{}  @i{true}
 (string< "aaaa" "aaab") @result{}  3
 (string>= "aaaaa" "aaaa") @result{}  4
 (string-not-greaterp "Abcde" "abcdE") @result{}  5
 (string-lessp "012AAAA789" "01aaab6" :start1 3 :end1 7
                                      :start2 2 :end2 6) @result{}  6
 (string-not-equal "AAAA" "aaaA") @result{}  @i{false}
@end example

@subsubheading  See Also::

@ref{char=; char/=; char<; char>; char<=; char>=; char-equal; char-not-equal; char-lessp; char-greaterp; char-not-greaterp; char-not-lessp}

@subsubheading  Notes::

@b{equal} calls @b{string=} if applied to two @i{strings}.

@node stringp, make-string, string=, Strings Dictionary
@subsection stringp                                                          [Function]

@code{stringp}  @i{object} @result{}  @i{generalized-boolean}

@subsubheading  Arguments and Values::

@i{object}---an @i{object}.

@i{generalized-boolean}---a @i{generalized boolean}.

@subsubheading  Description::

Returns @i{true} if @i{object} is of @i{type} @b{string};
otherwise, returns @i{false}.

@subsubheading  Examples::

@example
 (stringp "aaaaaa") @result{}  @i{true}
 (stringp #\a) @result{}  @i{false}
@end example

@subsubheading  See Also::

@ref{typep}
,
@b{string} (@i{type})

@subsubheading  Notes::

@example
 (stringp @i{object}) @equiv{} (typep @i{object} 'string)
@end example

@node make-string,  , stringp, Strings Dictionary
@subsection make-string                                                      [Function]

@code{make-string}  @i{size {&key} initial-element element-type} @result{}  @i{string}

@subsubheading  Arguments and Values::

@i{size}---a @i{valid array dimension}.

@i{initial-element}---a @i{character}.

 The default is @i{implementation-dependent}.

@i{element-type}---a @i{type specifier}.
 The default is @b{character}.

@i{string}---a @i{simple string}.

@subsubheading  Description::

@b{make-string} returns a @i{simple string} of length @i{size}
whose elements have been initialized to @i{initial-element}.

The @i{element-type} names the @i{type} of the @i{elements} of the @i{string};
a @i{string} is constructed of the most @i{specialized}
@i{type} that can accommodate @i{elements} of the given @i{type}.  

@subsubheading  Examples::

@example
 (make-string 10 :initial-element #\5) @result{}  "5555555555"
 (length (make-string 10)) @result{}  10
@end example

@subsubheading  Affected By::

The @i{implementation}.

@c end of including dict-strings

@c %**end of chapter