Module Lmdb.Cursor

Iterators over maps.

type ('key, 'value, -'perm, -'dup) t constraint 'perm = [< `Read | `Write ] constraint 'dup = [< `Dup | `Uni ]

A cursor inherits two phantom types: the [< `Read | `Write ] permissions from the transaction and the [< `Dup | `Uni ] support from the map.

val go : 'perm perm -> ?⁠txn:'perm Txn.t -> ('key, 'value, 'dup) Map.t -> (('key, 'value, 'perm, 'dup) t -> 'a) -> 'a

go perm map ?txn f makes a cursor in the transaction txn using the function f cursor.

The function f will receive the cursor. A cursor can only be created and used inside a transaction. The cursor inherits the permissions of the transaction. The cursor should not be leaked outside of f.

Here is an example that returns the first 5 elements of a map:

go ro map begin fun c ->
let h = first c in
let rec aux i =
  if i < 5 then next c :: aux (i+1)
  else []
in
h :: aux 1
end
parameter txn

if omitted a transient transaction will implicitely be created before calling f and be committed after f returns.

Modification

val add : ('key, 'value, [> `Read | `Write ], _) t -> ?⁠flags:Flags.t -> 'key -> 'value -> unit

add cursor key value adds value to key and moves the cursor to its position.

For a map not supporting duplicates an existing value is overwritten. For a map supporting duplicates the value is added to the key. This is the same as overwrite for duplicate maps, but overwrite ~flags:Flags.no_overwrite for non-duplicate maps.

parameter flags

Flags

raises Exists

on maps not supporting duplicates if the key already exists.

raises Exists

if key is already bound to value and Cursor.Flags.no_dup_data was passed.

val set : ('key, 'value, _, _) t -> ?⁠flags:Flags.t -> 'key -> 'value -> unit

set cursor key value sets binding of key to value. and moves the cursor to its position.

Values of an already existing key are silently overwritten.

parameter flags

Flags

val replace : ('key, 'value, [> `Read | `Write ], _) t -> 'value -> unit

replace cursor value replace the current value by value.

val remove : ?⁠all:bool -> ('key, 'value, [> `Read | `Write ], _) t -> unit

remove cursor removes the current binding.

parameter all

If true removes all values associated to the current key. Default is false.

Reading

val current : ('key, 'value, [> `Read ], _) t -> 'key * 'value

current cursor returns key and value at the position of the cursor.

val current_all : ('key, 'value, [> `Read ], [> `Dup ]) t -> 'key * 'value array

current_all cursor moves the cursor to the last value of the current key. Returns key and all values of the current key.

val count : ('key, 'value, [> `Read ], [> `Dup ]) t -> int

count cursor returns the number of values bound to the current key.

Seeking

val get : ('key, 'value, [> `Read ], _) t -> 'key -> 'value

get cursor key moves the cursor to the first value of key.

val get_all : ('key, 'value, [> `Read ], [> `Dup ]) t -> 'key -> 'value array

get_all cursor key moves the cursor to the last value of key. Returns all values of key.

val seek : ('key, 'value, [> `Read ], _) t -> 'key -> 'key * 'value

seek cursor key moves the cursor to the first value of key.

val seek_all : ('key, 'value, [> `Read ], [> `Dup ]) t -> 'key -> 'key * 'value array

seek_all cursor key moves the cursor to the last value of key. Returns all values of key.

val seek_range : ('key, 'value, [> `Read ], _) t -> 'key -> 'key * 'value

seek_range cursor key moves the cursor to the first value of the first key greater than or equal to key.

val seek_range_all : ('key, 'value, [> `Read ], [> `Dup ]) t -> 'key -> 'key * 'value array

seek_range_all cursor key moves the cursor to the last value of the first key greater than or equal to key. Returns all values of this key.

val seek_dup : ('key, 'value, [> `Read ], [> `Dup ]) t -> 'key -> 'value -> unit

seek_dup cursor key value moves the cursor to value of key.

val seek_range_dup : ('key, 'value, [> `Read ], [> `Dup ]) t -> 'key -> 'value -> 'key * 'value

seek_range_dup cursor key value moves the cursor to the first value greater than or equal to value of the first key greater than or equal to key.

Moving

Moving over all key-value pairs
val first : ('key, 'value, [> `Read ], _) t -> 'key * 'value

first cursor moves the cursor to the first value of the first key.

val last : ('key, 'value, [> `Read ], _) t -> 'key * 'value

last cursor moves the cursor to the last value of the last key.

val next : ('key, 'value, [> `Read ], _) t -> 'key * 'value

next cursor moves the cursor to the next key-value pair. This may be the next value of the current key or the first value of the next key.

val prev : ('key, 'value, [> `Read ], _) t -> 'key * 'value

prev cursor moves the cursor to the previous key-value pair. This may be the previous value of the current key or the last value of the previous key.

Moving to neighboring keys
val next_nodup : ('key, 'value, [> `Read ], _) t -> 'key * 'value

next_nodup cursor moves the cursor to the first value of the next key.

val prev_nodup : ('key, 'value, [> `Read ], _) t -> 'key * 'value

prev_nodup cursor moves the cursor to the last value of the previous key.

Moving over duplicates of a single key
val first_dup : ('key, 'value, [> `Read ], [> `Dup ]) t -> 'value

first_dup cursor moves the cursor to the first value of the current key.

val last_dup : ('key, 'value, [> `Read ], [> `Dup ]) t -> 'value

last_dup cursor moves the cursor to the last value of the current key.

val next_dup : ('key, 'value, [> `Read ], [> `Dup ]) t -> 'value

next_dup cursor moves the cursor to the next value of the current key.

raises Not_found

if the cursor is already on the last value of the current key.

val prev_dup : ('key, 'value, [> `Read ], [> `Dup ]) t -> 'value

prev_dup cursor moves the cursor to the previous value of the current key.

raises Not_found

if the cursor is already on the first value of the current key.

Moving over keys getting all duplicates
val first_all : ('key, 'value, [> `Read ], [> `Dup ]) t -> 'key * 'value array

first_all cursor moves the cursor to the last value of the first key. Returns all values of the first key.

val last_all : ('key, 'value, [> `Read ], [> `Dup ]) t -> 'key * 'value array

last_all cursor moves the cursor to the first value of the last key. Returns all values of the last key.

val next_all : ('key, 'value, [> `Read ], [> `Dup ]) t -> 'key * 'value array

next_all cursor moves the cursor to the last value of the next key. Returns all values of the next key.

val prev_all : ('key, 'value, [> `Read ], [> `Dup ]) t -> 'key * 'value array

prev_all cursor moves the cursor to the first value of the previous key. Returns all values of the previous key.

Convenient Iterators

val iter : ?⁠cursor:('key, 'value, [> `Read ], 'dup) t -> f:('key -> 'value -> unit) -> ('key, 'value, 'dup) Map.t -> unit
val iter_rev : ?⁠cursor:('key, 'value, [> `Read ] as 'perm, 'dup) t -> f:('key -> 'value -> unit) -> ('key, 'value, 'dup) Map.t -> unit
val fold_left : ?⁠cursor:('key, 'value, [> `Read ], 'dup) t -> f:('a -> 'key -> 'value -> 'a) -> 'a -> ('key, 'value, 'dup) Map.t -> 'a
val fold_right : ?⁠cursor:('key, 'value, [> `Read ], 'dup) t -> f:('key -> 'value -> 'a -> 'a) -> ('key, 'value, 'dup) Map.t -> 'a -> 'a
val iter_all : ?⁠cursor:('key, 'value, [> `Read ], 'dup) t -> f:('key -> 'value array -> unit) -> ('key, 'value, [> `Dup ] as 'dup) Map.t -> unit
val iter_rev_all : ?⁠cursor:('key, 'value, [> `Read ] as 'perm, 'dup) t -> f:('key -> 'value array -> unit) -> ('key, 'value, [> `Dup ] as 'dup) Map.t -> unit
val fold_left_all : ?⁠cursor:('key, 'value, [> `Read ], 'dup) t -> f:('a -> 'key -> 'value array -> 'a) -> 'a -> ('key, 'value, [> `Dup ] as 'dup) Map.t -> 'a
val fold_right_all : ?⁠cursor:('key, 'value, [> `Read ], 'dup) t -> f:('key -> 'value array -> 'a -> 'a) -> ('key, 'value, [> `Dup ] as 'dup) Map.t -> 'a -> 'a