Since all strings are arrays, all rules which apply generally to arrays also apply to strings. See section Array Concepts.
For example, strings can have fill pointers, and strings are also subject to the rules of element type upgrading that apply to arrays.
All functions that operate on strings will operate on subtypes of string as well.
However, the consequences are undefined if a character is inserted into a string for which the element type of the string does not include that character.
string, vector, array, sequence, t
A string is a specialized vector whose elements are of type character or a subtype of type character. When used as a type specifier for object creation, string means (vector character).
Abbreviating.
(string{[size]})
size---a non-negative fixnum, or the symbol *.
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.
section String Concepts, section Double-Quote, section Printing Strings
base-string, string, vector, array, sequence, t
The type base-string is equivalent to
(vector base-char).
The base string representation is the most efficient string representation that can hold an arbitrary sequence of standard characters.
Abbreviating.
(base-string{[size]})
size---a non-negative fixnum, or the symbol *.
This is equivalent to the type (vector base-char size); that is, the set of base strings of size size.
simple-string, string, vector, simple-array, array, sequence, t
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 specifier for object creation, simple-string means (simple-array character (size)).
Abbreviating.
(simple-string{[size]})
size---a non-negative fixnum, or the symbol *.
This denotes the union of all types (simple-array c (size)) for all subtypes c of character; that is, the set of simple strings of size size.
simple-base-string, base-string, simple-string, string, vector, simple-array, array, sequence, t
The type simple-base-string is equivalent to
(simple-array base-char (*)).
Abbreviating.
(simple-base-string{[size]})
size---a non-negative fixnum, or the symbol *.
This is equivalent to the type (simple-array base-char (size)); that is, the set of simple base strings of size size.
simple-string-p object => generalized-boolean
object---an object.
generalized-boolean---a generalized boolean.
Returns true if object is of type simple-string; otherwise, returns false.
(simple-string-p "aaaaaa") => true
(simple-string-p (make-array 6
:element-type 'character
:fill-pointer t)) => false
(simple-string-p object) == (typep object 'simple-string)
char string index => character
schar string index => character
(setf (char string index) new-character)
(setf (schar string index) new-character)
string---for char, a string; for schar, a simple string.
index---a valid array index for the string.
character, new-character---a character.
char and schar access the element of string specified by index.
char ignores fill pointers when accessing elements.
(setq my-simple-string (make-string 6 :initial-element #\A)) => "AAAAAA"
(schar my-simple-string 4) => #\A
(setf (schar my-simple-string 4) #\B) => #\B
my-simple-string => "AAAABA"
(setq my-filled-string
(make-array 6 :element-type 'character
:fill-pointer 5
:initial-contents my-simple-string))
=> "AAAAB"
(char my-filled-string 4) => #\B
(char my-filled-string 5) => #\A
(setf (char my-filled-string 3) #\C) => #\C
(setf (char my-filled-string 5) #\D) => #\D
(setf (fill-pointer my-filled-string) 6) => 6
my-filled-string => "AAACBD"
section aref [Accessor] , section elt [Accessor] ,
section Compiler Terminology
(char s j) == (aref (the string s) j)
string x => string
x---a string, a symbol, or a character.
string---a string.
Returns a string described by x; specifically:
(string "already a string") => "already a string" (string 'elm) => "ELM" (string #\c) => "c"
In the case where a conversion is defined neither by this specification nor by the implementation, an error of type type-error is signaled.
section coerce [Function] , string (type).
coerce can be used to convert a sequence of characters to a string.
prin1-to-string, princ-to-string, write-to-string, or format (with a first argument of nil) can be used to get a string representation of a number or any other object.
[Function]
string-upcase string {&key start end} => cased-string
string-downcase string {&key start end} => cased-string
string-capitalize string {&key start end} => cased-string
nstring-upcase string {&key start end} => string
nstring-downcase string {&key start end} => string
nstring-capitalize string {&key start end} => string
string---a string designator. For nstring-upcase, nstring-downcase, and nstring-capitalize, the string designator must be a string.
start, end---bounding index designators of string. The defaults for start and end are 0 and nil, respectively.
cased-string---a string.
string-upcase, string-downcase, string-capitalize, nstring-upcase, nstring-downcase, nstring-capitalize change the case of the subsequence of string bounded by start and end as follows:
For string-upcase, string-downcase, and string-capitalize, string is not modified. However, if no characters in string require conversion, the result may be either string or a copy of it, at the implementation's discretion.
(string-upcase "abcde") => "ABCDE" (string-upcase "Dr. Livingston, I presume?") => "DR. LIVINGSTON, I PRESUME?" (string-upcase "Dr. Livingston, I presume?" :start 6 :end 10) => "Dr. LiVINGston, I presume?" (string-downcase "Dr. Livingston, I presume?") => "dr. livingston, i presume?" (string-capitalize "elm 13c arthur;fig don't") => "Elm 13c Arthur;Fig Don'T" (string-capitalize " hello ") => " Hello " (string-capitalize "occlUDeD cASEmenTs FOreSTAll iNADVertent DEFenestraTION") => "Occluded Casements Forestall Inadvertent Defenestration" (string-capitalize 'kludgy-hash-search) => "Kludgy-Hash-Search" (string-capitalize "DON'T!") => "Don'T!" ;not "Don't!" (string-capitalize "pipe 13a, foo16c") => "Pipe 13a, Foo16c" (setq str (copy-seq "0123ABCD890a")) => "0123ABCD890a" (nstring-downcase str :start 5 :end 7) => "0123AbcD890a" str => "0123AbcD890a"
nstring-upcase, nstring-downcase, and nstring-capitalize modify string as appropriate rather than constructing a new string.
@xref{char-upcase; char-downcase} , char-downcase
The result is always of the same length as string.
string-trim character-bag string => trimmed-string
string-left-trim character-bag string => trimmed-string
string-right-trim character-bag string => trimmed-string
character-bag---a sequence containing characters.
string---a string designator.
trimmed-string---a string.
string-trim returns a substring of string, with all characters in character-bag stripped off the beginning and end. string-left-trim is similar but strips characters off only the beginning; string-right-trim strips off only the end.
If no characters need to be trimmed from the string, then either string itself or a copy of it may be returned, at the discretion of the implementation.
All of these functions observe the fill pointer.
(string-trim "abc" "abcaakaaakabcaaa") => "kaaak"
(string-trim '(#\Space #\Tab #\Newline) " garbanzo beans
") => "garbanzo beans"
(string-trim " (*)" " ( *three (silly) words* ) ")
=> "three (silly) words"
(string-left-trim "abc" "labcabcabc") => "labcabcabc"
(string-left-trim " (*)" " ( *three (silly) words* ) ")
=> "three (silly) words* ) "
(string-right-trim " (*)" " ( *three (silly) words* ) ")
=> " ( *three (silly) words"
The implementation.
[Function]
string= string1 string2 {&key start1 end1 start2 end2} => generalized-boolean
string/= string1 string2 {&key start1 end1 start2 end2} => mismatch-index
string< string1 string2 {&key start1 end1 start2 end2} => mismatch-index
string> string1 string2 {&key start1 end1 start2 end2} => mismatch-index
string<= string1 string2 {&key start1 end1 start2 end2} => mismatch-index
string>= string1 string2 {&key start1 end1 start2 end2} => mismatch-index
string-equal string1 string2 {&key start1 end1 start2 end2} => generalized-boolean
string-not-equal string1 string2 {&key start1 end1 start2 end2} => mismatch-index
string-lessp string1 string2 {&key start1 end1 start2 end2} => mismatch-index
string-greaterp string1 string2 {&key start1 end1 start2 end2} => mismatch-index
string-not-greaterp string1 string2 {&key start1 end1 start2 end2} => mismatch-index
string-not-lessp string1 string2 {&key start1 end1 start2 end2} => mismatch-index
string1---a string designator.
string2---a string designator.
start1, end1---bounding index designators of string1. The defaults for start and end are 0 and nil, respectively.
start2, end2---bounding index designators of string2. The defaults for start and end are 0 and nil, respectively.
generalized-boolean---a generalized boolean.
mismatch-index---a bounding index of string1, or nil.
These functions perform lexicographic comparisons on string1 and string2. string= and string-equal are called equality functions; the others are called inequality functions. The comparison operations these functions perform are restricted to the subsequence of string1 bounded by start1 and end1 and to the subsequence of string2 bounded by start2 and end2.
A string a is equal to a string b if it contains the same number of characters, and the corresponding characters are the same under char= or char-equal, as appropriate.
A string a is less than a string b if in the first position in which they differ the character of a is less than the corresponding character of b according to char< or char-lessp as appropriate, or if string a is a proper prefix of string b (of shorter length and matching in all the characters of a).
The equality functions return a generalized boolean that is true if the strings are equal, or false otherwise.
The inequality functions return a mismatch-index that is true if the strings are not equal, or false otherwise. When the mismatch-index is true, it is an integer representing the first character position at which the two substrings differ, as an offset from the beginning of string1.
The comparison has one of the following results:
(string= "foo" "foo") => true
(string= "foo" "Foo") => false
(string= "foo" "bar") => false
(string= "together" "frog" :start1 1 :end1 3 :start2 2) => true
(string-equal "foo" "Foo") => true
(string= "abcd" "01234abcd9012" :start2 5 :end2 9) => true
(string< "aaaa" "aaab") => 3
(string>= "aaaaa" "aaaa") => 4
(string-not-greaterp "Abcde" "abcdE") => 5
(string-lessp "012AAAA789" "01aaab6" :start1 3 :end1 7
:start2 2 :end2 6) => 6
(string-not-equal "AAAA" "aaaA") => false
@xref{char=; char/=; char<; char>; char<=; char>=; char-equal; char-not-equal; char-lessp; char-greaterp; char-not-greaterp; char-not-lessp}
equal calls string= if applied to two strings.
stringp object => generalized-boolean
object---an object.
generalized-boolean---a generalized boolean.
Returns true if object is of type string; otherwise, returns false.
(stringp "aaaaaa") => true (stringp #\a) => false
section typep [Function] , string (type)
(stringp object) == (typep object 'string)
make-string size {&key initial-element element-type} => string
size---a valid array dimension.
initial-element---a character.
The default is implementation-dependent.
element-type---a type specifier. The default is character.
string---a simple string.
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.
(make-string 10 :initial-element #\5) => "5555555555" (length (make-string 10)) => 10
The implementation.
Go to the first, previous, next, last section, table of contents.