diff --git a/stdlib/string.mli b/stdlib/string.mli index c8064e378..f0ec1ebd9 100644 --- a/stdlib/string.mli +++ b/stdlib/string.mli @@ -21,37 +21,58 @@ stringLabels.mli instead. *) -(** String operations. +(** Strings. - 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. + A string [s] of length [n] is an indexable and immutable sequence + of [n] bytes. For historical reasons these bytes are referred to + as characters. - Given a string [s] of length [l], we can access each of the [l] - characters of [s] via its index in the sequence. Indexes start at - [0], and we will call an index valid in [s] if it falls within the - range [[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 [s] if it falls within the range [[0...l]] - (inclusive). Note that the character at index [n] is between - positions [n] and [n+1]. + The semantics of string functions is defined in terms of + indices and positions. These are depicted and described + as follows. - Two parameters [start] and [len] are said to designate a valid - substring of [s] if [len >= 0] and [start] and [start+len] are - valid positions in [s]. +{v +positions 0 1 2 3 4 n-1 n + +---+---+---+---+ +-----+ + indices | 0 | 1 | 2 | 3 | ... | n-1 | + +---+---+---+---+ +-----+ +v} + {ul + {- An {e index} [i] of [s] is an integer in the range \[[0];[n-1]\]. + It represents the [i]th byte (character) of [s] which can be + acccessed using the constant time string indexing operator + [s.[i]].} + {- A {e position} [i] of [s] is an integer in the range + \[[0];[n]\]. It represents either the point at the beginning of + the string, or the point between two indices, or the point at + the end of the string. The [i]th byte index is between position + [i] and [i+1].}} - Note: OCaml strings used to be modifiable in place, for instance via - the {!set} and {!blit} functions described below. This - usage is only possible when the compiler is put in "unsafe-string" - mode by giving the [-unsafe-string] command-line option. This - compatibility mode makes the types [string] and [bytes] (see module - {!Bytes}) interchangeable so that functions expecting byte sequences - can also accept strings as arguments and modify them. + Two integers [start] and [len] are said to define a {e valid + substring} of [s] if [len >= 0] and [start], [start+len] are + positions of [s]. + + {b Unicode text.} Strings being arbitrary sequences of bytes, they + can hold any kind of textual encoding. However the recommended + encoding for storing Unicode text in OCaml strings is UTF-8. This + is the encoding used by Unicode escapes in string literals. For + example the string ["\u{1F42B}"] is the UTF-8 encoding of the + Unicode character U+1F42B. + + {b Past mutability.} OCaml strings used to be modifiable in place, + for instance via the {!String.set} and {!String.blit} + functions. This use is nowadays only possible when the compiler is + put in "unsafe-string" mode by giving the [-unsafe-string] + command-line option. This compatibility mode makes the types + [string] and [bytes] (see {!Bytes.t}) interchangeable so that + functions expecting byte sequences can also accept strings as + arguments and modify them. + + The distinction between [bytes] and [string] 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. - The distinction between [bytes] and [string] 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. The labeled version of this module, {!StringLabels}, is intended to be used through {!StdLabels} which replaces {!Array}, {!Bytes}, {!List} and @@ -64,46 +85,273 @@ let to_upper = String.map ~f:Char.uppercase_ascii ]} *) +(** {1:strings Strings} *) + +type t = string +(** The type for strings. *) + +val make : int -> char -> string +(** [make n c] is a string of length [n] with each index holding the + character [c]. + + @raise Invalid_argument if [n < 0] or [n > ]{!Sys.max_string_length}. *) + +val init : int -> (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). + + @raise Invalid_argument if [n < 0] or [n > ]{!Sys.max_string_length}. + @since 4.02.0 *) + external length : string -> int = "%string_length" -(** Return the length (number of characters) of the given string. *) +(** [length s] is the length (number of bytes/characters) of [s]. *) external get : string -> int -> char = "%string_safe_get" -(** [get s n] returns the character at index [n] in string [s]. - You can also write [s.[n]] instead of [get s n]. - @raise Invalid_argument if [n] not a valid index in [s]. *) +(** [get s i] is the character at index [i] in [s]. This is the same + as writing [s.[i]]. -external set : bytes -> int -> char -> unit = "%string_safe_set" - [@@ocaml.deprecated "Use Bytes.set/BytesLabels.set instead."] -(** [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]. - @raise Invalid_argument if [n] is not a valid index in [s]. + @raise Invalid_argument if [i] not an index of [s]. *) - @deprecated This is a deprecated alias of - {!Bytes.set}/{!BytesLabels.set}. *) +(** {1:concat Concatenating} + + {b Note.} The {!Stdlib.( ^ )} binary operator concatenates two + strings. *) + +val concat : string -> string list -> string +(** [concat sep ss] concatenates the list of strings [ss], inserting + the separator string [sep] between each. + + @raise Invalid_argument if the result is longer than + {!Sys.max_string_length} bytes. *) + +(** {1:predicates Predicates and comparisons} *) + +val equal : t -> t -> bool +(** [equal s0 s1] is [true] iff [s0] and [s1] are character-wise equal. + @since 4.03.0 (4.05.0 in StringLabels) *) + +val compare : t -> t -> int +(** [compare s0 s1] sorts [s0] and [s1] in lexicographical order. [compare] + behaves like {!Stdlib.compare} on strings but may be more efficient. *) + +val starts_with : + prefix (* comment thwarts tools/sync_stdlib_docs *) :string -> string -> bool +(** [starts_with ][~][prefix s] is [true] iff [s] starts with [prefix]. + + @since 4.12.0 *) + +val ends_with : + suffix (* comment thwarts tools/sync_stdlib_docs *) :string -> string -> bool +(** [ends_with suffix s] is [true] iff [s] ends with [suffix]. + + @since 4.12.0 *) + +val contains_from : string -> int -> char -> bool +(** [contains_from s start c] is [true] iff [c] appears in [s] after position + [start]. + + @raise 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] iff [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 contains : string -> char -> bool +(** [contains s c] is {!String.contains_from}[ s 0 c]. *) + +(** {1:extract Extracting substrings} *) + +val sub : string -> int -> 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]. + + @raise Invalid_argument if [pos] and [len] do not designate a valid + substring of [s]. *) + +val split_on_char : 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: + {ul + {- 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.04.0 (4.05.0 in StringLabels) *) + +(** {1:transforming Transforming} *) + +val map : (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 : (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 + [escape s] fails). + + @raise 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.03.0 (4.05.0 in StringLabels) *) + +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.03.0 (4.05.0 in StringLabels) *) + +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.03.0 (4.05.0 in StringLabels) *) + +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.03.0 (4.05.0 in StringLabels) *) + +(** {1:traversing Traversing} *) + +val iter : (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 : (int -> char -> unit) -> string -> unit +(** [iteri] is like {!iter}, but the function is also given the + corresponding character index. + + @since 4.00.0 *) + +(** {1:searching Searching} *) + +val index_from : string -> int -> char -> int +(** [index_from s i c] is the index of the first occurrence of [c] in + [s] after position [i]. + + @raise Not_found if [c] does not occur in [s] after position [i]. + @raise Invalid_argument if [i] is not a valid position in [s]. *) + + +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). + + @raise Invalid_argument if [i] is not a valid position in [s]. + @since 4.05 *) + +val rindex_from : string -> int -> char -> int +(** [rindex_from s i c] is the index of the last occurrence of [c] in + [s] before position [i+1]. + + @raise Not_found if [c] does not occur in [s] before position [i+1]. + @raise Invalid_argument if [i+1] is not a valid position in [s]. *) + +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). + + @raise Invalid_argument if [i+1] is not a valid position in [s]. + @since 4.05 *) + +val index : string -> char -> int +(** [index s c] is {!String.index_from}[ s 0 c]. *) + +val index_opt : string -> char -> int option +(** [index_opt s c] is {!String.index_from_opt}[ s 0 c]. + + @since 4.05 *) + +val rindex : string -> char -> int +(** [rindex s c] is {!String.rindex_from}[ s (length s - 1) c]. *) + +val rindex_opt : string -> char -> int option +(** [rindex_opt s c] is {!String.rindex_from_opt}[ s (length s - 1) c]. + + @since 4.05 *) + +(** {1:converting 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 *) + +(** {1:deprecated Deprecated functions} *) external create : int -> bytes = "caml_create_string" [@@ocaml.deprecated "Use Bytes.create/BytesLabels.create instead."] (** [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}. - - @deprecated This is a deprecated alias of - {!Bytes.create}/{!BytesLabels.create}. *) - -val make : int -> char -> 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 init : int -> (int -> char) -> string -(** [init n f] returns a string of length [n], with character - [i] initialized to the result of [f i] (called in increasing - index order). - + The sequence is uninitialized and contains arbitrary bytes. @raise Invalid_argument if [n < 0] or [n > ]{!Sys.max_string_length}. - @since 4.02.0 -*) + + @deprecated This is a deprecated alias of + {!Bytes.create}/{!BytesLabels.create}. *) + +external set : bytes -> int -> char -> unit = "%string_safe_set" + [@@ocaml.deprecated "Use Bytes.set/BytesLabels.set instead."] +(** [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]. + @raise Invalid_argument if [n] is not a valid index in [s]. + + @deprecated This is a deprecated alias of + {!Bytes.set}/{!BytesLabels.set}. *) + +val blit : + string -> int -> bytes -> int -> 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]. + + @raise 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 [@@ocaml.deprecated "Strings now immutable: no need to copy"] @@ -112,266 +360,49 @@ val copy : string -> string @deprecated Because strings are immutable, it doesn't make much sense to make identical copies of them. *) -val sub : string -> int -> int -> string -(** [sub s pos len] returns a fresh string of length [len], - containing the substring of [s] that starts at position [pos] and - has length [len]. - @raise Invalid_argument if [pos] and [len] do not - designate a valid substring of [s]. *) - val fill : bytes -> int -> int -> char -> unit [@@ocaml.deprecated "Use Bytes.fill/BytesLabels.fill instead."] (** [fill s pos len c] modifies byte sequence [s] in place, - replacing [len] bytes by [c], starting at [pos]. - @raise Invalid_argument if [pos] and [len] do not - designate a valid substring of [s]. + replacing [len] bytes by [c], starting at [pos]. + @raise 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 blit : - string -> int -> bytes -> int -> 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]. - @raise 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 concat : string -> string list -> 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 iter : (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 : (int -> char -> unit) -> string -> unit -(** Same as {!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. - @since 4.00.0 *) - -val map : (char -> char) -> string -> string -(** [map f s] applies function [f] in turn to all - the characters of [s] (in increasing index order) - and stores the results in a new string that is returned. - @since 4.00.0 *) - -val mapi : (int -> char -> char) -> string -> string -(** [mapi f s] calls [f] with each character of [s] and its - index (in increasing index order) and stores the results in a new - string that is returned. - @since 4.02.0 *) - -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 -(** [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 -(** [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 -(** [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 -(** [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 -(** [index_from s i c] returns the index of the - first occurrence of character [c] in string [s] after position [i]. - [index s c] is equivalent to [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 -(** [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]. - - [index_opt s c] is equivalent to [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 -(** [rindex_from s i c] returns the index of the - last occurrence of character [c] in string [s] before position [i+1]. - [rindex s c] is equivalent to - [rindex_from s (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 -(** [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]. - - [rindex_opt s c] is equivalent to - [rindex_from_opt s (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 -(** [contains s c] tests if character [c] - appears in the string [s]. *) - -val contains_from : string -> int -> char -> bool -(** [contains_from s start c] tests if character [c] - appears in [s] after position [start]. - [contains s c] is equivalent to - [contains_from s 0 c]. - @raise Invalid_argument if [start] is not a valid position in [s]. *) - -val rcontains_from : string -> int -> char -> bool -(** [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]. *) + @deprecated This is a deprecated alias of + {!Bytes.fill}/{!BytesLabels.fill}. *) val uppercase : string -> string [@@ocaml.deprecated "Use String.uppercase_ascii/StringLabels.uppercase_ascii instead."] (** 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. *) + 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 [@@ocaml.deprecated "Use String.lowercase_ascii/StringLabels.lowercase_ascii instead."] (** 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. *) + 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 [@@ocaml.deprecated "Use String.capitalize_ascii/StringLabels.capitalize_ascii instead."] (** 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. *) + using the ISO Latin-1 (8859-1) character set.. + + @deprecated Functions operating on Latin-1 character set are deprecated. *) val uncapitalize : string -> string [@@ocaml.deprecated "Use String.uncapitalize_ascii/StringLabels.uncapitalize_ascii instead."] (** 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. *) + using the ISO Latin-1 (8859-1) character set. -val uppercase_ascii : string -> string -(** Return a copy of the argument, with all lowercase letters - translated to uppercase, using the US-ASCII character set. - @since 4.03.0 (4.05.0 in StringLabels) *) - -val lowercase_ascii : string -> string -(** Return a copy of the argument, with all uppercase letters - translated to lowercase, using the US-ASCII character set. - @since 4.03.0 (4.05.0 in StringLabels) *) - -val capitalize_ascii : string -> string -(** Return a copy of the argument, with the first character set to uppercase, - using the US-ASCII character set. - @since 4.03.0 (4.05.0 in StringLabels) *) - -val uncapitalize_ascii : string -> string -(** Return a copy of the argument, with the first character set to lowercase, - using the US-ASCII character set. - @since 4.03.0 (4.05.0 in StringLabels) *) - -val starts_with : - prefix (* comment thwarts tools/sync_stdlib_docs *) :string -> string -> bool -(** [starts_with ][~][prefix s] tests if [s] starts with [prefix] - @since 4.12.0 *) - -val ends_with : - suffix (* comment thwarts tools/sync_stdlib_docs *) :string -> string -> bool -(** [ends_with suffix s] tests if [s] ends with [suffix] - @since 4.12.0 *) - -val split_on_char: char -> string -> string list -(** [split_on_char sep s] returns the list of all (possibly empty) - substrings of [s] that are delimited by the [sep] character. - - The function's output 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.04.0 (4.05.0 in StringLabels) -*) - -type t = string -(** An alias for the type of strings. *) - -val compare: t -> t -> int -(** The comparison function for strings, with the same specification as - {!Stdlib.compare}. Along with the type [t], this function [compare] - allows the module [String] to be passed as argument to the functors - {!Set.Make} and {!Map.Make}. *) - -val equal: t -> t -> bool -(** The equal function for strings. - @since 4.03.0 (4.05.0 in StringLabels) *) - - -(** {1 Iterators} *) - -val to_seq : t -> char Seq.t -(** Iterate on the string, in increasing index order. Modifications of the - string during iteration will be reflected in the iterator. - @since 4.07 *) - -val to_seqi : t -> (int * char) Seq.t -(** Iterate on the string, in increasing order, yielding indices along chars - @since 4.07 *) - -val of_seq : char Seq.t -> t -(** Create a string from the generator - @since 4.07 *) + @deprecated Functions operating on Latin-1 character set are deprecated. *) (**/**) diff --git a/stdlib/stringLabels.mli b/stdlib/stringLabels.mli index f1fe1ff0d..959f91f53 100644 --- a/stdlib/stringLabels.mli +++ b/stdlib/stringLabels.mli @@ -21,37 +21,58 @@ stringLabels.mli instead. *) -(** String operations. +(** Strings. - 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. + A string [s] of length [n] is an indexable and immutable sequence + of [n] bytes. For historical reasons these bytes are referred to + as characters. - Given a string [s] of length [l], we can access each of the [l] - characters of [s] via its index in the sequence. Indexes start at - [0], and we will call an index valid in [s] if it falls within the - range [[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 [s] if it falls within the range [[0...l]] - (inclusive). Note that the character at index [n] is between - positions [n] and [n+1]. + The semantics of string functions is defined in terms of + indices and positions. These are depicted and described + as follows. - Two parameters [start] and [len] are said to designate a valid - substring of [s] if [len >= 0] and [start] and [start+len] are - valid positions in [s]. +{v +positions 0 1 2 3 4 n-1 n + +---+---+---+---+ +-----+ + indices | 0 | 1 | 2 | 3 | ... | n-1 | + +---+---+---+---+ +-----+ +v} + {ul + {- An {e index} [i] of [s] is an integer in the range \[[0];[n-1]\]. + It represents the [i]th byte (character) of [s] which can be + acccessed using the constant time string indexing operator + [s.[i]].} + {- A {e position} [i] of [s] is an integer in the range + \[[0];[n]\]. It represents either the point at the beginning of + the string, or the point between two indices, or the point at + the end of the string. The [i]th byte index is between position + [i] and [i+1].}} - Note: OCaml strings used to be modifiable in place, for instance via - the {!set} and {!blit} functions described below. This - usage is only possible when the compiler is put in "unsafe-string" - mode by giving the [-unsafe-string] command-line option. This - compatibility mode makes the types [string] and [bytes] (see module - {!Bytes}) interchangeable so that functions expecting byte sequences - can also accept strings as arguments and modify them. + Two integers [start] and [len] are said to define a {e valid + substring} of [s] if [len >= 0] and [start], [start+len] are + positions of [s]. + + {b Unicode text.} Strings being arbitrary sequences of bytes, they + can hold any kind of textual encoding. However the recommended + encoding for storing Unicode text in OCaml strings is UTF-8. This + is the encoding used by Unicode escapes in string literals. For + example the string ["\u{1F42B}"] is the UTF-8 encoding of the + Unicode character U+1F42B. + + {b Past mutability.} OCaml strings used to be modifiable in place, + for instance via the {!String.set} and {!String.blit} + functions. This use is nowadays only possible when the compiler is + put in "unsafe-string" mode by giving the [-unsafe-string] + command-line option. This compatibility mode makes the types + [string] and [bytes] (see {!Bytes.t}) interchangeable so that + functions expecting byte sequences can also accept strings as + arguments and modify them. + + The distinction between [bytes] and [string] 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. - The distinction between [bytes] and [string] 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. The labeled version of this module, {!StringLabels}, is intended to be used through {!StdLabels} which replaces {!Array}, {!Bytes}, {!List} and @@ -64,46 +85,273 @@ let to_upper = String.map ~f:Char.uppercase_ascii ]} *) +(** {1:strings Strings} *) + +type t = string +(** The type for strings. *) + +val make : int -> char -> string +(** [make n c] is a string of length [n] with each index holding the + character [c]. + + @raise 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). + + @raise Invalid_argument if [n < 0] or [n > ]{!Sys.max_string_length}. + @since 4.02.0 *) + external length : string -> int = "%string_length" -(** Return the length (number of characters) of the given string. *) +(** [length s] is the length (number of bytes/characters) of [s]. *) external get : string -> int -> char = "%string_safe_get" -(** [get s n] returns the character at index [n] in string [s]. - You can also write [s.[n]] instead of [get s n]. - @raise Invalid_argument if [n] not a valid index in [s]. *) +(** [get s i] is the character at index [i] in [s]. This is the same + as writing [s.[i]]. -external set : bytes -> int -> char -> unit = "%string_safe_set" - [@@ocaml.deprecated "Use Bytes.set/BytesLabels.set instead."] -(** [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]. - @raise Invalid_argument if [n] is not a valid index in [s]. + @raise Invalid_argument if [i] not an index of [s]. *) - @deprecated This is a deprecated alias of - {!Bytes.set}/{!BytesLabels.set}. *) +(** {1:concat Concatenating} + + {b 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. + + @raise Invalid_argument if the result is longer than + {!Sys.max_string_length} bytes. *) + +(** {1:predicates Predicates and comparisons} *) + +val equal : t -> t -> bool +(** [equal s0 s1] is [true] iff [s0] and [s1] are character-wise equal. + @since 4.03.0 (4.05.0 in StringLabels) *) + +val compare : t -> t -> int +(** [compare s0 s1] sorts [s0] and [s1] in lexicographical order. [compare] + behaves like {!Stdlib.compare} on strings but may be more efficient. *) + +val starts_with : + prefix (* comment thwarts tools/sync_stdlib_docs *) :string -> string -> bool +(** [starts_with ][~][prefix s] is [true] iff [s] starts with [prefix]. + + @since 4.12.0 *) + +val ends_with : + suffix (* comment thwarts tools/sync_stdlib_docs *) :string -> string -> bool +(** [ends_with ~suffix s] is [true] iff [s] ends with [suffix]. + + @since 4.12.0 *) + +val contains_from : string -> int -> char -> bool +(** [contains_from s start c] is [true] iff [c] appears in [s] after position + [start]. + + @raise 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] iff [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 contains : string -> char -> bool +(** [contains s c] is {!String.contains_from}[ s 0 c]. *) + +(** {1:extract 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]. + + @raise 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: + {ul + {- 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.04.0 (4.05.0 in StringLabels) *) + +(** {1:transforming 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 + [escape s] fails). + + @raise 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.03.0 (4.05.0 in StringLabels) *) + +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.03.0 (4.05.0 in StringLabels) *) + +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.03.0 (4.05.0 in StringLabels) *) + +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.03.0 (4.05.0 in StringLabels) *) + +(** {1:traversing 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 *) + +(** {1:searching Searching} *) + +val index_from : string -> int -> char -> int +(** [index_from s i c] is the index of the first occurrence of [c] in + [s] after position [i]. + + @raise Not_found if [c] does not occur in [s] after position [i]. + @raise Invalid_argument if [i] is not a valid position in [s]. *) + + +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). + + @raise Invalid_argument if [i] is not a valid position in [s]. + @since 4.05 *) + +val rindex_from : string -> int -> char -> int +(** [rindex_from s i c] is the index of the last occurrence of [c] in + [s] before position [i+1]. + + @raise Not_found if [c] does not occur in [s] before position [i+1]. + @raise Invalid_argument if [i+1] is not a valid position in [s]. *) + +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). + + @raise Invalid_argument if [i+1] is not a valid position in [s]. + @since 4.05 *) + +val index : string -> char -> int +(** [index s c] is {!String.index_from}[ s 0 c]. *) + +val index_opt : string -> char -> int option +(** [index_opt s c] is {!String.index_from_opt}[ s 0 c]. + + @since 4.05 *) + +val rindex : string -> char -> int +(** [rindex s c] is {!String.rindex_from}[ s (length s - 1) c]. *) + +val rindex_opt : string -> char -> int option +(** [rindex_opt s c] is {!String.rindex_from_opt}[ s (length s - 1) c]. + + @since 4.05 *) + +(** {1:converting 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 *) + +(** {1:deprecated Deprecated functions} *) external create : int -> bytes = "caml_create_string" [@@ocaml.deprecated "Use Bytes.create/BytesLabels.create instead."] (** [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}. - - @deprecated This is a deprecated alias of - {!Bytes.create}/{!BytesLabels.create}. *) - -val make : int -> char -> 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 init : int -> f:(int -> char) -> string -(** [init n ~f] returns a string of length [n], with character - [i] initialized to the result of [f i] (called in increasing - index order). - + The sequence is uninitialized and contains arbitrary bytes. @raise Invalid_argument if [n < 0] or [n > ]{!Sys.max_string_length}. - @since 4.02.0 -*) + + @deprecated This is a deprecated alias of + {!Bytes.create}/{!BytesLabels.create}. *) + +external set : bytes -> int -> char -> unit = "%string_safe_set" + [@@ocaml.deprecated "Use Bytes.set/BytesLabels.set instead."] +(** [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]. + @raise 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]. + + @raise 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 [@@ocaml.deprecated "Strings now immutable: no need to copy"] @@ -112,266 +360,49 @@ val copy : string -> string @deprecated Because strings are immutable, it doesn't make much sense to make identical copies of them. *) -val sub : string -> pos:int -> len:int -> string -(** [sub s ~pos ~len] returns a fresh string of length [len], - containing the substring of [s] that starts at position [pos] and - has length [len]. - @raise Invalid_argument if [pos] and [len] do not - designate a valid substring of [s]. *) - val fill : bytes -> pos:int -> len:int -> char -> unit [@@ocaml.deprecated "Use Bytes.fill/BytesLabels.fill instead."] (** [fill s ~pos ~len c] modifies byte sequence [s] in place, - replacing [len] bytes by [c], starting at [pos]. - @raise Invalid_argument if [pos] and [len] do not - designate a valid substring of [s]. + replacing [len] bytes by [c], starting at [pos]. + @raise 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 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]. - @raise 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 concat : sep:string -> string list -> 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 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 -(** Same as {!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. - @since 4.00.0 *) - -val map : f:(char -> char) -> string -> string -(** [map ~f s] applies function [f] in turn to all - the characters of [s] (in increasing index order) - and stores the results in a new string that is returned. - @since 4.00.0 *) - -val mapi : f:(int -> char -> char) -> string -> string -(** [mapi ~f s] calls [f] with each character of [s] and its - index (in increasing index order) and stores the results in a new - string that is returned. - @since 4.02.0 *) - -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 -(** [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 -(** [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 -(** [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 -(** [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 -(** [index_from s i c] returns the index of the - first occurrence of character [c] in string [s] after position [i]. - [index s c] is equivalent to [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 -(** [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]. - - [index_opt s c] is equivalent to [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 -(** [rindex_from s i c] returns the index of the - last occurrence of character [c] in string [s] before position [i+1]. - [rindex s c] is equivalent to - [rindex_from s (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 -(** [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]. - - [rindex_opt s c] is equivalent to - [rindex_from_opt s (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 -(** [contains s c] tests if character [c] - appears in the string [s]. *) - -val contains_from : string -> int -> char -> bool -(** [contains_from s start c] tests if character [c] - appears in [s] after position [start]. - [contains s c] is equivalent to - [contains_from s 0 c]. - @raise Invalid_argument if [start] is not a valid position in [s]. *) - -val rcontains_from : string -> int -> char -> bool -(** [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]. *) + @deprecated This is a deprecated alias of + {!Bytes.fill}/{!BytesLabels.fill}. *) val uppercase : string -> string [@@ocaml.deprecated "Use String.uppercase_ascii/StringLabels.uppercase_ascii instead."] (** 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. *) + 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 [@@ocaml.deprecated "Use String.lowercase_ascii/StringLabels.lowercase_ascii instead."] (** 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. *) + 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 [@@ocaml.deprecated "Use String.capitalize_ascii/StringLabels.capitalize_ascii instead."] (** 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. *) + using the ISO Latin-1 (8859-1) character set.. + + @deprecated Functions operating on Latin-1 character set are deprecated. *) val uncapitalize : string -> string [@@ocaml.deprecated "Use String.uncapitalize_ascii/StringLabels.uncapitalize_ascii instead."] (** 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. *) + using the ISO Latin-1 (8859-1) character set. -val uppercase_ascii : string -> string -(** Return a copy of the argument, with all lowercase letters - translated to uppercase, using the US-ASCII character set. - @since 4.03.0 (4.05.0 in StringLabels) *) - -val lowercase_ascii : string -> string -(** Return a copy of the argument, with all uppercase letters - translated to lowercase, using the US-ASCII character set. - @since 4.03.0 (4.05.0 in StringLabels) *) - -val capitalize_ascii : string -> string -(** Return a copy of the argument, with the first character set to uppercase, - using the US-ASCII character set. - @since 4.03.0 (4.05.0 in StringLabels) *) - -val uncapitalize_ascii : string -> string -(** Return a copy of the argument, with the first character set to lowercase, - using the US-ASCII character set. - @since 4.03.0 (4.05.0 in StringLabels) *) - -val starts_with : - prefix (* comment thwarts tools/sync_stdlib_docs *) :string -> string -> bool -(** [starts_with ][~][prefix s] tests if [s] starts with [prefix] - @since 4.12.0 *) - -val ends_with : - suffix (* comment thwarts tools/sync_stdlib_docs *) :string -> string -> bool -(** [ends_with ~suffix s] tests if [s] ends with [suffix] - @since 4.12.0 *) - -val split_on_char: sep:char -> string -> string list -(** [split_on_char ~sep s] returns the list of all (possibly empty) - substrings of [s] that are delimited by the [sep] character. - - The function's output 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.04.0 (4.05.0 in StringLabels) -*) - -type t = string -(** An alias for the type of strings. *) - -val compare: t -> t -> int -(** The comparison function for strings, with the same specification as - {!Stdlib.compare}. Along with the type [t], this function [compare] - allows the module [String] to be passed as argument to the functors - {!Set.Make} and {!Map.Make}. *) - -val equal: t -> t -> bool -(** The equal function for strings. - @since 4.03.0 (4.05.0 in StringLabels) *) - - -(** {1 Iterators} *) - -val to_seq : t -> char Seq.t -(** Iterate on the string, in increasing index order. Modifications of the - string during iteration will be reflected in the iterator. - @since 4.07 *) - -val to_seqi : t -> (int * char) Seq.t -(** Iterate on the string, in increasing order, yielding indices along chars - @since 4.07 *) - -val of_seq : char Seq.t -> t -(** Create a string from the generator - @since 4.07 *) + @deprecated Functions operating on Latin-1 character set are deprecated. *) (**/**)