3.3 Strings
Strings (Unicode) in Guide: Racket introduces strings.
A string is a fixed-length array of characters.
A string can be mutable or immutable. When an immutable string is provided to a procedure like string-set!, the exn:fail:contract exception is raised. String constants generated by the default reader (see Reading Strings) are immutable.
Two strings are equal? when they have the same length and contain the same sequence of characters.
A string can be used as a single-valued sequence (see Sequences). The characters of the string serve as elements of the sequence. See also in-string.
See also: immutable?, symbol->string, bytes->string/utf-8.
3.3.1 String Constructors, Selectors, and Mutators
Returns #t if v
is a string, #f otherwise.
Examples: |
| > (string? "Apple") |
#t |
| > (string? 'apple) |
#f |
| (make-string k [char]) → string? |
| k : exact-nonnegative-integer? |
| char : char? = #\nul |
Returns a new mutable string of length k where
each position in the string is initialized with the character
char.
Example: |
| > (make-string 5 #\z) |
"zzzzz" |
Returns a new
mutable string whose length is the number of provided chars, and
whose positions are initialized with the given chars.
Example: |
| > (string #\A #\p #\p #\l #\e) |
"Apple" |
| (string->immutable-string str) → (and/c string? immutable?) |
| str : string? |
Returns an immutable string with the same content as
str, returning str itself if str is
immutable.
| (string-length str) → exact-nonnegative-integer? |
| str : string? |
Returns the length of str.
Example: |
| > (string-length "Apple") |
5 |
| (string-ref str k) → char? |
| str : string? |
| k : exact-nonnegative-integer? |
Returns the character at position k in str.
The first position in the string corresponds to 0, so the
position k must be less than the length of the string,
otherwise the exn:fail:contract exception is raised.
Example: |
| > (string-ref "Apple" 0) |
#\A |
| (string-set! str k char) → void? |
| str : (and/c string? (not/c immutable?)) |
| k : exact-nonnegative-integer? |
| char : char? |
Changes the
character position k in str to char. The first
position in the string corresponds to 0, so the position
k must be less than the length of the string, otherwise the
exn:fail:contract exception is raised.
Examples: |
| > (define s (string #\A #\p #\p #\l #\e)) |
| > (string-set! s 4 #\y) |
| > s |
"Apply" |
| (substring str start [end]) → string? |
| str : string? |
| start : exact-nonnegative-integer? |
| end : exact-nonnegative-integer? = (string-length str) |
Returns a new mutable string that is (- end start)
characters long, and that contains the same characters as
str from start inclusive to end exclusive.
The start and end arguments must be less than or
equal to the length of str, and end must be greater
than or equal to start, otherwise the
exn:fail:contract exception is raised.
Examples: |
| > (substring "Apple" 1 3) |
"pp" |
| > (substring "Apple" 1) |
"pple" |
| (string-copy str) → string? |
| str : string? |
| |||||||||||||||||||||||||||||||||||
| dest : (and/c string? (not/c immutable?)) | |||||||||||||||||||||||||||||||||||
| dest-start : exact-nonnegative-integer? | |||||||||||||||||||||||||||||||||||
| src : string? | |||||||||||||||||||||||||||||||||||
| src-start : exact-nonnegative-integer? = 0 | |||||||||||||||||||||||||||||||||||
| src-end : exact-nonnegative-integer? = (string-length src) |
Changes the characters of dest starting at position
dest-start to match the characters in src from
src-start (inclusive) to src-end (exclusive). The
strings dest and src can be the same string, and in
that case the destination region can overlap with the source region;
the destination characters after the copy match the source characters
from before the copy. If any of dest-start,
src-start, or src-end are out of range (taking into
account the sizes of the strings and the source and destination
regions), the exn:fail:contract exception is raised.
Examples: |
| > (define s (string #\A #\p #\p #\l #\e)) |
| > (string-copy! s 4 "y") |
| > (string-copy! s 0 s 3 4) |
| > s |
"lpply" |
| (string-fill! dest char) → void? |
| dest : (and/c string? (not/c immutable?)) |
| char : char? |
Changes dest so that every position in the
string is filled with char.
Examples: |
| > (define s (string #\A #\p #\p #\l #\e)) |
| > (string-fill! s #\q) |
| > s |
"qqqqq" |
| (string-append str ...) → string? |
| str : string? |
Returns a new mutable string that is
as long as the sum of the given strs’ lengths, and that
contains the concatenated characters of the given strs. If no
strs are provided, the result is a zero-length string.
Example: |
| > (string-append "Apple" "Banana") |
"AppleBanana" |
| (string->list str) → (listof char?) |
| str : string? |
Returns a new
list of characters corresponding to the content of str. That is,
the length of the list is (string-length str), and the
sequence of characters of str is the same sequence in the
result list.
Example: |
| > (string->list "Apple") |
'(#\A #\p #\p #\l #\e) |
| (list->string lst) → string? |
| lst : (listof char?) |
Returns a new
mutable string whose content is the list of characters in lst.
That is, the length of the string is (length lst), and
the sequence of characters in lst is in the same sequence in
the result string.
Example: |
| > (list->string (list #\A #\p #\p #\l #\e)) |
"Apple" |
| (build-string n proc) → string? |
| n : exact-nonnegative-integer? |
| proc : (exact-nonnegative-integer? . -> . char?) |
Creates a string of n characters by applying proc to
the integers from 0 to (sub1 n) in order. If
str is the resulting string, then (string-ref str i) is the character produced by (proc i).
Example: |
| > (build-string 5 (lambda (i) (integer->char (+ i 97)))) |
"abcde" |
3.3.2 String Comparisons
Returns
#t if all of the arguments are equal?.
Examples: |
| > (string=? "Apple" "apple") |
#f |
| > (string=? "a" "as" "a") |
#f |
Returns #t if the arguments are lexicographically sorted
increasing, where individual characters are ordered by
char<?, #f otherwise.
Examples: |
| > (string<? "Apple" "apple") |
#t |
| > (string<? "apple" "Apple") |
#f |
| > (string<? "a" "b" "c") |
#t |
Like string<?, but checks whether the arguments are nondecreasing.
Examples: |
| > (string<=? "Apple" "apple") |
#t |
| > (string<=? "apple" "Apple") |
#f |
| > (string<=? "a" "b" "b") |
#t |
Like string<?, but checks whether the arguments are decreasing.
Examples: |
| > (string>? "Apple" "apple") |
#f |
| > (string>? "apple" "Apple") |
#t |
| > (string>? "c" "b" "a") |
#t |
Like string<?, but checks whether the arguments are nonincreasing.
Examples: |
| > (string>=? "Apple" "apple") |
#f |
| > (string>=? "apple" "Apple") |
#t |
| > (string>=? "c" "b" "b") |
#t |
| (string-ci=? str1 str2 ...+) → boolean? |
| str1 : string? |
| str2 : string? |
Returns #t if all of the arguments are eqv? after
locale-insensitive case-folding via string-foldcase.
Examples: |
| > (string-ci=? "Apple" "apple") |
#t |
| > (string-ci=? "a" "a" "a") |
#t |
| (string-ci<? str1 str2 ...+) → boolean? |
| str1 : string? |
| str2 : string? |
Like string<?, but checks whether the arguments would be in
increasing order if each was first case-folded using
string-foldcase (which is locale-insensitive).
Examples: |
| > (string-ci<? "Apple" "apple") |
#f |
| > (string-ci<? "apple" "banana") |
#t |
| > (string-ci<? "a" "b" "c") |
#t |
| (string-ci<=? str1 str2 ...+) → boolean? |
| str1 : string? |
| str2 : string? |
Like string-ci<?, but checks whether the arguments would be nondecreasing after case-folding.
Examples: |
| > (string-ci<=? "Apple" "apple") |
#t |
| > (string-ci<=? "apple" "Apple") |
#t |
| > (string-ci<=? "a" "b" "b") |
#t |
| (string-ci>? str1 str2 ...+) → boolean? |
| str1 : string? |
| str2 : string? |
Like string-ci<?, but checks whether the arguments would be decreasing after case-folding.
Examples: |
| > (string-ci>? "Apple" "apple") |
#f |
| > (string-ci>? "banana" "Apple") |
#t |
| > (string-ci>? "c" "b" "a") |
#t |
| (string-ci>=? str1 str2 ...+) → boolean? |
| str1 : string? |
| str2 : string? |
Like string-ci<?, but checks whether the arguments would be nonincreasing after case-folding.
Examples: |
| > (string-ci>=? "Apple" "apple") |
#t |
| > (string-ci>=? "apple" "Apple") |
#t |
| > (string-ci>=? "c" "b" "b") |
#t |
3.3.3 String Conversions
| (string-upcase str) → string? |
| str : string? |
Returns a string
whose characters are the upcase conversion of the characters in
str. The conversion uses Unicode’s locale-independent
conversion rules that map code-point sequences to code-point
sequences (instead of simply mapping a 1-to-1 function on code points
over the string), so the string produced by the conversion can be
longer than the input string.
Examples: |
| > (string-upcase "abc!") |
"ABC!" |
| > (string-upcase "Straße") |
"STRASSE" |
| (string-downcase string) → string? |
| string : string? |
Like
string-upcase, but the downcase conversion.
Examples: |
| > (string-downcase "aBC!") |
"abc!" |
| > (string-downcase "Straße") |
"straße" |
| > (string-downcase "ΚΑΟΣ") |
"καος" |
| > (string-downcase "Σ") |
"σ" |
| (string-titlecase string) → string? |
| string : string? |
Like
string-upcase, but the titlecase conversion only for the
first character in each sequence of cased characters in str
(ignoring case-ignorable characters).
Examples: |
| > (string-titlecase "aBC twO") |
"Abc Two" |
| > (string-titlecase "y2k") |
"Y2K" |
| > (string-titlecase "main straße") |
"Main Straße" |
| > (string-titlecase "stra ße") |
"Stra Sse" |
| (string-foldcase string) → string? |
| string : string? |
Like
string-upcase, but the case-folding conversion.
Examples: |
| > (string-foldcase "aBC!") |
"abc!" |
| > (string-foldcase "Straße") |
"strasse" |
| > (string-foldcase "ΚΑΟΣ") |
"καοσ" |
| (string-normalize-nfd string) → string? |
| string : string? |
Returns a
string that is the Unicode normalized form D of string. If
the given string is already in the corresponding Unicode normal form,
the string may be returned directly as the result (instead of a newly
allocated string).
| (string-normalize-nfkd string) → string? |
| string : string? |
Like
string-normalize-nfd, but for normalized form KD.
| (string-normalize-nfc string) → string? |
| string : string? |
Like
string-normalize-nfd, but for normalized form C.
| (string-normalize-nfkc string) → string? |
| string : string? |
Like
string-normalize-nfd, but for normalized form KC.
3.3.4 Locale-Specific String Operations
| (string-locale=? str1 str2 ...+) → boolean? |
| str1 : string? |
| str2 : string? |
Like string=?, but the strings are compared in a
locale-specific way, based on the value of current-locale. See
Encodings and Locales for more information on locales.
| (string-locale<? str1 str2 ...+) → boolean? |
| str1 : string? |
| str2 : string? |
Like string<?, but the sort order compares strings in a
locale-specific way, based on the value of current-locale. In
particular, the sort order may not be simply a lexicographic
extension of character ordering.
| (string-locale>? str1 str2 ...+) → boolean? |
| str1 : string? |
| str2 : string? |
Like string>?, but locale-specific like
string-locale<?.
| (string-locale-ci=? str1 str2 ...+) → boolean? |
| str1 : string? |
| str2 : string? |
Like string-locale=?, but strings are compared
using rules that are both locale-specific and case-insensitive
(depending on what “case-insensitive” means for the current
locale).
| (string-locale-ci<? str1 str2 ...+) → boolean? |
| str1 : string? |
| str2 : string? |
Like string<?, but both locale-sensitive and
case-insensitive like string-locale-ci=?.
| (string-locale-ci>? str1 str2 ...+) → boolean? |
| str1 : string? |
| str2 : string? |
Like string>?, but both locale-sensitive and
case-insensitive like string-locale-ci=?.
| (string-locale-upcase string) → string? |
| string : string? |
Like
string-upcase, but using locale-specific case-conversion
rules based on the value of current-locale.
| (string-locale-downcase string) → string? |
| string : string? |
Like
string-downcase, but using locale-specific case-conversion
rules based on the value of current-locale.
3.3.5 Additional String Functions
The bindings documented in this section are provided by the racket/string and racket libraries, but not racket/base.
| (string-append* str ... strs) → string? |
| str : string? |
| strs : (listof string?) |
Like string-append, but the last argument is used as a list
of arguments for string-append, so (string-append* str ... strs) is the same as (apply string-append str ... strs). In other words, the relationship between
string-append and string-append* is similar to the
one between list and list*.
Examples: | ||
| > (string-append* "a" "b" '("c" "d")) | ||
"abcd" | ||
| ||
"Alpha, Beta, Gamma" |
| (string-join strs sep) → string? |
| strs : (listof string?) |
| sep : string? |
Appends the strings in strs, inserting sep between
each pair of strings in strs.
Example: |
| > (string-join '("one" "two" "three" "four") " potato ") |
"one potato two potato three potato four" |