stdune

Dune's unstable standard library
package stdune
Legend:
Library
Module
Module type
Parameter
Class
Class type
Library stdune
Module Stdune . String
type t = string
include module type of struct include StringLabels end with type t := t

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 -> f:( 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.0
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.

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.

Predicates and comparisons

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.

val split_on_char : sep: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.

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

Transforming

val map : f:( 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.0
val mapi : f:( 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.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.

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

Traversing

val iter : f:( 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 : f:( int -> char -> unit ) -> string -> unit

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

  • since 4.00.0

Searching

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_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_opt : string -> char -> int option

index_opt s c is String.index_from_opt s 0 c.

  • since 4.05
val rindex_opt : string -> char -> int option

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

  • since 4.05

Converting

val to_seq : t -> char Seq.t

to_seq s is a sequence made of the string's characters in increasing order. In "unsafe-string" mode, modifications of the string during iteration will be reflected in the iterator.

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

to_seqi s is like 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

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 set : bytes -> int -> char -> unit

set s n c modifies byte sequence s in place, replacing the byte at index n with c. You can also write s.[n] <- c instead of set s n c.

  • raises Invalid_argument

    if n is not a valid index in s.

  • deprecated

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

val blit : src:string -> src_pos:int -> dst:bytes -> dst_pos:int -> len:int -> unit

blit ~src ~src_pos ~dst ~dst_pos ~len copies len bytes from the string src, starting at index src_pos, to byte sequence dst, starting at character number dst_pos.

  • raises Invalid_argument

    if src_pos and len do not designate a valid range of src, or if dst_pos and len do not designate a valid range of dst.

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 equal : t -> t -> bool
val compare : t -> t -> Ordering.t
val hash : t -> int
val to_dyn : t -> Dyn.t
val break : t -> pos:int -> t * t
val is_empty : t -> bool
val of_list : char list -> t
val is_prefix : t -> prefix:t -> bool
val is_suffix : t -> suffix:t -> bool
val take : t -> int -> t
val drop : t -> int -> t
val split_n : t -> int -> t * t
val drop_prefix : t -> prefix:t -> t option
val drop_prefix_if_exists : t -> prefix:t -> t
val drop_suffix : t -> suffix:t -> t option
val drop_suffix_if_exists : t -> suffix:t -> t
val capitalize : t -> t

These only change ASCII characters

val uncapitalize : t -> t
val uppercase : t -> t
val lowercase : t -> t
val index : t -> char -> int option
val index_from : t -> int -> char -> int option
val rindex : t -> char -> int option
val rindex_from : t -> int -> char -> int option
val extract_words : t -> is_word_char:( char -> bool ) -> t list
val extract_comma_space_separated_words : t -> t list
val extract_blank_separated_words : t -> t list
val lsplit2 : t -> on:char -> (t * t) option
val lsplit2_exn : t -> on:char -> t * t
val rsplit2 : t -> on:char -> (t * t) option
val split : t -> on:char -> t list
val split_lines : t -> t list
val escape_only : char -> t -> t

Escape ONLY one character. escape also escapes '\n',... and transforms all chars above '~' into '\xxx' which is not suitable for UTF-8 strings.

val longest : string list -> int

Return the length of the longest string in the list

val longest_map : 'a list -> f:( 'a -> string ) -> int
val longest_prefix : t list -> t
val exists : t -> f:( char -> bool ) -> bool
val for_all : t -> f:( char -> bool ) -> bool
val maybe_quoted : t -> t

maybe_quoted s is s if s doesn't need escaping according to OCaml lexing conventions and sprintf "%S" s otherwise.

(* CR-someday aalekseyev: this function is not great: barely anything "needs escaping according to OCaml lexing conventions", so the condition for whether to add the quote characters ends up being quite arbitrary. *)

val quoted : t -> t
val enumerate_and : string list -> string

Produces: "x, y and z"

val enumerate_or : string list -> string

Produces: "x, y or z"

val enumerate_one_of : t list -> t

Produces: "One of x, y or z"

val findi : string -> f:( char -> bool ) -> int option

Find index of first character satisfying f

val rfindi : string -> f:( char -> bool ) -> int option

Find index of last character satisfying f

include Comparable_intf.S with type key := t
module Map : sig ... end
module Set : sig ... end
module Table : Hashtbl.S with type key = t
val need_quoting : string -> bool

Whether the string needs quoting if it is part of a shell command

val quote_for_shell : string -> string

quote_for_shell s quotes s using Filename.quote if need_quoting s is true

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