Previous  Up  Next

Module type Api.BASIC_STRING

module type BASIC_STRING = sig .. end
The minimal API implemented by string modules.
type character
A string is composed of characters.
type t
The type of the string.
val max_string_length : int option
If the representation of strings is bounded (by a constant other than the process memory), the maximum length of a string is assumed to be this number of characters.
val empty : t
A string of zero length.
val is_empty : t -> bool
Test whether a string is empty.
val make : int -> character -> t
make size char builds a new string of the passed length where the character at every position is char, like String.make.

The behavior of make size is undefined when size is < 0 or > {max_string_length} (if it is Some _). Depending on the backend implementing the API, the function may raise an exception.

val length : t -> int
Get the length of the string (i.e. the number of characters).
val of_character : character -> t
Make a string with one character.
val of_character_list : character list -> t
Make a string out of a list of characters. This function may also raise an exception when the required length is larger than Api.BASIC_STRING.max_string_length (depends on the backend implementation).
val to_character_list : t -> character list
Explode a string into a list of characters.
val get : t -> index:int -> character option
Get the n-th char, indexes are not necessarily bytes, they can be bits. get returns None when index is out of bounds.
val set : t ->
       index:int -> v:character -> t option
set str ~index ~v creates a new string equal to t with character v at position index. set returns None when index is out of bounds.
val get_exn : t -> index:int -> character
Like get but fail with an exception.
Raises Invalid_argument when index is not in [0,length)
val set_exn : t ->
       index:int -> v:character -> t
Like set but fail with an exception.
Raises Invalid_argument when index is not in [0,length)
val concat : ?sep:t -> t list -> t
The classical concat function.

The function is subject to same limitations as Api.BASIC_STRING.of_character_list regarding Api.BASIC_STRING.max_string_length.

include Api.NATIVE_CONVERSIONS
By including NATIVE_CONVERSIONS, a basic string provides of_native_string, of_native_substring, and to_native_string.
val to_string_hum : t -> string
Convert the string to a human-readable native string (à la sprintf "%S").

Returning an OCaml native string, the function may raise an exception when the resulting string exceeds Sys.max_string_length.

val fold : t ->
       init:'a -> f:('a -> character -> 'a) -> 'a
The standard fold function, see List.fold_left for example.
val foldi : t ->
       init:'a -> f:(int -> 'a -> character -> 'a) -> 'a
Pass an accumulator over the string's characters and their ordinals, starting with the first; left most.
val fold2_exn : t ->
       t ->
       init:'a ->
       f:('a -> character -> character -> 'a) ->
       'a
The standard fold2 function, see List.fold_left2 for example. Fails on ts of different length.
val compare : t -> t -> int
Comparison function (as expected by most common functors in the ecosystem).
val sub : t -> index:int -> length:int -> t option
Get the sub-string of size length at position index. If length is 0, sub returns Some empty regardless of the other parameters.
val sub_exn : t -> index:int -> length:int -> t
Like sub but throw an exception instead of returning None.
Raises Invalid_argument when index and length do not represent a valid substring.
val slice : ?start:int -> ?finish:int -> t -> t option
Create a sub-string from start to just before finish if all of the indices are in bounds.
start : defaults to 0, must be within [0,length)
finish : default to length, must be within [0,length)
val slice_exn : ?start:int -> ?finish:int -> t -> t
Like slice but throw an exception instead of returning None if the indices are out of bounds.
Raises Invalid_argument when start or finish are not in their respective bounds. See slice.
val is_prefix : t -> prefix:t -> bool
Does t start with prefix?
val is_suffix : t -> suffix:t -> bool
Does t end with suffix?
val chop_prefix_exn : t -> prefix:t -> t
Return a copy of t with prefix removed from the beginning.
Raises Invalid_argument if t does not start with prefix.
val chop_prefix : t -> prefix:t -> t option
Like chop_prefix_exn but return None instead of throwing an Invalid_argument.
val chop_suffix_exn : t -> suffix:t -> t
Return a copy of t with suffix removed from the end.
Raises Invalid_argument if t does not end with suffix.
val chop_suffix : t -> suffix:t -> t option
Like chop_suffix_exn but return None instead of throwing an exception.
val split_at : t -> index:int -> t * t
Return a tuple where the first string is a prefix of the specified length and the second is the rest.

If index is =< 0 then the first element is empty and the string is returned in the second element, similarly if the index is >= length t then the first element is t and the second is empty.

val take : t -> index:int -> t
Just the first part of split_at.
val drop : t -> index:int -> t
Just the second part of split_at.
val compare_substring : t * int * int -> t * int * int -> int
Comparison function for substrings: use as compare_substring (s1, index1, length1) (s2, index2, length2).

Note that out-of-bounds accesses will not be reported: for performance reasons, if the result can be decided with the smallest sub-string then compare_substring won't look further.

However, if compare_substring_strict returns Some c then compare_substring must return d such as c = d or c × d > 0 (i.e. strictly same sign).

In other words, if sub a ~index:ia ~length:la returns Some suba and sub b ~index:ib ~length:lb returns Some subb, then compare_substring (a, ia, la) (b, ib, lb) will behave like compare suba subb (again, with the same sign).

val compare_substring_strict : t * int * int ->
       t * int * int -> int option
Like compare_substring but return Some _ only when it is well defined (same validity criteria as sub: if length is 0, index is irrelevant).

Depending on the backend implementation, this function might be significantly slower than compare_substring (for example when calls to length are not O(1)).

val iter : t -> f:(character -> unit) -> unit
Apply f on every character successively.
val iteri : t -> f:(int -> character -> unit) -> unit
Apply f on every character and its index.
val iter_reverse : t -> f:(character -> unit) -> unit
Apply f on every character successively in reverse order.
val rev : t -> t
Reverse the string. *
val map : t ->
       f:(character -> character) ->
       t
Make a new string by applying f to all characters of the input.
val mapi : t ->
       f:(int -> character -> character) ->
       t
Make a new string by applying f to all characters and their indices.
val map2_exn : t ->
       t ->
       f:(character ->
          character -> character) ->
       t
Make a new string by applying f to all pairs of characters of the inputs. Fail if strings are not the same length.
val for_all : t -> f:(character -> bool) -> bool
Return true if-and-only-if f returns true on all characters.
val exists : t -> f:(character -> bool) -> bool
Return true if-and-only-if f returns true on at least one character.
val take_while : t ->
       f:(character -> bool) -> t
Take a prefix of the string until f returns false.
val take_while_with_index : t ->
       f:(int -> character -> bool) -> t
Like take_while but the function also takes the current index.
val index_of_character : t -> ?from:int -> character -> int option
Find the first occurrence of a character in the string (starting at position from).
from : default value is 0. If from is negative, 0 will be used. If from >= length t, None will be returned.
val index_of_character_reverse : t -> ?from:int -> character -> int option
Like index_of_character but start from the end of the string.
from : defaults to length t - 1 (end of the string). If from is negative, None will be returned. If from >= length t, length t - 1 will be used.
val index_of_string : ?from:int ->
       ?sub_index:int ->
       ?sub_length:int -> t -> sub:t -> int option
Find the first occurrence of the substring (sub, sub_index, sub_length) in a given string, starting at from.
from : behaves like from in index_of_character.
sub_index : is constrained to [0, length sub)
sub_length : is constrained to [0, length sub - sub_index).

For example, if called with ~sub:"abc" ~sub_index:(-1) ~sub_length:4 then sub_index and sub_length will be constrained to 0 and 3, respectively.

If called with ~sub:"abc" ~sub_index:1 ~sub_length:3 then sub_index and sub_length will be constrained to 1 and 2, respectively.

Searching for an empty string (if sub is empty or it is constrained via sub_index or sub_length) from a valid position always succeeds at that position (ie from).

val index_of_string_reverse : ?from:int ->
       ?sub_index:int ->
       ?sub_length:int -> t -> sub:t -> int option
Like index_of_string but start from the end of the string.
from : behaves like from in index_of_character_reverse.
sub_index : is constrained like index_of_string.
sub_length : is constrained like index_of_string.
val find : ?from:int ->
       ?length:int ->
       t -> f:(character -> bool) -> int option
Find the index of the first character c for which f c is true.

One can restrict to the sub-string (from, length) (the default is to use the whole string, “out-of-bound” values are restricted to the bounds of the string).

val find_reverse : ?from:int ->
       ?length:int ->
       t -> f:(character -> bool) -> int option
Find the index of the last character c for which f c is true.

One can restrict to the reverse sub-string (from, length) (the default is to use the whole string, “out-of-bound” values are restricted to the bounds of the string).

val filter_map : ?from:int ->
       ?length:int ->
       t ->
       f:(character -> character option) ->
       t
Create a new string with the characters for which f c returned Some c.

One can restrict to the sub-string (from, length) (the default is to use the whole string, “out-of-bound” values are restricted to the bounds of the string).

val filter : ?from:int ->
       ?length:int ->
       t ->
       f:(character -> bool) -> t
Create a new string with the characters for which f c is true.

One can restrict to the sub-string (from, length) (the default is to use the whole string, “out-of-bound” values are restricted to the bounds of the string).

val split : t ->
       on:[ `Character of character | `String of t ] ->
       t list
Split the string using on as separator.

Splitting the empty string returns [].

Splitting with ~on:(`String empty) explodes the t into a list of one-character strings.

val strip : ?on:[ `Both | `Left | `Right ] ->
       ?whitespace:(character -> bool) ->
       t -> t
Remove any whitespace characters at the beginning and/or the end of the string
on : defaults to `Both.
whitespace : defaults to calling is_whitespace of the implemented character.
module Make_output (Model : Api.OUTPUT_MODEL) : sig .. end
Make_output(Asynchronous_output_model) provides a function output given an OUTPUT_MODEL.