Module B0_std.String

Strings.

Stdlib String

include module type of String

Strings

type t = string

The type for strings.

val make : int -> char -> string

make n c is a string of length n with each index holding the character c.

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

init n f is a string of length n with index i holding the character f i (called in increasing index order).

  • since 4.02
val length : string -> int

length s is the length (number of bytes/characters) of s.

val get : string -> int -> char

get s i is the character at index i in s. This is the same as writing s.[i].

val of_bytes : bytes -> string

Return a new string that contains the same bytes as the given byte sequence.

  • since 4.13
val to_bytes : string -> bytes

Return a new byte sequence that contains the same bytes as the given string.

  • since 4.13
val blit : string -> int -> bytes -> int -> int -> unit

Same as Bytes.blit_string which should be preferred.

Concatenating

Note. The Stdlib.(^) binary operator concatenates two strings.

val concat : string -> string list -> string

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

val cat : string -> string -> string

cat s1 s2 concatenates s1 and s2 (s1 ^ s2).

  • since 4.13

Predicates and comparisons

val equal : t -> t -> bool

equal s0 s1 is true if and only if s0 and s1 are character-wise equal.

  • since 4.03 (4.05 in StringLabels)
val compare : t -> t -> int

compare s0 s1 sorts s0 and s1 in lexicographical order. compare behaves like Stdlib.compare on strings but may be more efficient.

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

contains_from s start c is true if and only if c appears in s after position start.

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

rcontains_from s stop c is true if and only if c appears in s before position stop+1.

val contains : string -> char -> bool

contains s c is String.contains_from s 0 c.

Extracting substrings

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

sub s pos len is a string of length len, containing the substring of s that starts at position pos and has length len.

val split_on_char : char -> string -> string list

split_on_char sep s is the list of all (possibly empty) substrings of s that are delimited by the character sep. If s is empty, the result is the singleton list [""].

The function's result 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 (concat (make 1 sep) (split_on_char sep s) = s).
  • No string in the result contains the sep character.
  • since 4.04 (4.05 in StringLabels)

Transforming

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

map f s is the string resulting from applying f to all the characters of s in increasing order.

  • since 4.00
val mapi : (int -> char -> char) -> string -> string

mapi f s is like map but the index of the character is also passed to f.

  • since 4.02
val fold_left : ('acc -> char -> 'acc) -> 'acc -> string -> 'acc

fold_left f x s computes f (... (f (f x s.[0]) s.[1]) ...) s.[n-1], where n is the length of the string s.

  • since 4.13
val fold_right : (char -> 'acc -> 'acc) -> string -> 'acc -> 'acc

fold_right f s x computes f s.[0] (f s.[1] ( ... (f s.[n-1] x) ...)), where n is the length of the string s.

  • since 4.13
val trim : string -> string

trim s is s without leading and trailing whitespace. Whitespace characters are: ' ', '\x0C' (form feed), '\n', '\r', and '\t'.

  • since 4.00
val escaped : string -> string

escaped s is s with special characters represented by escape sequences, following the lexical conventions of OCaml.

All characters outside the US-ASCII printable range [0x20;0x7E] are escaped, as well as backslash (0x2F) and double-quote (0x22).

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

val uppercase_ascii : string -> string

uppercase_ascii s is s with all lowercase letters translated to uppercase, using the US-ASCII character set.

  • since 4.03 (4.05 in StringLabels)
val lowercase_ascii : string -> string

lowercase_ascii s is s with all uppercase letters translated to lowercase, using the US-ASCII character set.

  • since 4.03 (4.05 in StringLabels)
val capitalize_ascii : string -> string

capitalize_ascii s is s with the first character set to uppercase, using the US-ASCII character set.

  • since 4.03 (4.05 in StringLabels)
val uncapitalize_ascii : string -> string

uncapitalize_ascii s is s with the first character set to lowercase, using the US-ASCII character set.

  • since 4.03 (4.05 in StringLabels)

Traversing

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

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.[length s - 1]; ().

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

iteri is like iter, but the function is also given the corresponding character index.

  • since 4.00

Searching

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

index_from s i c is the index of the first occurrence of c in s after position i.

  • raises Not_found

    if c does not occur in s after position i.

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

index_from_opt s i c is the index of the first occurrence of c in s after position i (if any).

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

rindex_from s i c is the index of the last occurrence of c in s before position i+1.

  • raises Not_found

    if c does not occur in s before position i+1.

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

rindex_from_opt s i c is the index of the last occurrence of c in s before position i+1 (if any).

  • since 4.05
val index : string -> char -> int

index s c is String.index_from s 0 c.

val index_opt : string -> char -> int option

index_opt s c is String.index_from_opt s 0 c.

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

rindex s c is String.rindex_from s (length s - 1) c.

val rindex_opt : string -> char -> int option

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

  • since 4.05

Strings and Sequences

val to_seq : t -> char Seq.t

to_seq s is a sequence made of the string's characters in increasing order.

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

to_seqi s is like to_seq but also tuples the corresponding index.

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

of_seq s is a string made of the sequence's characters.

  • since 4.07

UTF decoding and validations

  • since 4.14

UTF-8

val get_utf_8_uchar : t -> int -> Uchar.utf_decode

get_utf_8_uchar b i decodes an UTF-8 character at index i in b.

val is_valid_utf_8 : t -> bool

is_valid_utf_8 b is true if and only if b contains valid UTF-8 data.

UTF-16BE

val get_utf_16be_uchar : t -> int -> Uchar.utf_decode

get_utf_16be_uchar b i decodes an UTF-16BE character at index i in b.

val is_valid_utf_16be : t -> bool

is_valid_utf_16be b is true if and only if b contains valid UTF-16BE data.

UTF-16LE

val get_utf_16le_uchar : t -> int -> Uchar.utf_decode

get_utf_16le_uchar b i decodes an UTF-16LE character at index i in b.

val is_valid_utf_16le : t -> bool

is_valid_utf_16le b is true if and only if b contains valid UTF-16LE data.

Binary decoding of integers

The functions in this section binary decode integers from strings.

All following functions raise Invalid_argument if the characters needed at index i to decode the integer are not available.

Little-endian (resp. big-endian) encoding means that least (resp. most) significant bytes are stored first. Big-endian is also known as network byte order. Native-endian encoding is either little-endian or big-endian depending on Sys.big_endian.

32-bit and 64-bit integers are represented by the int32 and int64 types, which can be interpreted either as signed or unsigned numbers.

8-bit and 16-bit integers are represented by the int type, which has more bits than the binary encoding. These extra bits are sign-extended (or zero-extended) for functions which decode 8-bit or 16-bit integers and represented them with int values.

val get_uint8 : string -> int -> int

get_uint8 b i is b's unsigned 8-bit integer starting at character index i.

  • since 4.13
val get_int8 : string -> int -> int

get_int8 b i is b's signed 8-bit integer starting at character index i.

  • since 4.13
val get_uint16_ne : string -> int -> int

get_uint16_ne b i is b's native-endian unsigned 16-bit integer starting at character index i.

  • since 4.13
val get_uint16_be : string -> int -> int

get_uint16_be b i is b's big-endian unsigned 16-bit integer starting at character index i.

  • since 4.13
val get_uint16_le : string -> int -> int

get_uint16_le b i is b's little-endian unsigned 16-bit integer starting at character index i.

  • since 4.13
val get_int16_ne : string -> int -> int

get_int16_ne b i is b's native-endian signed 16-bit integer starting at character index i.

  • since 4.13
val get_int16_be : string -> int -> int

get_int16_be b i is b's big-endian signed 16-bit integer starting at character index i.

  • since 4.13
val get_int16_le : string -> int -> int

get_int16_le b i is b's little-endian signed 16-bit integer starting at character index i.

  • since 4.13
val get_int32_ne : string -> int -> int32

get_int32_ne b i is b's native-endian 32-bit integer starting at character index i.

  • since 4.13
val hash : t -> int

An unseeded hash function for strings, with the same output value as Hashtbl.hash. This function allows this module to be passed as argument to the functor Hashtbl.Make.

  • since 5.0
val seeded_hash : int -> t -> int

A seeded hash function for strings, with the same output value as Hashtbl.seeded_hash. This function allows this module to be passed as argument to the functor Hashtbl.MakeSeeded.

  • since 5.0
val get_int32_be : string -> int -> int32

get_int32_be b i is b's big-endian 32-bit integer starting at character index i.

  • since 4.13
val get_int32_le : string -> int -> int32

get_int32_le b i is b's little-endian 32-bit integer starting at character index i.

  • since 4.13
val get_int64_ne : string -> int -> int64

get_int64_ne b i is b's native-endian 64-bit integer starting at character index i.

  • since 4.13
val get_int64_be : string -> int -> int64

get_int64_be b i is b's big-endian 64-bit integer starting at character index i.

  • since 4.13
val get_int64_le : string -> int -> int64

get_int64_le b i is b's little-endian 64-bit integer starting at character index i.

  • since 4.13

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 starts_with : prefix:string -> string -> bool

starts_with ~prefix s is true iff sub.[i] = s.[i] for all indices i of prefix.

Note. Available in 4.12.

val ends_with : suffix:string -> string -> bool

eds_with ~suffix s is true iff sub.[i] = s.[m - i] for all indices i of sufix and with m = String.length s - 1.

Note. Available in 4.12.

val includes : affix:string -> string -> bool

includes ~affix s is true iff there exists an index j such that for all indices i of affix, sub.[i] = s.[j+ 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.

Finding substrings

val find_sub : ?start:int -> sub:string -> string -> int option

find_sub ~start ~sub s is the start index (if any) of the first occurence of sub in s at or after start.

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.

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 <> []
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 distinct : string list -> string list

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

val unique : ?limit:int -> exists:(string -> bool) -> string -> string

unique ~exist n is n if exists n is false or r = strf "%s~%d" n d with d the smallest integer such that exists r if false. If no d in [1;1e9] satisfies the condition Invalid_argument is raised, limit defaults to 1e9.

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.

Here's a small example that escapes '"' by prefixing them by backslashes. double quotes from strings:

let escape_dquotes s =
  let char_len = function '"' -> 2 | _ -> 1 in
  let set_char b i = function
  | '"' -> Bytes.set b i '\\'; Bytes.set b (i+1) '"'; i + 2
  | c -> Bytes.set b i c; i + 1
  in
  String.byte_escaper char_len set_char s
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) 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) 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

type version = int * int * int * string option

The type for version strings. Major, minor, patch and additional info.

val to_version : string -> version 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 of_version : version -> string

of_version v is "major.minor.patchlevel[(+|~)additional-info]"

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

String sets.

module Map : sig ... end

String maps.

Variable substitution

val subst_pct_vars : ?buf:Buffer.t -> (string -> string option) -> string -> string

subst_pct_vars ~buf vars s substitutes in s sub-strings of the form %%VAR%% by the value of vars "VAR" (if any).