Module B00_std.String

Strings.

Stdlib String

include module type of Stdlib.String
val length : string -> int

Return the length (number of characters) of the given string.

val get : string -> int -> char

String.get s n returns the character at index n in string s. You can also write s.[n] instead of String.get s n.

Raise Invalid_argument if n not a valid index in s.

val set : bytes -> int -> char -> unit

String.set s n c modifies byte sequence s in place, replacing the byte at index n with c. You can also write s.[n] <- c instead of String.set s n c.

Raise Invalid_argument if n is not a valid index in s.

deprecated

This is a deprecated alias of Bytes.set.

val create : int -> bytes

String.create n returns a fresh byte sequence of length n. The sequence is uninitialized and contains arbitrary bytes.

Raise Invalid_argument if n < 0 or n > Sys.max_string_length.

deprecated

This is a deprecated alias of Bytes.create.

val make : int -> char -> string

String.make n c returns a fresh string of length n, filled with the character c.

Raise Invalid_argument if n < 0 or n > Sys.max_string_length.

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

String.init n f returns a string of length n, with character i initialized to the result of f i (called in increasing index order).

Raise Invalid_argument if n < 0 or n > Sys.max_string_length.

since
4.02.0
val copy : string -> string

Return a copy of the given string.

deprecated

Because strings are immutable, it doesn't make much sense to make identical copies of them.

val sub : string -> int -> int -> string

String.sub s start len returns a fresh string of length len, containing the substring of s that starts at position start and has length len.

Raise Invalid_argument if start and len do not designate a valid substring of s.

val fill : bytes -> int -> int -> char -> unit

String.fill s start len c modifies byte sequence s in place, replacing len bytes with c, starting at start.

Raise Invalid_argument if start and len do not designate a valid range of s.

deprecated

This is a deprecated alias of Bytes.fill.

val blit : string -> int -> bytes -> int -> int -> unit

Same as Bytes.blit_string.

val concat : string -> string list -> string

String.concat sep sl concatenates the list of strings sl, inserting the separator string sep between each.

Raise Invalid_argument if the result is longer than Sys.max_string_length bytes.

val iter : (char -> unit) -> string -> unit

String.iter f s applies function f in turn to all the characters of s. It is equivalent to f s.[0]; f s.[1]; ...; f s.[String.length s - 1]; ().

val iteri : (int -> char -> unit) -> string -> unit

Same as String.iter, but the function is applied to the index of the element as first argument (counting from 0), and the character itself as second argument.

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

String.map f s applies function f in turn to all the characters of s (in increasing index order) and stores the results in a new string that is returned.

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

String.mapi f s calls f with each character of s and its index (in increasing index order) and stores the results in a new string that is returned.

since
4.02.0
val trim : string -> string

Return a copy of the argument, without leading and trailing whitespace. The characters regarded as whitespace are: ' ', '\012', '\n', '\r', and '\t'. If there is neither leading nor trailing whitespace character in the argument, return the original string itself, not a copy.

since
4.00.0
val escaped : string -> string

Return a copy of the argument, with special characters represented by escape sequences, following the lexical conventions of OCaml. All characters outside the ASCII printable range (32..126) are escaped, as well as backslash and double-quote.

If there is no special character in the argument that needs escaping, return the original string itself, not a copy.

Raise Invalid_argument if the result is longer than Sys.max_string_length bytes.

The function Scanf.unescaped is a left inverse of escaped, i.e. Scanf.unescaped (escaped s) = s for any string s (unless escape s fails).

val index : string -> char -> int

String.index s c returns the index of the first occurrence of character c in string s.

Raise Not_found if c does not occur in s.

val index_opt : string -> char -> int option

String.index_opt s c returns the index of the first occurrence of character c in string s, or None if c does not occur in s.

since
4.05
val rindex : string -> char -> int

String.rindex s c returns the index of the last occurrence of character c in string s.

Raise Not_found if c does not occur in s.

val rindex_opt : string -> char -> int option

String.rindex_opt s c returns the index of the last occurrence of character c in string s, or None if c does not occur in s.

since
4.05
val index_from : string -> int -> char -> int

String.index_from s i c returns the index of the first occurrence of character c in string s after position i. String.index s c is equivalent to String.index_from s 0 c.

Raise Invalid_argument if i is not a valid position in s. Raise Not_found if c does not occur in s after position i.

val index_from_opt : string -> int -> char -> int option

String.index_from_opt s i c returns the index of the first occurrence of character c in string s after position i or None if c does not occur in s after position i.

String.index_opt s c is equivalent to String.index_from_opt s 0 c. Raise Invalid_argument if i is not a valid position in s.

since
4.05
val rindex_from : string -> int -> char -> int

String.rindex_from s i c returns the index of the last occurrence of character c in string s before position i+1. String.rindex s c is equivalent to String.rindex_from s (String.length s - 1) c.

Raise Invalid_argument if i+1 is not a valid position in s. Raise Not_found if c does not occur in s before position i+1.

val rindex_from_opt : string -> int -> char -> int option

String.rindex_from_opt s i c returns the index of the last occurrence of character c in string s before position i+1 or None if c does not occur in s before position i+1.

String.rindex_opt s c is equivalent to String.rindex_from_opt s (String.length s - 1) c.

Raise Invalid_argument if i+1 is not a valid position in s.

since
4.05
val contains : string -> char -> bool

String.contains s c tests if character c appears in the string s.

val contains_from : string -> int -> char -> bool

String.contains_from s start c tests if character c appears in s after position start. String.contains s c is equivalent to String.contains_from s 0 c.

Raise Invalid_argument if start is not a valid position in s.

val rcontains_from : string -> int -> char -> bool

String.rcontains_from s stop c tests if character c appears in s before position stop+1.

Raise Invalid_argument if stop < 0 or stop+1 is not a valid position in s.

val uppercase : string -> string

Return a copy of the argument, with all lowercase letters translated to uppercase, including accented letters of the ISO Latin-1 (8859-1) character set.

deprecated

Functions operating on Latin-1 character set are deprecated.

val lowercase : string -> string

Return a copy of the argument, with all uppercase letters translated to lowercase, including accented letters of the ISO Latin-1 (8859-1) character set.

deprecated

Functions operating on Latin-1 character set are deprecated.

val capitalize : string -> string

Return a copy of the argument, with the first character set to uppercase, using the ISO Latin-1 (8859-1) character set..

deprecated

Functions operating on Latin-1 character set are deprecated.

val uncapitalize : string -> string

Return a copy of the argument, with the first character set to lowercase, using the ISO Latin-1 (8859-1) character set..

deprecated

Functions operating on Latin-1 character set are deprecated.

val uppercase_ascii : string -> string

Return a copy of the argument, with all lowercase letters translated to uppercase, using the US-ASCII character set.

since
4.03.0
val lowercase_ascii : string -> string

Return a copy of the argument, with all uppercase letters translated to lowercase, using the US-ASCII character set.

since
4.03.0
val capitalize_ascii : string -> string

Return a copy of the argument, with the first character set to uppercase, using the US-ASCII character set.

since
4.03.0
val uncapitalize_ascii : string -> string

Return a copy of the argument, with the first character set to lowercase, using the US-ASCII character set.

since
4.03.0
type t = string

An alias for the type of strings.

val compare : t -> t -> int

The comparison function for strings, with the same specification as Stdlib.compare. Along with the type t, this function compare allows the module String to be passed as argument to the functors Set.Make and Map.Make.

val equal : t -> t -> bool

The equal function for strings.

since
4.03.0
val split_on_char : char -> string -> string list

String.split_on_char sep s returns the list of all (possibly empty) substrings of s that are delimited by the sep character.

The function's output is specified by the following invariants:

  • The list is not empty.
  • Concatenating its elements using sep as a separator returns a string equal to the input (String.concat (String.make 1 sep) (String.split_on_char sep s) = s).
  • No string in the result contains the sep character.
since
4.04.0

Iterators

val to_seq : t -> char Stdlib.Seq.t

Iterate on the string, in increasing index order. Modifications of the string during iteration will be reflected in the iterator.

since
4.07
val to_seqi : t -> (int * char) Stdlib.Seq.t

Iterate on the string, in increasing order, yielding indices along chars

since
4.07
val of_seq : char Stdlib.Seq.t -> t

Create a string from the generator

since
4.07

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

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.

Version strings

val to_version : string -> (int * int * int * string option) option

to_version parses version strings of the form:

"[v|V]major.minor[.patchlevel][+additional-info]"

into (major, minor, patch, additional_info) tuples. If no patchlevel is found 0 is used.

val drop_initial_v : string -> string

drop_initial_v s drops a leading 'v' or 'V' from s.

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.