.TH "String" 3o source: 2019-08-06 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 
.B s
of length 
.B l
, we can access each of the 
.B l
characters of 
.B s
via its index in the sequence\&. Indexes start at
.B 0
, and we will call an index valid in 
.B s
if it falls within the
range 
.B [0\&.\&.\&.l\-1]
(inclusive)\&. A position is the point between two
characters or at the beginning or end of the string\&.  We call a
position valid in 
.B s
if it falls within the range 
.B [0\&.\&.\&.l]
(inclusive)\&. Note that the character at index 
.B n
is between
positions 
.B n
and 
.B n+1
\&.
.sp
Two parameters 
.B start
and 
.B len
are said to designate a valid
substring of 
.B s
if 
.B len >= 0
and 
.B start
and 
.B start+len
are
valid positions in 
.B s
\&.
.sp
OCaml strings used to be modifiable in place, for instance via the
.B String\&.set
and 
.B String\&.blit
functions described below\&. This
usage is deprecated and only possible when the compiler is put in
"unsafe\-string" mode by giving the 
.B \-unsafe\-string
command\-line
option (which is currently the default for reasons of backward
compatibility)\&. This is done by making the types 
.B string
and
.B bytes
(see module 
.B Bytes
) interchangeable so that functions
expecting byte sequences can also accept strings as arguments and
modify them\&.
.sp
All new code should avoid this feature and be compiled with the
.B \-safe\-string
command\-line option to enforce the separation between
the types 
.B string
and 
.B bytes
\&.

.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

.B String\&.get s n
returns the character at index 
.B n
in string 
.B s
\&.
You can also write 
.B s\&.[n]
instead of 
.B String\&.get s n
\&.
.sp
Raise 
.B Invalid_argument
if 
.B n
not a valid index in 
.B s
\&.

.sp

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


.sp

.B String\&.set s n c
modifies byte sequence 
.B s
in place,
replacing the byte at index 
.B n
with 
.B c
\&.
You can also write 
.B s\&.[n] <\- c
instead of 
.B String\&.set s n c
\&.
.sp
Raise 
.B Invalid_argument
if 
.B n
is not a valid index in 
.B s
\&.

.sp

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


.sp

.B String\&.create n
returns a fresh byte sequence of length 
.B n
\&.
The sequence is uninitialized and contains arbitrary bytes\&.
.sp
Raise 
.B Invalid_argument
if 
.B n < 0
or 
.B n > 
.B Sys\&.max_string_length
\&.

.sp

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

.B String\&.make n c
returns a fresh string of length 
.B n
,
filled with the character 
.B c
\&.
.sp
Raise 
.B Invalid_argument
if 
.B n < 0
or 
.B n > 
.B Sys\&.max_string_length
\&.

.sp

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

.B String\&.init n f
returns a string of length 
.B n
, with character
.B i
initialized to the result of 
.B f i
(called in increasing
index order)\&.
.sp
Raise 
.B Invalid_argument
if 
.B n < 0
or 
.B n > 
.B Sys\&.max_string_length
\&.

.sp
.B "Since"
4.02.0

.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

.B String\&.sub s start len
returns a fresh string of length 
.B len
,
containing the substring of 
.B s
that starts at position 
.B start
and
has length 
.B len
\&.
.sp
Raise 
.B Invalid_argument
if 
.B start
and 
.B len
do not
designate a valid substring of 
.B s
\&.

.sp

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


.sp

.B String\&.fill s start len c
modifies byte sequence 
.B s
in place,
replacing 
.B len
bytes with 
.B c
, starting at 
.B start
\&.
.sp
Raise 
.B Invalid_argument
if 
.B start
and 
.B len
do not
designate a valid range of 
.B s
\&.

.sp

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

.sp

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

.B String\&.concat sep sl
concatenates the list of strings 
.B sl
,
inserting the separator string 
.B sep
between each\&.
.sp
Raise 
.B Invalid_argument
if the result is longer than
.B Sys\&.max_string_length
bytes\&.

.sp

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

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

.sp

.I val iteri 
: 
.B (int -> char -> unit) -> string -> unit
.sp
Same as 
.B String\&.iter
, 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

.B String\&.map f s
applies function 
.B f
in turn to all the
characters of 
.B s
(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

.B String\&.mapi f s
calls 
.B f
with each character of 
.B s
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: 
.B \&' \&'
,
.B \&'\(rs012\&'
, 
.B \&'\(rsn\&'
, 
.B \&'\(rsr\&'
, and 
.B \&'\(rst\&'
\&.  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
Raise 
.B Invalid_argument
if the result is longer than
.B Sys\&.max_string_length
bytes\&.
.sp
The function 
.B Scanf\&.unescaped
is a left inverse of 
.B escaped
,
i\&.e\&. 
.B Scanf\&.unescaped (escaped s) = s
for any string 
.B s
(unless
.B escape s
fails)\&.

.sp

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

.B String\&.index s c
returns the index of the first
occurrence of character 
.B c
in string 
.B s
\&.
.sp
Raise 
.B Not_found
if 
.B c
does not occur in 
.B s
\&.

.sp

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

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

.sp
.B "Since"
4.05

.sp

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

.B String\&.rindex s c
returns the index of the last
occurrence of character 
.B c
in string 
.B s
\&.
.sp
Raise 
.B Not_found
if 
.B c
does not occur in 
.B s
\&.

.sp

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

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

.sp
.B "Since"
4.05

.sp

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

.B String\&.index_from s i c
returns the index of the
first occurrence of character 
.B c
in string 
.B s
after position 
.B i
\&.
.B String\&.index s c
is equivalent to 
.B String\&.index_from s 0 c
\&.
.sp
Raise 
.B Invalid_argument
if 
.B i
is not a valid position in 
.B s
\&.
Raise 
.B Not_found
if 
.B c
does not occur in 
.B s
after position 
.B i
\&.

.sp

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

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

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

.sp
.B "Since"
4.05

.sp

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

.B String\&.rindex_from s i c
returns the index of the
last occurrence of character 
.B c
in string 
.B s
before position 
.B i+1
\&.
.B String\&.rindex s c
is equivalent to
.B String\&.rindex_from s (String\&.length s \- 1) c
\&.
.sp
Raise 
.B Invalid_argument
if 
.B i+1
is not a valid position in 
.B s
\&.
Raise 
.B Not_found
if 
.B c
does not occur in 
.B s
before position 
.B i+1
\&.

.sp

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

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

.B String\&.rindex_opt s c
is equivalent to
.B String\&.rindex_from_opt s (String\&.length s \- 1) c
\&.
.sp
Raise 
.B Invalid_argument
if 
.B i+1
is not a valid position in 
.B s
\&.

.sp
.B "Since"
4.05

.sp

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

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

.sp

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

.B String\&.contains_from s start c
tests if character 
.B c
appears in 
.B s
after position 
.B start
\&.
.B String\&.contains s c
is equivalent to
.B String\&.contains_from s 0 c
\&.
.sp
Raise 
.B Invalid_argument
if 
.B start
is not a valid position in 
.B s
\&.

.sp

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

.B String\&.rcontains_from s stop c
tests if character 
.B c
appears in 
.B s
before position 
.B stop+1
\&.
.sp
Raise 
.B Invalid_argument
if 
.B stop < 0
or 
.B stop+1
is not a valid
position in 
.B s
\&.

.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
.B Pervasives\&.compare
\&.  Along with the type 
.B t
, this function 
.B compare
allows the module 
.B String
to be passed as argument to the functors
.B Set\&.Make
and 
.B Map\&.Make
\&.

.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

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


.sp
.B "Since"
4.04.0

.sp