Base.String
An extension of the standard StringLabels
. If you open Base
, you'll get these extensions in the String
module.
include Sexpable.S with type t := t
val t_sexp_grammar : Sexp.Private.Raw_grammar.t
include Container.S0 with type t := t with type elt = char
val is_empty : t -> bool
iter
must allow exceptions raised in f
to escape, terminating the iteration cleanly. The same holds for all functions below taking an f
.
fold t ~init ~f
returns f (... f (f (f init e1) e2) e3 ...) en
, where e1..en
are the elements of t
.
val fold_result : t -> init:'accum -> f:('accum -> elt -> ('accum, 'e) Result.t) -> ('accum, 'e) Result.t
fold_result t ~init ~f
is a short-circuiting version of fold
that runs in the Result
monad. If f
returns an Error _
, that value is returned without any additional invocations of f
.
val fold_until : t -> init:'accum -> f:('accum -> elt -> ('accum, 'final) Base__Container_intf.Export.Continue_or_stop.t) ->
finish:('accum -> 'final) -> 'final
fold_until t ~init ~f ~finish
is a short-circuiting version of fold
. If f
returns Stop _
the computation ceases and results in that value. If f
returns Continue _
, the fold will proceed. If f
never returns Stop _
, the final result is computed by finish
.
Example:
type maybe_negative =
| Found_negative of int
| All_nonnegative of { sum : int }
(** [first_neg_or_sum list] returns the first negative number in [list], if any,
otherwise returns the sum of the list. *)
let first_neg_or_sum =
List.fold_until ~init:0
~f:(fun sum x ->
if x < 0
then Stop (Found_negative x)
else Continue (sum + x))
~finish:(fun sum -> All_nonnegative { sum })
;;
let x = first_neg_or_sum [1; 2; 3; 4; 5]
val x : maybe_negative = All_nonnegative {sum = 15}
let y = first_neg_or_sum [1; 2; -3; 4; 5]
val y : maybe_negative = Found_negative -3
Returns true
if and only if there exists an element for which the provided function evaluates to true
. This is a short-circuiting operation.
Returns true
if and only if the provided function evaluates to true
for all elements. This is a short-circuiting operation.
Returns the number of elements for which the provided function evaluates to true.
Returns the sum of f i
for all i
in the container.
Returns as an option
the first element for which f
evaluates to true.
Returns the first evaluation of f
that returns Some
, and returns None
if there is no such element.
Returns a min (resp. max) element from the collection using the provided compare
function. In case of a tie, the first element encountered while traversing the collection is returned. The implementation uses fold
so it has the same complexity as fold
. Returns None
iff the collection is empty.
include Identifiable.S with type t := t
val hash_fold_t : Hash.state -> t -> Hash.state
include Sexpable.S with type t := t
val t_of_sexp : Sexplib0.Sexp.t -> t
val sexp_of_t : t -> Sexplib0.Sexp.t
include Comparable.S with type t := t
include Comparisons.S with type t := t
compare t1 t2
returns 0 if t1
is equal to t2
, a negative integer if t1
is less than t2
, and a positive integer if t1
is greater than t2
.
ascending
is identical to compare
. descending x y = ascending y x
. These are intended to be mnemonic when used like List.sort ~compare:ascending
and List.sort
~cmp:descending
, since they cause the list to be sorted in ascending or descending order, respectively.
clamp_exn t ~min ~max
returns t'
, the closest value to t
such that between t' ~low:min ~high:max
is true.
Raises if not (min <= max)
.
val clamp : t -> min:t -> max:t -> t Or_error.t
include Comparator.S with type t := t
val comparator : (t, comparator_witness) Comparator.comparator
val validate_lbound : min:t Maybe_bound.t -> t Validate.check
val validate_ubound : max:t Maybe_bound.t -> t Validate.check
val validate_bound : min:t Maybe_bound.t -> max:t Maybe_bound.t -> t Validate.check
include Pretty_printer.S with type t := t
val pp : Formatter.t -> t -> unit
include Invariant.S with type t := t
val invariant : t -> unit
val length : t -> int
val get : t -> int -> char
unsafe_get t i
is like get t i
but does not perform bounds checking. The caller must ensure that it is a memory-safe operation.
val make : int -> char -> t
Assuming you haven't passed -unsafe-string to the compiler, strings are immutable, so there'd be no motivation to make a copy.
val init : int -> f:(int -> char) -> t
String append. Also available unqualified, but re-exported here for documentation purposes.
Note that a ^ b
must copy both a
and b
into a newly-allocated result string, so a ^ b ^ c ^ ... ^ z
is quadratic in the number of strings. String.concat
does not have this problem -- it allocates the result buffer only once.
Concatenates all strings in the list using separator sep
(with a default separator ""
).
Special characters are represented by escape sequences, following the lexical conventions of OCaml.
val contains : ?pos:int -> ?len:int -> t -> char -> bool
Operates on the whole string using the US-ASCII character set, e.g. uppercase "foo" = "FOO"
.
Operates on just the first character using the US-ASCII character set, e.g. capitalize "foo" = "Foo"
.
index
gives the index of the first appearance of char
in the string when searching from left to right, or None
if it's not found. rindex
does the same but searches from the right.
For example, String.index "Foo" 'o'
is Some 1
while String.rindex "Foo" 'o'
is Some 2
.
The _exn
versions return the actual index (instead of an option) when char
is found, and throw an exception otherwise.
module Caseless : sig ... end
Caseless
compares and hashes strings ignoring case, so that for example Caseless.equal "OCaml" "ocaml"
and Caseless.("apple" < "Banana")
are true
.
val index : t -> char -> int option
index_exn
and index_from_exn
raise Caml.Not_found
or Not_found_s
when char
cannot be found in s
.
val index_exn : t -> char -> int
val index_from : t -> int -> char -> int option
val index_from_exn : t -> int -> char -> int
val rindex : t -> char -> int option
rindex_exn
and rindex_from_exn
raise Caml.Not_found
or Not_found_s
when char
cannot be found in s
.
val rindex_exn : t -> char -> int
val rindex_from : t -> int -> char -> int option
val rindex_from_exn : t -> int -> char -> int
module Search_pattern : sig ... end
Substring search and replace functions. They use the Knuth-Morris-Pratt algorithm (KMP) under the hood.
Substring search and replace convenience functions. They call Search_pattern.create
and then forget the preprocessed pattern when the search is complete. pos < 0
or pos >= length t
result in no match (hence substr_index
returns None
and substr_index_exn
raises). may_overlap
indicates whether to report overlapping matches, see Search_pattern.index_all
.
As with Search_pattern.replace_all
, the result may still contain pattern
.
is_substring_at "foo bar baz" ~pos:4 ~substring:"bar"
is true.
val to_list_rev : t -> char list
Returns the reversed list of characters contained in a list.
If the string s
contains the character on
, then lsplit2_exn s ~on
returns a pair containing s
split around the first appearance of on
(from the left). Raises Caml.Not_found
or Not_found_s
when on
cannot be found in s
.
If the string s
contains the character on
, then rsplit2_exn s ~on
returns a pair containing s
split around the first appearance of on
(from the right). Raises Caml.Not_found
or Not_found_s
when on
cannot be found in s
.
lsplit2 s ~on
optionally returns s
split into two strings around the first appearance of on
from the left.
rsplit2 s ~on
optionally returns s
split into two strings around the first appearance of on
from the right.
split s ~on
returns a list of substrings of s
that are separated by on
. Consecutive on
characters will cause multiple empty strings in the result. Splitting the empty string returns a list of the empty string, not the empty list.
split_on_chars s ~on
returns a list of all substrings of s
that are separated by one of the chars from on
. on
are not grouped. So a grouping of on
in the source string will produce multiple empty string splits in the result.
split_lines t
returns the list of lines that comprise t
. The lines do not include the trailing "\n"
or "\r\n"
.
val lfindi : ?pos:int -> t -> f:(int -> char -> bool) -> int option
lfindi ?pos t ~f
returns the smallest i >= pos
such that f i t.[i]
, if there is such an i
. By default, pos = 0
.
val rfindi : ?pos:int -> t -> f:(int -> char -> bool) -> int option
rfindi ?pos t ~f
returns the largest i <= pos
such that f i t.[i]
, if there is such an i
. By default pos = length t - 1
.
lstrip ?drop s
returns a string with consecutive chars satisfying drop
(by default white space, e.g. tabs, spaces, newlines, and carriage returns) stripped from the beginning of s
.
rstrip ?drop s
returns a string with consecutive chars satisfying drop
(by default white space, e.g. tabs, spaces, newlines, and carriage returns) stripped from the end of s
.
strip ?drop s
returns a string with consecutive chars satisfying drop
(by default white space, e.g. tabs, spaces, newlines, and carriage returns) stripped from the beginning and end of s
.
Like map
, but passes each character's index to f
along with the char.
val foldi : t -> init:'a -> f:(int -> 'a -> char -> 'a) -> 'a
foldi
works similarly to fold
, but also passes the index of each character to f
.
Like map
, but allows the replacement of a single character with zero or two or more characters.
filter s ~f:predicate
discards characters not satisfying predicate
.
tr ~target ~replacement s
replaces every instance of target
in s
with replacement
.
tr_multi ~target ~replacement
returns a function that replaces every instance of a character in target
with the corresponding character in replacement
.
If replacement
is shorter than target
, it is lengthened by repeating its last character. Empty replacement
is illegal unless target
also is.
If target
contains multiple copies of the same character, the last corresponding replacement
character is used. Note that character ranges are not supported, so ~target:"a-z"
means the literal characters 'a'
, '-'
, and 'z'
.
chop_suffix_exn s ~suffix
returns s
without the trailing suffix
, raising Invalid_argument
if suffix
is not a suffix of s
.
chop_prefix_exn s ~prefix
returns s
without the leading prefix
, raising Invalid_argument
if prefix
is not a prefix of s
.
chop_suffix_if_exists s ~suffix
returns s
without the trailing suffix
, or just s
if suffix
isn't a suffix of s
.
Equivalent to chop_suffix s ~suffix |> Option.value ~default:s
, but avoids allocating the intermediate option.
chop_prefix_if_exists s ~prefix
returns s
without the leading prefix
, or just s
if prefix
isn't a prefix of s
.
Equivalent to chop_prefix s ~prefix |> Option.value ~default:s
, but avoids allocating the intermediate option.
suffix s n
returns the longest suffix of s
of length less than or equal to n
.
prefix s n
returns the longest prefix of s
of length less than or equal to n
.
drop_suffix s n
drops the longest suffix of s
of length less than or equal to n
.
drop_prefix s n
drops the longest prefix of s
of length less than or equal to n
.
concat_array sep ar
like String.concat
, but operates on arrays.
val hash : t -> int
Slightly faster hash function on strings.
val of_char : char -> t
val of_char_list : char list -> t
module Escaping : sig ... end
Operations for escaping and unescaping strings, with parameterized escape and escapeworthy characters. Escaping/unescaping using this module is more efficient than using Pcre. Benchmark code can be found in core/benchmarks/string_escaping.ml.