3.3 Strings

Strings (Unicode) in The Racket Guide 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, and they are interned in read-syntax mode.

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 Reading Strings for information on reading strings and Printing Strings for information on printing strings.

3.3.1 String Constructors, Selectors, and Mutators

procedure
(string? v) → boolean?
v : any/c

Returns #t if v is a string, #f otherwise.

Examples:
> (string? "Apple")
#t
> (string? 'apple)
#f

procedure
(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"

procedure
(string char ...) → string?
char : char?

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"

procedure
(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.

procedure
(string-length str) → exact-nonnegative-integer?
str : string?

Returns the length of str.

Example:
> (string-length "Apple")
5

procedure
(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

procedure
(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"

procedure
(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 first position in a string corresponds to 0, so the start and end arguments so they 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"

procedure
(string-copy str) → string?
str : string?

Returns (substring str 0).

procedure
(string-copy! dest
dest-start
src
[ src-start
src-end]) → void?
  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), where the first position in a string corresponds to 0. 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"

procedure
(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"

procedure
(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"

procedure
(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 in str is the same sequence in the result list.

Example:
> (string->list "Apple")
'(#\A #\p #\p #\l #\e)

procedure
(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 the same sequence in the result string.

Example:
> (list->string (list #\A #\p #\p #\l #\e))
"Apple"

procedure
(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

procedure
(string=? str1 str2 ...+) → boolean?
str1 : string?
str2 : string?

Returns #t if all of the arguments are equal?.

Examples:
> (string=? "Apple" "apple")
#f
> (string=? "a" "as" "a")
#f

procedure
(string<? str1 str2 ...+) → boolean?
str1 : string?
str2 : string?

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

procedure
(string<=? str1 str2 ...+) → boolean?
str1 : string?
str2 : string?

Like string<?, but checks whether the arguments are nondecreasing.

Examples:
> (string<=? "Apple" "apple")
#t
> (string<=? "apple" "Apple")
#f
> (string<=? "a" "b" "b")
#t

procedure
(string>? str1 str2 ...+) → boolean?
str1 : string?
str2 : string?

Like string<?, but checks whether the arguments are decreasing.

Examples:
> (string>? "Apple" "apple")
#f
> (string>? "apple" "Apple")
#t
> (string>? "c" "b" "a")
#t

procedure
(string>=? str1 str2 ...+) → boolean?
str1 : string?
str2 : string?

Like string<?, but checks whether the arguments are nonincreasing.

Examples:
> (string>=? "Apple" "apple")
#f
> (string>=? "apple" "Apple")
#t
> (string>=? "c" "b" "b")
#t

procedure
(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

procedure
(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

procedure
(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

procedure
(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

procedure
(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

procedure
(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"

procedure
(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 "Σ")
"σ"

procedure
(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"

procedure
(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 "ΚΑΟΣ")
"καοσ"

procedure
(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).

procedure
(string-normalize-nfkd string) → string?
string : string?

Like string-normalize-nfd, but for normalized form KD.

procedure
(string-normalize-nfc string) → string?
string : string?

Like string-normalize-nfd, but for normalized form C.

procedure
(string-normalize-nfkc string) → string?
string : string?

Like string-normalize-nfd, but for normalized form KC.

3.3.4 Locale-Specific String Operations

procedure
(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.

procedure
(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.

procedure
(string-locale>? str1 str2 ...+) → boolean?
str1 : string?
str2 : string?

Like string>?, but locale-specific like string-locale<?.

procedure
(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).

procedure
(string-locale-ci<? str1 str2 ...+) → boolean?
str1 : string?
str2 : string?

Like string<?, but both locale-sensitive and case-insensitive like string-locale-ci=?.

procedure
(string-locale-ci>? str1 str2 ...+) → boolean?
str1 : string?
str2 : string?

Like string>?, but both locale-sensitive and case-insensitive like string-locale-ci=?.

procedure
(string-locale-upcase string) → string?
string : string?

Like string-upcase, but using locale-specific case-conversion rules based on the value of current-locale.

procedure
(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

(require racket/string)

The bindings documented in this section are provided by the racket/string and racket libraries, but not racket/base.

procedure
(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"
> (string-append* (cdr (append* (map (lambda (x) (list ", " x))
'("Alpha" "Beta" "Gamma")))))
"Alpha, Beta, Gamma"

procedure
(string-join strs
[ sep
#:before-first before-first
#:before-last before-last
#:after-last after-last]) → string?
  strs : (listof string?)
  sep : string? = " "
  before-first : string? = ""
  before-last : string? = sep
  after-last : string? = ""

Appends the strings in strs, inserting sep between each pair of strings in strs. before-last, before-first, and after-last are analogous to the inputs of add-between: they specify an alternate separator between the last two strings, a prefix string, and a suffix string respectively.

Examples:
> (string-join '("one" "two" "three" "four"))
"one two three four"
> (string-join '("one" "two" "three" "four") ", ")
"one, two, three, four"
> (string-join '("one" "two" "three" "four") " potato ")
"one potato two potato three potato four"
> (string-join '("x" "y" "z") ", "
               #:before-first "Todo: "
               #:before-last " and "
               #:after-last ".")
"Todo: x, y and z."

procedure
(string-normalize-spaces str
[ sep
space
#:trim? trim?
#:repeat? repeat?]) → string?
  str : string?
  sep : (or/c string? regexp?) = #px"\\s+"
  space : string? = " "
  trim? : any/c = #t
  repeat? : any/c = #f

Normalizes spaces in the input str by trimming it (using string-trim and sep) and replacing all whitespace sequences in the result with space, which defaults to a single space.

Example:
> (string-normalize-spaces " foo bar baz \r\n\t")
"foo bar baz"

The result of (string-normalize-spaces str sep space) is the same as (string-join (string-split str sep ....) space).

procedure
(string-replace str from to [#:all all?]) → string?
  str : string?
  from : (or/c string? regexp?)
  to : string?
  all? : any/c = #t

Returns str with all occurrences of from replaced with by to. If from is a string, it is matched literally (as opposed to being used as a regular expression).

By default, all occurrences are replaced, but only the first match is replaced if all? is #f.

Example:
> (string-replace "foo bar baz" "bar" "blah")
"foo blah baz"

procedure
(string-split str
[ sep
#:trim? trim?
#:repeat? repeat?]) → (listof string?)
  str : string?
  sep : (or/c string? regexp?) = #px"\\s+"
  trim? : any/c = #t
  repeat? : any/c = #f

Splits the input str on whitespaces, returning a list of substrings of str that are separated by sep. The input is first trimmed using sep (see string-trim), unless trim? is #f. Empty matches are handled in the same way as for regexp-split. As a special case, if str is the empty string after trimming, the result is '() instead of '("").

Like string-trim, provide sep to use a different separator, and repeat? controls matching repeated sequences.

Examples:
> (string-split "  foo bar  baz \r\n\t")
'("foo" "bar" "baz")
> (string-split "  ")
'()
> (string-split "  " #:trim? #f)
'("" "")

procedure
(string-trim str
[ sep
#:left? left?
#:right? right?
#:repeat? repeat?]) → string?
  str : string?
  sep : (or/c string? regexp?) = #px"\\s+"
  left? : any/c = #t
  right? : any/c = #t
  repeat? : any/c = #f

Trims the input str by removing prefix and suffix sep, which defaults to whitespace. A string sep is matched literally (as opposed to being used as a regular expression).

Use #:left? #f or #:right? #f to suppress trimming the corresponding side. When repeat? is #f (the default), only one match is removed from each side; when repeat? is true, all initial or trailing matches are trimmed (which is an alternative to using a regular expression sep that contains +).

Examples:
> (string-trim "  foo bar  baz \r\n\t")
"foo bar  baz"
> (string-trim "  foo bar  baz \r\n\t" " " #:repeat? #t)
"foo bar  baz \r\n\t"
> (string-trim "aaaxaayaa" "aa")
"axaay"

top← prev up next →

1	Language Model
2	Syntactic Forms
3	Datatypes
4	Structures
5	Classes and Objects
6	Units
7	Contracts
8	Pattern Matching
9	Control Flow
10	Concurrency and Parallelism
11	Macros
12	Input and Output
13	Reflection and Security
14	Operating System
15	Memory Management
16	Unsafe Operations
17	Running Racket
	Bibliography
	Index

3.1	Booleans and Equality
3.2	Numbers
3.3	Strings
3.4	Byte Strings
3.5	Characters
3.6	Symbols
3.7	Regular Expressions
3.8	Keywords
3.9	Pairs and Lists
3.10	Mutable Pairs and Lists
3.11	Vectors
3.12	Boxes
3.13	Hash Tables
3.14	Sequences and Streams
3.15	Dictionaries
3.16	Sets
3.17	Procedures
3.18	Void and Undefined

3.3.1	String Constructors, Selectors, and Mutators
3.3.2	String Comparisons
3.3.3	String Conversions
3.3.4	Locale-Specific String Operations
3.3.5	Additional String Functions