containers

A modular, clean and powerful extension of the OCaml standard library
back to documentation root
package containers
Legend:
Library
Module
Module type
Parameter
Class
Class type
Library containers
Module CCStringLabels

Basic String Utils

type 'a sequence = ( 'a -> unit ) -> unit
  • deprecated

    use 'a iter instead

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

Fast internal iterator.

  • since 2.8
type 'a gen = unit -> 'a option
type 'a klist = unit -> [ `Nil | `Cons of 'a * 'a klist ]

Common Signature

module type S = sig ... end

Strings

include module type of struct include StringLabels end

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 empty : string

The empty string.

  • since 4.13.0
val of_bytes : bytes -> string

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

  • since 4.13.0
val to_bytes : string -> bytes

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

  • since 4.13.0
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.

Concatenating

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

val concat : sep: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 then than Sys.max_string_length bytes.

  • since 4.13.0

Predicates and comparisons

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

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

  • since 4.13.0
val ends_with : suffix:string -> string -> bool

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

  • since 4.13.0
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 -> pos:int -> len: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 fold_left : f:( 'a -> char -> 'a ) -> init:'a -> string -> 'a

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.0
val fold_right : f:( char -> 'a -> 'a ) -> string -> init:'a -> 'a

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

Traversing

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

Deprecated functions

val create : int -> bytes

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

  • raises Invalid_argument

    if n < 0 or n > Sys.max_string_length.

  • deprecated

    This is a deprecated alias of Bytes.create/BytesLabels.create.

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 fill : bytes -> pos:int -> len:int -> char -> unit

fill s ~pos ~len c modifies byte sequence s in place, replacing len bytes by c, starting at pos.

  • raises Invalid_argument

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

  • deprecated

    This is a deprecated alias of Bytes.fill/BytesLabels.fill.

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.

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.0
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.0
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.0
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.0
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.0
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.0
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.0
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.0
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.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.0
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.0
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.0
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.0
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.0
val equal : string -> string -> bool

Equality function on strings.

val compare : string -> string -> int
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
val init : int -> ( int -> char ) -> string

Like Array.init.

  • since 0.3.3
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 n str ensures that str 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

Convert a gen of characters to a string.

val of_iter : char iter -> string

Convert a iter of characters to a string.

  • since 2.8
val of_std_seq : char Seq.t -> string

Convert a sequence of characters to a string.

  • since 2.8
val of_seq : char sequence -> string
val of_klist : char klist -> string
val of_list : char list -> string

Convert a list of characters to a string.

val of_array : char array -> string

Convert an array of characters to a string.

val to_array : string -> char array

Return the array of characters contained in the string.

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

Find sub in string, returns its first index or -1.

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

find_all ~sub s finds all occurrences of sub in s, even overlapping instances.

  • 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 ~sub s is true iff sub is a substring of s.

  • since 0.12
val rfind : sub:string -> string -> int

Find sub in string 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 ~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 -> sub_pos:int -> string -> pos:int -> sub_len:int -> bool

is_sub ~sub i s j ~len returns true iff the substring of sub starting at position i and of length len is a substring of s starting at position j.

val repeat : string -> int -> string

The same string, repeated 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 = 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 a generator of the lines of s (splits along '\n').

  • since 0.10
val concat_gen : sep:string -> string gen -> string

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

  • since 0.10
val unlines : string list -> string

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

  • since 0.10
val unlines_gen : string gen -> string

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

  • since 0.10
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 : f:( char -> unit ) -> string -> unit

Alias to String.iter.

  • since 0.12
val iteri : f:( int -> char -> unit ) -> string -> unit

Iter on chars with their index.

  • since 0.12
val map : f:( char -> char ) -> string -> string

Map chars.

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

Map chars with their index.

  • since 0.12
val filter_map : f:( 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 : f:( char -> bool ) -> string -> string

filter f s discards characters not satisfying f.

  • since 0.17
val flat_map : ?sep:string -> f:( char -> string ) -> string -> string

Map each chars to a string, then concatenates them all.

  • parameter sep

    optional separator between each generated string.

  • since 0.12
val for_all : f:( char -> bool ) -> string -> bool

True for all chars?

  • since 0.12
val exists : f:( char -> bool ) -> string -> bool

True for some char?

  • since 0.12
include S with type t := string
val length : string -> int

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

val blit : src:string -> src_pos:int -> dst:Bytes.t -> dst_pos:int -> len:int -> unit

Like String.blit. Compatible with the -safe-string option.

  • raises Invalid_argument

    if indices are not valid.

val fold : f:( 'a -> char -> 'a ) -> init:'a -> string -> 'a

Fold on chars by increasing index.

  • since 0.7

Conversions

val to_gen : string -> char gen

Return the gen of characters contained in the string.

val to_iter : string -> char iter

Return the iter of characters contained in the string.

  • since 2.8
val to_std_seq : string -> char Seq.t

to_std_seq s returns a Seq.t of the bytes in s.

  • since 2.8
val to_seq : string -> char sequence
val to_klist : string -> char klist
val to_list : string -> char list

Return the list of characters contained in the string.

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

Renamed from pp since 2.0.

val pp : Format.formatter -> string -> unit

Print the string within quotes.

Renamed from print since 2.0.

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

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

  • since 2.2
val rdrop_while : f:( char -> bool ) -> t -> t

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

  • since 2.2
val ltrim : t -> t

Trim space on the left (see String.trim for more details).

  • since 1.2
val rtrim : t -> t

Trim space on the right (see String.trim for more details).

  • since 1.2

Operations on 2 strings

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

Map pairs of chars.

  • raises Invalid_argument

    if the strings have not the same length.

  • since 0.12
val iter2 : f:( char -> char -> unit ) -> string -> string -> unit

Iterate on pairs of chars.

  • raises Invalid_argument

    if the strings have not the same length.

  • since 0.12
val iteri2 : f:( int -> char -> char -> unit ) -> string -> string -> unit

Iterate on pairs of chars with their index.

  • raises Invalid_argument

    if the strings have not the same length.

  • since 0.12
val fold2 : f:( 'a -> char -> char -> 'a ) -> init:'a -> string -> string -> 'a

Fold on pairs of chars.

  • raises Invalid_argument

    if the strings have not the same length.

  • since 0.12
val for_all2 : f:( char -> char -> bool ) -> string -> string -> bool

All pairs of chars respect the predicate?

  • raises Invalid_argument

    if the strings have not the same length.

  • since 0.12
val exists2 : f:( char -> char -> bool ) -> string -> string -> bool

Exists a pair of chars?

  • 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 capitalize_ascii : string -> string

See String.

  • since 0.18
val uncapitalize_ascii : string -> string

See String.

  • since 0.18
val uppercase_ascii : string -> string

See String.

  • since 0.18
val lowercase_ascii : string -> string

See String.

  • since 0.18
val equal_caseless : string -> string -> bool

Comparison without respect to ascii lowercase.

  • since 1.2

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 : by:char -> string -> string list

Split the string along the given char.

  • since 1.2
val split : by:string -> string -> string list

Alias to Split.list_cpy.

  • since 1.2

Utils

val compare_versions : string -> string -> int

compare_versions a b compares version strings a and b, considering that numbers are above text.

  • since 0.13
val compare_natural : string -> string -> int

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

  • since 1.3
val edit_distance : string -> string -> int

Edition distance between two strings. This satisfies the classical distance axioms: it is always positive, symmetric, and satisfies the formula distance a b + distance b c >= distance a c.

Slices

A contiguous part of a string

module Sub : sig ... end