String Module

(string/ascii-lower str)

Returns a new string where all bytes are replaced with the lowercase version of themselves in ASCII. Does only a very simple case check, meaning no unicode support.

(string/ascii-upper str)

Returns a new string where all bytes are replaced with the uppercase version of themselves in ASCII. Does only a very simple case check, meaning no unicode support.

(string/bytes str)

Returns a tuple of integers that are the byte values of the string.

(string/check-set set str)

Checks that the string `str` only contains bytes that appear in the string `set`. Returns true if all bytes in `str` appear in `set`, false if some bytes in `str` do not appear in `set`.

(string/find patt str &opt start-index)

Searches for the first instance of pattern `patt` in string `str`. Returns the index of the first character in `patt` if found, otherwise returns nil.

(string/find-all patt str &opt start-index)

Searches for all instances of pattern `patt` in string `str`. Returns an array of all indices of found patterns. Overlapping instances of the pattern are counted individually, meaning a byte in `str` may contribute to multiple found patterns.

(string/format format & values)

Similar to C's `snprintf`, but specialized for operating with Janet values. Returns a new string.

The following conversion specifiers are supported, where the upper case specifiers generate upper case output:
- `c`: ASCII character.
- `d`, `i`: integer, formatted as a decimal number.
- `x`, `X`: integer, formatted as a hexadecimal number.
- `o`: integer, formatted as an octal number.
- `f`, `F`: floating point number, formatted as a decimal number.
- `e`, `E`: floating point number, formatted in scientific notation.
- `g`, `G`: floating point number, formatted in its shortest form.
- `a`, `A`: floating point number, formatted as a hexadecimal number.
- `s`: formatted as a string, precision indicates padding and maximum length.
- `t`: emit the type of the given value.
- `v`: format with (describe x)
- `V`: format with (string x)
- `j`: format to jdn (Janet data notation).

The following conversion specifiers are used for "pretty-printing", where the upper-case variants generate colored output. These specifiers can take a precision argument to specify the maximum nesting depth to print.
- `p`, `P`: pretty format, truncating if necessary
- `m`, `M`: pretty format without truncating.
- `q`, `Q`: pretty format on one line, truncating if necessary.
- `n`, `N`: pretty format on one line without truncation.

(string/from-bytes & byte-vals)

Creates a string from integer parameters with byte values. All integers will be coerced to the range of 1 byte 0-255.

(string/has-prefix? pfx str)

Tests whether `str` starts with `pfx`.

(string/has-suffix? sfx str)

Tests whether `str` ends with `sfx`.

(string/join parts &opt sep)

Joins an array of strings into one string, optionally separated by a separator string `sep`.

(string/repeat bytes n)

Returns a string that is `n` copies of `bytes` concatenated.

(string/replace patt subst str)

Replace the first occurrence of `patt` with `subst` in the string `str`. If `subst` is a function, it will be called with `patt` only if a match is found, and should return the actual replacement text to use. Will return the new string if `patt` is found, otherwise returns `str`.

(string/replace-all patt subst str)

Replace all instances of `patt` with `subst` in the string `str`. Overlapping matches will not be counted, only the first match in such a span will be replaced. If `subst` is a function, it will be called with `patt` once for each match, and should return the actual replacement text to use. Will return the new string if `patt` is found, otherwise returns `str`.

(string/reverse str)

Returns a string that is the reversed version of `str`.

(string/slice bytes &opt start end)

Returns a substring from a byte sequence. The substring is from index `start` inclusive to index `end`, exclusive. All indexing is from 0. `start` and `end` can also be negative to indicate indexing from the end of the string. Note that if `start` is negative it is exclusive, and if `end` is negative it is inclusive, to allow a full negative slice range.

(string/split delim str &opt start limit)

Splits a string `str` with delimiter `delim` and returns an array of substrings. The substrings will not contain the delimiter `delim`. If `delim` is not found, the returned array will have one element. Will start searching for `delim` at the index `start` (if provided), and return up to a maximum of `limit` results (if provided).

# substrings split by delimiter
(string/split "," "x,y,z") # -> @["x" "y" "z"]

# delimiter not found so result has one element
(string/split "!" "1 2 3") # -> @["1 2 3"]

# start searching part-way through
(string/split "," "a,e,i,o" 3) # -> @["a,e" "i" "o"]

# limit number of results
(string/split ";" "a;b;c;d;e" 0 3) # -> @["a" "b" "c;d;e"]

# delimiter should be non-empty
(string/split "" "word") # -> error: expected non-empty pattern

(string/trim str &opt set)

Trim leading and trailing whitespace from a byte sequence. If the argument `set` is provided, consider only characters in `set` to be whitespace.

# trim leading and trailing whitespace
(string/trim "  foo ") # -> "foo"

# default whitespace includes " \t\r\n\v\f"
(string/trim "\t bar\n\r\f") # -> "bar"

# provide custom set of characters to trim
(string/trim "_.foo_bar. \n" " ._\n") # -> "foo_bar"

(string/triml str &opt set)

Trim leading whitespace from a byte sequence. If the argument `set` is provided, consider only characters in `set` to be whitespace.

# trim leading/left side whitespace
(string/triml "  foo ") # -> "foo "

# default whitespace includes " \t\r\n\v\f"
(string/triml "\t bar\n\r\f") # -> "bar\n\r\f"

# provide custom set of characters to triml
(string/triml "_.foo_bar. \n" " ._\n") # -> "foo_bar. \n"

(string/trimr str &opt set)

Trim trailing whitespace from a byte sequence. If the argument `set` is provided, consider only characters in `set` to be whitespace.

# trim trailing/right side whitespace
(string/trimr "  foo ") # -> "  foo"

# default whitespace includes " \t\r\n\v\f"
(string/trimr "\t bar\n\r\f") # -> "\t bar"

# provide custom set of characters to trimr
(string/trimr "_.foo_bar. \n" " ._\n") # -> "_.foo_bar"