1414 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
1515 *)
1616
17+ (* * Manipulate external buffers as C-like structs *)
18+
1719type buffer = (char , Bigarray .int8_unsigned_elt , Bigarray .c_layout ) Bigarray.Array1 .t
20+ (* * Type of a buffer. A cstruct is composed of an underlying buffer
21+ and position/length within this buffer. *)
1822
1923type t = private {
2024 buffer : buffer ;
2125 off : int ;
2226 len : int ;
2327}
28+ (* * Type of a cstruct. *)
29+
30+ (* * Functions that create a new cstruct. *)
2431
2532val of_bigarray : ?off : int -> ?len : int -> buffer -> t
33+ (* * [of_bigarray ~off ~len b] is the cstruct contained in [b] starting
34+ at [off], of length [len]. *)
35+
2636val create : int -> t
37+ (* * [create len] is a cstruct of size [len] with an offset of 0. *)
38+
39+ val of_string : ?allocator : (int -> t ) -> string -> t
40+ (* * [of_string ~alloc str] is the cstruct representation of [str],
41+ with the underlying buffer allocated by [alloc]. If [alloc] is not
42+ provided, [create] is used. *)
43+
44+ (* * Functions that operate over cstructs. *)
45+
2746val check_bounds : t -> int -> bool
47+ (* * [check_bounds cstr len] is [true] if [cstr.buffer]'s size is
48+ greater or equal than [len], [false] otherwise. *)
2849
2950type byte = char
51+
3052val byte : int -> byte
3153val byte_to_int : byte -> int
3254
@@ -54,16 +76,47 @@ val set_char: t -> int -> char -> unit
5476val set_uint8 : t -> int -> uint8 -> unit
5577
5678val sub : t -> int -> int -> t
79+ (* * [sub cstr off len] is [{ t with off = t.off + off; len }] *)
5780
5881val shift : t -> int -> t
82+ (* * [shift cstr len] is [{ t with off = t.off + off; len = t.len - off
83+ }] *)
5984
6085val copy : t -> int -> int -> string
86+ (* * [copy cstr off len] is the string representation of the segment of
87+ [t] starting at [off] of size [len].
88+
89+ Raise [Invalid_argument] if [off] and [len] do not designate a
90+ valid segment of [t]. *)
6191
6292val blit : t -> int -> t -> int -> int -> unit
93+ (* * [blit src srcoff dst dstoff len] copies [len] characters from
94+ cstruct [src], starting at index [srcoff], to cstruct [dst],
95+ starting at index [dstoff]. It works correctly even if [src] and
96+ [dst] are the same string, and the source and destination
97+ intervals overlap.
98+
99+ Raise [Invalid_argument] if [srcoff] and [len] do not designate a
100+ valid segment of [src], or if [dstoff] and [len] do not designate
101+ a valid segment of [dst]. *)
63102
64103val blit_from_string : string -> int -> t -> int -> int -> unit
104+ (* * [blit_from_string src srcoff dst dstoff len] copies [len]
105+ characters from string [src], starting at index [srcoff], to
106+ string [dst], starting at index [dstoff].
107+
108+ Raise [Invalid_argument] if [srcoff] and [len] do not designate a
109+ valid substring of [src], or if [dstoff] and [len] do not
110+ designate a valid segment of [dst]. *)
65111
66112val blit_to_string : t -> int -> string -> int -> int -> unit
113+ (* * [blit_to_string src srcoff dst dstoff len] copies [len] characters
114+ from cstruct [src], starting at index [srcoff], to string [dst],
115+ starting at index [dstoff].
116+
117+ Raise [Invalid_argument] if [srcoff] and [len] do not designate a
118+ valid segment of [src], or if [dstoff] and [len] do not designate
119+ a valid substring of [dst]. *)
67120
68121val len : t -> int
69122
@@ -72,11 +125,13 @@ val set_len : t -> int -> t
72125val add_len : t -> int -> t
73126
74127val split : ?start : int -> t -> int -> t * t
128+ (* * [split ~start cstr len] is a tuple containing the cstruct
129+ extracted from [cstr] at offset [start] (default: 0) of length
130+ [len] as first element, and the rest of [cstr] as second
131+ element. *)
75132
76133val to_string : t -> string
77134
78- val of_string : ?allocator : (int -> t ) -> string -> t
79-
80135val hexdump : t -> unit
81136val debug : t -> string
82137
@@ -103,13 +158,20 @@ end
103158(* * {2 List of buffers} *)
104159
105160val lenv : t list -> int
161+ (* * [lenv cstrs] is the combined length of all cstructs in [cstrs]. *)
106162
107163val copyv : t list -> string
164+ (* * [copyv cstrs] is the string representation of the concatenation of
165+ all cstructs in [cstrs]. *)
108166
109167(* * {2 Iterations} *)
110168
111169type 'a iter = unit -> 'a option
170+ (* * Type of an iterator. *)
112171
113172val iter : (t -> int option ) -> (t -> 'a ) -> t -> 'a iter
173+ (* * [iter lenf of_cstr cstr] is an iterator over [cstr] that returns
174+ elements of size [lenf cstr] and type [of_cstr cstr]. *)
114175
115176val fold : ('b -> 'a -> 'b ) -> 'a iter -> 'b -> 'b
177+ (* * [fold f iter acc] is [(f iterN accN ... (f iter acc)...)]. *)
0 commit comments