Module `B0_std.String`

Strings.

Stdlib `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

Strings

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 subrange : ?⁠first:int -> ?⁠last:int -> string -> string

subrange ~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.

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.

(Un)escaping bytes

The following functions can only (un)escape a single byte. See also these functions to convert a string to printable US-ASCII characters.

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

byte_escaper char_len set_char is a byte escaper such that:

char_len c is the length of the unescaped byte c in the escaped form. If 1 is returned then c is assumed to be unchanged use byte_replacer if that does not hold
set_char b i c sets an unescaped byte c to its escaped form at index i in b and returns the next writable index. set_char is called regardless if c needs to be escaped or not in the latter case you must write c (use byte_replacer if that is not the case). No bounds check need to be performed on i or the returned value.

For any b, c and i the invariant i + char_len c = set_char b i c must hold.

val byte_replacer : (char -> int) -> (bytes -> int -> char -> int) -> string -> string: byte_replacer char_len set_char is like byte_escaper but a byte can be substituted by another one by set_char.

exception Illegal_escape of int: See unescaper.

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

byte_unescaper char_len_at set_char is a byte unescaper such that:

char_len_at s i is the length of an escaped byte at index i of s. If 1 is returned then the byte is assumed to be unchanged by the unescape, use byte_unreplace if that does not hold.
set_char b k s i sets at index k in b the unescaped byte read at index i in s and returns the next readable index in s. set_char is called regardless of wheter the byte at i must be unescaped or not in the latter case you must write s.i only (use byte_unreplacer if that is not the case). No bounds check need to be performed on k, i or the returned value.

For any b, s, k and i the invariant i + char_len_at s i = set_char b k s i must hold.

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 turns this exception into Error i if that happens.

val byte_unreplacer : (string -> int -> int) -> (bytes -> int -> string -> int -> int) -> string -> (string, int) Stdlib.result: byte_unreplacer char_len_at set_char is like byte_unscaper except set_char can set a different byte whenever char_len_at returns 1.

US-ASCII strings

module Ascii : sig ... end: US-ASCII string support.

Sets and maps

module Set : sig ... end with type Set.t = Stdlib.Set.Make(Stdlib.String).t: String sets.

module Map : sig ... end with type 'a Map.t = 'a Stdlib.Map.Make(Stdlib.String).t: String maps.

Variable substitution

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 substitution was performed.