.TH "String" 3o 2020-10-30 OCamldoc "OCaml library"
.SH NAME
String \- String operations.
.SH Module
Module   String
.SH Documentation
.sp
Module
.BI "String"
 : 
.B sig end

.sp
String operations\&.
.sp
A string is an immutable data structure that contains a
fixed\-length sequence of (single\-byte) characters\&. Each character
can be accessed in constant time through its index\&.
.sp
Given a string 
.ft B
s
.ft R
of length 
.ft B
l
.ft R
, we can access each of the 
.ft B
l
.ft R
characters of 
.ft B
s
.ft R
via its index in the sequence\&. Indexes start at
.ft B
0
.ft R
, and we will call an index valid in 
.ft B
s
.ft R
if it falls within the
range 
.ft B
[0\&.\&.\&.l\-1]
.ft R
(inclusive)\&. A position is the point between two
characters or at the beginning or end of the string\&.  We call a
position valid in 
.ft B
s
.ft R
if it falls within the range 
.ft B
[0\&.\&.\&.l]
.ft R
(inclusive)\&. Note that the character at index 
.ft B
n
.ft R
is between
positions 
.ft B
n
.ft R
and 
.ft B
n+1
.ft R
\&.
.sp
Two parameters 
.ft B
start
.ft R
and 
.ft B
len
.ft R
are said to designate a valid
substring of 
.ft B
s
.ft R
if 
.ft B
len >= 0
.ft R
and 
.ft B
start
.ft R
and 
.ft B
start+len
.ft R
are
valid positions in 
.ft B
s
.ft R
\&.
.sp
Note: OCaml strings used to be modifiable in place, for instance via
the 
.ft B
String\&.set
.ft R
and 
.ft B
String\&.blit
.ft R
functions described below\&. This
usage is only possible when the compiler is put in "unsafe\-string"
mode by giving the 
.ft B
\-unsafe\-string
.ft R
command\-line option\&. This
compatibility mode makes the types 
.ft B
string
.ft R
and 
.ft B
bytes
.ft R
(see module
.ft B
Bytes
.ft R
) interchangeable so that functions expecting byte sequences
can also accept strings as arguments and modify them\&.
.sp
The distinction between 
.ft B
bytes
.ft R
and 
.ft B
string
.ft R
was introduced in OCaml
4\&.02, and the "unsafe\-string" compatibility mode was the default
until OCaml 4\&.05\&. Starting with 4\&.06, the compatibility mode is
opt\-in; we intend to remove the option in the future\&.

.sp

.sp
.sp

.I val length 
: 
.B string -> int
.sp
Return the length (number of characters) of the given string\&.

.sp

.I val get 
: 
.B string -> int -> char
.sp

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

.sp
.B "Raises Invalid_argument"
if 
.ft B
n
.ft R
not a valid index in 
.ft B
s
.ft R
\&.

.sp

.I val set 
: 
.B bytes -> int -> char -> unit
.sp
.B "Deprecated."
This is a deprecated alias of 
.ft B
Bytes\&.set
.ft R
\&.
.ft B
.ft R


.sp

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

.sp
.B "Raises Invalid_argument"
if 
.ft B
n
.ft R
is not a valid index in 
.ft B
s
.ft R
\&.

.sp

.I val create 
: 
.B int -> bytes
.sp
.B "Deprecated."
This is a deprecated alias of 
.ft B
Bytes\&.create
.ft R
\&.
.ft B
.ft R


.sp

.ft B
String\&.create n
.ft R
returns a fresh byte sequence of length 
.ft B
n
.ft R
\&.
The sequence is uninitialized and contains arbitrary bytes\&.

.sp
.B "Raises Invalid_argument"
if 
.ft B
n < 0
.ft R
or 
.ft B
n > 
.ft R
.ft B
Sys\&.max_string_length
.ft R
\&.

.sp

.I val make 
: 
.B int -> char -> string
.sp

.ft B
String\&.make n c
.ft R
returns a fresh string of length 
.ft B
n
.ft R
,
filled with the character 
.ft B
c
.ft R
\&.

.sp
.B "Raises Invalid_argument"
if 
.ft B
n < 0
.ft R
or 
.ft B
n > 
.ft R
.ft B
Sys\&.max_string_length
.ft R
\&.

.sp

.I val init 
: 
.B int -> (int -> char) -> string
.sp

.ft B
String\&.init n f
.ft R
returns a string of length 
.ft B
n
.ft R
, with character
.ft B
i
.ft R
initialized to the result of 
.ft B
f i
.ft R
(called in increasing
index order)\&.

.sp
.B "Since"
4.02.0

.sp
.B "Raises Invalid_argument"
if 
.ft B
n < 0
.ft R
or 
.ft B
n > 
.ft R
.ft B
Sys\&.max_string_length
.ft R
\&.

.sp

.I val copy 
: 
.B string -> string
.sp
.B "Deprecated."
Because strings are immutable, it doesn\&'t make much
sense to make identical copies of them\&.

.sp
Return a copy of the given string\&.

.sp

.I val sub 
: 
.B string -> int -> int -> string
.sp

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

.sp
.B "Raises Invalid_argument"
if 
.ft B
start
.ft R
and 
.ft B
len
.ft R
do not
designate a valid substring of 
.ft B
s
.ft R
\&.

.sp

.I val fill 
: 
.B bytes -> int -> int -> char -> unit
.sp
.B "Deprecated."
This is a deprecated alias of 
.ft B
Bytes\&.fill
.ft R
\&.
.ft B
.ft R


.sp

.ft B
String\&.fill s start len c
.ft R
modifies byte sequence 
.ft B
s
.ft R
in place,
replacing 
.ft B
len
.ft R
bytes with 
.ft B
c
.ft R
, starting at 
.ft B
start
.ft R
\&.

.sp
.B "Raises Invalid_argument"
if 
.ft B
start
.ft R
and 
.ft B
len
.ft R
do not
designate a valid range of 
.ft B
s
.ft R
\&.

.sp

.I val blit 
: 
.B string -> int -> bytes -> int -> int -> unit
.sp
Same as 
.ft B
Bytes\&.blit_string
.ft R
\&.

.sp

.I val concat 
: 
.B string -> string list -> string
.sp

.ft B
String\&.concat sep sl
.ft R
concatenates the list of strings 
.ft B
sl
.ft R
,
inserting the separator string 
.ft B
sep
.ft R
between each\&.

.sp
.B "Raises Invalid_argument"
if the result is longer than
.ft B
Sys\&.max_string_length
.ft R
bytes\&.

.sp

.I val iter 
: 
.B (char -> unit) -> string -> unit
.sp

.ft B
String\&.iter f s
.ft R
applies function 
.ft B
f
.ft R
in turn to all
the characters of 
.ft B
s
.ft R
\&.  It is equivalent to
.ft B
f s\&.[0]; f s\&.[1]; \&.\&.\&.; f s\&.[String\&.length s \- 1]; ()
.ft R
\&.

.sp

.I val iteri 
: 
.B (int -> char -> unit) -> string -> unit
.sp
Same as 
.ft B
String\&.iter
.ft R
, but the
function is applied to the index of the element as first argument
(counting from 0), and the character itself as second argument\&.

.sp
.B "Since"
4.00.0

.sp

.I val map 
: 
.B (char -> char) -> string -> string
.sp

.ft B
String\&.map f s
.ft R
applies function 
.ft B
f
.ft R
in turn to all the
characters of 
.ft B
s
.ft R
(in increasing index order) and stores the
results in a new string that is returned\&.

.sp
.B "Since"
4.00.0

.sp

.I val mapi 
: 
.B (int -> char -> char) -> string -> string
.sp

.ft B
String\&.mapi f s
.ft R
calls 
.ft B
f
.ft R
with each character of 
.ft B
s
.ft R
and its
index (in increasing index order) and stores the results in a new
string that is returned\&.

.sp
.B "Since"
4.02.0

.sp

.I val trim 
: 
.B string -> string
.sp
Return a copy of the argument, without leading and trailing
whitespace\&.  The characters regarded as whitespace are: 
.ft B
\&' \&'
.ft R
,
.ft B
\&'\(rs012\&'
.ft R
, 
.ft B
\&'\(rsn\&'
.ft R
, 
.ft B
\&'\(rsr\&'
.ft R
, and 
.ft B
\&'\(rst\&'
.ft R
\&.  If there is neither leading nor
trailing whitespace character in the argument, return the original
string itself, not a copy\&.

.sp
.B "Since"
4.00.0

.sp

.I val escaped 
: 
.B string -> string
.sp
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\&.
.sp
If there is no special character in the argument that needs
escaping, return the original string itself, not a copy\&.

.sp
.B "Raises Invalid_argument"
if the result is longer than
.ft B
Sys\&.max_string_length
.ft R
bytes\&.
.sp
The function 
.ft B
Scanf\&.unescaped
.ft R
is a left inverse of 
.ft B
escaped
.ft R
,
i\&.e\&. 
.ft B
Scanf\&.unescaped (escaped s) = s
.ft R
for any string 
.ft B
s
.ft R
(unless
.ft B
escape s
.ft R
fails)\&.

.sp

.I val index 
: 
.B string -> char -> int
.sp

.ft B
String\&.index s c
.ft R
returns the index of the first
occurrence of character 
.ft B
c
.ft R
in string 
.ft B
s
.ft R
\&.

.sp
.B "Raises Not_found"
if 
.ft B
c
.ft R
does not occur in 
.ft B
s
.ft R
\&.

.sp

.I val index_opt 
: 
.B string -> char -> int option
.sp

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

.sp
.B "Since"
4.05

.sp

.I val rindex 
: 
.B string -> char -> int
.sp

.ft B
String\&.rindex s c
.ft R
returns the index of the last
occurrence of character 
.ft B
c
.ft R
in string 
.ft B
s
.ft R
\&.

.sp
.B "Raises Not_found"
if 
.ft B
c
.ft R
does not occur in 
.ft B
s
.ft R
\&.

.sp

.I val rindex_opt 
: 
.B string -> char -> int option
.sp

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

.sp
.B "Since"
4.05

.sp

.I val index_from 
: 
.B string -> int -> char -> int
.sp

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

.sp
.B "Raises Invalid_argument"
if 
.ft B
i
.ft R
is not a valid position in 
.ft B
s
.ft R
\&.

.sp
.B "Raises Not_found"
if 
.ft B
c
.ft R
does not occur in 
.ft B
s
.ft R
after position 
.ft B
i
.ft R
\&.

.sp

.I val index_from_opt 
: 
.B string -> int -> char -> int option
.sp

.ft B
String\&.index_from_opt s i c
.ft R
returns the index of the
first occurrence of character 
.ft B
c
.ft R
in string 
.ft B
s
.ft R
after position 
.ft B
i
.ft R
or 
.ft B
None
.ft R
if 
.ft B
c
.ft R
does not occur in 
.ft B
s
.ft R
after position 
.ft B
i
.ft R
\&.
.sp

.ft B
String\&.index_opt s c
.ft R
is equivalent to 
.ft B
String\&.index_from_opt s 0 c
.ft R
\&.

.sp
.B "Since"
4.05

.sp
.B "Raises Invalid_argument"
if 
.ft B
i
.ft R
is not a valid position in 
.ft B
s
.ft R
\&.

.sp

.I val rindex_from 
: 
.B string -> int -> char -> int
.sp

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

.sp
.B "Raises Invalid_argument"
if 
.ft B
i+1
.ft R
is not a valid position in 
.ft B
s
.ft R
\&.

.sp
.B "Raises Not_found"
if 
.ft B
c
.ft R
does not occur in 
.ft B
s
.ft R
before position 
.ft B
i+1
.ft R
\&.

.sp

.I val rindex_from_opt 
: 
.B string -> int -> char -> int option
.sp

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

.ft B
String\&.rindex_opt s c
.ft R
is equivalent to
.ft B
String\&.rindex_from_opt s (String\&.length s \- 1) c
.ft R
\&.

.sp
.B "Since"
4.05

.sp
.B "Raises Invalid_argument"
if 
.ft B
i+1
.ft R
is not a valid position in 
.ft B
s
.ft R
\&.

.sp

.I val contains 
: 
.B string -> char -> bool
.sp

.ft B
String\&.contains s c
.ft R
tests if character 
.ft B
c
.ft R
appears in the string 
.ft B
s
.ft R
\&.

.sp

.I val contains_from 
: 
.B string -> int -> char -> bool
.sp

.ft B
String\&.contains_from s start c
.ft R
tests if character 
.ft B
c
.ft R
appears in 
.ft B
s
.ft R
after position 
.ft B
start
.ft R
\&.
.ft B
String\&.contains s c
.ft R
is equivalent to
.ft B
String\&.contains_from s 0 c
.ft R
\&.

.sp
.B "Raises Invalid_argument"
if 
.ft B
start
.ft R
is not a valid position in 
.ft B
s
.ft R
\&.

.sp

.I val rcontains_from 
: 
.B string -> int -> char -> bool
.sp

.ft B
String\&.rcontains_from s stop c
.ft R
tests if character 
.ft B
c
.ft R
appears in 
.ft B
s
.ft R
before position 
.ft B
stop+1
.ft R
\&.

.sp
.B "Raises Invalid_argument"
if 
.ft B
stop < 0
.ft R
or 
.ft B
stop+1
.ft R
is not a valid
position in 
.ft B
s
.ft R
\&.

.sp

.I val uppercase 
: 
.B string -> string
.sp
.B "Deprecated."
Functions operating on Latin\-1 character set are deprecated\&.

.sp
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\&.

.sp

.I val lowercase 
: 
.B string -> string
.sp
.B "Deprecated."
Functions operating on Latin\-1 character set are deprecated\&.

.sp
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\&.

.sp

.I val capitalize 
: 
.B string -> string
.sp
.B "Deprecated."
Functions operating on Latin\-1 character set are deprecated\&.

.sp
Return a copy of the argument, with the first character set to uppercase,
using the ISO Latin\-1 (8859\-1) character set\&.\&.

.sp

.I val uncapitalize 
: 
.B string -> string
.sp
.B "Deprecated."
Functions operating on Latin\-1 character set are deprecated\&.

.sp
Return a copy of the argument, with the first character set to lowercase,
using the ISO Latin\-1 (8859\-1) character set\&.\&.

.sp

.I val uppercase_ascii 
: 
.B string -> string
.sp
Return a copy of the argument, with all lowercase letters
translated to uppercase, using the US\-ASCII character set\&.

.sp
.B "Since"
4.03.0

.sp

.I val lowercase_ascii 
: 
.B string -> string
.sp
Return a copy of the argument, with all uppercase letters
translated to lowercase, using the US\-ASCII character set\&.

.sp
.B "Since"
4.03.0

.sp

.I val capitalize_ascii 
: 
.B string -> string
.sp
Return a copy of the argument, with the first character set to uppercase,
using the US\-ASCII character set\&.

.sp
.B "Since"
4.03.0

.sp

.I val uncapitalize_ascii 
: 
.B string -> string
.sp
Return a copy of the argument, with the first character set to lowercase,
using the US\-ASCII character set\&.

.sp
.B "Since"
4.03.0

.sp
.I type t 
= 
.B string

.sp
An alias for the type of strings\&.

.sp

.I val compare 
: 
.B t -> t -> int
.sp
The comparison function for strings, with the same specification as
.ft B
compare
.ft R
\&.  Along with the type 
.ft B
t
.ft R
, this function 
.ft B
compare
.ft R
allows the module 
.ft B
String
.ft R
to be passed as argument to the functors
.ft B
Set\&.Make
.ft R
and 
.ft B
Map\&.Make
.ft R
\&.

.sp

.I val equal 
: 
.B t -> t -> bool
.sp
The equal function for strings\&.

.sp
.B "Since"
4.03.0

.sp

.I val split_on_char 
: 
.B char -> string -> string list
.sp

.ft B
String\&.split_on_char sep s
.ft R
returns the list of all (possibly empty)
substrings of 
.ft B
s
.ft R
that are delimited by the 
.ft B
sep
.ft R
character\&.
.sp
The function\&'s output is specified by the following invariants:
.sp
.sp
\-The list is not empty\&.
.sp
\-Concatenating its elements using 
.ft B
sep
.ft R
as a separator returns a
string equal to the input (
.ft B
String\&.concat (String\&.make 1 sep)
.br
\&      (String\&.split_on_char sep s) = s
.ft R
)\&.
.sp
\-No string in the result contains the 
.ft B
sep
.ft R
character\&.


.sp
.B "Since"
4.04.0

.sp

.PP
.SS Iterators

.PP

.I val to_seq 
: 
.B t -> char Seq.t
.sp
Iterate on the string, in increasing index order\&. Modifications of the
string during iteration will be reflected in the iterator\&.

.sp
.B "Since"
4.07

.sp

.I val to_seqi 
: 
.B t -> (int * char) Seq.t
.sp
Iterate on the string, in increasing order, yielding indices along chars

.sp
.B "Since"
4.07

.sp

.I val of_seq 
: 
.B char Seq.t -> t
.sp
Create a string from the generator

.sp
.B "Since"
4.07

.sp