CCString (containers.CCString)

type 'a iter = ('a -> unit) -> unit

Fast internal iterator.

since 2.8

type 'a gen = unit -> 'a option

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

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

since 4.02

val empty : string

The empty string.

since 4.13

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_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

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.

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

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

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

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

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

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

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

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.

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

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

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_seqi : t -> (int * char) Stdlib.Seq.t

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

since 4.07

UTF decoding and validations

since 4.14

UTF-8

val get_utf_8_uchar : t -> int -> Stdlib.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 -> Stdlib.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 -> Stdlib.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 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

val length : t -> int

length s returns the length (number of characters) of the given string s.

val blit : t -> int -> Stdlib.Bytes.t -> int -> int -> unit

blit src src_pos dst dst_pos len copies len characters from string src starting at character indice src_pos, to the Bytes sequence dst starting at character indice dst_pos. Like String.blit. Compatible with the -safe-string option.

raises Invalid_argument
if indices are not valid.

val fold : ('a -> char -> 'a) -> 'a -> t -> 'a

fold f init s folds on chars by increasing index. Computes f(… (f (f init s.[0]) s.[1]) …) s.[n-1].

since 0.7

val foldi : ('a -> int -> char -> 'a) -> 'a -> t -> 'a

foldi f init s is just like fold, but it also passes in the index of each chars as second argument to the folded function f.

since 3.3

Conversions

val to_gen : t -> char gen

to_gen s returns the gen of characters contained in the string s.

val to_iter : t -> char iter

to_iter s returns the iter of characters contained in the string s.

since 2.8

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

to_seq s returns the Seq.t of characters contained in the string s. Renamed from to std_seq since 3.0.

since 3.0

val to_list : t -> char list

to_list s returns the list of characters contained in the string s.

val pp_buf : Stdlib.Buffer.t -> t -> unit

pp_buf buf s prints s to the buffer buf. Renamed from pp since 2.0.

val pp : Stdlib.Format.formatter -> t -> unit

pp f s prints the string s within quotes to the formatter f. Renamed from print since 2.0.

val compare : string -> string -> int

compare s1 s2 compares the strings s1 and s2 and returns an integer that indicates their relative position in the sort order.

val is_empty : string -> bool

is_empty s returns true iff s is empty (i.e. its length is 0).

since 1.5

val hash : string -> int

hash s returns the hash value of s.

val rev : string -> string

rev s returns the reverse of s.

since 0.17

val pad : ?side:[ `Left | `Right ] -> ?c:char -> int -> string -> string

pad ~side ~c n s ensures that the string s is at least n bytes long, and pads it on the side with c if it's not the case.

parameter side
determines where padding occurs (default: `Left).

parameter c
the char used to pad (default: ' ').

since 0.17

val of_char : char -> string

of_char 'a' is "a".

since 0.19

val of_gen : char gen -> string

of_gen gen converts a gen of characters to a string.

val of_iter : char iter -> string

of_iter iter converts an iter of characters to a string.

since 2.8

val of_seq : char Stdlib.Seq.t -> string

of_seq seq converts a seq of characters to a string. Renamed from of_std_seq since 3.0.

since 3.0

val of_list : char list -> string

of_list lc converts a list of characters lc to a string.

val of_array : char array -> string

of_array ac converts an array of characters ac to a string.

val to_array : string -> char array

to_array s returns the array of characters contained in the string s.

val find : ?start:int -> sub:string -> string -> int

find ~start ~sub s returns the starting index of the first occurrence of sub within s or -1.

parameter start
starting position in s.

val find_all : ?start:int -> sub:string -> string -> int gen

find_all ~start ~sub s finds all occurrences of sub in s, even overlapping instances and returns them in a generator gen.

parameter start
starting position in s.

since 0.17

val find_all_l : ?start:int -> sub:string -> string -> int list

find_all_l ~sub s finds all occurrences of sub in s and returns them in a list.

parameter start
starting position in s.

since 0.17

val mem : ?start:int -> sub:string -> string -> bool

mem ~start ~sub s is true iff sub is a substring of s.

since 0.12

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

rfind ~sub s finds sub in string s from the right, returns its first index or -1. Should only be used with very small sub.

since 0.12

val replace : 
  ?which:[ `Left | `Right | `All ] ->
  sub:string ->
  by:string ->
  string ->
  string

replace ~which ~sub ~by s replaces some occurrences of sub by by in s.

parameter which
decides whether the occurrences to replace are:
- `Left first occurrence from the left (beginning).
- `Right first occurrence from the right (end).
- `All all occurrences (default).

raises Invalid_argument
if sub = "".

since 0.14

val is_sub : sub:string -> int -> string -> int -> sub_len:int -> bool

is_sub ~sub ~sub_pos s ~pos ~sub_len returns true iff the substring of sub starting at position sub_pos and of length sub_len is a substring of s starting at position pos.

val repeat : string -> int -> string

repeat s n creates a string by repeating the string s n times.

val prefix : pre:string -> string -> bool

prefix ~pre s returns true iff pre is a prefix of s.

val suffix : suf:string -> string -> bool

suffix ~suf s returns true iff suf is a suffix of s.

since 0.7

val chop_prefix : pre:string -> string -> string option

chop_prefix ~pre s removes pre from s if pre really is a prefix of s, returns None otherwise.

since 0.17

val chop_suffix : suf:string -> string -> string option

chop_suffix ~suf s removes suf from s if suf really is a suffix of s, returns None otherwise.

since 0.17

val take : int -> string -> string

take n s keeps only the n first chars of s.

since 0.17

val drop : int -> string -> string

drop n s removes the n first chars of s.

since 0.17

val take_drop : int -> string -> string * string

take_drop n s is take n s, drop n s.

since 0.17

val lines : string -> string list

lines s returns a list of the lines of s (splits along '\n').

since 0.10

val lines_gen : string -> string gen

lines_gen s returns the gen of the lines of s (splits along '\n').

since 0.10

val lines_iter : string -> string iter

lines_iter s returns the iter of the lines of s (splits along '\n').

since 3.2

val lines_seq : string -> string Stdlib.Seq.t

lines_seq s returns the Seq.t of the lines of s (splits along '\n').

since 3.2

val concat_gen : sep:string -> string gen -> string

concat_gen ~sep gen concatenates all strings of gen, separated with sep.

since 0.10

val concat_seq : sep:string -> string Stdlib.Seq.t -> string

concat_seq ~sep seq concatenates all strings of seq, separated with sep.

since 3.2

val concat_iter : sep:string -> string iter -> string

concat_iter ~sep iter concatenates all strings of iter, separated with sep.

since 3.2

val unlines : string list -> string

unlines ls concatenates all strings of ls, separated with '\n'.

since 0.10

val unlines_gen : string gen -> string

unlines_gen gen concatenates all strings of gen, separated with '\n'.

since 0.10

val unlines_iter : string iter -> string

unlines_iter iter concatenates all strings of iter, separated with '\n'.

since 3.2

val unlines_seq : string Stdlib.Seq.t -> string

unlines_seq seq concatenates all strings of seq, separated with '\n'.

since 3.2

val set : string -> int -> char -> string

set s i c creates a new string which is a copy of s, except for index i, which becomes c.

raises Invalid_argument
if i is an invalid index.

since 0.12

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

iter f s applies function f on each character of s. Alias to String.iter.

since 0.12

val filter_map : (char -> char option) -> string -> string

filter_map f s calls (f a0) (f a1) … (f an) where a0 … an are the characters of s. It returns the string of characters ci such as f ai = Some ci (when f returns None, the corresponding element of s is discarded).

since 0.17

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

filter f s discards characters of s not satisfying f.

since 0.17

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

uniq eq s remove consecutive duplicate characters in s.

since 3.4

val flat_map : ?sep:string -> (char -> string) -> string -> string

flat_map ~sep f s maps each chars of s to a string, then concatenates them all.

parameter sep
optional separator between each generated string.

since 0.12

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

for_all f s is true iff all characters of s satisfy the predicate f.

since 0.12

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

exists f s is true iff some character of s satisfy the predicate f.

since 0.12

val drop_while : (char -> bool) -> t -> t

drop_while f s discards any characters of s starting from the left, up to the first character c not satisfying f c.

since 2.2

val rdrop_while : (char -> bool) -> t -> t

rdrop_while f s discards any characters of s starting from the right, up to the first character c not satisfying f c.

since 2.2

val ltrim : t -> t

ltrim s trims space on the left (see String.trim for more details).

since 1.2

val rtrim : t -> t

rtrim s trims space on the right (see String.trim for more details).

since 1.2

Operations on 2 strings

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

map2 f s1 s2 maps pairs of chars.

raises Invalid_argument
if the strings have not the same length.

since 0.12

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

iter2 f s1 s2 iterates on pairs of chars.

raises Invalid_argument
if the strings have not the same length.

since 0.12

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

iteri2 f s1 s2 iterates on pairs of chars with their index.

raises Invalid_argument
if the strings have not the same length.

since 0.12

val fold2 : ('a -> char -> char -> 'a) -> 'a -> string -> string -> 'a

fold2 f init s1 s2 folds on pairs of chars.

raises Invalid_argument
if the strings have not the same length.

since 0.12

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

for_all2 f s1 s2 returns true iff all pairs of chars satisfy the predicate f.

raises Invalid_argument
if the strings have not the same length.

since 0.12

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

exists2 f s1 s2 returns true iff a pair of chars satisfy the predicate f.

raises Invalid_argument
if the strings have not the same length.

since 0.12

Ascii functions

Those functions are deprecated in String since 4.03, so we provide a stable alias for them even in older versions.

val equal_caseless : string -> string -> bool

equal_caseless s1 s2 compares s1 and s2 without respect to ascii lowercase.

since 1.2

val to_hex : string -> string

Convert a string with arbitrary content into a hexadecimal string.

since 3.8

val of_hex : string -> string option

Convert a string in hex into a string with arbitrary content.

since 3.8

val of_hex_exn : string -> string

Same as of_hex but fails harder.

raises Invalid_argument
if the input is not valid hex.

since 3.8

Finding

A relatively efficient algorithm for finding sub-strings.

since 1.0

module Find : sig ... end

Splitting

module Split : sig ... end

val split_on_char : char -> string -> string list

split_on_char by s splits the string s along the given char by.

since 1.2

val split : by:string -> string -> string list

split ~by s splits the string s along the given string by. Alias to Split.list_cpy.

since 1.2

Utils

val compare_versions : string -> string -> int

compare_versions s1 s2 compares version strings s1 and s2, considering that numbers are above text.

since 0.13

val compare_natural : string -> string -> int

compare_natural s1 s2 is the Natural Sort Order, comparing chunks of digits as natural numbers. https://en.wikipedia.org/wiki/Natural_sort_order

since 1.3

val edit_distance : ?cutoff:int -> string -> string -> int

edit_distance ~cutoff s1 s2 is the edition distance between the two strings s1 and s2. This satisfies the classical distance axioms: it is always positive, symmetric, and satisfies the formula distance s1 s2 + distance s2 s3 >= distance s1 s3.

parameter cutoff
if provided, it's a cap on the number of iterations. (since 3.0). This is useful if you just want to check whether the edit distance is less or equal than 2 without (use edit_distance s1 s2 ~cutoff:3 <= 2). note that contrary to what was previously documented here, the result can still be higher than cutoff if it's reached in <cutoff iterations. However if the result is < cutoff then it is accurate.

Infix operators

since 3.0

module Infix : sig ... end

include module type of Infix

val (=) : t -> t -> bool

since 3.0

val (<>) : t -> t -> bool

since 3.0

val (<) : t -> t -> bool

since 3.0

val (<=) : t -> t -> bool

since 3.0

val (>=) : t -> t -> bool

since 3.0

val (>) : t -> t -> bool

since 3.0