Merge pull request #262 from hannesm/cap

cstruct_cap: order interface

lib/cstruct.ml

@@ -384,22 +384,19 @@ let fillv ~src ~dst =
         ) in
   aux dst 0 src
 
-
-let to_bytes t =
-  let sz = len t in
-  let b = Bytes.create sz in
-  unsafe_blit_bigstring_to_bytes t.buffer t.off b 0 sz;
-  b
-
-let to_string t =
+let to_string ?(off=0) ?len:sz t =
+  let len = match sz with None -> len t - off | Some l -> l in
   (* The following call is safe, since this is the only reference to the
      freshly-created value built by [to_bytes t]. *)
-  Bytes.unsafe_to_string (to_bytes t)
+  copy t off len
 
-let of_data_abstract blitfun lenfun ?allocator ?(off=0) ?len buf =
+let to_bytes ?off ?len t =
+  Bytes.unsafe_of_string (to_string ?off ?len t)
+
+let [@inline always] of_data_abstract blitfun lenfun ?allocator ?(off=0) ?len buf =
   let buflen =
     match len with
-    | None -> lenfun buf
+    | None -> lenfun buf - off
     | Some len -> len in
   match allocator with
   | None ->
@@ -417,7 +414,11 @@ let of_string ?allocator ?off ?len buf =
 let of_bytes ?allocator ?off ?len buf =
   of_data_abstract blit_from_bytes Bytes.length ?allocator ?off ?len buf
 
-let of_hex str =
+let of_hex ?(off=0) ?len str =
+  let str =
+    let l = match len with None -> String.length str - off | Some l -> l in
+    String.sub str off l
+  in
   let string_fold ~f ~z str =
     let st = ref z in
     ( String.iter (fun c -> st := f !st c) str  ; !st )

lib/cstruct.mli

@@ -177,7 +177,8 @@ val empty : t
 
 val of_bigarray: ?off:int -> ?len:int -> buffer -> t
 (** [of_bigarray ~off ~len b] is the cstruct contained in [b] starting
-    at [off], of length [len]. *)
+    at offset [off] (default [0]) of length [len]
+    (default [Bigarray.Array1.dim b - off]). *)
 
 val to_bigarray: t -> buffer
 (** [to_bigarray t] converts a {!t} into a {!buffer} Bigarray, using
@@ -202,24 +203,34 @@ val create_unsafe : int -> t
 
 val of_string: ?allocator:(int -> t) -> ?off:int -> ?len:int -> string -> t
 (** [of_string ~allocator ~off ~len str] is the cstruct representation of [str]
-    slice located at [off] offset and of [len] length,
+    slice located at offset [off] (default [0]) and of length [len] (default
+    [String.length str - off]),
     with the underlying buffer allocated by [alloc]. If [allocator] is not
-    provided, [create] is used. *)
+    provided, [create] is used.
+
+    @raise Invalid_argument if [off] or [len] is negative, or
+    [String.length str - off] < [len].
+*)
 
 val of_bytes: ?allocator:(int -> t) -> ?off:int -> ?len:int -> bytes -> t
 (** [of_bytes ~allocator byt] is the cstruct representation of [byt]
-    slice located at [off] offset and of [len] length,
+    slice located at offset [off] (default [0]) and of length [len] (default
+    [Bytes.length byt - off]),
     with the underlying buffer allocated by [alloc]. If [allocator] is not
-    provided, [create] is used. *)
+    provided, [create] is used.
+
+    @raise Invalid_argument if [off] or [len] is negative, or
+    [Bytes.length str - off] < [len]. *)
 
-val of_hex: string -> t
-(** [of_hex str] is the cstruct [cs].  Every pair of hex-encoded characters in
-    [str] are converted to one byte in [cs].  Whitespaces (space, newline, tab,
-    carriage return) in [str] are skipped.  The resulting cstruct is exactly
-    half the size of the non-skipped characters of [str].
+val of_hex: ?off:int -> ?len:int -> string -> t
+(** [of_hex ~off ~len str] is the cstruct [cs].  Every pair of hex-encoded
+    characters in [str] starting at offset [off] (default [0]) of length [len]
+    (default [String.length str - off]) are converted to one byte in [cs].
+    Whitespaces (space, newline, tab, carriage return) in [str] are skipped.
 
     @raise Invalid_argument if the input string contains invalid characters or
-    has an odd numbers of non-whitespace characters. *)
+    has an odd numbers of non-whitespace characters, or if [off] or [len] are
+    negative, or [String.length str - off] < [len]. *)
 
 (** {2 Comparison } *)
 
@@ -351,13 +362,21 @@ val split: ?start:int -> t -> int -> t * t
     @raise Invalid_argument if [start] exceeds the cstruct length,
     or if there is a bounds violation of the cstruct via [len+start]. *)
 
-val to_string: t -> string
-(** [to_string t] will allocate a fresh OCaml [string] and copy the
-    contents of the cstruct into it, and return that string copy. *)
+val to_string: ?off:int -> ?len:int -> t -> string
+(** [to_string ~off ~len t] will allocate a fresh OCaml [string] and copy the
+    contents of the cstruct starting at offset [off] (default [0]) of length
+    [len] (default [Cstruct.len t - off]) into it, and return that string.
+
+    @raise Invalid_argument if [off] or [len] is negative, or
+    [Cstruct.len str - off] < [len]. *)
+
+val to_bytes: ?off:int -> ?len:int -> t -> bytes
+(** [to_bytes ~off ~len t] will allocate a fresh OCaml [bytes] and copy the
+    contents of the cstruct starting at offset [off] (default [0]) of length
+    [len] (default [Cstruct.len t - off]) into it, and return that bytes.
 
-val to_bytes: t -> bytes
-(** [to_bytes t] will allocate a fresh OCaml [bytes] and copy the
-    contents of the cstruct into it, and return that byte copy. *)
+    @raise Invalid_argument if [off] or [len] is negative, or
+    [Cstruct.len str - off] < [len]. *)
 
 (** {2 Debugging } *)
 

lib/cstruct_cap.ml

@@ -29,24 +29,8 @@ type wo = < wr: unit; >
 external ro : 'a rd t -> ro t = "%identity"
 external wo : 'a wr t -> wo t = "%identity"
 
-let of_string ?off ?len x =
-  Cstruct.of_string ?off ?len x
-let of_bytes ?off ?len x =
-  Cstruct.of_bytes ?off ?len x
-
-let to_string ?(off= 0) ?len t =
-  let len = match len with
-    | Some len -> len
-    | None -> Cstruct.length t - off in
-  Cstruct.copy t off len
-
-let to_bytes ?(off= 0) ?len t =
-  let len = match len with
-    | Some len -> len
-    | None -> Cstruct.length t - off in
-  (* XXX(dinosaure): this is safe when [copy] allocates itself [bytes]
-     and uses [Bytes.unsafe_to_string]. *)
-  Bytes.unsafe_of_string (Cstruct.copy t off len)
+let of_string = Cstruct.of_string ?allocator:None
+let of_bytes = Cstruct.of_bytes ?allocator:None
 
 let pp ppf t = Cstruct.hexdump_pp ppf t
 
@@ -72,6 +56,8 @@ let sub t ~off ~len =
   Cstruct.sub t off len
 [@@inline]
 
+let unsafe_to_bigarray = Cstruct.to_bigarray
+
 let concat vss =
   let res = create_unsafe (Cstruct.sum_lengths ~caller:"Cstruct.Cap.concat" vss) in
   let go off v =