Version 15.17, X3J13/94-101. Version 15.17, X3J13/94-101.

Wed 11-May-1994 6:57pm EDT Wed 11-May-1994 6:57pm EDT

Programming Language|Common Lisp

16. Strings

Strings i ii Programming Language|Common Lisp

Version 15.17, X3J13/94-101. Version 15.17, X3J13/94-101.
Wed 11-May-1994 6:57pm EDT Wed 11-May-1994 6:57pm EDT

16.1 String Concepts string System Class

16.1.1 Implications of Strings Being Arrays Class Precedence List:

string, vector, array , sequence, t
Since all strings are arrays , all rules which apply generally to arrays also apply to strings . See
Section 15.1 (Array Concepts). Description:
A string is a specialized vector whose elements are of type character or a subtype of type
For example, strings can have ll pointers , and strings are also subject to the rules of element character. When used as a type specier for object creation, string means (vector character).
type upgrading that apply to arrays .
Compound Type Specier Kind:
16.1.2 Subtypes of STRING Abbreviating.
All functions that operate on strings will operate on subtypes of string as well. Compound Type Specier Syntax:
(string [size ])
However, the consequences are undened if a character is inserted into a string for which the
element type of the string does not include that character .
Compound Type Specier Arguments:
size |a non-negative xnum , or the symbol *.
Compound Type Specier Description:
This denotes the union of all types (array c (size )) for all subtypes c of character; that is, the
set of strings of size size .
See Also:
Section 16.1 (String Concepts), Section 2.4.5 (Double-Quote), Section 22.1.3.4 (Printing Strings)

base-string Type

Supertypes:
base-string, string, vector, array , sequence, t
Description:
The type base-string is equivalent to (vector base-char). The base string representation is the
most ecient string representation that can hold an arbitrary sequence of standard characters .
Compound Type Specier Kind:
Abbreviating.
Compound Type Specier Syntax:
(base-string [ size ])

Strings 16{1 16{2 Programming Language|Common Lisp

Version 15.17, X3J13/94-101. Version 15.17, X3J13/94-101.
Wed 11-May-1994 6:57pm EDT Wed 11-May-1994 6:57pm EDT

Compound Type Specier Arguments:

size |a non-negative xnum , or the symbol *.
simple-base-string Type

Compound Type Specier Description: Supertypes:

This is equivalent to the type (vector base-char size ); that is, the set of base strings of size size . simple-base-string, base-string, simple-string, string, vector, simple-array, array , sequence, t
Description:
simple-string Type The type simple-base-string is equivalent to (simple-array base-char (*)).
Compound Type Specier Kind:
Supertypes: Abbreviating.
simple-string, string, vector, simple-array, array , sequence, t Compound Type Specier Syntax:
Description: (simple-base-string [ size ])
A simple string is a specialized one-dimensional simple array whose elements are of type
character or a subtype of type character. When used as a type specier for object creation,
simple-string means (simple-array character (size)). Compound Type Specier Arguments:
Compound Type Specier Kind: size |a non-negative xnum , or the symbol *.
Abbreviating. Compound Type Specier Description:
Compound Type Specier Syntax: This is equivalent to the type (simple-array base-char (size )); that is, the set of simple base
strings of size size .
(simple-string [ size ])

Compound Type Specier Arguments:

size |a non-negative xnum , or the symbol *.
simple-string-p Function
Compound Type Specier Description: Syntax:
This denotes the union of all types (simple-array c (size )) for all subtypes c of character; that simple-string-p object ! generalized-boolean
is, the set of simple strings of size size .
Arguments and Values:
object |an object .
generalized-boolean|a generalized boolean .
Description:
Returns true if object is of type simple-string; otherwise, returns false .
Examples:
(simple-string-p "aaaaaa") ! true
(simple-string-p (make-array 6
:element-type 'character
:fill-pointer t)) ! false

Strings 16{3 16{4 Programming Language|Common Lisp

Version 15.17, X3J13/94-101. Version 15.17, X3J13/94-101.
Wed 11-May-1994 6:57pm EDT Wed 11-May-1994 6:57pm EDT

Notes: See Also:

aref , elt, Section 3.2.1 (Compiler Terminology)
(simple-string-p object )  (typep object 'simple-string)
Notes:

char, schar
(char s j) (aref (the string s) j)

Accessor

Syntax:
char string index ! character
string Function
schar string index ! character
Syntax:
(setf (char string index) new-character) string x ! string
(setf (schar string index) new-character)
Arguments and Values: Arguments and Values:
x |a string , a symbol , or a character .
string |for char, a string ; for schar, a simple string .
string |a string .
index |a valid array index for the string .
character , new-character |a character .
Description:
Returns a string described by x ; specically:
Description: If x is a string , it is returned.
char and schar access the element of string specied by index . 

char ignores ll pointers when accessing elements .  If x is a symbol , its name is returned.
 If x is a character , then a string containing that one character is returned.
Examples:  string might perform additional, implementation-dened conversions.
(setq my-simple-string (make-string 6 :initial-element #\A))
(schar my-simple-string 4) ! #\A
! "AAAAAA"
Examples:
(setf (schar my-simple-string 4) #\B) ! #\B (string "already a string") ! "already a string"
my-simple-string ! "AAAABA" (string 'elm) ! "ELM"
(setq my-filled-string (string #\c) ! "c"
(make-array 6 :element-type 'character
:fill-pointer 5 Exceptional Situations:
:initial-contents my-simple-string)) In the case where a conversion is dened neither by this specication nor by the implementation ,
! "AAAAB" an error of type type-error is signaled.
(char my-filled-string 4) ! #\B
(char my-filled-string 5) ! #\A See Also:
(setf (char my-filled-string 3) #\C) ! #\C
(setf (char my-filled-string 5) #\D) ! #\D
coerce, string (type ).
(setf (fill-pointer my-filled-string) 6) ! 6
my-filled-string ! "AAACBD"
Notes:
coerce can be used to convert a sequence of characters to a string .

Strings 16{5 16{6 Programming Language|Common Lisp

Version 15.17, X3J13/94-101. Version 15.17, X3J13/94-101.
Wed 11-May-1994 6:57pm EDT Wed 11-May-1994 6:57pm EDT

string-upcase, string-downcase, string-capitalize, :::

prin1-to-string, princ-to-string, write-to-string, or format (with a rst argument of nil) can be string-capitalize
used to get a string representation of a number or any other object .
string-capitalize produces a copy of string such that, for every word in the copy, the rst
character of the \word," if it has case , is uppercase and any other characters with case in
string-upcase, string-downcase, string-capitalize, the word are lowercase . For the purposes of string-capitalize, a \word" is dened to be
a consecutive subsequence consisting of alphanumeric characters , delimited at each end
nstring-upcase, nstring-downcase, nstring- either by a non-alphanumeric character or by an end of the string .
capitalize Function nstring-upcase, nstring-downcase, nstring-capitalize

nstring-upcase, nstring-downcase, and nstring-capitalize are identical to

Syntax: string-upcase, string-downcase, and string-capitalize respectively except that they
string-upcase string &key start end !cased-string modify string .
string-downcase string &key start end !cased-string
For string-upcase, string-downcase, and string-capitalize, string is not modied. However, if
string-capitalize string &key start end !cased-string
no characters in string require conversion, the result may be either string or a copy of it, at the
nstring-upcase string &key start end ! string implementation's discretion.
nstring-downcase string &key start end ! string
nstring-capitalize string &key start end ! string Examples:
Arguments and Values: (string-upcase "abcde") ! "ABCDE"
string |a string designator . For nstring-upcase, nstring-downcase, and nstring-capitalize, the (string-upcase "Dr. Livingston, I presume?")
! "DR. LIVINGSTON, I PRESUME?"
string designator must be a string . (string-upcase "Dr. Livingston, I presume?" :start 6 :end 10)
start , end |bounding index designators of string . The defaults for start and end are 0 and nil, ! "Dr. LiVINGston, I presume?"
respectively. (string-downcase "Dr. Livingston, I presume?")
! "dr. livingston, i presume?"
cased-string |a string .
Description: (string-capitalize "elm 13c arthur;fig don't") ! "Elm 13c Arthur;Fig Don'T"
(string-capitalize " hello ") ! " Hello "
string-upcase, string-downcase, string-capitalize, nstring-upcase, nstring-downcase, (string-capitalize "occlUDeD cASEmenTs FOreSTAll iNADVertent DEFenestraTION")
nstring-capitalize change the case of the subsequence of string bounded by start and end as ! "Occluded Casements Forestall Inadvertent Defenestration"
follows: (string-capitalize 'kludgy-hash-search) ! "Kludgy-Hash-Search"
(string-capitalize "DON'T!") ! "Don'T!" ;not "Don't!"
string-upcase (string-capitalize "pipe 13a, foo16c") ! "Pipe 13a, Foo16c"

string-upcase returns a string just like string with all lowercase characters replaced by (setq str (copy-seq "0123ABCD890a")) ! "0123ABCD890a"
the corresponding uppercase characters. More precisely, each character of the result string (nstring-downcase str :start 5 :end 7) ! "0123AbcD890a"
is produced by applying the function char-upcase to the corresponding character of str ! "0123AbcD890a"
string .
Side Eects:
string-downcase nstring-upcase, nstring-downcase, and nstring-capitalize modify string as appropriate rather
string-downcase is like string-upcase except that all uppercase characters are replaced than constructing a new string .
by the corresponding lowercase characters (using char-downcase). See Also:
char-upcase, char-downcase

Strings 16{7 16{8 Programming Language|Common Lisp

Version 15.17, X3J13/94-101. Version 15.17, X3J13/94-101.
Wed 11-May-1994 6:57pm EDT Wed 11-May-1994 6:57pm EDT

Notes: Aected By:

The result is always of the same length as string . The implementation .

string-trim, string-left-trim, string-right-trim Func- string=, string/=, string<, string>, string<=,

tion string>=, string-equal, string-not-equal, string-
lessp, string-greaterp, string-not-greaterp, string-
Syntax:
string-trim character-bag string ! trimmed-string
not-lessp Function
string-left-trim character-bag string ! trimmed-string
string-right-trim character-bag string ! trimmed-string Syntax:
Arguments and Values: string= string1 string2 &key start1 end1 start2 end2 ! generalized-boolean
character-bag |a sequence containing characters . string/= string1 string2 &key start1 end1 start2 end2 ! mismatch-index
string |a string designator . string< string1 string2 &key start1 end1 start2 end2 ! mismatch-index
string> string1 string2 &key start1 end1 start2 end2 ! mismatch-index
trimmed-string |a string . string<= string1 string2 &key start1 end1 start2 end2 ! mismatch-index
string>= string1 string2 &key start1 end1 start2 end2 ! mismatch-index
Description: string-equal string1 string2 &key start1 end1 start2 end2 ! generalized-boolean
string-trim returns a substring of string , with all characters in character-bag stripped o the
beginning and end. string-left-trim is similar but strips characters o only the beginning; string-not-equal string1 string2 &key start1 end1 start2 end2 ! mismatch-index
string-right-trim strips o only the end. string-lessp string1 string2 &key start1 end1 start2 end2 ! mismatch-index
If no characters need to be trimmed from the string , then either string itself or a copy of it may string-greaterp string1 string2 &key start1 end1 start2 end2 ! mismatch-index
be returned, at the discretion of the implementation. string-not-greaterp string1 string2 &key start1 end1 start2 end2 ! mismatch-index
string-not-lessp string1 string2 &key start1 end1 start2 end2 ! mismatch-index
All of these functions observe the ll pointer . Arguments and Values:
Examples: string1 |a string designator .
(string-trim "abc" "abcaakaaakabcaaa") ! "kaaak" string2 |a string designator .
(string-trim '(#\Space #\Tab #\Newline) " garbanzo beans
") ! "garbanzo beans"
start1 , end1 |bounding index designators of string1 . The defaults for start and end are 0 and nil,
(string-trim " (*)" " ( *three (silly) words* ) ")
respectively.
! "three (silly) words" start2 , end2 |bounding index designators of string2 . The defaults for start and end are 0 and nil,
respectively.
(string-left-trim "abc" "labcabcabc") ! "labcabcabc"
(string-left-trim " (*)" " ( *three (silly) words* ) ") generalized-boolean|a generalized boolean .
! "three (silly) words* ) "
mismatch-index |a bounding index of string1 , or nil.
!
(string-right-trim " (*)" " ( *three (silly) words* ) ")
" ( *three (silly) words"
Description:
These functions perform lexicographic comparisons on string1 and string2 . string= and
string-equal are called equality functions; the others are called inequality functions. The compar-

Strings 16{9 16{10 Programming Language|Common Lisp

Version 15.17, X3J13/94-101. Version 15.17, X3J13/94-101.
Wed 11-May-1994 6:57pm EDT Wed 11-May-1994 6:57pm EDT

string=, string/=, string<, string>, string<=, :::

ison operations these functions perform are restricted to the subsequence of string1 bounded by string>=
start1 and end1 and to the subsequence of string2 bounded by start2 and end2 .
string>= is true if substring1 is greater than or equal to substring2; otherwise it is false .
A string a is equal to a string b if it contains the same number of characters, and the correspond-
ing characters are the same under char= or char-equal, as appropriate. string-not-greaterp, string-not-lessp
A string a is less than a string b if in the rst position in which they dier the character of a is string-not-greaterp and string-not-lessp are exactly like string<= and string>=,
less than the corresponding character of b according to char< or char-lessp as appropriate, or if respectively, except that distinctions between uppercase and lowercase letters are ignored.
string a is a proper prex of string b (of shorter length and matching in all the characters of a). It is as if char-lessp were used instead of char< for comparing characters.
The equality functions return a generalized boolean that is true if the strings are equal, or false
otherwise.
Examples:
(string= "foo" "foo") ! true
The inequality functions return a mismatch-index that is true if the strings are not equal, or (string= "foo" "Foo") ! false
false otherwise. When the mismatch-index is true , it is an integer representing the rst character (string= "foo" "bar") ! false
position at which the two substrings dier, as an oset from the beginning of string1 . (string= "together" "frog" :start1 1 :end1 3 :start2 2) ! true
The comparison has one of the following results: (string-equal "foo" "Foo") ! true
(string= "abcd" "01234abcd9012" :start2 5 :end2 9) ! true
(string< "aaaa" "aaab") ! 3
string= (string>= "aaaaa" "aaaa") ! 4
string= is true if the supplied substrings are of the same length and contain the same (string-not-greaterp "Abcde" "abcdE") ! 5
characters in corresponding positions; otherwise it is false . (string-lessp "012AAAA789" "01aaab6" :start1 3 :end1 7
:start2 2 :end2 6) ! 6
string/= (string-not-equal "AAAA" "aaaA") ! false
string/= is true if the supplied substrings are dierent; otherwise it is false . See Also:
char=
string-equal
string-equal is just like string= except that dierences in case are ignored; two charac-
Notes:
equal calls string= if applied to two strings .
ters are considered to be the same if char-equal is true of them.
string<
string< is true if substring1 is less than substring2; otherwise it is false .
stringp Function

string> Syntax:
string> is true if substring1 is greater than substring2; otherwise it is false . stringp object ! generalized-boolean

string-lessp, string-greaterp
Arguments and Values:
object |an object .
string-lessp and string-greaterp are exactly like string< and string>, respectively, generalized-boolean|a generalized boolean .
except that distinctions between uppercase and lowercase letters are ignored. It is as if
char-lessp were used instead of char< for comparing characters. Description:
string<= Returns true if object is of type string; otherwise, returns false .
string<= is true if substring1 is less than or equal to substring2; otherwise it is false .

Strings 16{11 16{12 Programming Language|Common Lisp

Version 15.17, X3J13/94-101. Version 15.17, X3J13/94-101.
Wed 11-May-1994 6:57pm EDT Wed 11-May-1994 6:57pm EDT

Examples:
(stringp "aaaaaa") ! true
(stringp #\a) ! false
See Also:
typep, string (type )
Notes:
(stringp object )  (typep object 'string)

make-string Function

Syntax:
make-string size &key initial-element element-type ! string
Arguments and Values:
size |a valid array dimension .
initial-element |a character . The default is implementation-dependent .
element-type |a type specier . The default is character.
string |a simple string .
Description:
make-string returns a simple string of length size whose elements have been initialized to initial-
element .
The element-type names the type of the elements of the string ; a string is constructed of the most
specialized type that can accommodate elements of the given type .
Examples:
(make-string 10 :initial-element #\5) ! "5555555555"
(length (make-string 10)) ! 10

Aected By:
The implementation .

Strings 16{13 16{14 Programming Language|Common Lisp