Merge pull request #28 from palainp/update-api

add partial read/write, size and rename

Author: hannesm

src/mirage_kv.ml

@@ -66,9 +66,11 @@ module type RO = sig
   type key = Key.t
   val exists: t -> key -> ([`Value | `Dictionary] option, error) result Lwt.t
   val get: t -> key -> (string, error) result Lwt.t
+  val get_partial: t -> key -> offset:int -> length:int -> (string, error) result Lwt.t
   val list: t -> key -> ((string * [`Value | `Dictionary]) list, error) result Lwt.t
   val last_modified: t -> key -> (int * int64, error) result Lwt.t
   val digest: t -> key -> (string, error) result Lwt.t
+  val size: t -> key -> (int, error) result Lwt.t
 end
 
 type write_error = [ error | `No_space | `Too_many_retries of int ]
@@ -84,6 +86,8 @@ module type RW = sig
   type nonrec write_error = private [> write_error]
   val pp_write_error: write_error Fmt.t
   val set: t -> key -> string -> (unit, write_error) result Lwt.t
+  val set_partial: t -> key -> offset:int -> string -> (unit, write_error) result Lwt.t
   val remove: t -> key -> (unit, write_error) result Lwt.t
+  val rename: t -> source:key -> dest:key -> (unit, write_error) result Lwt.t
   val batch: t -> ?retries:int -> (t -> 'a Lwt.t) -> 'a Lwt.t
 end

src/mirage_kv.mli

@@ -134,6 +134,17 @@ module type RO = sig
       The result is [Error (`Value_expected k)] if [k] refers to a
       dictionary in [t]. *)
 
+  val get_partial: t -> key -> offset:int -> length:int -> (string, error) result Lwt.t
+  (** [get_partial t k ~offset ~length] is the [length] bytes wide value
+     bound at [offset] of [k] in [t].
+
+      If the size of [k] is less than [offset], [get_partial] returns an
+     empty string.
+      If the size of [k] is less than [offset]+[length], [get_partial]
+     returns a short string.
+      The result is [Error (`Value_expected k)] if [k] refers to a
+     dictionary in [t]. *)
+
   val list: t -> key -> ((string * [`Value | `Dictionary]) list, error) result Lwt.t
   (** [list t k] is the list of entries and their types in the
      dictionary referenced by [k] in [t].
@@ -161,6 +172,10 @@ module type RO = sig
       When the value bound to [k] is a dictionary, the digest is a
      unique and deterministic digest of its entries. *)
 
+  val size: t -> key -> (int, error) result Lwt.t
+  (** [size t k] is the size of [k] in [t]. *)
+
+
 end
 
 type write_error = [
@@ -199,6 +214,19 @@ module type RW = sig
      {!batch} operation, where durability will be guaranteed at the
      end of the batch. *)
 
+  val set_partial: t -> key -> offset:int -> string -> (unit, write_error) result Lwt.t
+  (** [set_partial t k offset v] attempts to write [v] at [offset] in the
+     value bound to [k] in [t].
+      If [k] contains directories that do not exist, [set_partial] will
+     attempt to create them.
+      If the size of [k] is less than [offset], [set_partial] appends [v]
+     at the end of [k].
+      If the size of [k] is greater than [offset]+length of [v],
+     [set_partial] leaves the last bytes of [k] unchanged.
+
+      The result is [Error (`Value_expected k)] if [k] refers to a
+     dictionary in [t]. *)
+
   val remove: t -> key -> (unit, write_error) result Lwt.t
   (** [remove t k] removes any binding of [k] in [t]. If [k] was bound
      to a dictionary, the full dictionary will be removed.
@@ -207,6 +235,19 @@ module type RW = sig
      enclosing {!batch} operation, where durability will be guaranteed
      at the end of the batch. *)
 
+  val rename: t -> source:key -> dest:key -> (unit, write_error) result Lwt.t
+  (** [rename t source dest] rename [source] to [dest] in [t].
+      If [source] and [dest] are both bound to values in [t], [dest]
+     is removed and the binding of [source] is moved to [dest].
+      If [dest] is bound to a dictionary in [t], [source] is moved
+     inside [dest]. If [source] is bound to a dictionary, the full
+     dictionary is moved.
+
+      The result is [Error (`Not_found source)] if [source] does not
+     exists in [t].
+      The result is [Error (`Value_expected source)] if [source] is
+     bound to a dictionary in [t] and [dest] is bound to a value in [t]. *)
+
   val batch: t -> ?retries:int -> (t -> 'a Lwt.t) -> 'a Lwt.t
   (** [batch t f] run [f] in batch. Ensure the durability of
      operations.