Documented all non-trivial functions in module Cstruct

Author: Vincent Bernardoff

lib/cstruct.ml

@@ -117,31 +117,39 @@ let set_len t len =
 let add_len t len =
   { t with len = t.len + len }
 
+let invalid_arg fmt =
+  let b = Buffer.create 20 in (* for thread safety. *)
+  let ppf = Format.formatter_of_buffer b in
+  let k ppf = Format.pp_print_flush ppf (); invalid_arg (Buffer.contents b) in
+  Format.kfprintf k ppf fmt
+
+let invalid_bounds j l = invalid_arg "invalid bounds (index %d, length %d)" j l
+
 external unsafe_blit_bigstring_to_bigstring : buffer -> int -> buffer -> int -> int -> unit = "caml_blit_bigstring_to_bigstring" "noalloc"
 
 external unsafe_blit_string_to_bigstring : string -> int -> buffer -> int -> int -> unit = "caml_blit_string_to_bigstring" "noalloc"
 
 external unsafe_blit_bigstring_to_string : buffer -> int -> string -> int -> int -> unit = "caml_blit_bigstring_to_string" "noalloc"
 
 let copy src srcoff len =
-  if src.len - srcoff < len then raise (Failure "copy");
+  if src.len - srcoff < len then raise (Invalid_argument (invalid_bounds srcoff len));
   let s = String.create len in
   unsafe_blit_bigstring_to_string src.buffer (src.off+srcoff) s 0 len;
   s
 
 let blit src srcoff dst dstoff len =
-  if src.len - srcoff < len then raise (Failure "blit");
-  if dst.len - dstoff < len then raise (Failure "blitdst");
+  if src.len - srcoff < len then raise (Invalid_argument (invalid_bounds srcoff len));
+  if dst.len - dstoff < len then raise (Invalid_argument (invalid_bounds dstoff len));
   unsafe_blit_bigstring_to_bigstring src.buffer (src.off+srcoff) dst.buffer (dst.off+dstoff) len
 
 let blit_from_string src srcoff dst dstoff len =
-  if String.length src - srcoff < len then raise (Failure "blit_from_string");
-  if dst.len - dstoff < len then raise (Failure "blit_from_string dst");
+  if String.length src - srcoff < len then raise (Invalid_argument (invalid_bounds srcoff len));
+  if dst.len - dstoff < len then raise (Invalid_argument (invalid_bounds dstoff len));
   unsafe_blit_string_to_bigstring src srcoff dst.buffer (dst.off+dstoff) len
 
 let blit_to_string src srcoff dst dstoff len =
-  if src.len - srcoff < len then raise (Failure "blit_to_string");
-  if String.length dst - dstoff < len then raise (Failure "blit_to_string dst");
+  if src.len - srcoff < len then raise (Invalid_argument (invalid_bounds srcoff len));
+  if String.length dst - dstoff < len then raise (Invalid_argument (invalid_bounds dstoff len));
   unsafe_blit_bigstring_to_string src.buffer (src.off+srcoff) dst dstoff len
 
 let set_uint8 t i c =

lib/cstruct.mli

@@ -14,19 +14,41 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  *)
 
+(** Manipulate external buffers as C-like structs *)
+
 type buffer = (char, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t
+(** Type of a buffer. A cstruct is composed of an underlying buffer
+    and position/length within this buffer. *)
 
 type t = private {
   buffer: buffer;
   off   : int;
   len   : int;
 }
+(** Type of a cstruct. *)
+
+(** Functions that create a new cstruct. *)
 
 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]. *)
+
 val create : int -> t
+(** [create len] is a cstruct of size [len] with an offset of 0. *)
+
+val of_string: ?allocator:(int -> t) -> string -> t
+(** [of_string ~alloc str] is the cstruct representation of [str],
+    with the underlying buffer allocated by [alloc]. If [alloc] is not
+    provided, [create] is used. *)
+
+(** Functions that operate over cstructs. *)
+
 val check_bounds : t -> int -> bool
+(** [check_bounds cstr len] is [true] if [cstr.buffer]'s size is
+    greater or equal than [len], [false] otherwise. *)
 
 type byte = char
+
 val byte : int -> byte
 val byte_to_int : byte -> int
 
@@ -54,16 +76,47 @@ val set_char: t -> int -> char -> unit
 val set_uint8: t -> int -> uint8 -> unit
 
 val sub: t -> int -> int -> t
+(** [sub cstr off len] is [{ t with off = t.off + off; len }] *)
 
 val shift: t -> int -> t
+(** [shift cstr len] is [{ t with off = t.off + off; len = t.len - off
+    }] *)
 
 val copy: t -> int -> int -> string
+(** [copy cstr off len] is the string representation of the segment of
+    [t] starting at [off] of size [len].
+
+    Raise [Invalid_argument] if [off] and [len] do not designate a
+    valid segment of [t]. *)
 
 val blit: t -> int -> t -> int -> int -> unit
+(** [blit src srcoff dst dstoff len] copies [len] characters from
+    cstruct [src], starting at index [srcoff], to cstruct [dst],
+    starting at index [dstoff]. It works correctly even if [src] and
+    [dst] are the same string, and the source and destination
+    intervals overlap.
+
+    Raise [Invalid_argument] if [srcoff] and [len] do not designate a
+    valid segment of [src], or if [dstoff] and [len] do not designate
+    a valid segment of [dst]. *)
 
 val blit_from_string: string -> int -> t -> int -> int -> unit
+(** [blit_from_string src srcoff dst dstoff len] copies [len]
+    characters from string [src], starting at index [srcoff], to
+    string [dst], starting at index [dstoff].
+
+    Raise [Invalid_argument] if [srcoff] and [len] do not designate a
+    valid substring of [src], or if [dstoff] and [len] do not
+    designate a valid segment of [dst]. *)
 
 val blit_to_string: t -> int -> string -> int -> int -> unit
+(** [blit_to_string src srcoff dst dstoff len] copies [len] characters
+    from cstruct [src], starting at index [srcoff], to string [dst],
+    starting at index [dstoff].
+
+    Raise [Invalid_argument] if [srcoff] and [len] do not designate a
+    valid segment of [src], or if [dstoff] and [len] do not designate
+    a valid substring of [dst]. *)
 
 val len: t -> int
 
@@ -72,11 +125,13 @@ val set_len : t -> int -> t
 val add_len : t -> int -> t
 
 val split: ?start:int -> t -> int -> t * t
+(** [split ~start cstr len] is a tuple containing the cstruct
+    extracted from [cstr] at offset [start] (default: 0) of length
+    [len] as first element, and the rest of [cstr] as second
+    element. *)
 
 val to_string: t -> string
 
-val of_string: ?allocator:(int -> t) -> string -> t
-
 val hexdump: t -> unit
 val debug: t -> string
 
@@ -103,13 +158,20 @@ end
 (** {2 List of buffers} *)
 
 val lenv: t list -> int
+(** [lenv cstrs] is the combined length of all cstructs in [cstrs]. *)
 
 val copyv: t list -> string
+(** [copyv cstrs] is the string representation of the concatenation of
+    all cstructs in [cstrs]. *)
 
 (** {2 Iterations} *)
 
 type 'a iter = unit -> 'a option
+(** Type of an iterator. *)
 
 val iter: (t -> int option) -> (t -> 'a) -> t -> 'a iter
+(** [iter lenf of_cstr cstr] is an iterator over [cstr] that returns
+    elements of size [lenf cstr] and type [of_cstr cstr]. *)
 
 val fold: ('b -> 'a -> 'b) -> 'a iter -> 'b -> 'b
+(** [fold f iter acc] is [(f iterN accN ... (f iter acc)...)]. *)