6.3 Common LISP String Functions
A Common LISP compatible package of string functions has been implemented in PSL,
obtained by loading the strings module. This section describes the strings module, including a
few functions in it that are not Common LISP functions.
6.3.1 String comparison:
(string= S1:string S2:string): boolean expr
Compares two strings S1 and S2, case sensitive.
(string-equal S1:string S2:string): boolean expr
Compare two strings S1 and S2, ignoring case, bits and font.
The following string comparison functions are extra-boolean. If the comparison results in a
value of t, the index of the first character position at which the strings fail to match is
returned. The result can also be thought of as the longest common prefix of the two
strings.
(string< S1:string S2:string): extra-boolean expr
Lexicographic comparison of strings. Case sensitive.
(string> S1:string S2:string): extra-boolean expr
Lexicographic comparison of strings. Case sensitive.
(string<= S1:string S2:string): extra-boolean expr
Lexicographic comparison of strings. Case sensitive.
(string>= S1:string S2:string): extra-boolean expr
Lexicographic comparison of strings. Case sensitive.
(string<> S1:string S2:string): extra-boolean expr
Lexicographic comparison of strings. Case sensitive. In Common LISP the
function is named string/=.
(string-lessp S1:string S2:string): extra-boolean expr
Lexicographic comparison of strings. Case differences are ignored.
(string-greaterp S1:string S2:string): extra-boolean expr
Lexicographic comparison of strings. Case differences are ignored.
(string-not-greaterp S1:string S2:string): extra-boolean expr
Lexicographic comparison of strings. Case differences are ignored.
(string-not-lessp S1:string S2:string): extra-boolean expr
Lexicographic comparison of strings. Case differences are ignored.
(string-not-equal S1:string S2:string): extra-boolean expr
Lexicographic comparison of strings. Case differences are ignored.
6.3.2 String Concatenation:
(string-concat [S:string]): string macro
Concatenates all of its string arguments, returning the newly created string.
Not in Common LISP.
(string-repeat S:string I:integer): string expr
Appends copy of S to itself total of I-1 times. Not in Common LISP.
6.3.3 Transformation of Strings:
(substring S:string LO:integer HI:integer): string expr
Same as subseq, but the first argument must be a string. Returns a substring
of S of size (sub1 (- HI LO)), beginning with the element with index LO.
Not in Common LISP.
(string-trim BAG:{list, string} S:string): string expr
Remove leading and trailing characters in BAG from a string S.
1 lisp> (string-trim "ABC" "AABAXYZCB")
"XYZ"
2 lisp> (string-trim (list (char a)
2 lisp> (char b)
2 lisp> (char c))
2 lisp> "AABAXYZCB")
"XYZ"
3 lisp> (string-trim '(65 66 67) "ABCBAVXZCC")
"VXZ"
(string-left-trim BAG:{list, string} S:string): string expr
Remove leading characters from string.
(string-right-trim BAG:{list, string} S:string): string expr
Remove trailing characters from string.
(string-upcase S:string): string expr
Copy and raise all alphabetic characters in string.
(nstring-upcase S:string): string expr
Destructively raise all alphabetic characters in string.
(string-downcase S:string): string expr
Copy and lower all alphabetic characters in string.
(nstring-downcase S:string): string expr
Destructively lower all alphabetic characters in string.
(string-capitalize S:string): string expr
Copy and raise first letter of all words in string; other letters in lower case.
(nstring-capitalize S:string): string expr
Destructively raise first letter of all words; other letters in lower case.
6.3.4 Type Conversion:
(string-to-list S:string): list expr
Unpack string characters into a list. Not in Common LISP.
(string-to-vector S:string): vector expr
Unpack string characters into a vector. Not in Common LISP.
6.3.5 Other:
(string-length S:string): integer expr
Last index of a string, plus one. Not in Common LISP. Use string-size.
(rplachar S:string I:integer C:character): character expr
Store a character C in a string S at position I.
6.3.6 Substring Comparison
The library module STRING-SEARCH provides efficient functions for comparing a string
against a substring of another string.
(substring= S1:string S2:string START:integer): boolean expr
Returns true if there is a substring of S2 starting at START and string= to
S1, otherwise returns nil.
Similar to
(string= S1 (substring S2 START (+ START (string-length S1))))
but note that this returns nil (no error is signalled) if there are fewer than
(string-length S1)
characters from position START through the end of S2.
(substring-equal S1:string S2:string START:integer): boolean expr
Returns true if there is a substring of S2 starting at START and string-equal
to S1, otherwise returns nil.
Similar to
(string-equal S1 (substring S2 START (+ START (string-length S1))))
but note that this returns nil (no error is signalled) if there are fewer than
(string-length S1)
characters from position START through the end of S2.
6.3.7 Searching for Strings
The library module str-search provides functions for searching for a string within another
string. These functions are efficiently implemented.
The two strings involved in these searching operations are referred to as the ”domain” and the
”target”. These functions search for an occurrence of the ”target” string within the ”domain”
string.
The operations for string searching return the index of the leftmost character in the first
matching part of the domain string that is found, starting from the left. If no match is found, nil
is returned.
(string-search TARG:string DOM:string):{integer, nil} expr
Searches for the leftmost occurrence of the target in the domain. This
function is case-sensitive. If passed two strings, Common LISP ”search”
will give the same results.
(string-search-from TARG:string DOM:string START:integer):{integer, nil} expr
Like string-search, but the search effectively starts at index START in the
domain.
(string-search-equal TARG:string DOM:string):{integer, nil} expr
Like string-search except that the comparisons are case-insensitive.
(string-search-from-equal TA:string D:string ST:integer):{integer, nil} expr
Like string-search-from except that the comparisons are case-insensitive.
6.3.8 Reading and Writing Strings
The library module str-input provides some facilities to support taking input from strings.
Among other things, this permits a user to obtain a number from its printed representation using
the PSL number parser.
(with-input-from-string HEADER:list [BODY:form]):any macro
The argument HEADER should be a two element list.
The first element should be an identifier, the second a string. (<
channel >< string >). The argument < string > is treated as if it were
the text of a file. The argument < channel > is bound to an input channel
which is opened to give access to < string >. Once the channel has been
opened, each form BODY is evaluated (the forms are evaluated in a left to
right order). It is expected that these forms will be used to read and process
input from < string >. The value of the last form is returned. Once the
application of with-input-from-string is complete the input channel will be
closed.
(de string-to-words (string)
(with-input-from-string
(channel string)
(do ((result nil (aconc result item))
(item (channelread channel) (channelread channel)))
((eq item $eof$) result))))
1 lisp> (string-to-words "DOCUMENTATION IS FUN")
(DOCUMENTATION IS FUN)
(string-read STR:string): any expr
Reads one s-expression from the string STR. The function channelread is
used to do this. Note that it is not necessary to terminate the string with
a delimiter character. An end of file character is also considered to be a
delimiter character.
1 lisp> (string-read "TOKEN")
TOKEN
2 lisp> (string-read "TWO TOKENS")
TWO
Notice that characters beyond the first s-expression are ignored. This function is defined in
terms of with-input-from-string.
(de string-read (string)
(with-input-from-string
(ch string)
(channelread ch)))
The library module string-output provides a facility for writing to strings. The function bldmsg
provides the capability to construct a string using formatting directives. However,
complicated strings can be constructed more easily using the macro with-output-to-string.
For example, longer strings can be constructed by including the channellinelength
function; items can be printed to the string incrementally (in a stream-like fashion) from a
loop
(with-output-to-string HEADER:list [BODY:form]): string macro
The argument HEADER should be a two element list. The first element
should be an identifier. The second element can be either a string or nil (in
which case a default initial string is allocated) – in either case, the initial
string is extened as necessary.
The written string is return as a result (this is a substring copy of the string used for writing).
For example,
(setf row
(with-output-to-string (wchan nil)
(channellinelength wchan 350)
(for (in tab '(0 100 200 300))
(in str '("A" "B" "C" "D"))
(do (channelprintf wchan "%t%w" tab str))
)))