The strings Library#

The strings library exports definitions for basic string manipulation.

The strings library was originally defined in DEP-0004. Some additional background material can be found there.

Note

  • This library does not address any higher-level operations such as text formatting or anything that requires semantic knowledge of words, such as pluralization or internationalization.

  • Where it makes sense, functions can be applied to either a single character or a string of characters. For example, lowercase('C') => 'c' and lowercase("Foo") => "foo".

  • Functions are case-sensitive by default. Versions that ignore alphabetic case are named with a trailing “-ic” or “-ic?”, which means “ignore case”.

The strings Module#

Character Class Predicates#

alphabetic? Sealed Generic function#

Return #t if the argument is alphabetic, else #f.

Signature:

alphabetic? (string-or-character, #key) => (alphabetic?)

Parameters:

  • string-or-character – An instance of type-union(<string>, <character>).

Values:
alphabetic?(<character>) Sealed Method#

Returns #t if the given character is a member of the set a-z or A-Z. Otherwise returns #f.

Signature:

alphabetic? (character) => (alphabetic?)

Parameters:
Values:
Example:
alphabetic?('a') => #t
alphabetic?('-') => #f
alphabetic?(<string>) Sealed Method#

Returns #t if every character in the string is a member of the set a-z or A-Z. Otherwise returns #f.

Signature:

alphabetic? (string, #key start, end) => (alphabetic?)

Parameters:

  • string – An instance of <string>.

  • start (#key) – Index into string at which to start the comparison. An instance of <integer>, default 0.

  • end (#key) – Index into string at which to stop the comparison. An instance of <integer>, default string.size.

Values:
Example:
alphabetic?("abc") => #t
alphabetic?("abc123") => #f
alphabetic?("abc123", end: 3) => #t
alphanumeric? Sealed Generic function#

Returns #t if the argument is alphanumeric, otherwise #f.

Signature:

alphanumeric? (string-or-character, #key) => (alphanumeric?)

Parameters:

  • string-or-character – An instance of type-union(<string>, <character>).

Values:

  • alphanumeric? – An instance of <boolean>.

alphanumeric?(<character>) Sealed Method#

Returns #t if the argument is a member of the set of characters a-z, A-Z, or 0-9, otherwise #f.

Signature:

alphanumeric? (character) => (alphanumeric?)

Parameters:
Values:

  • alphanumeric? – An instance of <boolean>.

Example:
alphanumeric?('Z') => #t
alphanumeric?('9') => #t
alphanumeric?('*') => #f
alphanumeric?(<string>) Sealed Method#

Returns #t if every character in the string is a member of the set a-z, A-Z, or 0-9, otherwise #f.

Signature:

alphanumeric? (string) => (alphanumeric?)

Parameters:
Values:

  • alphanumeric? – An instance of <boolean>.

Example:
alphanumeric?("abc123") => #t
alphanumeric?("abc...") => #f
alphanumeric?("abc...",  end: 3) => #t
control? Sealed Generic function#

Returns #t if the argument is entirely composed of control characters, otherwise #f.

Signature:

control? (string-or-character, #key) => (control?)

Parameters:

  • string-or-character – An instance of type-union(<string>, <character>).

Values:
control?(<character>) Sealed Method#

Returns #t if the argument is not a graphic or whitespace character, otherwise #f.

Signature:

control? (character) => (control?)

Parameters:
Values:
Example:
control?('a') => #f
control?('\0') => #t
control?(<string>) Sealed Method#

Returns #t if the argument is entirely composed of non-graphic, non-whitespace characters.

Signature:

control? (string) => (control?)

Parameters:

  • string – An instance of <string>.

  • start (#key) – Index into string at which to start the comparison. An instance of <integer>, default 0.

  • end (#key) – Index into string at which to stop the comparison. An instance of <integer>, default string.size.

Values:
Example:
control?("\0\a\b") => #t
control?("abc\0") => #f
control?("abc\0", start: 3) => #t
graphic? Sealed Generic function#

Returns #t if the argument is entirely composed of graphic characters.

Signature:

graphic? (string-or-character, #key) => (graphic?)

Parameters:

  • string-or-character – An instance of type-union(<string>, <character>).

Values:
graphic?(<character>) Sealed Method#

Returns #t if the argument is a graphic character, defined as those with character codes between 32 (Space) and 126 (~) in the US ASCII character set.

Signature:

graphic? (character, #key) => (graphic?)

Parameters:
Values:
Example:
graphic?('a') => #t
graphic?('\b') => #f
graphic?(<string>) Sealed Method#

Returns #t if the argument is entirely composed of graphic characters, defined as those with character codes between 32 (Space) and 126 (~).

Signature:

graphic? (string, #key) => (graphic?)

Parameters:

  • string – An instance of <string>.

  • start (#key) – Index into string at which to start the comparison. An instance of <integer>, default 0.

  • end (#key) – Index into string at which to stop the comparison. An instance of <integer>, default string.size.

Values:
Example:
graphic?("ABC") => #t
graphic?("ABC\n") => #f
graphic?("ABC\n", end: 3) => #t
printable? Sealed Generic function#

Returns #t if the argument is entirely composed of printable characters, defined as either a graphic or whitespace character.

Signature:

printable? (string-or-character, #key) => (printable?)

Parameters:

  • string-or-character – An instance of type-union(<string>, <character>).

Values:
printable?(<character>) Sealed Method#

Returns #t if the argument is a printable character, defined as either a graphic or whitespace character. Otherwise #f is returned.

Signature:

printable? (character, #key) => (printable?)

Parameters:
Values:
Example:
printable?('x') => #t
printable?('\t') => #t
printable?('\0') => #f
printable?(<string>) Sealed Method#

Returns #t if the argument is entirely composed of printable characters, defined as either a graphic or whitespace character. Otherwise #f is returned.

Signature:

printable? (string, #key) => (printable?)

Parameters:

  • string – An instance of <string>.

  • start (#key) – Index into string at which to start the comparison. An instance of <integer>, default 0.

  • end (#key) – Index into string at which to stop the comparison. An instance of <integer>, default string.size.

Values:
Example:
printable?("a b c") => #t
printable?("abc\0") => #f
printable?("abc\0", end: 3) => #t
whitespace? Sealed Generic function#

Returns #t if the argument is entirely composed of whitespace characters.

Signature:

whitespace? (string-or-character, #key) => (whitespace?)

Parameters:

  • string-or-character – An instance of type-union(<string>, <character>).

Values:
whitespace?(<character>) Sealed Method#

Returns #t if the argument is ‘ ‘ (Space), ‘\t’ (Tab), ‘\n’ (Newline), ‘\f’ (Formfeed), or ‘\r’ (Return). Otherwise #f is returned.

Signature:

whitespace? (character, #key) => (whitespace?)

Parameters:
Values:
Example:
whitespace?(' ') => #t
whitespace?('\r') => #t
whitespace?('x') => #f
whitespace?(<string>) Sealed Method#

Returns #t if the argument is entirely composed of whitespace characters, defined as ‘ ‘ (Space), ‘\t’ (Tab), ‘\n’ (Newline), ‘\f’ (Formfeed), or ‘\r’ (Return). Otherwise #f is returned.

Signature:

whitespace? (string, #key) => (whitespace?)

Parameters:

  • string – An instance of <string>.

  • start (#key) – Index into string at which to start the comparison. An instance of <integer>, default 0.

  • end (#key) – Index into string at which to stop the comparison. An instance of <integer>, default string.size.

Values:
Example:
whitespace?("x\t x") => #f
whitespace?("x\t x", start: 1, end: 3) => #t
decimal-digit? Sealed Generic function#

Returns #t if the argument is a decimal digit, otherwise #f.

Signature:

decimal-digit? (string-or-character, #key) => (decimal-digit?)

Parameters:

  • string-or-character – An instance of type-union(<string>, <character>).

Values:

  • decimal-digit? – An instance of <boolean>.

decimal-digit?(<character>) Sealed Method#

Returns #t if the character is a member of the set [0-9], otherwise #f is returned.

Signature:

decimal-digit? (character, #key) => (decimal-digit?)

Parameters:
Values:

  • decimal-digit? – An instance of <boolean>.

Example:
decimal-digit?('a') => #f
decimal-digit?('4') => #t
decimal-digit?(<string>) Sealed Method#

Returns #t if every character in the string is a member of the set [0-9], otherwise #f is returned.

Signature:

decimal-digit? (string, #key) => (decimal-digit?)

Parameters:

  • string – An instance of <string>.

  • start (#key) – Index into string at which to start the comparison. An instance of <integer>, default 0.

  • end (#key) – Index into string at which to stop the comparison. An instance of <integer>, default string.size.

Values:

  • decimal-digit? – An instance of <boolean>.

Example:
decimal-digit?("123") => #t
decimal-digit?("x123y") => #f
decimal-digit?("x123y", start: 1, end: 4) => #t
hexadecimal-digit? Sealed Generic function#

Returns #t if the argument is entirely composed of hexadecimal digits, otherwise #f is returned.

Signature:

hexadecimal-digit? (string-or-character, #key) => (hexadecimal-digit?)

Parameters:

  • string-or-character – An instance of type-union(<string>, <character>).

Values:

  • hexadecimal-digit? – An instance of <boolean>.

hexadecimal-digit?(<character>) Sealed Method#

Returns #t if the character is a member of the set [0-9a-fA-F], otherwise #f is returned.

Signature:

hexadecimal-digit? (character, #key) => (hexadecimal-digit?)

Parameters:
Values:

  • hexadecimal-digit? – An instance of <boolean>.

Example:
hexadecimal-digit?('a') => #t
hexadecimal-digit?('g') => #f
hexadecimal-digit?('0') => #t
hexadecimal-digit?(<string>) Sealed Method#

Returns #t if every character in the string is a member of the set [0-9a-fA-F], otherwise #f is returned.

Signature:

hexadecimal-digit? (string, #key) => (hexadecimal-digit?)

Parameters:

  • string – An instance of <string>.

  • start (#key) – Index into string at which to start the comparison. An instance of <integer>, default 0.

  • end (#key) – Index into string at which to stop the comparison. An instance of <integer>, default string.size.

Values:

  • hexadecimal-digit? – An instance of <boolean>.

Example:
hexdecimal-digit?("ff00") => #t
hexdecimal-digit?(" ff00 ") => #f
hexdecimal-digit?(" ff00 ", start: 1, end: 5) => #t
octal-digit? Sealed Generic function#

Returns #t if the argument is entirely composed of octal digits, otherwise #f is returned.

Signature:

octal-digit? (string-or-character, #key) => (octal-digit?)

Parameters:

  • string-or-character – An instance of type-union(<string>, <character>).

Values:
octal-digit?(<character>) Sealed Method#

Returns #t if the character is a member of the set [0-9a-fA-F], otherwise #f is returned.

Signature:

octal-digit? (character, #key) => (octal-digit?)

Parameters:
Values:
Example:
octal-digit?('7') => #t
octal-digit?('0') => #t
octal-digit?('8') => #f
octal-digit?(<string>) Sealed Method#

Returns #t if every character in the string is a member of the set [0-9a-fA-F], otherwise #f is returned.

Signature:

octal-digit? (string, #key) => (octal-digit?)

Parameters:

  • string – An instance of <string>.

  • start (#key) – Index into string at which to start the comparison. An instance of <integer>, default 0.

  • end (#key) – Index into string at which to stop the comparison. An instance of <integer>, default string.size.

Values:
Example:
octal-digit?("700") => #t
octal-digit?("7008") => #f
octal-digit?("7008", end: 3) => #t

Substring Functions#

count-substrings Sealed Generic function#

Count how many times a substring pattern occurs in a larger string.

Signature:

count-substrings (big pattern #key start end ignore-case?) => (count)

Parameters:

  • big – An instance of <string>. The string in which to search.

  • pattern – An instance of <string>. The substring to search for.

  • start (#key) – An instance of <integer>, default 0. Where to start searching.

  • end (#key) – An instance of <integer>, default big.size. Where to stop searching. Note that if pattern is not completely between the bounds of start (inclusive) and end (exclusive) it will not be counted.

  • ignore-case? (#key) – An instance of <boolean>, default #f.

Values:
Example:
count-substrings("", "") => 1
count-substrings("xxxxxx", "xx", end: 5) => 2  // no overlap
count-substrings("xXx", "x", ignore-case?: #t) => 3
find-substring Sealed Generic function#

Find the index of a substring pattern in a larger string. Returns #f if not found.

Signature:

find-substring (big pattern #key start end ignore-case?) => (index)

Parameters:

  • big – An instance of <string>. The string in which to search.

  • pattern – An instance of <string>. The substring to search for.

  • start (#key) – An instance of <integer>, default 0. Where to start searching.

  • end (#key) – An instance of <integer>, default big.size. Where to stop searching. Note that if pattern is not completely between the bounds of start (inclusive) and end (exclusive) it will not match.

  • ignore-case? (#key) – An instance of <boolean>, default #f.

Values:

  • index – An instance of false-or(<integer>).

Example:
find-substring("My dog has fleas.", "dog") => 3
replace-substrings Sealed Generic function#

Replace a substring pattern in a larger string. Allocates a new string for the return value if any replacements are done. If there are no replacements the implementation may return big unmodified.

Signature:

replace-substrings (big pattern replacement #key count start end ignore-case?) => (new-string)

Parameters:

  • big – An instance of <string>. The string in which to search.

  • pattern – An instance of <string>. The substring pattern to search for.

  • replacement – An instance of <string>. The string with which to replace pattern.

  • count (#key) – An instance of false-or(<integer>). The number of occurrences to replace. The default is #f, meaning to replace all. Replacements are performed from left to right within big until count has been reached.

  • start (#key) – An instance of <integer>, default 0. Where to start searching.

  • end (#key) – An instance of <integer>, default big.size. Where to stop searching. Note that if pattern is not completely between the bounds of start (inclusive) and end (exclusive) it will not be replaced.

  • ignore-case? (#key) – An instance of <boolean>, default #f.

Values:

  • new-string – An instance of <string>.

Example:
replace-substrings("My cat and your cat", "cat", "dog")
=> "My dog and your dog"

Case Conversion Functions#

lowercase Sealed Generic function#

Returns a lowercased version of its argument.

Signature:

lowercase (string-or-character) => (new-string-or-character)

Parameters:

  • string-or-character – An instance of type-union(<string>, <character>).

Values:

  • new-string-or-character – An instance of type-union(<string>, <character>).

lowercase(<character>) Sealed Method#

If the given character is alphabetic, its lowercase equivalent is returned. Otherwise the character itself is returned.

Signature:

lowercase (character) => (new-character)

Parameters:
Values:
Example:
lowercase('A') => 'a'
lowercase('#') => '#'
lowercase(<string>) Sealed Method#

Returns a newly allocated string with all uppercase characters converted to lowercase. The implementation may return the given string unchanged if it contains no uppercase characters.

Signature:

lowercase (string) => (lowercase-string)

Parameters:

  • string – An instance of <string>.

  • start (#key) – An instance of <integer>, default 0. The index at which to start lowercasing.

  • end (#key) – An instance of <integer>, default string.size. The index before which to stop lowercasing.

Values:

  • lowercase-string – An instance of <string>.

Example:
lowercase("Hack Dylan!") => "hack dylan!"
lowercase("Hack Dylan!", end: 4) => "hack"
lowercase! Sealed Generic function#
Signature:

lowercase! (string-or-character) => (new-string-or-character)

Parameters:

  • string-or-character – An instance of type-union(<string>, <character>).

Values:

  • new-string-or-character – An instance of type-union(<string>, <character>).

lowercase!(<character>) Sealed Method#

If the given character is alphabetic, its lowercase equivalent is returned. Otherwise the character is returned unchanged. This operation is not a mutation; this method is provided for symmetry with lowercase(<character>).

Signature:

lowercase! (character) => (new-character)

Parameters:
Values:
Example:
lowercase!('A') => 'a'
lowercase!('#') => '#'
lowercase!(<string>) Sealed Method#

Mutates the given string such that all uppercase characters are converted to lowercase.

Signature:

lowercase! (string) => (string)

Parameters:

  • string – An instance of <string>.

  • start (#key) – An instance of <integer>, default 0. The index at which to start lowercasing.

  • end (#key) – An instance of <integer>, default string.size. The index before which to stop lowercasing.

Values:

  • lowercase-string – An instance of <string>.

Example:
let text = concatenate("Hack", "Dylan!");
lowercase!(text);
=> "hackdylan!"
text;
=> "hackdylan!"
lowercase!("Hack Dylan!")
=> error, attempt to modify a string constant
lowercase? Sealed Generic function#

Returns #t if the argument is entirely composed of non-uppercase characters.

Signature:

lowercase? (string-or-character) => (is-lowercase?)

Parameters:

  • string-or-character – An instance of type-union(<string>, <character>).

Values:

  • is-lowercase? – An instance of <boolean>.

lowercase?(<character>) Sealed Method#

Returns #t if the given character is not an uppercase alphabetic. Otherwise #f is returned.

Signature:

lowercase? (character) => (is-lowercase?)

Parameters:
Values:

  • is-lowercase? – An instance of <boolean>.

Example:
lowercase?('n') => #t
lowercase?('N') => #f
lowercase?('*') => #t
lowercase?(<string>) Sealed Method#

Returns #t if the argument does not contain any uppercase alphabetic characters. Otherwise #f is returned.

Signature:

lowercase? (string) => (is-lowercase?)

Parameters:

  • string – An instance of <string>.

  • start (#key) – An instance of <integer>, default 0. The index at which to start checking.

  • end (#key) – An instance of <integer>, default string.size. The index before which to stop checking.

Values:

  • is-lowercase? – An instance of <boolean>.

Example:
lowercase?("Why me?") => #f
lowercase?("Why me?", start: 1) => #t
lowercase?("e.e. cummings") => #t
uppercase Sealed Generic function#

Returns an uppercased version of its argument.

Signature:

uppercase (string-or-character) => (new-string-or-character)

Parameters:

  • string-or-character – An instance of type-union(<string>, <character>).

Values:

  • new-string-or-character – An instance of type-union(<string>, <character>).

uppercase(<character>) Sealed Method#

If the given character is alphabetic, its uppercase equivalent is returned. Otherwise the character itself is returned.

Signature:

uppercase (character) => (new-character)

Parameters:
Values:
Example:
uppercase('x') => 'X'
uppercase('*') => '*'
uppercase(<string>) Sealed Method#

Returns a newly allocated string with all lowercase alphabetic characters converted to uppercase. The implementation may return the original string unchanged if it contains no lowercase characters.

Signature:

uppercase (string) => (uppercase-string)

Parameters:

  • string – An instance of <string>.

  • start (#key) – An instance of <integer>, default 0. The index at which to start uppercasing.

  • end (#key) – An instance of <integer>, default string.size. The index before which to stop uppercasing.

Values:

  • uppercase-string – An instance of <string>.

Example:
uppercase("Hack Dylan!") => "HACK DYLAN!"
uppercase("Hack Dylan!", end: 4) => "HACK Dylan!"
uppercase! Sealed Generic function#
Signature:

uppercase! (string-or-character) => (new-string-or-character)

Parameters:

  • string-or-character – An instance of type-union(<string>, <character>).

Values:

  • new-string-or-character – An instance of type-union(<string>, <character>).

uppercase!(<character>) Sealed Method#

If the given character is alphabetic, its uppercase equivalent is returned. Otherwise the character is returned unchanged. This operation is not a mutation, but the method is provided for symmetry with uppercase(<character>).

Signature:

uppercase! (character) => (uppercase-character)

Parameters:
Values:
Example:
uppercase!('t') => 'T'
uppercase!(<string>) Sealed Method#

Mutates the given string such that all lowercase characters are converted to uppercase.

Signature:

uppercase! (string) => (uppercase-string)

Parameters:

  • string – An instance of <string>.

  • start (#key) – An instance of <integer>, default 0. The index at which to start uppercasing.

  • end (#key) – An instance of <integer>, default string.size. The index before which to stop uppercasing.

Values:

  • uppercase-string – An instance of <string>.

Example:
let text = concatenate("Hack", "Dylan!");
uppercase!(text);
=> "HACKDYLAN!"
text;
=> "HACKDYLAN!"
uppercase!("Hack Dylan!")
=> error, attempt to modify a string constant
uppercase? Sealed Generic function#

Returns #t if the argument is entirely composed of non-lowercase characters.

Signature:

uppercase? (string-or-character) => (is-uppercase?)

Parameters:

  • string-or-character – An instance of type-union(<string>, <character>).

Values:

  • is-uppercase? – An instance of <boolean>.

uppercase?(<character>) Sealed Method#

Returns #t if the given character is not a lowercase alphabetic. Otherwise #f is returned.

Signature:

uppercase? (character) => (is-uppercase?)

Parameters:
Values:

  • is-uppercase? – An instance of <boolean>.

Example:
uppercase?('T') => #t
uppercase?('t') => #f
uppercase?('^') => #t
uppercase?(<string>) Sealed Method#

Returns #t if the argument does not contain any lowercase alphabetic characters. Otherwise #f is returned.

Signature:

uppercase? (string) => (is-uppercase?)

Parameters:

  • string – An instance of <string>.

  • start (#key) – An instance of <integer>, default 0. The index at which to start checking.

  • end (#key) – An instance of <integer>, default string.size. The index before which to stop checking.

Values:

  • is-uppercase? – An instance of <boolean>.

Example:
uppercase?("AbC") => #f
uppercase?("ABC") => #t

Comparison Functions#

Case insensitive character comparison functions are provided for convenience. (See DEP-0004 for discussion.)

char-compare Function#

Returns -1 if char1 < char2, 0 if char1 = char2, and 1 if char1 > char2, using case sensitive comparison.

Signature:

char-compare (char1 char2) => (result)

Parameters:
Values:

  • result – An instance of one-of(-1, 0, 1).

Example:
char-compare('a', 'b') => -1
char-compare('a', 'a') => 0
char-compare('b', 'a') => 1
char-compare('a', 'B') => 1
char-compare-ic Function#

Returns -1 if char1 < char2, 0 if char1 = char2, and 1 if char1 > char2, using case insensitive comparison.

Signature:

char-compare-ic (char1 char2) => (result)

Parameters:
Values:

  • result – An instance of one-of(-1, 0, 1).

Example:
char-compare-ic('a', 'b') => -1
char-compare-ic('a', 'a') => 0
char-compare-ic('b', 'a') => 1
char-compare-ic('a', 'B') => -1
char-equal-ic? Function#

Returns #t if char1 and char2 are the same, ignoring case. Otherwise #f is returned.

Signature:

char-equal-ic? (char1 char2) => (equal?)

Parameters:
Values:
Example:
char-equal-ic?('a', 'A') => #t
string-compare Sealed Generic function#

Returns -1 if string1 < string2, 0 if string1 and string2 are the same, and 1 if string1 > string2, using case sensitive comparison.

Signature:

string-compare (string1 string2 #key start1 end1 start2 end2 test) => (result)

Parameters:

  • string1 – An instance of <string>.

  • string2 – An instance of <string>.

  • start1 (#key) – An instance of <integer>, default 0. The index in string1 at which to start the comparison.

  • end1 (#key) – An instance of <integer>, default string1.size. The index in string1 before which to stop the comparison.

  • start2 (#key) – An instance of <integer>, default 0. The index in string2 at which to start the comparison.

  • end2 (#key) – An instance of <integer>, default string2.size. The index in string2 before which to stop the comparison.

  • test (#key) – An instance of <function>, default char-compare.

Values:

  • result – An instance of one-of(-1, 0, 1).

Example:
string-compare("abc", "abc") => 0
string-compare("the", "them") => -1
string-compare("beer", "bee") => 1
string-equal? Sealed Generic function#

Returns #t if string1 and string2 are of equal length and contain the same sequence of characters. Otherwise returns #f.

Signature:

string-equal? (string1 string2 #key start1 end1 start2 end2 test) => (equal?)

Parameters:

  • string1 – An instance of <string>.

  • string2 – An instance of <string>.

  • start1 (#key) – An instance of <integer>, default 0. The index in string1 at which to start the comparison.

  • end1 (#key) – An instance of <integer>, default string1.size. The index in string1 before which to stop the comparison.

  • start2 (#key) – An instance of <integer>, default 0. The index in string2 at which to start the comparison.

  • end2 (#key) – An instance of <integer>, default string2.size. The index in string2 before which to stop the comparison.

  • test (#key) – An instance of <function>, default char-compare.

Values:
Example:
string-equal?("abc", "abc") => #t
string-equal?("ABC", "abc") => #f
string-equal?("the", "them") => #f
string-equal?("the", "them", end2: 3) => #t
string-equal-ic? Sealed Generic function#

Returns #t if string1 and string2 are of equal length and contain the same sequence of characters, ignoring case. Otherwise returns #f.

Signature:

string-equal-ic? (string1 string2 #key start1 end1 start2 end2) => (equal?)

Parameters:

  • string1 – An instance of <string>.

  • string2 – An instance of <string>.

  • start1 (#key) – An instance of <integer>, default 0. The index in string1 at which to start the comparison.

  • end1 (#key) – An instance of <integer>, default string1.size. The index in string1 before which to stop the comparison.

  • start2 (#key) – An instance of <integer>, default 0. The index in string2 at which to start the comparison.

  • end2 (#key) – An instance of <integer>, default string2.size. The index in string2 before which to stop the comparison.

Values:
Example:
string-equal-ic?("ABC", "abc") => #t
string-equal-ic?("the", "them") => #f
string-equal-ic?("The", "them", end2: 3) => #t
string-greater? Sealed Generic function#

Return #t if string1 is greater than string2, using case sensitive comparison.

Signature:

string-greater? (string1 string2 #key start1 end1 start2 end2 test) => (greater?)

Parameters:

  • string1 – An instance of <string>.

  • string2 – An instance of <string>.

  • start1 (#key) – An instance of <integer>, default 0. The index in string1 at which to start the comparison.

  • end1 (#key) – An instance of <integer>, default string1.size. The index in string1 before which to stop the comparison.

  • start2 (#key) – An instance of <integer>, default 0. The index in string2 at which to start the comparison.

  • end2 (#key) – An instance of <integer>, default string2.size. The index in string2 before which to stop the comparison.

  • test (#key) – An instance of <function>, default char-compare.

Values:
Example:
string-greater?("dog", "cat") => #t
string-greater?("Dog", "cat") => #f
string-greater?("dogs", "dog") => #t
string-greater-ic? Sealed Generic function#

Return #t if string1 is greater than string2, using case insensitive comparison.

Signature:

string-greater-ic? (string1 string2 #key start1 end1 start2 end2) => (greater?)

Parameters:

  • string1 – An instance of <string>.

  • string2 – An instance of <string>.

  • start1 (#key) – An instance of <integer>, default 0. The index in string1 at which to start the comparison.

  • end1 (#key) – An instance of <integer>, default string1.size. The index in string1 before which to stop the comparison.

  • start2 (#key) – An instance of <integer>, default 0. The index in string2 at which to start the comparison.

  • end2 (#key) – An instance of <integer>, default string2.size. The index in string2 before which to stop the comparison.

Values:
Example:
string-greater-ic?("dog", "cat") => #t
string-greater-ic?("Dog", "cat") => #t
string-greater-ic?("DOGS", "dog") => #t
string-less? Sealed Generic function#

Return #t if string1 is less than string2, using case sensitive comparison.

Signature:

string-less? (string1 string2 #key start1 end1 start2 end2 test) => (less?)

Parameters:

  • string1 – An instance of <string>.

  • string2 – An instance of <string>.

  • start1 (#key) – An instance of <integer>, default 0. The index in string1 at which to start the comparison.

  • end1 (#key) – An instance of <integer>, default string1.size. The index in string1 before which to stop the comparison.

  • start2 (#key) – An instance of <integer>, default 0. The index in string2 at which to start the comparison.

  • end2 (#key) – An instance of <integer>, default string2.size. The index in string2 before which to stop the comparison.

  • test (#key) – An instance of <function>, default char-compare.

Values:
Example:
string-less?("dog", "cat") => #f
string-less?("Dog", "cat") => #t
string-less?("dogs", "dog") => #f
string-less-ic? Sealed Generic function#

Return #t if string1 is less than string2, using case insensitive comparison.

Signature:

string-less-ic? (string1 string2 #key start1 end1 start2 end2) => (less?)

Parameters:

  • string1 – An instance of <string>.

  • string2 – An instance of <string>.

  • start1 (#key) – An instance of <integer>, default 0. The index in string1 at which to start the comparison.

  • end1 (#key) – An instance of <integer>, default string1.size. The index in string1 before which to stop the comparison.

  • start2 (#key) – An instance of <integer>, default 0. The index in string2 at which to start the comparison.

  • end2 (#key) – An instance of <integer>, default string2.size. The index in string2 before which to stop the comparison.

Values:
Example:
string-less-ic?("cat", "dog") => #t
string-less-ic?("cat", "Dog") => #t
string-less-ic?("dog", "DOGS") => #t
starts-with? Sealed Generic function#

Return #t if string1 is starts with string2, using case sensitive comparison.

Signature:

starts-with? (string pattern #key test) => (starts-with?)

Parameters:

  • string – An instance of <string>.

  • pattern – An instance of <string>.

  • test (#key) – An instance of <function>, default char-compare. For case insensitive comparison pass char-compare-ic here.

Values:
Example:
starts-with?("Watermelon", "water") => #f
starts-with?("Watermelon", "water", test: char-compare-ic) => #t
ends-with? Sealed Generic function#

Return #t if string1 is ends with string2, using case sensitive comparison.

Signature:

ends-with? (string pattern #key test) => (ends-with?)

Parameters:

  • string – An instance of <string>.

  • pattern – An instance of <string>.

  • test (#key) – An instance of <function>, default char-compare. For case insensitive comparison pass char-compare-ic here.

Values:
Example:
ends-with?("Open Dylan", "dylan") => #f
ends-with?("Open Dylan", "dylan", test: char-compare-ic) => #t

Miscellaneous Functions#

find-any Sealed Generic function#

Find the index of any character matching a predicate function.

Signature:

find-any (string predicate #key start end from-end?)

Parameters:

  • string – The string to search.

  • predicate – An instance of <function> that accepts a <character> and returns a <boolean>.

  • start (#key) – An instance of <integer>. The index at which to begin the search. Defaults to 0.

  • end (#key) – An instance of <integer>. The index at which to end the search. Defaults to the end of the string.

  • from-end? (#key) – An instance of <boolean>. If #t, search backward from end - 1.

Values:

  • index – An instance of false-or(<integer>). The index of the first character for which the predicate returns #t, or #f if no character matches.

Example:
find-any("foo bar", whitespace?) => 3
find-any("foo bar", whitespace?, start: 4) => #f
find-any("foo bar", curry(\=, 'o'), from-end?: #t) => 2
pad Sealed Generic function#

Add a character to both sides of a string until it reaches the given width.

Signature:

pad (string width #key fill) => (padded-string)

Parameters:

  • string – An instance of <string>. The string to pad.

  • width – An instance of <integer>. The final width of the result string.

  • fill (#key) – An instance of <character>. The character to pad with.

Values:

  • padded-string – An instance of <string>.

Example:
pad("foo", 5) => " foo "
pad("foo", 5, fill: '*') => "*foo*"
pad-left Sealed Generic function#

Add a character to the left side of a string until it reaches the given width.

Signature:

pad-left (string width #key fill) => (padded-string)

Parameters:

  • string – An instance of <string>. The string to pad.

  • width – An instance of <integer>. The final width of the result string.

  • fill (#key) – An instance of <character>. The character to pad with.

Values:

  • padded-string – An instance of <string>.

Example:
pad-left("foo", 5) => "  foo"
pad-left("foo", 5, fill: '*') => "**foo"
pad-right Sealed Generic function#

Add a character to the right side of a string until it reaches the given width.

Signature:

pad-right (string width #key fill) => (padded-string)

Parameters:

  • string – An instance of <string>. The string to pad.

  • width – An instance of <integer>. The final width of the result string.

  • fill (#key) – An instance of <character>. The character to pad with.

Values:

  • padded-string – An instance of <string>.

Example:
pad-right("foo", 5) => "foo  "
pad-right("foo", 5, fill: '*') => "foo**"
split-lines Function#

Split a string on line boundaries, which may be CR alone, CRLF, or LF alone.

Signature:

split-lines (string #key remove-if-empty?) => (lines)

Parameters:

  • string – An instance of <string>.

  • remove-if-empty? (#key) – An instance of <boolean>. If true, the result will not contain any empty strings.

Values:
Example:
// Lines are separated by CR, CRLF, or LF, but not LFCR
split-lines("aa\nbb\r\ncc\rdd\n\ree") => #["aa", "bb", "cc", "dd", "", "ee"]

// The end-of-line marker (CR, CRLF, or LF) is considered part
// of the line and is stripped.
split-lines("\nXYZ\n") => #["", "XYZ"]

// Remove empty lines...
split-lines("abc\r\rdef", remove-if-empty?: #t) => #["abc", "def"]
See also:

strip Sealed Generic function#

Remove characters (whitespace by default) from both sides of a string.

Signature:

strip (string #key test start end) => (new-string)

Parameters:

  • string – An instance of <string>. The string to strip.

  • test (#key) – An instance of <function>. A function that accepts a character and returns #t if the character should be removed and #f otherwise.

  • start (#key) – An instance of <integer>, default 0. The index in string at which to start stripping.

  • end (#key) – An instance of <integer>, default string.size. The index in string before which to stop stripping.

Values:

  • new-string – An instance of <string>.

Example:
strip(" \tabc\n") => "abc"
strip("*foo*", test: curry(\=, '*')) => "foo"
strip-left Sealed Generic function#

Remove characters (whitespace by default) from the beginning of a string.

Signature:

strip-left (string #key test start end) => (new-string)

Parameters:

  • string – An instance of <string>. The string to strip.

  • test (#key) – An instance of <function>. A function that accepts a character and returns #t if the character should be removed and #f otherwise.

  • start (#key) – An instance of <integer>, default 0. The index in string at which to start stripping.

  • end (#key) – An instance of <integer>, default string.size. The index in string before which to stop stripping.

Values:

  • new-string – An instance of <string>.

Example:
strip-left(" \tabc\n") => "abc\n"
strip-left("*foo*", test: curry(\=, '*')) => "foo*"
strip-right Sealed Generic function#

Remove characters (whitespace by default) from the end of a string.

Signature:

strip-right (string #key test start end) => (new-string)

Parameters:

  • string – An instance of <string>. The string to strip.

  • test (#key) – An instance of <function>. A function that accepts a character and returns #t if the character should be removed and #f otherwise.

  • start (#key) – An instance of <integer>, default 0. The index in string at which to start stripping.

  • end (#key) – An instance of <integer>, default string.size. The index in string before which to stop stripping.

Values:

  • new-string – An instance of <string>.

Example:
strip-right(" \tabc\n") => " \tabc"
strip-right("*foo*", test: curry(\=, '*')) => "*foo"

String Functions in Other Libraries#

There are a number of functions outside the strings library itself that can be used with strings.

dylan Module#

Since strings are a kind of <sequence>, all sequence operations apply to strings, including most Collection Operations. The ones listed below are most frequently used for strings.

common-extensions Module#