package containers

  1. Overview
  2. Docs
package containers
Legend:
Library
Module
Module type
Parameter
Class
Class type

Basic String Utils

Consider using Containers_string.KMP for pattern search, or Regex libraries.

type 'a gen = unit -> 'a option
type 'a sequence = ('a -> unit) -> unit
type 'a klist = unit -> [ `Nil | `Cons of 'a * 'a klist ]

Common Signature

module type S = sig ... end

Strings

include module type of String
val get : string -> int -> char

String.get s n returns the character at index n in string s. You can also write s.[n] instead of String.get s n.

Raise Invalid_argument if n not a valid index in s.

val create : int -> bytes

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

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

val make : int -> char -> string

String.make n c returns a fresh string of length n, filled with the character c.

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

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 sub : string -> int -> int -> string

String.sub s start len returns a fresh string of length len, containing the substring of s that starts at position start and has length len.

Raise Invalid_argument if start and len do not designate a valid substring of s.

val fill : bytes -> int -> int -> char -> unit

String.fill s start len c modifies byte sequence s in place, replacing len bytes with c, starting at start.

Raise Invalid_argument if start and len do not designate a valid range of s.

  • deprecated

    This is a deprecated alias of Bytes.fill.

val concat : string -> string list -> string

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

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

val trim : string -> string

Return a copy of the argument, without leading and trailing whitespace. The characters regarded as whitespace are: ' ', '\012', '\n', '\r', and '\t'. If there is neither leading nor trailing whitespace character in the argument, return the original string itself, not a copy.

  • since 4.00.0
val escaped : string -> string

Return a copy of the argument, with special characters represented by escape sequences, following the lexical conventions of OCaml. All characters outside the ASCII printable range (32..126) are escaped, as well as backslash and double-quote.

If there is no special character in the argument that needs escaping, return the original string itself, not a copy.

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

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

val index : string -> char -> int

String.index s c returns the index of the first occurrence of character c in string s.

Raise Not_found if c does not occur in s.

val index_opt : string -> char -> int option

String.index_opt s c returns the index of the first occurrence of character c in string s, or None if c does not occur in s.

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

String.rindex s c returns the index of the last occurrence of character c in string s.

Raise Not_found if c does not occur in s.

val rindex_opt : string -> char -> int option

String.rindex_opt s c returns the index of the last occurrence of character c in string s, or None if c does not occur in s.

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

String.index_from s i c returns the index of the first occurrence of character c in string s after position i. String.index s c is equivalent to String.index_from s 0 c.

Raise Invalid_argument if i is not a valid position in s. Raise Not_found if c does not occur in s after position i.

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

String.index_from_opt s i c returns the index of the first occurrence of character c in string s after position i or None if c does not occur in s after position i.

String.index_opt s c is equivalent to String.index_from_opt s 0 c. Raise Invalid_argument if i is not a valid position in s.

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

String.rindex_from s i c returns the index of the last occurrence of character c in string s before position i+1. String.rindex s c is equivalent to String.rindex_from s (String.length s - 1) c.

Raise Invalid_argument if i+1 is not a valid position in s. Raise Not_found if c does not occur in s before position i+1.

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

String.rindex_from_opt s i c returns the index of the last occurrence of character c in string s before position i+1 or None if c does not occur in s before position i+1.

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

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

  • since 4.05
val contains : string -> char -> bool

String.contains s c tests if character c appears in the string s.

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

String.contains_from s start c tests if character c appears in s after position start. String.contains s c is equivalent to String.contains_from s 0 c.

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

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

String.rcontains_from s stop c tests if character c appears in s before position stop+1.

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

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.

type t = string

An alias for the type of strings.

Iterators
val to_seqi : t -> (int * char) Seq.t

Iterate on the string, in increasing order, yielding indices along chars

  • since 4.07
val equal : string -> string -> bool
val compare : string -> string -> int
val hash : string -> int
val init : int -> (int -> char) -> string

Analog to 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' = "a"

  • since 0.19
val of_gen : char gen -> string
val of_seq : char sequence -> string
val of_klist : char klist -> string
val of_list : char list -> string
val of_array : char array -> string
val to_array : string -> char array
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 ~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 -> int -> string -> int -> 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_pref ~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 : (char -> unit) -> string -> unit

Alias to String.iter

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

Iter on chars with their index

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

Map chars

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

Map chars with their index

  • since 0.12
val filter_map : (char -> char option) -> string -> string
  • since 0.17
val filter : (char -> bool) -> string -> string
  • since 0.17
val flat_map : ?sep:string -> (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 : (char -> bool) -> string -> bool

True for all chars?

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

True for some char?

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

Similar to String.blit. Compatible with the -safe-string option.

  • raises Invalid_argument

    if indices are not valid

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

Fold on chars by increasing index.

  • since 0.7

Conversions

val to_gen : string -> char gen
val to_seq : string -> char sequence
val to_klist : string -> char klist
val to_list : string -> char list
val pp : Buffer.t -> string -> unit
val print : Format.formatter -> string -> unit

Print the string within quotes

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 : (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 : (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 : (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 : ('a -> char -> char -> 'a) -> '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 : (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 : (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 : 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
OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct