Module B0_std.String

Strings.

String

include module type of Stdlib.String
val length : string -> int
val get : string -> int -> char
val set : bytes -> int -> char -> unit
val create : int -> bytes
val make : int -> char -> string
val init : int -> (int -> char) -> string
val copy : string -> string
val sub : string -> int -> int -> string
val fill : bytes -> int -> int -> char -> unit
val blit : string -> int -> bytes -> int -> int -> unit
val concat : string -> string list -> string
val iter : (char -> unit) -> string -> unit
val iteri : (int -> char -> unit) -> string -> unit
val map : (char -> char) -> string -> string
val mapi : (int -> char -> char) -> string -> string
val trim : string -> string
val escaped : string -> string
val index : string -> char -> int
val index_opt : string -> char -> int option
val rindex : string -> char -> int
val rindex_opt : string -> char -> int option
val index_from : string -> int -> char -> int
val index_from_opt : string -> int -> char -> int option
val rindex_from : string -> int -> char -> int
val rindex_from_opt : string -> int -> char -> int option
val contains : string -> char -> bool
val contains_from : string -> int -> char -> bool
val rcontains_from : string -> int -> char -> bool
val uppercase : string -> string
val lowercase : string -> string
val capitalize : string -> string
val uncapitalize : string -> string
val uppercase_ascii : string -> string
val lowercase_ascii : string -> string
val capitalize_ascii : string -> string
val uncapitalize_ascii : string -> string
type t = string
val compare : t -> t -> int
val equal : t -> t -> bool
val split_on_char : char -> string -> string list
val to_seq : t -> char Stdlib.Seq.t
val to_seqi : t -> (int * char) Stdlib.Seq.t
val of_seq : char Stdlib.Seq.t -> t
val unsafe_get : string -> int -> char
val unsafe_set : bytes -> int -> char -> unit
val unsafe_blit : string -> int -> bytes -> int -> int -> unit
val unsafe_fill : bytes -> int -> int -> char -> unit
val empty : string

empty is "".

val head : string -> char option

head s if Some s.[0] if s <> "" and None otherwise.

val of_char : char -> string

of_char c is c as a string.

Predicates

val is_empty : string -> bool

is_empty s is equal empty s.

val is_prefix : affix:string -> string -> bool

is_prefix ~affix s is true iff affix.[i] = s.[i] for all indices i of affix.

val is_infix : affix:string -> string -> bool

is_infix ~affix s is true iff there exists an index j such that for all indices i of affix, affix.[i] = s.[j+ 1].

val is_suffix : affix:string -> string -> bool

is_suffix ~affix s is true iff affix.[i] = s.[m - i] for all indices i of affix and with m = String.length s - 1.

val for_all : (char -> bool) -> string -> bool

for_all p s is true iff for all indices i of s, p s.[i] = true.

val exists : (char -> bool) -> string -> bool

exists p s is true iff there exists an index i of s with p s.[i] = true.

Extracting substrings

val with_index_range : ?⁠first:int -> ?⁠last:int -> string -> string

with_index_range ~first ~last s are the consecutive bytes of s whose indices exist in the range [first;last].

first defaults to 0 and last to String.length s - 1.

Note that both first and last can be any integer. If first > last the interval is empty and the empty string is returned.

Breaking

Breaking with magnitudes

val take_left : int -> string -> string

take_left n s are the first n bytes of s. This is s if n >= length s and "" if n <= 0.

val take_right : int -> string -> string

take_right n s are the last n bytes of s. This is s if n >= length s and "" if n <= 0.

val drop_left : int -> string -> string

drop_left n s is s without the first n bytes of s. This is "" if n >= length s and s if n <= 0.

val drop_right : int -> string -> string

drop_right n s is s without the last n bytes of s. This is "" if n >= length s and s if n <= 0.

val break_left : int -> string -> string * string

break_left n v is (take_left n v, drop_left n v).

val break_right : int -> string -> string * string

break_right n v is (drop_left n v, take_right n v).

Breaking with predicates

val keep_left : (char -> bool) -> string -> string

keep_left sat s are the first consecutive sat statisfying bytes of s.

val keep_right : (char -> bool) -> string -> string

keep_right sat s are the last consecutive sat satisfying bytes of s.

val lose_left : (char -> bool) -> string -> string

lose_left sat s is s without the first consecutive sat satisfying bytes of s.

val lose_right : (char -> bool) -> string -> string

lose_right sat s is s without the last consecutive sat satisfying bytes of s.

val span_left : (char -> bool) -> string -> string * string

span_left sat s is (keep_left sat s, lose_left sat s).

val span_right : (char -> bool) -> string -> string * string

span_right sat s is (lose_right sat s, keep_right sat s).

Breaking with separators

val cut_left : sep:string -> string -> (string * string) option

cut ~sep s is either the pair Some (l,r) of the two (possibly empty) substrings of s that are delimited by the first match of the separator character sep or None if sep can't be matched in s. Matching starts from the left of s.

The invariant l ^ sep ^ r = s holds.

raises Invalid_argument

if sep is the empty string.

val cut_right : sep:string -> string -> (string * string) option

cut_right ~sep s is like cut_left but matching starts on the right of s.

val cuts_left : ?⁠drop_empty:bool -> sep:string -> string -> string list

cuts_left sep s is the list of all substrings of s that are delimited by matches of the non empty separator string sep. Empty substrings are omitted in the list if drop_empty is true (defaults to false).

Matching separators in s starts from the left of s (rev is false, default) or the end (rev is true). Once one is found, the separator is skipped and matching starts again, that is separator matches can't overlap. If there is no separator match in s, the list [s] is returned.

The following invariants hold:

  • concat ~sep (cuts ~drop_empty:false ~sep s) = s
  • cuts ~drop_empty:false ~sep s <> []
raises Invalid_argument

if sep is the empty string.

val cuts_right : ?⁠drop_empty:bool -> sep:string -> string -> string list

cuts_right sep s is like cuts_left but matching starts on the right of s.

Traversing

val map : (char -> char) -> string -> string

map f s is s' with s'.[i] = f s.[i] for all indices i of s. f is invoked in increasing index order.

val mapi : (int -> char -> char) -> string -> string

mapi f s is s' with s'.[i] = f i s.[i] for all indices i of s. f is invoked in increasing index order.

Formatting

val pp : string Fmt.t

pp ppf s prints s's bytes on ppf.

val pp_dump : string Fmt.t

pp_dump ppf s prints s as a syntactically valid OCaml string on ppf.

Uniqueness

val uniquify : string list -> string list

uniquify ss is ss without duplicates, the list order is preserved.

val unique : exists:(string -> bool) -> string -> (string, string) Stdlib.result

unique ~exist n is n if exists n is false or r = strf "%s~%d" n d with d the smallest integer in [1;1e9] such that exists r is false or an error if there is no such string.

Suggesting

val edit_distance : string -> string -> int

edit_distance s0 s1 is the number of single character edits (insertion, deletion, substitution) that are needed to change s0 into s1.

val suggest : ?⁠dist:int -> string list -> string -> string list

suggest ~dist candidates s are the elements of candidates whose edit distance is the smallest to s and at most at a distance of dist of s (defaults to 2). If multiple results are returned the order of candidates is preserved.

Escaping and unescaping bytes

See also the Converting to printable US-ASCII characters.

XXX. Limitation cannot escape/unescape multiple bytes (e.g. UTF-8 byte sequences). This could be achieved by tweaking the sigs to return integer pairs but that would allocate quite a bit.

val escaper : (char -> int) -> (bytes -> int -> char -> int) -> string -> string

escaper char_len set_char is a byte escaper that given a byte c uses char_len c bytes in the escaped form. set_char b i c is used to set the index i if a buffer b to byte c in the escaped form nd must return the next writable index (no bounds checks need to be peformed). set_char is invoked both for bytes that need escaping and those that do not. For any b, c and i the invariant i + char_len c = set_char b i c must hold.

exception Illegal_escape of int

See unescaper.

val unescaper : (string -> int -> int) -> (bytes -> int -> string -> int -> int) -> string -> (string, int) Stdlib.result

unescaper char_len_at set_char is a byte unescaper that uses char_len_at to determine the length of a byte at a given index in the string to unescape and set_char b k s i to set at index k in b the unescaped character read at index i in s; and returns the next readable index in s (no bound check need to be performed). For any b, s, k and i the invariant i + char_len_at s i = set_char b k s i.

Both char_len_at and set_char may raise Illegal_escape i if the given index i has an illegal or truncated escape. The unescaper only uses this exception internally it returns Error i if it found an illegal escape at index i.

Strings as US-ASCII character sequences

module Ascii : sig ... end

US-ASCII string support.

String map and sets

module Set : sig ... end

String sets.

module Map : sig ... end

String maps.

Substituting

val subst_pct_vars : ?⁠buf:Stdlib.Buffer.t -> string Map.t -> string -> string option

subst_pct_vars ~buf vars s substitutes in s strings of the form %%VAR%% by the value of "VAR" in vars (if any). None is returned if no substition was performed.