Module type Sosa.BASIC_STRING

module type BASIC_STRING = sig .. end

The minimal API implemented by string modules.

type character

A string is a string of characters.

type t

The type of the string.

val empty : t

An “empty” string.

val is_empty : t -> bool

Test whether a string is empty.

val make : int -> character -> t

Build a new string like String.make.

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.

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

val set_exn : t ->
       index:int -> v:character -> t

Like set but fail with an exception

val concat : ?sep:t -> t list -> t

The classical concat function.

include Sosa.NATIVE_CONVERSIONS

By including Sosa.NATIVE_CONVERSIONS, a basic string provides Sosa.NATIVE_CONVERSIONS.of_native_string, Sosa.NATIVE_CONVERSIONS.of_native_substring, and Sosa.NATIVE_CONVERSIONS.to_native_string.

val to_string_hum : t -> string

Convert the string to a human-readable native string (à la sprintf "%S").

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 whichever the other parameters are.

val sub_exn : t -> index:int -> length:int -> t

Do like sub but throw an exception instead of returning None

val slice : ?start:int ->
       ?finish:int -> t -> t option

Create a sub-string from the start (default 0, within [0,length\)) position to before the finish (default length, within [0,length]) if all of the indices are in bounds.

val slice_exn : ?start:int -> ?finish:int -> t -> t

Like slice but throw an exception instead of returning None

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. Throws 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 exception.

val chop_suffix_exn : t -> suffix:t -> t

Return a copy of t with suffix removed from the end. Throws 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 Sosa.BASIC_STRING.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, is 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

Do like Sosa.BASIC_STRING.compare_substring but return Some _ only when it is well defined (same validity criteria as Sosa.BASIC_STRING.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 Sosa.BASIC_STRING.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).

Default value for from 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

Do like index_of_character but start from the end of the string.

Default value for from is 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 index from.

The from parameter behaves like for Sosa.BASIC_STRING.index_of_character.

The (sub_index, sub_length) parameters are constrained to (0, length sub), for example, if sub is "abc", (-1, 4) will be equivalent to (0, 3), (1, 3) will be equivalent to (1, 2).

Searching for an empty string from a valid position always succeeds at that position.

val index_of_string_reverse : ?from:int ->
       ?sub_index:int ->
       ?sub_length:int ->
       t -> sub:t -> int option

Do like index_of_string but start from the end of the string.

The from parameter behaves like for Sosa.BASIC_STRING.index_of_character_reverse.

The (sub_index, sub_length) parameters are constrained like in Sosa.BASIC_STRING.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 [empty], splitting on the empty string explodes the string 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 (default `Both).

The default is to call the Sosa.BASIC_CHARACTER.is_whitespace function of the implemented character.

module Make_output: functor (Model : Sosa.OUTPUT_MODEL) -> sig .. end

Make_output(Asynchronous_output_model) provides a function Sosa.BASIC_STRING.Make_output.output given any Sosa.OUTPUT_MODEL.