#
Chapter 42
`string.ss`: String Utilities

To load: `(require (lib "string.ss"))`

`(eval-string``` `str``` [`err-display err-result`]`)` PROCEDURE

Reads and evaluates S-expressions from the string `str`, returning a result for each expression. Note that if `str` contains only whitespace and comments, zero values are returned, while if `str` contains two expressions, two values are returned.

If `err-display` is not `#f` (the default), then errors are caught and `err-display` is used as the error display handler. If `err-result` is specified, it must be a thunk that returns a value to be returned when an error is caught; otherwise, `#f` is returned when an error is caught.

`(expr->string``` `expr``)` PROCEDURE

Prints `expr` into a string and returns the string.

`(read-from-string``` `str``` [`err-display err-result`]`)` PROCEDURE

Reads the first S-expression from the string `str` and returns it. The `err-display` and `err-result` are as in `eval-str`.

`(read-from-string-all``` `str``` [`err-display err-result`]`)` PROCEDURE

Reads all S-expressions from the string `str` and returns them in a list. The `err-display` and `err-result` are as in `eval-str`.

`(regexp-match*``` `pattern string-or-input-port``` [`start-k end-k`]`)` PROCEDURE

Like `regexp-match` (see section 10 in PLT MzScheme: Language Manual), but the result is a list of strings corresponding to a sequence of matches of `pattern` in `string-or-input-port`. (Unlike `regexp-match`, results for parenthesized sub-patterns in `pattern` are not returned.) If `pattern` matches a zero-length string along the way, the `exn:fail` exception is raised.

If `string-or-input-port` contains no matches (in the range `start-k` to `end-k`), `null` is returned. Otherwise, each string in the resulting list is a distinct substring in `string-or-input-port` that matches `pattern`. The `end-k` argument can be `#f` to match to the end of `string-or-input-port`.

`(regexp-match/fail-without-reading``` `pattern input-port``` [`start-k end-k output-port`]`)` PROCEDURE

Like `regexp-match` on input ports (see section 10 in PLT MzScheme: Language Manual), except that if the match fails, no characters are read and discarded from `input-port`.

This procedure is especially useful with a `pattern` that begins with a start-of-string caret (```^`'') or with a non-`#f` `end-k`, since each limits the amount of peeking into the port.

`(regexp-match-exact?``` `pattern string-or-input-port``)` PROCEDURE

This procedure is like MzScheme's built-in `regexp-match` (see section 10 in PLT MzScheme: Language Manual), but the result is always `#t` or `#f`; `#t` is only returned when the entire content of `string-or-input-port` matches `pattern`.

`(regexp-match-peek-positions*``` `pattern input-port``` [`start-k end-k`]`)` PROCEDURE

Like `regexp-match-positions*`, but it works only on input ports, and the port is peeked instead of read for matches.

`(regexp-match-positions*``` `pattern string-or-input-port``` [`start-k end-k`]`)` PROCEDURE

Like `regexp-match-positions` (see section 10 in PLT MzScheme: Language Manual), but the result is a list of integer pairs corresponding to a sequence of matches of `pattern` in `string-or-input-port`. (Unlike `regexp-match-positions`, results for parenthesized sub-patterns in `pattern` are not returned.) If `pattern` matches a zero-length string along the way, the `exn:fail` exception is raised.

If `string-or-input-port` contains no matches (in the range `start-k` to `end-k`), `null` is returned. Otherwise, each position pair in the resulting list corresponds to a distinct substring in `string-or-input-port` that matches `pattern`. The `end-k` argument can be `#f` to match to the end of `string-or-input-port`.

`(regexp-quote``` `str``` [`case-sensitive?`]`)` PROCEDURE

Produces a string suitable for use with ``regexp`` (see section 10 in PLT MzScheme: Language Manual) to match the literal sequence of characters in `str`. If `case-sensitive?` is true, the resulting regexp matches letters in `str` case-insensitively, otherwise (and by default) it matches case-sensitively.

`(regexp-replace-quote``` `str``)` PROCEDURE

Produces a string suitable for use as the third argument to ``regexp-replace`` (see section 10 in PLT MzScheme: Language Manual) to insert the literal sequence of characters in `str` as a replacement. Concretely, every backslash and ampersand in `str` is protected by a quoting backslash.

`(regexp-split``` `pattern string-or-input-port``` [`start-k end-k`]`)` PROCEDURE

The complement of `regexp-match*` (see above): the result is a list of sub-strings in `string-or-input-port` that are separated by matches to `pattern`; adjacent matches are separated with `""`. If `pattern` matches a zero-length string along the way, the `exn:fail` exception is raised.

If `string-or-input-port` contains no matches (in the range `start-k` to `end-k`), the result will be a list containing `string-or-input-port` (from `start-k` to `end-k`). If a match occurs at the beginning of `string-or-input-port` (at `start-k`), the resulting list will start with an empty string, and if a match occurs at the end (at `end-k`), the list will end with an empty string. The `end-k` argument can be `#f`, in which case splitting goes to the end of `string-or-input-port`.

`(string-lowercase!``` `str``)` PROCEDURE

Destructively changes `str` to contain only lowercase characters.

`(string-uppercase!``` `str``)` PROCEDURE

Destructively changes `str` to contain only uppercase characters.