astring 0.8.0 · OCaml Package

Substrings.

A substring defines a possibly empty subsequence of bytes in a base string.

The positions of a string s of length l are the slits found before each byte and after the last byte of the string. They are labelled from left to right by increasing number in the range [0;l].

positions  0   1   2   3   4    l-1    l
           +---+---+---+---+     +-----+
  indices  | 0 | 1 | 2 | 3 | ... | l-1 |
           +---+---+---+---+     +-----+

The ith byte index is between positions i and i+1.

Formally we define a substring of s as being a subsequence of bytes defined by a start and a stop position. The former is always smaller or equal to the latter. When both positions are equal the substring is empty. Note that for a given base string there are as many empty substrings as there are positions in the string.

Like in strings, we index the bytes of a substring using zero-based indices.

See how to use substrings to parse data.

Substrings

type t = sub

The type for substrings.

val empty : sub

empty is the empty substring of the empty string String.empty.

val v : ?start:int -> ?stop:int -> string -> sub

v ~start ~stop s is the substring of s that starts at position start (defaults to 0) and stops at position stop (defaults to String.length s).

raises Invalid_argument
if start or stop are not positions of s or if stop < start.

val start_pos : sub -> int

start_pos s is s's start position in the base string.

val stop_pos : sub -> int

stop_pos s is s's stop position in the base string.

val base_string : sub -> string

base_string s is s's base string.

val length : sub -> int

length s is the number of bytes in s.

val get : sub -> int -> char

get s i is the byte of s at its zero-based index i.

raises Invalid_argument
if i is not an index of s.

val get_byte : sub -> int -> int

get_byte s i is Char.to_int (get s i).

val head : ?rev:bool -> sub -> char option

head s is Some (get s h) with h = 0 if rev = true (default) or h = length s - 1 if rev = false. None is returned if s is empty.

val get_head : ?rev:bool -> sub -> char

get_head s is like head but

raises Invalid_argument
if s is empty.

val of_string : string -> sub

of_string s is v s

val to_string : sub -> string

to_string s is the bytes of s as a string.

val rebase : sub -> sub

rebase s is v (to_string s). This puts s on a base string made solely of its bytes.

val hash : sub -> int

hash s is Hashtbl.hashs.

Stretching substrings

See the graphical guide.

val start : sub -> sub

start s is the empty substring at the start position of s.

val stop : sub -> sub

stop s is the empty substring at the stop position of s.

val base : sub -> sub

base s is a substring that spans the whole base string of s.

val tail : ?rev:bool -> sub -> sub

tail s is s without its first (rev is false, default) or last (rev is true) byte or s if it is empty.

val extend : ?rev:bool -> ?max:int -> ?sat:(char -> bool) -> sub -> sub

extend ~rev ~max ~sat s extends s by at most max consecutive sat satisfiying bytes of the base string located after stop s (rev is false, default) or before start s (rev is true). If max is unspecified the extension is limited by the extents of the base string of s. sat defaults to fun _ -> true.

raises Invalid_argument
if max is negative.

val reduce : ?rev:bool -> ?max:int -> ?sat:(char -> bool) -> sub -> sub

reduce ~rev ~max ~sat s reduces s by at most max consecutive sat satisfying bytes of s located before stop s (rev is false, default) or after start s (rev is true). If max is unspecified the reduction is limited by the extents of the substring s. sat defaults to fun _ -> true.

raises Invalid_argument
if max is negative.

val extent : sub -> sub -> sub

extent s s' is the smallest substring that includes all the positions of s and s'.

raises Invalid_argument
if s and s' are not on the same base string according to physical equality.

val overlap : sub -> sub -> sub option

overlap s s' is the smallest substring that includes all the positions common to s and s' or None if there are no such positions. Note that the overlap substring may be empty.

raises Invalid_argument
if s and s' are not on the same base string according to physical equality.

Appending substrings

val append : sub -> sub -> sub

append s s' is like append. The substrings can be on different bases and the result is on a base string that holds exactly the appended bytes.

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

concat ~sep ss is like String.concat. The substrings can all be on different bases and the result is on a base string that holds exactly the concatenated bytes.

Predicates

val is_empty : sub -> bool

is_empty s is length s = 0.

val is_prefix : affix:sub -> sub -> bool

is_prefix is like String.is_prefix. Only bytes are compared, affix can be on a different base string.

val is_infix : affix:sub -> sub -> bool

is_infix is like String.is_infix. Only bytes are compared, affix can be on a different base string.

val is_suffix : affix:sub -> sub -> bool

is_suffix is like String.is_suffix. Only bytes are compared, affix can be on a different base string.

val for_all : (char -> bool) -> sub -> bool

for_all is like String.for_all on the substring.

val exists : (char -> bool) -> sub -> bool

exists is like String.exists on the substring.

val same_base : sub -> sub -> bool

same_base s s' is true iff the substrings s and s' have the same base string according to physical equality.

val equal_bytes : sub -> sub -> bool

equal_bytes s s' is true iff the substrings s and s' have exactly the same bytes. The substrings can be on a different base string.

val compare_bytes : sub -> sub -> int

compare_bytes s s' compares the bytes of s and s' in lexicographical order. The substrings can be on a different base string.

val equal : sub -> sub -> bool

equal s s' is true iff s and s' have the same positions.

raises Invalid_argument
if s and s' are not on the same base string according to physical equality.

val compare : sub -> sub -> int

compare s s' compares the positions of s and s' in lexicographical order.

raises Invalid_argument
if s and s' are not on the same base string according to physical equality.

Extracting substrings

Extracted substrings are always on the same base string as the substring s acted upon.

val with_range : ?first:int -> ?len:int -> sub -> sub

with_range is like String.sub_with_range. The indices are the substring's zero-based ones, not those in the base string.

val with_index_range : ?first:int -> ?last:int -> sub -> sub

with_index_range is like String.sub_with_index_range. The indices are the substring's zero-based ones, not those in the base string.

val trim : ?drop:(char -> bool) -> sub -> sub

trim is like String.trim. If all bytes are dropped returns an empty string located in the middle of the argument.

val span : 
  ?rev:bool ->
  ?min:int ->
  ?max:int ->
  ?sat:(char -> bool) ->
  sub ->
  sub * sub

span is like String.span. For a substring s a left empty span is start s and a right empty span is stop s.

val take : 
  ?rev:bool ->
  ?min:int ->
  ?max:int ->
  ?sat:(char -> bool) ->
  sub ->
  sub

take is like String.take.

val drop : 
  ?rev:bool ->
  ?min:int ->
  ?max:int ->
  ?sat:(char -> bool) ->
  sub ->
  sub

drop is like String.drop.

val cut : ?rev:bool -> sep:sub -> sub -> (sub * sub) option

cut is like String.cut. sep can be on a different base string

val cuts : ?rev:bool -> ?empty:bool -> sep:sub -> sub -> sub list

cuts is like String.cuts. sep can be on a different base string

val fields : ?empty:bool -> ?is_sep:(char -> bool) -> sub -> sub list

fields is like String.fields.

Traversing substrings

val find : ?rev:bool -> (char -> bool) -> sub -> sub option

find ~rev sat s is the substring of s (if any) that spans the first byte that satisfies sat in s after position start s (rev is false, default) or before stop s (rev is true). None is returned if there is no matching byte in s.

val find_sub : ?rev:bool -> sub:sub -> sub -> sub option

find_sub ~rev ~sub s is the substring of s (if any) that spans the first match of sub in s after position start s (rev is false, defaults) or before stop s (rev is false). Only bytes are compared and sub can be on a different base string. None is returned if there is no match of sub in s.

val filter : (char -> bool) -> sub -> sub

filter sat s is like String.filter. The result is on a base string that holds only the filtered bytes.

val filter_map : (char -> char option) -> sub -> sub

filter_map f s is like String.filter_map. The result is on a base string that holds only the filtered bytes.

val map : (char -> char) -> sub -> sub

map is like String.map. The result is on a base string that holds only the mapped bytes.

val mapi : (int -> char -> char) -> sub -> sub

mapi is like String.mapi. The result is on a base string that holds only the mapped bytes. The indices are the substring's zero-based ones, not those in the base string.

val fold_left : ('a -> char -> 'a) -> 'a -> sub -> 'a

fold_left is like String.fold_left.

val fold_right : (char -> 'a -> 'a) -> sub -> 'a -> 'a

fold_right is like String.fold_right.

val iter : (char -> unit) -> sub -> unit

iter is like String.iter.

val iteri : (int -> char -> unit) -> sub -> unit

iteri is like String.iteri. The indices are the substring's zero-based ones, not those in the base string.

Pretty printing

val pp : Format.formatter -> sub -> unit

pp ppf s prints s's bytes on ppf.

val dump : Format.formatter -> sub -> unit

dump ppf s prints s as a syntactically valid OCaml string on ppf using Ascii.escape_string.

val dump_raw : Format.formatter -> sub -> unit

dump_raw ppf s prints an unspecified raw internal representation of s on ppf.

OCaml base type conversions

val of_char : char -> sub

of_char c is a string that contains the byte c.

val to_char : sub -> char option

to_char s is the single byte in s or None if there is no byte or more than one in s.

val of_bool : bool -> sub

of_bool b is a string representation for b. Relies on Pervasives.string_of_bool.

val to_bool : sub -> bool option

to_bool s is a bool from s, if any. Relies on Pervasives.bool_of_string.

val of_int : int -> sub

of_int i is a string representation for i. Relies on Pervasives.string_of_int.

val to_int : sub -> int option

to_int is an int from s, if any. Relies on Pervasives.int_of_string.

val of_nativeint : nativeint -> sub

of_nativeint i is a string representation for i. Relies on Nativeint.of_string.

val to_nativeint : sub -> nativeint option

to_nativeint is an nativeint from s, if any. Relies on Nativeint.to_string.

val of_int32 : int32 -> sub

of_int32 i is a string representation for i. Relies on Int32.of_string.

val to_int32 : sub -> int32 option

to_int32 is an int32 from s, if any. Relies on Int32.to_string.

val of_int64 : int64 -> sub

of_int64 i is a string representation for i. Relies on Int64.of_string.

val to_int64 : sub -> int64 option

to_int64 is an int64 from s, if any. Relies on Int64.to_string.

val of_float : float -> sub

of_float f is a string representation for f. Relies on Pervasives.string_of_float.

val to_float : sub -> float option

to_float s is a float from s, if any. Relies on Pervasives.float_of_string.

Substring stretching graphical guide

+---+---+---+---+---+---+---+---+---+---+---+
| R | e | v | o | l | t |   | n | o | w | ! |
+---+---+---+---+---+---+---+---+---+---+---+
        |---------------|                      a
        |                                      start a
                        |                      stop a
            |-----------|                      tail a
        |-----------|                          tail ~rev:true a
        |-----------------------------------|  extend a
|-----------------------|                      extend ~rev:true a
|-------------------------------------------|  base a
|-----------|                                  b
|                                              start b
            |                                  stop b
    |-------|                                  tail b
|-------|                                      tail ~rev:true b
|-------------------------------------------|  extend b
|-----------|                                  extend ~rev:true b
|-------------------------------------------|  base b
|-----------------------|                      extent a b
        |---|                                  overlap a b
                            |                  c
                            |                  start c
                            |                  stop c
                            |                  tail c
                            |                  tail ~rev:true c
                            |---------------|  extend c
|---------------------------|                  extend ~rev:true c
|-------------------------------------------|  base c
        |-------------------|                  extent a c
                                         None  overlap a c
                            |---------------|  d
                            |                  start d
                                            |  stop d
                                |-----------|  tail d
                            |-----------|      tail ~rev:true d
                            |---------------|  extend d
|-------------------------------------------|  extend ~rev:true d
|-------------------------------------------|  base d
                            |---------------|  extent d c
                            |                  overlap d c

package astring