10.8 srfi-13 - String library

Module: srfi-13

Defines a large set of string-related functions. In Gauche, those functions are splitted to number of files and the form (use srfi-13) merely sets up autoloading of those files. So it is not likely to slow down the script startup. See SRFI-13 (SRFI-13) for the detailed specification and discussion of design issues. This manual serves as a reference of function API. Some SRFI-13 functions are Gauche built-in and not listed here. Note: SRFI-13 documents suggests the name of the module that implements these functions to be “string-lib” and “string-lib-internals”. Gauche uses the name “srfi-13” for consistency.

10.8.1 General conventions

There are a few common factors in string library API, which I don't repeat in each function description

argument convention

The following argument names imply their types.

s, s1, s2

Those arguments must be strings.

char/char-set/pred

This argument can be a character, a character-set object, or a predicate that takes a single character and returns a boolean value. “Applying char/char-set/pred to a character” means, if char/char-set/pred is a character, it is compared to the given character; if char/char-set/pred is a character set, it is checked if the character set contains the given character; if char/char-set/pred is a procedure, it is applied to the given character. “A character satisfies char/char-set/pred” means such application to the character yields true value.

start, end

Lots of SRFI-13 functions takes these two optional arguments, which limit the area of input string from start-th character (inclusive) to end-th character (exclusive), where the operation is performed. When specified, the condition 0 <= start <= end <= length of the string must be satisfied. Default value of start and end is 0 and the length of the string, respectively.

`shared' variant

Some functions have variants with “/shared” attached to its name. SRFI-13 defines those functions to allow to share the part of input string, for better performance. Gauche doesn't have a concept of shared string, and these functions are mere synonyms of their non-shared variants. However, Gauche internally shares the storage of strings, so generally you don't need to worry about the overhead of copying substrings.

`right' variant

Most functions works from left to right of the input string. Some functions have variants with “-right” to its name, that works from right to left.

10.8.2 String predicates

Function: string-null? s

[SRFI-13] Returns #t if s is an empty string, "".

Function: string-every char/char-set/pred s &optional start end

[SRFI-13] Sees if every character in s satisfies char/char-set/pred. If so, string-every returns the value that is returned at the last application of char/char-set/pred. If any of the application returns #f, string-every returns #f immediately.

Function: string-any char/char-set/pred s &optional start end

[SRFI-13] Sees if any character in s satisfies char/char-set/pred. If so, string-any returns the value that is returned by the application. If no character satisfies char/char-set/pred, #f is returned.

10.8.3 String Constructors

Function: string-tabulate proc len

[SRFI-13] proc must be a procedure that takes an integer argument and returns a character. string-tabulate creates a string, whose i-th character is calculated by (proc i).

(string-tabulate (lambda (i) (integer->char (+ i #x30))) 10) ⇒ "0123456789"

Function: reverse-list->string char-list

[SRFI-13] ≡ (list->string (reverse char-list)).

10.8.4 String selection

Function: substring/shared s start &optional end

[SRFI-13] In Gauche, this is the same as substring, except that the end argument is optional.

(substring/shared "abcde" 2) ⇒ "cde"

Function: string-copy! target tstart s &optional start end

[SRFI-13] Copies a string s into a string target from the position tstart. Optional start and end arguments limits the range of s. If the copied string run over the end of target, an error is signalled.

(define s (string-copy "abcde")) (string-copy! s 2 "ZZ") s ⇒ "abZZe"

Function: string-take s nchars

Function: string-drop s nchars

Function: string-take-right s nchars

Function: string-drop-right s nchars

[SRFI-13] Returns the first nchars-character string of s (string-take) or the string without first nchars (string-drop). The *-right variation counts from the end of string. It is guaranteed that the returned string is always a copy of s, even no character is dropped.

(string-take "abcde" 2) ⇒ "ab" (string-drop "abcde" 2) ⇒ "cde" (string-take-right "abcde" 2) ⇒ "de" (string-drop-right "abcde" 2) ⇒ "abc"

Function: string-pad s len &optional char start end

Function: string-pad-right s len &optional char start end

[SRFI-13] If a string s is shorter than len, returns a string of len where char is padded to the left or right, respectively. If s is longer than len, the rightmost or leftmost len chars are taken. Char defaults to #\space. If start and end are provided, the substring of s is used as the source.

(string-pad "abc" 10) ⇒ " abc" (string-pad "abcdefg" 3) ⇒ "efg" (string-pad-right "abc" 10) ⇒ "abc " (string-pad "abcdefg" 10 #\+ 2 5) ⇒ "+++++++cde"

Function: string-trim s &optional char/char-set/pred start end

Function: string-trim-right s &optional char/char-set/pred start end

Function: string-trim-both s &optional char/char-set/pred start end

[SRFI-13] Removes characters that match char/char-set/pred from s. String-trim removes the characters from left of s, string-trim-right does from right, and string-trim-both does from both sides. Char/char-set/pred defaults to #[\s], i.e. a char-set of whitespaces. If start and end are provided, the substring of s is used as the source.

(string-trim " abc ") ⇒ "abc " (string-trim-right " abc ") ⇒ " abc" (string-trim-both " abc ") ⇒ "abc"

10.8.5 String comparison

Function: string-compare s1 s2 proc< proc= proc> &optional start1 end1 start2 end2

Function: string-compare-ci s1 s2 proc< proc= proc> &optional start1 end1 start2 end2

[SRFI-13]

Function: string= s1 s2 &optional start1 end1 start2 end2

Function: string<> s1 s2 &optional start1 end1 start2 end2

Function: string< s1 s2 &optional start1 end1 start2 end2

Function: string<= s1 s2 &optional start1 end1 start2 end2

Function: string> s1 s2 &optional start1 end1 start2 end2

Function: string>= s1 s2 &optional start1 end1 start2 end2

[SRFI-13]

Function: string-ci= s1 s2 &optional start1 end1 start2 end2

Function: string-ci<> s1 s2 &optional start1 end1 start2 end2

Function: string-ci< s1 s2 &optional start1 end1 start2 end2

Function: string-ci<= s1 s2 &optional start1 end1 start2 end2

Function: string-ci> s1 s2 &optional start1 end1 start2 end2

Function: string-ci>= s1 s2 &optional start1 end1 start2 end2

[SRFI-13]

Function: string-hash s &optional bound start end

Function: string-hash-ci s &optional bound start end

[SRFI-13]

10.8.6 String Prefixes & Suffixes

Function: string-prefix-length s1 s2 &optional start1 end1 start2 end2

Function: string-suffix-length s1 s2 &optional start1 end1 start2 end2

Function: string-prefix-length-ci s1 s2 &optional start1 end1 start2 end2

Function: string-suffix-length-ci s1 s2 &optional start1 end1 start2 end2

[SRFI-13]

Function: string-prefix? s1 s2 &optional start1 end1 start2 end2

Function: string-suffix? s1 s2 &optional start1 end1 start2 end2

Function: string-prefix-ci? s1 s2 &optional start1 end1 start2 end2

Function: string-suffix-ci? s1 s2 &optional start1 end1 start2 end2

[SRFI-13]

10.8.7 String searching

Function: string-index s char/char-set/pred &optional start end

Function: string-index-right s char/char-set/pred &optional start end

[SRFI-13] Looks for the first element in a string s that matches char/char-set/pred, and returns its index. If char/char-set/pred is not found in s, returns #f. Optional start and end limit the range of s to search.

(string-index "Aloha oe" #\a) ⇒ 4 (string-index "Aloha oe" #[Aa]) ⇒ 0 (string-index "Aloha oe" #[\s]) ⇒ 5 (string-index "Aloha oe" char-lower-case?) ⇒ 1 (string-index "Aloha oe" #\o 3) ⇒ 6

See also the Gauche built-in procedure string-scan (String utilities), if you need speed over portability.

Function: string-skip s char/char-set/pred &optional start end

Function: string-skip-right s char/char-set/pred &optional start end

[SRFI-13] Looks for the first element that does not match char/char-set/pred and returns its index. If such element is not found, returns #f. Optional start and end limit the range of s to search.

Function: string-count s char/char-set/pred &optional start end

[SRFI-13] Counts the number of elements in s that matches char/char-set/pred. Optional start and end limit the range of s to search.

Function: string-contains s1 s2 &optional start1 end1 start2 end2

Function: string-contains-ci s1 s2 &optional start1 end1 start2 end2

[SRFI-13] Looks for a string s2 inside another string s1. If found, returns an index in s1 from where the matching string begins. Returns #f otherwise. Optional start1, end1, start2 and end2 limits the range of s1 and s2.

See also the Gauche built-in procedure string-scan (String utilities), if you need speed over portability.

10.8.8 String case mapping

Function: string-titlecase s &optional start end

Function: string-titlecase! s &optional start end

[SRFI-13]

Function: string-upcase s &optional start end

Function: string-upcase! s &optional start end

[SRFI-13]

Function: string-downcase s &optional start end

Function: string-downcase! s &optional start end

[SRFI-13]

10.8.9 String reverse & append

Function: string-reverse s &optional start end

Function: string-reverse! s &optional start end

[SRFI-13] Returns a string in which the character positions are reversed from s. string-reverse! modifies s.

(string-reverse "mahalo") ⇒ "olaham" (string-reverse "mahalo" 3) ⇒ "ola" (string-reverse "mahalo" 1 4) ⇒ "aha" (let ((s (string-copy "mahalo"))) (string-reverse! s 1 5) s) ⇒ "mlahao"

Function: string-concatenate string-list

[SRFI-13] Concatenates list of strings.

(string-concatenate '("humuhumu" "nukunuku" "apua" "`a")) ⇒ "humuhumunukunukuapua`a"

Function: string-concatenate/shared string-list

Function: string-append/shared s …

[SRFI-13] “Shared” version of string-concatenate and string-append. In Gauche, these are just synonyms of them.

Function: string-concatenate-reverse string-list

Function: string-concatenate-reverse/shared string-list

[SRFI-13] Reverses string-list before concatenation. “Shared” version works the same in Gauche.

10.8.10 String mapping

Function: string-map proc s &optional start end

Function: string-map! proc s &optional start end

[SRFI-13] string-map applies proc on every character of s, and collects the results into a string and returns it. On the other hand, string-map! modifies s.

(string-map char-upcase "wikiwiki") ⇒ "WIKIWIKI" (string-map char-upcase "wikiwiki" 4) ⇒ "WIKI" (let ((s (string-copy "wikiwiki"))) (string-map! char-upcase s 4) s) ⇒ "wikiWIKI"

Function: string-fold kons knil s &optional start end

Function: string-fold-right kons knil s &optional start end

[SRFI-13]

Function: string-unfold p f g seed &optional base make-final

[SRFI-13]

Function: string-unfold-right p f g seed &optional base make-final

[SRFI-13]

Function: string-for-each proc s &optional start end

[SRFI-13]

Function: string-for-each-index proc s &optional start end

[SRFI-13]

10.8.11 String rotation

Function: xsubstring s from &optional to start end

[SRFI-13]

Function: string-xcopy! target tstart s sfrom &optional sto start end

[SRFI-13]

10.8.12 Other string operations

Function: string-replace s1 s2 start1 end2 &optional start2 end2

[SRFI-13]

Function: string-tokenize s &optional token-set start end

[SRFI-13] Splits the string s into a list of substrings, where each substring is a maximal non-empty contiguous sequence of characters from the character set token-set. The default of token-set is char-set:graphic (See section Predefined character-set).

See also Gauche's built-in string-split (See section String utilities), which provides similar features but different criteria.

10.8.13 String filtering

Function: string-filter s char/char-set/pred &optional start end

Function: string-delete s char/char-set/pred &optional start end

[SRFI-13]

10.8.14 Low-level string procedures

Function: string-parse-start+end proc s args

Function: string-parse-final-start+end proc s args

[SRFI-13]

Macro: let-string-start+end (start end [rest]) proc-exp s-exp args-exp body …

[SRFI-13]

Function: check-substring-spec proc s start end

Function: substring-spec-ok? s start end

[SRFI-13]

Function: make-kmp-restart-vector s &optional c= start end

[SRFI-13]

Function: kmp-step pat rv c i c= p-start

[SRFI-13]

Function: string-kmp-partial-search pat rv s i &optional c= p-start s-start s-end

[SRFI-13]

This document was generated by Shiro Kawai on October, 7 2008 using texi2html 1.78.