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 .

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

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

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

val empty : string

The empty string.

Since 4.13

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

Raises Invalid_argument if i not an index of s .

val of_char : char -> string

of_char c is c as a string.

Since 5.5

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 (^) 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.

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

val cat : string -> string -> string

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

Since 4.13

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

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 compare on strings but may be more efficient.

val is_empty : string -> bool

is_empty s is true if and only if s is an empty string.

Since 5.5

val starts_with : prefix:string -> string -> bool

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

Since 4.13

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

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

Since 4.13

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

includes affix s is true if and only if affix occurs in s .

Note. To test the same affix string multiple times, partially applying the ~affix argument and using the resulting function repeatedly is more efficient.

Since 5.5

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 .

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

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 .

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

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 .

Raises Invalid_argument if pos and len do not designate a valid substring of s .

Splitting strings¶

Splitting with magnitudes¶

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

Since 5.5

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

Since 5.5

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

Since 5.5

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

Since 5.5

val cut_first : int -> string -> string * string

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

Since 5.5

val cut_last : int -> string -> string * string

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

Since 5.5

Splitting with predicates¶

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

take_first_while p s is the first consecutive bytes of s satisfying the predicate p .

Since 5.5

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

take_last_while p s is the last consecutive bytes of s satisfying the predicate p .

Since 5.5

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

drop_first_while p s is s without the first consecutive bytes of s satisfying the predicate p .

Since 5.5

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

drop_last_while p s is s without the last consecutive bytes of s satisfying the predicate p .

Since 5.5

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

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

Since 5.5

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

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

Since 5.5

Splitting with separators¶

Note. To split the same sep string multiple times, partially applying the ~sep argument of these functions and using the resulting function repeatedly is more efficient.

val 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 in s or None if sep can't be found. Search for sep starts at position 0 and uses String.find_first .

If sep is "" , this is Some ("", s) .

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

Since 5.5

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

split_last sep s is the pair Some (left, right) made of the two (possibly empty) substrings of s that are delimited by the last match of the separator sep in s or None if sep can't be found. Search for sep starts at position length s and uses String.find_last .

If sep is "" , this is Some (s, "") .

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

Since 5.5

val split_all : sep:string -> ?drop:(string -> bool) -> 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 or the list [s] if sep can't be found. Search for sep starts at position 0 in increasing indexing order and uses String.find_all .

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

If sep is "" , this is [""; c0; ...; cn; ""] with ci the string of_char s.[i] .

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

Since 5.5

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

rsplit_all sep s is the list of all substrings of s that are delimited by non-overlapping matches of the separator sep or [s] if sep can't be found. Search for sep starts at position length s in decreasing indexing order and uses String.rfind_all .

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

If sep is "" , this is [""; c0; ...; cn; ""] with ci the string of_char s.[i] .

The invariant concat sep (rsplit_all sep s) = s holds.

Since 5.5

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

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

Since 4.13

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

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

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 (0x5C) 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).

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

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 String.iter , but the function is also given the corresponding character index.

Since 4.00

Finding indices¶

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

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

If start is length s , the result is always None .

Since 5.5

Raises Invalid_argument if start is not a valid position of s .

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

find_last_index p start s is the index of the last character of s that satisfies predicate p at or before the index or position start (defaults to length s ).

Since 5.5

Raises Invalid_argument if start is not a valid position of s .

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 .

Raises Invalid_argument if i is not a valid position in s .

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

Raises Invalid_argument if i is not a valid position in s .

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 .

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

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

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

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

Finding substrings¶

Note. To find the same sub string multiple times, partially applying the ~sub argument of these functions and using the resulting function repeatedly is more efficient

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

find_first sub start s is the starting position of the first occurrence of sub in s at or after the index or position start (defaults to 0 ).

If sub is "" the result is Some start . The result of the function is always a valid index of s except when sub is "" and start is length s .

Since 5.5

Raises Invalid_argument if start is not a valid position of s .

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

find_last sub start s is the starting position of the last occurrence of sub in s at or before the index or position start (defaults to String.length s ).

If sub is "" the result is Some start . The result of the function is always a valid index of s except when sub is "" and start is length s .

Since 5.5

Raises Invalid_argument if start is not a valid position of s .

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

find_all sub f start s acc , starting with acc , folds f by increasing index order over all non-overlapping starting positions of sub in s at or after the index or position start (defaults to 0 ). The result is acc if sub could not be found in s .

If sub is "" , f gets invoked on all positions of s at or after start .

Since 5.5

Raises Invalid_argument if start is not a valid position of s .

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

rfind_all sub f start s acc , starting with acc , folds f by decreasing index order over all non-overlapping starting positions of sub in s at or before the index or position start (defaults to String.length s ). The result is acc if sub could not be found in s .

If sub is "" , f gets invoked on all positions of s at or before start .

Since 5.5

Raises Invalid_argument if start is not a valid position of s .

Replacing substrings¶

Note. To replace the same sub string multiple times, partially applying the ~sub argument of these functions and using the resulting function repeatedly is more efficient.

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

replace_first sub by start s replaces by by the first occurrence of sub in s at or after the index or position start (defaults to 0 ).

If sub is "" , this inserts by at position start .

Since 5.5

Raises Invalid_argument if start is not a valid position of s .

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

replace_last sub by start s replaces by by the last occurrence of sub in s at or after the index or position start (defaults to String.length s ).

If sub is "" , this inserts by at position start .

Since 5.5

Raises Invalid_argument if start is not a valid position of s .

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

replace_all sub by start s replaces by by all non-overlapping occurrences of sub in s at or after the index or position start (defaults to 0 ). Occurrences are found in increasing indexing order.

If sub is "" , this inserts by on all positions from start on.

Since 5.5

Raises Invalid_argument if start is not a valid position of s .

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 String.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¶

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.

Spellchecking¶

val 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 Alignment (OSA) distance, not the Damerau-Levenshtein distance. With this function "ca" and "abc" have a distance of 3 not 2.

Since 5.4

val 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 String.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.

Since 5.4

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