2.8.3.5 Selection

Function: string-length str

Return the number of characters in the string str.

Function: string-ref str i

Return character s[i] using zero–origin indexing. i must be a valid index of str.

Function: string-copy str

Function: string-copy str start

Function: string-copy str start end

Function: substring/shared str start

Function: substring/shared str start end

substring/shared returns a string whose contents are the characters of str beginning with index start (inclusive) and ending with index end (exclusive). It differs from the R5RS substring in two ways:

• The end parameter is optional, not required.
• substring/shared may return a value that shares memory with str or is eq? to str.

string-copy is extended from its R5RS definition by the addition of its optional start/end parameters. In contrast to substring/shared, it is guaranteed to produce a freshly–allocated string.

Use string-copy when you want to indicate explicitly in your code that you wish to allocate new storage; use substring/shared when you don’t care if you get a fresh copy or share storage with the original string.

Examples:

(string-copy "Beta substitution")
⇒ "Beta substitution"

(string-copy "Beta substitution" 1 10)
⇒ "eta subst"

(string-copy "Beta substitution" 5)
⇒ "substitution"

Function: string-copy! dst.str dst.start src.str

Function: string-copy! dst.str dst.start src.str src.start

Function: string-copy! dst.str dst.start src.str src.start src.end

Copy the sequence of characters from index range from src.start included and src.end excluded in the string src.str to the string dst.str, beginning at index dst.start. The characters are copied left–to–right or right–to–left as needed; the copy is guaranteed to work, even if dst.str and src.str are the same string.

It is an error if the copy operation runs off the end of the target string, e.g.

(string-copy! (string-copy "Microsoft") 0
              "Regional Microsoft Operating Companies")
error→ not enough room in destination string

Function: string-take str nchars

Function: string-drop str nchars

Function: string-take-right str nchars

Function: string-drop-right str nchars

string-take returns the first nchars of str.

string-drop returns all but the first nchars of str.

string-take-right returns the last nchars of str.

string-drop-right returns all but the last nchars of str.

If these procedures produce the entire string, they may return either str or a copy of str; in some implementations, proper substrings may share memory with str.

Examples:

(string-take "Pete Szilagyi" 6) ⇒ "Pete S"
(string-drop "Pete Szilagyi" 6) ⇒ "zilagyi"

(string-take-right "Beta rules" 5) ⇒ "rules"
(string-drop-right "Beta rules" 5) ⇒ "Beta "

It is an error to take or drop more characters than are in the string:

(string-take "foo" 37) ⇒ error

Function: string-pad str len

Function: string-pad str len char

Function: string-pad str len char start

Function: string-pad str len char start end

Function: string-pad-right str len

Function: string-pad-right str len char

Function: string-pad-right str len char start

Function: string-pad-right str len char start end

Build a string of length len comprised of str padded on the left (right) by as many occurrences of the character char as needed. If str has more than len chars, it is truncated on the left (right) to length len. char defaults to #\space.

If len <= (end - start), the returned value is allowed to share storage with str, or be exactly str if len = (end - start).

Examples:

(string-pad     "325" 5) ⇒ "  325"
(string-pad   "71325" 5) ⇒ "71325"
(string-pad "8871325" 5) ⇒ "71325"

Function: string-trim str

Function: string-trim str char/char-set/pred

Function: string-trim str char/char-set/pred start

Function: string-trim str char/char-set/pred start end

Function: string-trim-right str

Function: string-trim-right str char/char-set/pred

Function: string-trim-right str char/char-set/pred start

Function: string-trim-right str char/char-set/pred start end

Function: string-trim-both str

Function: string-trim-both str char/char-set/pred

Function: string-trim-both str char/char-set/pred start

Function: string-trim-both str char/char-set/pred start end

Trim str by skipping over all characters on the left/on the right/on both sides that satisfy the second parameter char/char-set/pred:

• if it is a character char, characters equal to char are trimmed;
• if it is a char set char-set, characters contained in char-set are trimmed;
• if it is a predicate pred, it is a test predicate that is applied to the characters in str; a character causing it to return true is skipped.

char/char-set/pred defaults to the character set char-set:whitespace defined in SRFI-14.

If no trimming occurs, these functions may return either str or a copy of str; in some implementations, proper substrings may share memory with str.

Example:

(string-trim-both "  The outlook wasn't brilliant,  \n\r")
⇒ "The outlook wasn't brilliant,"