6.6.5.5 String Selection

Portions of strings can be extracted by these procedures. string-ref delivers individual characters whereas substring can be used to extract substrings from longer strings.

Scheme Procedure: string-length string

C Function: scm_string_length (string)

Return the number of characters in string.

C Function: size_t scm_c_string_length (SCM str)

Return the number of characters in str as a size_t.

Scheme Procedure: string-ref str k

C Function: scm_string_ref (str, k)

Return character k of str using zero-origin indexing. k must be a valid index of str.

C Function: SCM scm_c_string_ref (SCM str, size_t k)

Return character k of str using zero-origin indexing. k must be a valid index of str.

Scheme Procedure: string-copy str [start [end]]

C Function: scm_substring_copy (str, start, end)

C Function: scm_string_copy (str)

Return a copy of the given string str.

The returned string shares storage with str initially, but it is copied as soon as one of the two strings is modified.

Scheme Procedure: substring str start [end]

C Function: scm_substring (str, start, end)

Return a new string formed from the characters of str beginning with index start (inclusive) and ending with index end (exclusive). str must be a string, start and end must be exact integers satisfying:

0 <= start <= end <= (string-length str).

The returned string shares storage with str initially, but it is copied as soon as one of the two strings is modified.

Scheme Procedure: substring/shared str start [end]

C Function: scm_substring_shared (str, start, end)

Like substring, but the strings continue to share their storage even if they are modified. Thus, modifications to str show up in the new string, and vice versa.

Scheme Procedure: substring/copy str start [end]

C Function: scm_substring_copy (str, start, end)

Like substring, but the storage for the new string is copied immediately.

Scheme Procedure: substring/read-only str start [end]

C Function: scm_substring_read_only (str, start, end)

Like substring, but the resulting string can not be modified.

C Function: SCM scm_c_substring (SCM str, size_t start, size_t end)

C Function: SCM scm_c_substring_shared (SCM str, size_t start, size_t end)

C Function: SCM scm_c_substring_copy (SCM str, size_t start, size_t end)

C Function: SCM scm_c_substring_read_only (SCM str, size_t start, size_t end)

Like scm_substring, etc. but the bounds are given as a size_t.

Scheme Procedure: string-take s n

C Function: scm_string_take (s, n)

Return the n first characters of s.

Scheme Procedure: string-drop s n

C Function: scm_string_drop (s, n)

Return all but the first n characters of s.

Scheme Procedure: string-take-right s n

C Function: scm_string_take_right (s, n)

Return the n last characters of s.

Scheme Procedure: string-drop-right s n

C Function: scm_string_drop_right (s, n)

Return all but the last n characters of s.

Scheme Procedure: string-pad s len [chr [start [end]]]

Scheme Procedure: string-pad-right s len [chr [start [end]]]

C Function: scm_string_pad (s, len, chr, start, end)

C Function: scm_string_pad_right (s, len, chr, start, end)

Take characters start to end from the string s and either pad with chr or truncate them to give len characters.

string-pad pads or truncates on the left, so for example

(string-pad "x" 3)     ⇒ "  x"
(string-pad "abcde" 3) ⇒ "cde"

string-pad-right pads or truncates on the right, so for example

(string-pad-right "x" 3)     ⇒ "x  "
(string-pad-right "abcde" 3) ⇒ "abc"

Scheme Procedure: string-trim s [char_pred [start [end]]]

Scheme Procedure: string-trim-right s [char_pred [start [end]]]

Scheme Procedure: string-trim-both s [char_pred [start [end]]]

C Function: scm_string_trim (s, char_pred, start, end)

C Function: scm_string_trim_right (s, char_pred, start, end)

C Function: scm_string_trim_both (s, char_pred, start, end)

Trim occurrences of char_pred from the ends of s.

string-trim trims char_pred characters from the left (start) of the string, string-trim-right trims them from the right (end) of the string, string-trim-both trims from both ends.

char_pred can be a character, a character set, or a predicate procedure to call on each character. If char_pred is not given the default is whitespace as per char-set:whitespace (see Standard Character Sets).

(string-trim " x ")              ⇒ "x "
(string-trim-right "banana" #\a) ⇒ "banan"
(string-trim-both ".,xy:;" char-set:punctuation)
                  ⇒ "xy"
(string-trim-both "xyzzy" (lambda (c)
                             (or (eqv? c #\x)
                                 (eqv? c #\y))))
                  ⇒ "zz"