lwd/lib/lwd/lwd_table.mli

103 lines
3.2 KiB
OCaml
Raw Normal View History

2020-09-17 15:21:40 +02:00
(** {0 Table manipulation}
[Lwd_table] is an ordered collection with an impure interface.
It is designed to be efficient in an interactive setting.
The interface mimics the one of a doubly-linked lists: from a node, called
row, you can iterate backward and forward, insert and delete other nodes,
and change the value it is bound to.
The sequence of nodes can be observed by map/reduce operations, that will
be recomputed efficiently when sequence changes.
*)
2019-12-12 11:36:58 +01:00
type 'a t
type 'a row
2020-09-17 15:21:40 +02:00
(** The type of tables *)
2019-12-12 11:36:58 +01:00
val make : unit -> 'a t
2020-09-17 15:21:40 +02:00
(** Create a new table *)
(** {1 Inserting rows} *)
2019-12-12 11:36:58 +01:00
val prepend : ?set:'a -> 'a t -> 'a row
2020-09-17 15:21:40 +02:00
(** Insert and return a new row at the start of a table.
It can be optionnally initialized to the value of [set]. *)
2019-12-12 11:36:58 +01:00
val append : ?set:'a -> 'a t -> 'a row
2020-09-17 15:21:40 +02:00
(** Insert and return a new row at the end of a table.
It can be optionnally initialized to the value of [set]. *)
2019-12-12 11:36:58 +01:00
val prepend' : 'a t -> 'a -> unit
2020-09-17 15:21:40 +02:00
(* Insert a new initialized row at start of a table *)
2019-12-12 11:36:58 +01:00
val append' : 'a t -> 'a -> unit
2020-09-17 15:21:40 +02:00
(* Insert a new initialized row at end of a table *)
2019-12-12 11:36:58 +01:00
val before : ?set:'a -> 'a row -> 'a row
2020-09-17 15:21:40 +02:00
(** Insert and return a new row just before an existing row.
It can be optionnally initialized to the value of [set].
If the input row is unbound ([is_bound] returns false), the returned row is
too.
*)
2019-12-12 11:36:58 +01:00
val after : ?set:'a -> 'a row -> 'a row
2020-09-17 15:21:40 +02:00
(** Insert and return a new row just after an existing row.
It can be optionnally initialized to the value of [set].
If the input row is unbound ([is_bound] returns false), the returned row is
too.
*)
(** {1 Iterating over rows} *)
2019-12-12 11:36:58 +01:00
val first : 'a t -> 'a row option
2020-09-17 15:21:40 +02:00
(** Returns the first row of a table, or [None] if the table is empty *)
val last : 'a t -> 'a row option
2020-09-17 15:21:40 +02:00
(** Returns the last row of a table, or [None] if the table is empty *)
val next : 'a row -> 'a row option
2020-09-17 15:21:40 +02:00
(** Returns the row next to another one, or [None] if the input row is unbound
or is the last row *)
val prev : 'a row -> 'a row option
2020-09-17 15:21:40 +02:00
(** Returns the row just before another one, or [None] if the input row is
unbound or is the first row *)
(** {1 Accessing and changing row contents} *)
2019-12-12 11:36:58 +01:00
val get : 'a row -> 'a option
2020-09-17 15:21:40 +02:00
(** Get the value associated with a row, if any, or [None] if the row is
unbound *)
2019-12-12 11:36:58 +01:00
val set : 'a row -> 'a -> unit
2020-09-17 15:21:40 +02:00
(** Set the value associated with a row, or do nothing if the row is unbound *)
2019-12-12 11:36:58 +01:00
val unset : 'a row -> unit
2020-09-17 15:21:40 +02:00
(** Unset the value associated with a row *)
(** {1 Removing rows} *)
2019-12-12 11:36:58 +01:00
val is_bound : 'a row -> bool
2020-09-17 15:21:40 +02:00
(** Returns [true] iff the row is bound in a table (it has not beem [remove]d
yet, the table has not been [clear]ed) *)
2019-12-12 11:36:58 +01:00
val remove : 'a row -> unit
2020-09-17 15:21:40 +02:00
(** [remove] a row from its table, [is_bound] will be [true] after that *)
val clear : 'a t -> unit
(** Remove all rows from a table *)
(** {1 Observing table contents} *)
2019-12-12 11:36:58 +01:00
val reduce : 'a Lwd_utils.monoid -> 'a t -> 'a Lwd.t
2020-09-17 15:21:40 +02:00
(** Observe the content of a table by reducing it with a monoid *)
2019-12-12 11:36:58 +01:00
val map_reduce : ('a row -> 'a -> 'b) -> 'b Lwd_utils.monoid -> 'a t -> 'b Lwd.t
2020-09-17 15:21:40 +02:00
(** Observe the content of a table by mapping and reducing it *)
2019-12-12 11:36:58 +01:00
val iter : ('a -> unit) -> 'a t -> unit
2020-09-17 15:21:40 +02:00
(** Immediate, non reactive, iteration over elements of a table *)