2023-04-05

(sph string)

string processing. includes string-replace-string, a fast replacer.

part of sph-lib

library description

# syntax

string-case :: string (condition any:consequent) ...

  like case but for strings instead of symbols.

  example:

    (string-case "test"

      ("a" 1)

      (("b" "c") 2)

      (mystringlist 3)

      (else 4))

module name

(sph string)

exported bindings

procedure: any->string a ->
any -> string
generalized string conversion function.
get the string representation for the value of an object.
symbols like \".\" are converted to \"#{.}\" using display.
procedure: any->string-display a ->
procedure: any->string-pretty-print a ->
procedure: any->string-write a ->
procedure: any->string-write* a ->
write converts symbols like \".\" to #{.}, this procedure avoids this
procedure: list->string-columns a #:justify #:separator #:max-width ->
(string ...) #:justify symbol:left/right #:separator string #:max-width integer -> string
create a string of equally sized columns containing elements of the string list \"a\", separated
by #:separator
procedure: parenthesise a ->
string -> string
surround string with an open and a closing round bracket
procedure: parenthesised? a ->
string -> boolean
checks if the string is enclosed by round brackets.
also checks if every opening bracket is paired with a closing one after it
procedure: regexp-match-replace a replacements ->
string ((regexp . string:replacement)/(regexp string:search-string . string:replacement) ...) -> string
replace strings inside string portions matched by regular expressions
the two part replacement element makes a simple replace,
the three part version replaces search-string only inside matches with replacement
procedure: regexp-replace str regexp replacement ->
string string/regexp string/procedure:{match-structure -> string} -> string
replace all occurences of regexp in string with replacement
variable: sph-string-description
procedure: string-ascii->utf8 a ->
string -> string
convert an ascii string that has incorrectly coded utf8 chars to an utf8 string
procedure: string-brackets-closed? a start-char end-char ->
string character character -> boolean
checks if every start-char in string has an end-char somewhere after it.
this can be used to check if there are missing round brackets in a string.
example: (string-brackets-closed? \"(ab (cd (e)) f)\" #\\( #\\))
procedure: string-brackets-unclosed-count a start-char end-char ->
string character character -> integer:unclosed-count
procedure: string-camelcase->dash a ->
string -> string
aA -> a-a
aa aAa -> aa a-aa
procedure: string-camelcase->underscore a ->
string -> string
aA -> a-a
aa aAa -> aa a-aa
syntax: string-case
procedure: string-compress-space a ->
string -> string
replace multiple subsequent space characters with one space
procedure: string-contains-all? a b ->
string (string ...) -> boolean
result in a boolean indicating if string contains all of the patterns
procedure: string-contains-char? a char ->
string character -> boolean
procedure: string-contains-some? a b ->
string (string ...) -> boolean
result in a boolean indicating if string contains any of the patterns
procedure: string-downcase-first a ->
string -> string
AA -> aA
Aa -> aa
procedure: string-drop-prefix prefix a ->
string string -> string
procedure: string-drop-prefix-if-exists prefix a ->
string string -> string
remove prefix if string has prefix
procedure: string-drop-suffix suffix a ->
string string -> string
procedure: string-drop-suffix-if-exists suffix a ->
string string -> string
remove suffix if string has suffix
procedure: string-each a b [c d] ->
procedure: string-enclose a enclose-str ->
append enclose-str to beginning and end of argument string
procedure: string-equal? a b [c d e f] ->
procedure: string-fill-left a target-length character ->
string character integer -> string
prepend character to the given string until the string length equals target-length.
examples
(string-fill-left \"1\" #\\0 2) -> \"01\"
(string-fill-left \"10\" #\\0 2) -> \"10\"
string-fill-left-zeros
procedure: string-fill-right a target-length character ->
procedure: string-indices a search-string ->
string string -> (integer ...)
result in a list of indices at which search-string occurs in a string
procedure: string-indices-char a search-char ->
string char -> (integer ...)
create a list of indices at which search-char occurs in a string
procedure: string-join-tree a delimiter ->
(list/string ...) string -> string
same as (string-join (flatten a) delimiter)
procedure: string-last-index a ->
string -> integer
get the last possible index of a string
procedure: string-longest-prefix a prefix-list ->
string (string ...) -> string/boolean
result in the element of prefix-list that is the longest prefix of prefix-list in string \"a\"
procedure: string-lowercase? a ->
test if a string contains no uppercase characters
procedure: string-matches-any-regexp? a regexp-list ->
string (regexp-object ...) -> boolean
procedure: string-matches-every-regexp? a regexp-list ->
string (regexp-object ...) -> boolean
procedure: string-multiply a n ->
string integer -> string
procedure: string-numeric? a ->
string -> boolean
check if string is a valid scheme representation of a number
procedure: string-octet-length a ->
string -> integer
the number of bytes of string, regardless of the character encoding, without terminator like \"null\"
procedure: string-quote a ->
procedure: string-replace-char a char replacement ->
string character character -> string
replace all occurences of \"char\" in a string
procedure: string-replace-chars a spec ->
string ((char [replacements] ...) ...) -> string
replace chars in string with none, one or multiple chars
procedure: string-replace-string a replace replacement ->
string string string -> string
replace all occurences of string \"replace\" inside string \"a\" with string \"replacement\".
tests have shown it to be up to 28x times faster than regexp-substitute/global (guile2.06 22x, guile3 5.75-28x).
this procedure is quite nice to debug - comment out one or all string-copy! calls and
the result string will be a partial result
procedure: string-replace-strings a strings-and-replacements ->
string ((string:search . string:replacement) ...) -> string
procedure: string-skip-string a skip ->
string string -> integer
skip over string \"skip\" at the beginning of a string and return the first index afterwards,
or the first index 0 if skip string is not a prefix
procedure: string-slice-at-words a slice-length ->
string integer -> (string ...)
split line into slices/chunks of size slice-length, unless it would split words (subsequent characters without the space character),
in which case the word is moved to the next slice. ignores newlines. can be used for single lines. can be used for \"text-wrapping\".
splits string at spaces, then uses the parts to build lines while checking if the line length with spaces would exceed slice-length.
if yes, the exceeding part is moved to the next line
procedure: string-split-regexp str regexp [handle-delim] ->
string string [symbol:discard/concat] -> (string ...)
split string into a list of substrings delimited by a regular expression.
1. all regexp matches are collected
2. substrings between matches are extracted
procedure: string-trim-string a trim ->
string string -> string
remove all occurences of string \"trim\" from the beginning of a string.
like string-trim but with a trim-string instead of a character
procedure: symbol?->string a ->
any -> any
converts \"a\" to string only if it is a symbol, otherwise results in \"a\"