Tloc (serialkit.Serialkit

File paths

type fpath = string

The type for file paths.

val file_none : fpath

file_none is "-". A file path to use when there is none.

Positions

Byte positions

type pos = int

The type for zero-based, absolute, byte positions in text. If the text has n bytes, 0 is the first position and n-1 is the last position.

val pos_none : int

pos_none is -1. A position to use when there is none.

Lines

type line = int

The type for one-based, line numbers in the text. Lines increment after a newline which is either a line feed '\n' (U+000A), a carriage return '\r' (U+000D) or a carriage return and a line feed "\r\n" (<U+000D,U+000A>).

val line_none : int

line_none is -1. A line number to use when there is none.

Line positions

type line_pos = line * pos

The type for line positions. The line number and the byte position of the first element on the line. The later is the byte position after the newline or the start of text. If the text ends with a newline or is empty that byte position is equal to the text's length, it is not a valid byte index of the input string.

val line_pos_first : line_pos

line_pos_first is 1, 0. Note that this is the only line position of the empty text.

val line_pos_none : line_pos

line_pos_none is (line_none, pos_none).

Text locations

type t

The type for text locations. A text location is an inclusive range of byte positions and the line positions on which they occur in the UTF-8 encoding of a given file.

If the first byte equals the last byte the range contains exactly that byte. If the first byte is greater than the last byte this represents an insertion point before the first byte.

val none : t

none is an position to use when there is none.

val v : 
  file:fpath ->
  first_byte:pos ->
  last_byte:pos ->
  first_line:line_pos ->
  last_line:line_pos ->
  t

v ~file ~first_byte ~last_byte ~first_line ~last_line is a text location with the given arguments, see corresponding accessors for the semantics. If you don't have a file use file_none.

val file : t -> fpath

file l is l's file.

val first_byte : t -> pos

first_byte l is l's first byte. Irrelevant if is_none is true.

val last_byte : t -> pos

last_byte l is l's last byte. Irrelevant if is_none or is_empty is true.

val first_line : t -> line_pos

first_line l is the line position on which first_byte l lies. Irrelevant if is_none is true.

val last_line : t -> line_pos

last_line l is the line position on which last_byte l lies. Irrelevant if is_none or is_empty is true.

Predicates and comparisons

val is_none : t -> bool

is_none t is true iff first_byte < 0.

val is_empty : t -> bool

is_empty t is true iff first_byte t > last_byte t.

val equal : t -> t -> bool

equal t0 t1 is true iff t0 and t1 are equal. This checks that file, first_byte and last_byte are equal. Line information is ignored.

val compare : t -> t -> int

compare t0 t1 orders t0 and t1. The order is compatible with equal. Comparison starts with file, follows with first_byte and ends, if needed, with last_byte. Line information is ignored.

Shrink and stretch

val to_first : t -> t

to_first l has both first and last positions set to l's first position. The range spans first_byte.

val to_last : t -> t

to_last l has both first and last positions set to l's last position. The range spans last_byte.

val before : t -> t

before t is the empty text location starting at first_byte.

val after : t -> t

after t is the empty empty location starting at last_byte t + 1; note that at the end of input this may be an invalid byte index. The first_line and last_line of the result is last_line t.

val span : t -> t -> t

span l0 l1 is the span from the smallest byte position of l0 and l1 to the largest byte position of l0 and l1. The file path is taken from the greatest byte position.

val reloc : first:t -> last:t -> t

reloc ~first ~last uses the first position of first, the last position of last and the file of last.

Formatting

val pp_ocaml : Stdlib.Format.formatter -> t -> unit

pp_ocaml formats location like the OCaml compiler.

val pp_gnu : Stdlib.Format.formatter -> t -> unit

pp_gnu formats location according to the GNU convention.

val pp : Stdlib.Format.formatter -> t -> unit

pp is pp_gnu.

val pp_dump : Stdlib.Format.formatter -> t -> unit

pp_dump formats raw data for debugging.

String substitutions and insertions

Strictly speaking this doesn't belong here but here you go.

val string_subrange : ?first:int -> ?last:int -> string -> string

string_subrange ~first ~last s are the consecutive bytes of s whose indices exist in the range [first;last].

first defaults to 0 and last to String.length s - 1.

Note that both first and last can be any integer. If first > last the interval is empty and the empty string is returned.

val string_replace : start:int -> stop:int -> rep:string -> string -> string

string_replace ~start ~stop ~rep s replaces the index range [start;stop-1] of s with rep as follows. If start = stop the rep is inserted before start. start and stop must be in range [0;String.length s] and start <= stop or Invalid_argument is raised.