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 stands for “ignore case”.
Open Dylan doesn’t yet support Unicode. When it does, this library will be updated to support it also.

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

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? – An instance of <boolean>.

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:

character – An instance of <character>.

Values:

alphabetic? – An instance of <boolean>.

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:

alphabetic? – An instance of <boolean>.

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:

character – An instance of <character>.

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:

string – An instance of <string>.

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? – An instance of <boolean>.

control?(<character>) Sealed Method¶

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

Signature:

control? (character) => (control?)

Parameters:

character – An instance of <character>.

Values:

control? – An instance of <boolean>.

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:

control? – An instance of <boolean>.

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? – An instance of <boolean>.

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:

character – An instance of <character>.

Values:

graphic? – An instance of <boolean>.

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:

graphic? – An instance of <boolean>.

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? – An instance of <boolean>.

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:

character – An instance of <character>.

Values:

printable? – An instance of <boolean>.

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:

printable? – An instance of <boolean>.

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? – An instance of <boolean>.

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:

character – An instance of <character>.

Values:

whitespace? – An instance of <boolean>.

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:

whitespace? – An instance of <boolean>.

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:

character – An instance of <character>.

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:

character – An instance of <character>.

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? – An instance of <boolean>.

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:

character – An instance of <character>.

Values:

octal-digit? – An instance of <boolean>.

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:

octal-digit? – An instance of <boolean>.

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:

count – An instance of <integer>.

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:

character – An instance of <character>.

Values:

lowercase-character – An instance of <character>.

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:

character – An instance of <character>.

Values:

lowercase-character – An instance of <character>.

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? Function¶

Returns #t if the argument is a lowercase alphabetic character. Otherwise returns #f.

Signature:

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

Parameters:

character – An instance of <character>.

Values:

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

lowercase?('n') => #t
lowercase?('N') => #f
lowercase?('*') => #f

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:

character – An instance of <character>.

Values:

uppercase-character – An instance of <character>.

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:

character – An instance of <character>.

Values:

uppercase-character – An instance of <character>.

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? Function¶

Returns #t if the argument is an uppercase alphabetic character. Otherwise returns #f.

Signature:

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

Parameters:

character – An instance of <character>.

Values:

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

uppercase?('T') => #t
uppercase?('t') => #f
uppercase?('^') => #f

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:

char1 – An instance of <character>.
char2 – An instance of <character>.

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:

char1 – An instance of <character>.
char2 – An instance of <character>.

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:

char1 – An instance of <character>.
char2 – An instance of <character>.

Values:

equal? – An instance of <boolean>.

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:

equal? – An instance of <boolean>.

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:

equal? – An instance of <boolean>.

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:

greater? – An instance of <boolean>.

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:

greater? – An instance of <boolean>.

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:

less? – An instance of <boolean>.

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:

less? – An instance of <boolean>.

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:

starts-with? – An instance of <boolean>.

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:

ends-with? – An instance of <boolean>.

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:

lines – An instance of <sequence>.

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:

split

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¶

concatenate!
float-to-string
integer-to-string
string-to-integer