package b0

  1. Overview
  2. Docs
package b0
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Module B0_std.StringSource

Strings.

include module type of String

Strings

Sourcetype t = string

The type for strings.

Sourceval make : int -> char -> string

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

Sourceval 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
Sourceval length : string -> int

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

Sourceval get : string -> int -> char

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

Sourceval of_bytes : bytes -> string

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

  • since 4.13
Sourceval to_bytes : string -> bytes

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

  • since 4.13
Sourceval 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.

Sourceval concat : string -> string list -> string

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

Sourceval cat : string -> string -> string

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

  • since 4.13

Predicates and comparisons

Sourceval 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)
Sourceval 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.

Sourceval starts_with : prefix:string -> string -> bool

starts_with ~prefix s is true if and only if s starts with prefix.

  • since 4.13
Sourceval ends_with : suffix:string -> string -> bool

ends_with ~suffix s is true if and only if s ends with suffix.

  • since 4.13
Sourceval contains_from : string -> int -> char -> bool

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

Sourceval 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.

Sourceval contains : string -> char -> bool

contains s c is String.contains_from s 0 c.

Extracting substrings

Sourceval 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.

Sourceval 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

Sourceval 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
Sourceval 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
Sourceval 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
Sourceval 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
Sourceval for_all : (char -> bool) -> string -> bool

for_all p s checks if all characters in s satisfy the predicate p.

  • since 4.13
Sourceval exists : (char -> bool) -> string -> bool

exists p s checks if at least one character of s satisfies the predicate p.

  • since 4.13
Sourceval 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
Sourceval 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).

Sourceval 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)
Sourceval 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)
Sourceval 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)
Sourceval 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

Sourceval 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]; ().

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

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

  • since 4.00

Searching

Sourceval 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.

Sourceval 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
Sourceval 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.

Sourceval 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
Sourceval index : string -> char -> int

index s c is String.index_from s 0 c.

Sourceval index_opt : string -> char -> int option

index_opt s c is String.index_from_opt s 0 c.

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

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

Sourceval 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

Sourceval to_seq : t -> char Seq.t

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

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

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

  • since 4.07
Sourceval 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

Sourceval 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.

Sourceval 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

Sourceval 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.

Sourceval 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

Sourceval 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.

Sourceval 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.

Sourceval get_uint8 : string -> int -> int

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

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

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

  • since 4.13
Sourceval 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
Sourceval 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
Sourceval 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
Sourceval 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
Sourceval 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
Sourceval 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
Sourceval 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
Sourceval 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
Sourceval 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
Sourceval 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
Sourceval 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
Sourceval 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
Sourceval 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
Sourceval 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

Sourceval empty : string

empty is "".

Sourceval head : string -> char option

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

Sourceval of_char : char -> string

of_char c is c as a string.

Predicates

Sourceval is_empty : string -> bool

is_empty s is equal empty s.

Sourceval 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].

Finding indices

TODO. Harmonize indexing errors with find_first. This never raises.

Sourceval find_first_index : ?start:int -> (char -> bool) -> string -> int option

find_first_index ~start sat is the index of the first character of s that satisfies sat after or at start (defaults to 0).

Sourceval find_last_index : ?start:int -> (char -> bool) -> string -> int option

find_last_index ~start sat is the index of the last character of s that satisfies sat before or at start (defaults to String.length s - 1).

Finding substrings

Sourceval find_first : ?start:int -> sub:string -> string -> int option

find_first ~start ~sub s is the start position (if any) of the first occurence of sub in s after or at position start (which includes index start if it exists, defaults to 0). Note if you need to search for sub multiple times in s use find_sub_all it is more efficient.

Sourceval find_last : ?start:int -> sub:string -> string -> int option

find_last ~start ~sub s is the start position (if any) of the last occurences of sub in s before or at position start (which includes index start if it exists, defaults to String.length s).

Note if you need to search for sub multiple times in s use rfind_sub_all it is more efficient.

Sourceval find_all : ?start:int -> (int -> 'acc -> 'acc) -> sub:string -> string -> 'acc -> 'acc

find_all ~start f ~sub s acc, starting with acc, folds f over all non-overlapping starting positions of sub in s after or at position start (which includes index start if it exists, defaults to 0). This is acc if sub could not be found in s.

Sourceval rfind_all : ?start:int -> (int -> 'acc -> 'acc) -> sub:string -> string -> 'acc -> 'acc

rfind_all ~start f ~sub s acc, starting with acc, folds f over all non-overlapping starting positions of sub in s before or at position start (which includes index start if it exists, defaults to String.length s). This is acc if sub could not be found in s.

Replacing substrings

Sourceval replace_first : ?start:int -> sub:string -> by:string -> string -> string

replace_first ~start ~sub ~by s replaces by by in s the first occurence of sub at or after position start (which includes index start if it exists, defaults to 0) by by.

Sourceval replace_last : ?start:int -> sub:string -> by:string -> string -> string

replace_last ~start ~sub ~by s replaces by by in s the last occurence of sub at or before position start (which includes index start if it exists, defaults to String.length s).

Sourceval replace_all : ?start:int -> sub:string -> by:string -> string -> string

replace_all ~start ~sub ~by replaces in s all non-overlapping occurences of sub at or after position start (default to 0) by by.

Extracting substrings

Sourceval 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

Sourceval take_first : int -> string -> string

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

Sourceval take_last : int -> string -> string

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

Sourceval drop_first : int -> string -> string

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

Sourceval drop_last : int -> string -> string

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

Sourceval cut_first : int -> string -> string * string

cut_first n v is (take_first n v, drop_first n v).

Sourceval cut_last : int -> string -> string * string

cut_last n v is (drop_last n v, take_last n v).

Breaking with predicates

Sourceval take_first_while : (char -> bool) -> string -> string

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

Sourceval take_last_while : (char -> bool) -> string -> string

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

Sourceval drop_first_while : (char -> bool) -> string -> string

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

Sourceval drop_last_while : (char -> bool) -> string -> string

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

Sourceval cut_first_while : (char -> bool) -> string -> string * string

cut_first_while sat s is (take_first_while sat s, drop_first_while sat s).

Sourceval cut_last_while : (char -> bool) -> string -> string * string

cut_last_while sat s is (drop_last_while sat s, take_last_while sat s).

Breaking with separators

Sourceval split_first : sep:string -> string -> (string * string) option

split_first ~sep s is the pair Some (left, right) made of the two (possibly empty) substrings of s that are delimited by the first match of the separator sep or None if sep can't be matched in s. Matching starts at position 0 using find_first.

The invariant concat sep [left; right] = s holds.

Sourceval split_last : sep:string -> string -> (string * string) option

split_last ~sep s is like split_first but matching starts at position length s using find_last.

Sourceval split_all : ?drop:(string -> bool) -> sep:string -> string -> string list

split_all ~sep s is the list of all substrings of s that are delimited by non-overlapping matches of the separator sep. If sep can't be matched in s, the list [s] is returned. Matches starts at position 0 and are determined using find_all.

Substrings sub for which drop sub is true are not included in the result. drop default to Fun.const false.

The invariant concat sep (split_all ~sep s) = s holds.

Sourceval rsplit_all : ?drop:(string -> bool) -> sep:string -> string -> string list

rsplit_all ~sep s is like split_all but matching starts at position length s using rfind_all.

Breaking lines

Sourceval fold_ascii_lines : strip_newlines:bool -> (int -> 'a -> string -> 'a) -> 'a -> string -> 'a

fold_ascii_lines ~strip_newlines f acc s folds over the lines of s by calling f linenum acc' line with linenum the one-based line number count, acc' the result of accumulating acc with f so far and line the data of the line (without the newline found in the data if strip_newlines is true).

Lines are delimited by newline sequences which are either one of "\n", "\r\n" or "\r". More precisely the function determines lines and line data as follows:

  • If s = "", the function considers there are no lines in s and acc is returned without f being called.
  • If s <> "", s is repeteadly split on the first newline sequences "\n", "\r\n" or "\r" into (left, newline, right), left (or left ^ newline when strip_newlines = false) is given to f and the process is repeated with right until a split can no longer be found. At that point this final string is given to f and the process stops.
Sourceval detach_ascii_newline : string -> string * string

detach_ascii_newline s is (data, endline) with:

  • endline either the suffix "\n", "\r\n" or "\r" of s or "" if s has no such suffix.
  • data the bytes before endline such that data ^ newline = s

Tokenize

Sourceval next_token : ?is_sep:(char -> bool) -> ?is_token:(char -> bool) -> string -> string * string

next_token ~is_sep ~is_token s skips characters satisfying is_sep from s, then gather zero or more consecutive characters satisfying is_token into a string which is returned along the remaining characters after that. is_sep defaults to Char.Ascii.is_white and is_token is Char.Ascii.is_graphic.

Sourceval tokens : ?is_sep:(char -> bool) -> string -> string list

tokens s are the strings separated by sequences of is_sep characters (default to Char.Ascii.is_white). The empty list is returned if s is empty or made only of separators.

Uniqueness

Sourceval distinct : string list -> string list

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

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

unique ~limit ~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;limit] satisfies the condition Invalid_argument is raised, limit defaults to 1e6.

Spellchecking

All additions available in OCaml 5.4

Sourceval edit_distance : ?limit:int -> t -> t -> int

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

If limit is provided the function returns with limit as soon as it was determined that s0 and s1 have distance of at least limit. This is faster if you have a fixed limit, for example for spellchecking.

The function assumes the strings are UTF-8 encoded and uses Uchar.t for the notion of character. Decoding errors are replaced by Uchar.rep. Normalizing the strings to NFC gives better results.

Note. This implements the simpler Optimal String Alignement (OSA) distance, not the Damerau-Levenshtein distance. With this function "ca" and "abc" have a distance of 3 not 2.

Sourceval spellcheck : ?max_dist:(string -> int) -> ((string -> unit) -> unit) -> string -> string list

spellcheck iter_dict s are the strings enumerated by the iterator iter_dict whose edit distance to s is the smallest and at most max_dist s. If multiple corrections are returned their order is as found in iter_dict. The default max_dist s is:

  • 0 if s has 0 to 2 Unicode characters.
  • 1 if s has 3 to 4 Unicode characters.
  • 2 otherwise.

If your dictionary is a list l, a suitable iter_dict is given by (fun yield -> List.iter yield l).

All strings are assumed to be UTF-8 encoded, decoding errors are replaced by Uchar.rep characters.

(Un)escaping bytes

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

Sourceval 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
Sourceval 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.

Sourceexception Illegal_escape of int

See byte_unescaper.

Sourceval 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_unreplacer 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.

Sourceval byte_unreplacer : (string -> int -> int) -> (bytes -> int -> string -> int -> int) -> string -> (string, int) result

byte_unreplacer char_len_at set_char is like byte_unescaper except set_char can set a different byte whenever char_len_at returns 1.

ASCII strings

Sourcemodule Ascii : sig ... end

ASCII string support.

Variable substitution

Sourceval 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).

ANSI stripping

Sourceval strip_ansi_escapes : string -> string

strip_ansi_escapes s removes ANSI escapes from s.

Formatting

Sourceval pp : string Fmt.t

pp ppf s prints s's bytes on ppf.

Sets and maps

Sourcemodule Set : sig ... end

String sets.

Sourcemodule Map : sig ... end

String maps.