# (chibi string)

A cursor-oriented string library. Provides efficient string utilities for implementations with or without fast random-access strings.

#### `(string-for-each proc str . los)`

## High-level API

The procedures below are similar to those in SRFI 13 or other string libraries, except instead of receiving and returning character indexes they use opaque string cursors.

#### `(string-null? str)`

Returns true iff `str` is equal to the empty string `""`.

#### `(->cursor str x)`

#### `(string-any check str . o)`

Returns true iff `check` is true for any character in `str`. `check` can be a procedure, char (to test for `char=?` equivalence) or char-set (to test for `char-set-contains?`). Always returns false if `str` is empty.

#### `(string-every check str . o)`

Returns true iff `check` is true for every character in `str`. `check` can be a procedure, char or char-set as in `string-any`. Always returns true if `str` is empty.

#### `(string-find str check [i])`

Returns a cursor pointing to the first position from the left in string for which `check` is true. `check` can be a procedure, char or char-set as in `string-any`. The optional cursors `start` and `end` can specify a substring to search, and default to the whole string. Returns a cursor just past the end of `str` if no character matches.

#### `(string-find? str check . o)`

As above, ignoring the position and returning true iff any character matches.

#### `(string-find-right str check . o)`

As `string-find`, but returns the position of the first character from the right of `str`. If no character matches, returns a string cursor pointing just before `start`.

#### `(string-skip str check . o)`

As `string-find`, but inverts the check, returning the position of the first character which doesn't match.

#### `(string-skip-right str check . o)`

As `string-find-right`, but inverts the check, returning the position of the first character which doesn't match.

#### `(string-join list-of-strings [separator])`

#### `string-skip-right`

Concatenates the `list-of-strings` and return the result as a single string. If `separator` is provided it is inserted between each pair of strings.

#### `(string-split str [limit])`

Split `str` into a list of substrings separated by `pred`, which defaults to `#\space`. Multiple adjacent characters which satisy `pred` will result in empty strings in the list. If the optional `limit` is provided, splits into at most that many substrings starting from the left.

#### `(string-trim-left str . o)`

Returns a copy of the string `str` with all characters matching `pred` (default `#\space`) removed from the left.

#### `(string-trim-right str . o)`

Returns a copy of the string `str` with all characters matching `pred` (default `#\space`) removed from the right.

#### `(string-trim str [pred])`

Returns a copy of the string `str` with all characters matching `pred` (default `#\space`) removed from both sides.

#### `(string-mismatch prefix str)`

Returns two values: the first cursors from the left in `prefix` and in `str` where the two strings don't match.

#### `(string-mismatch-right suffix str)`

Returns two values: the first cursors from the right in `prefix` and in `str` where the two strings don't match.

#### `(string-prefix? prefix str)`

Returns true iff `prefix` is a prefix of `str`.

#### `(string-suffix? suffix str)`

Returns true iff `suffix` is a suffix of `str`.

#### `(string-fold kons knil str . los)`

The fundamental string iterator. Calls `kons` on each character of `str` and an accumulator, starting with `knil`. If multiple strings are provided, calls `kons` on the corresponding characters of all strings, with the accumulator as the final argument, and terminates when the shortest string runs out.

#### `(string-fold-right kons knil str)`

Equivalent to `string-fold`, but iterates over `str` from right to left.

#### `(string-map proc str)`

Returns a new string composed of applying the procedure `proc` to every character in `string`.

#### `(string-for-each proc str)`

Apply `proc` to every character in `str` in order and discard the result.

#### `(string-count str check)`

Count the number of characters in `str` for which `check` is true.

#### `(string-contains s1 s2 [start])`

Returns a cursor pointing to the first position in the string `s1` where `s2` occurs, or `#f` if there is no such match.

#### `(make-string-searcher needle)`

Partial application of `string-contains`. Return a procedure of one argument, a string, which runs `(string-contains str `needle`)`.

#### `(string-downcase-ascii s)`

Return a copy of string `s` with all 26 upper-case ASCII characters mapped to their corresponding 26 lower-case ASCII characters.

#### `(string-upcase-ascii s)`

Return a copy of string `s` with all 26 lower-case ASCII characters mapped to their corresponding 26 upper-case ASCII characters.

## Cursor API

#### `(substring-cursor str i [j])`

Returns the substring of `str` between `i` (inclusive) and optional `j` (exclusive), which defaults to the end of the string.

#### `(string-cursor-ref str i)`

Returns the character of `str` at position `i`.

#### `(string-cursor-start str)`

Returns a string cursor pointing to the start of `str`.

#### `(string-cursor-end str)`

Returns a string cursor pointing just past the end of `str`.

#### `(string-cursor-next str i)`

Returns a string cursor to the character in `str` just after the cursor `i`.

#### `(string-cursor-prev str i)`

#### `(string-cursor-forward str cursor n)`

Returns a string cursor to the character in `str` just before the cursor `i`.

#### `(string-cursor-back str cursor n)`

#### `(string-cursor<? i j)`

#### `(string-cursor>? i j)`

#### `(string-cursor=? i j)`

#### `(string-cursor<=? i j)`

#### `(string-cursor>=? i j)`

String cursor comparators.