richer API for byte_buf

src/core/CCByte_buffer.ml

@@ -35,13 +35,19 @@ let[@inline never] grow_ self =
   let newcap = grow_cap_ self in
   grow_to_ self newcap
 
-let ensure_cap self n =
-  if n > capacity self then (
-    let newcap = max n (grow_cap_ self) in
-    grow_to_ self newcap
-  )
+let[@inline never] ensure_cap_grow_ self n =
+  (* new capacity, make sure it's at least [grow_cap_] so
+     that repeated calls to [ensure_cap] have the amortized complexity *)
+  let newcap = max n (grow_cap_ self) in
+  grow_to_ self newcap
 
-let shrink_to self n = if self.len > n then self.len <- n
+let[@inline] ensure_cap self n =
+  if n > capacity self then ensure_cap_grow_ self n
+
+let[@inline] ensure_free self n =
+  if n > capacity self - self.len then ensure_cap_grow_ self (self.len + n)
+
+let[@inline] shrink_to self n = if self.len > n then self.len <- n
 
 let append_buf (self : t) buf : unit =
   let n = Buffer.length buf in
@@ -54,10 +60,10 @@ let append_subbytes self b off len =
   Bytes.blit b off self.bs self.len len;
   self.len <- self.len + len
 
-let append_bytes self b = append_subbytes self b 0 (Bytes.length b)
-let append_string self s = append_bytes self (Bytes.unsafe_of_string s)
+let[@inline] append_bytes self b = append_subbytes self b 0 (Bytes.length b)
+let[@inline] append_string self s = append_bytes self (Bytes.unsafe_of_string s)
 
-let append_substring self s off len =
+let[@inline] append_substring self s off len =
   append_subbytes self (Bytes.unsafe_of_string s) off len
 
 let[@inline] add_char_unsafe_ self c =
@@ -94,13 +100,19 @@ let fold_left f acc self =
   done;
   !acc
 
-let iter f self =
-  let { bs; len } = self in
+let[@inline] iter f self =
   (* capture current content *)
+  let { bs; len } = self in
   for i = 0 to len do
     f (Bytes.unsafe_get bs i)
   done
 
+let[@inline] iteri f self =
+  let { bs; len } = self in
+  for i = 0 to len do
+    f i (Bytes.unsafe_get bs i)
+  done
+
 let of_seq seq =
   let self = create ~cap:32 () in
   append_seq self seq;

src/core/CCByte_buffer.mli

@@ -1,6 +1,7 @@
 (** Byte buffer.
 
-    A dynamic vector of bytes.
+    A dynamic vector of bytes that doesn't hide its internal from you.
+    Same use case as [Buffer.t] but with more power.
     @since 3.7
 *)
 
@@ -33,16 +34,24 @@ val bytes : t -> bytes
     operations that affect the capacity (e.g. {!add_char}). *)
 
 val clear : t -> unit
+(** [clear buf] sets [buf.len <- 0]. This doesn't resize the byte buffer. *)
 
 val ensure_cap : t -> int -> unit
-(** [ensure_cap self n] ensures that [capacity self >= n]. *)
+(** [ensure_cap self n] ensures that [capacity self >= n].
+    @raise Invalid_argument if this requires the buffer to grow beyond system limits. *)
+
+val ensure_free : t -> int -> unit
+(** [ensure_free buf n] ensures that the free space at the end of the
+    buffer is at least [n].
+    @raise Invalid_argument if this requires the buffer to grow beyond system limits. *)
 
 val shrink_to : t -> int -> unit
 (** [shrink_to buf n] reduces [length buf] to at most [n].
     Does nothing if the length is already <= n. *)
 
 val add_char : t -> char -> unit
-(** Push a character at the end. *)
+(** Push a character at the end.
+    @raise Invalid_argument if this requires the buffer to grow beyond system limits. *)
 
 val append_bytes : t -> bytes -> unit
 val append_subbytes : t -> bytes -> int -> int -> unit
@@ -57,12 +66,13 @@ val set : t -> int -> char -> unit
 val unsafe_set : t -> int -> char -> unit
 
 val contents : t -> string
-(** Copy the internal data to a string *)
+(** Copy the internal data to a string. Allocates. *)
 
 val contents_bytes : t -> bytes
-(** Copy the internal data to a byte buffer *)
+(** Copy the internal data to a {!bytes}. Allocates. *)
 
 val iter : (char -> unit) -> t -> unit
+val iteri : (int -> char -> unit) -> t -> unit
 val fold_left : ('a -> char -> 'a) -> 'a -> t -> 'a
 val of_iter : char iter -> t
 val of_seq : char Seq.t -> t

src/core/containers.ml

@@ -4,8 +4,6 @@
 
 module Array = CCArray
 module Bool = CCBool
-module Byte_buffer = CCByte_buffer
-module Byte_slice = CCByte_slice
 module Char = CCChar
 module Equal = CCEqual
 module Either = CCEither
@@ -30,6 +28,10 @@ module Hashtbl = struct
   module Make' = CCHashtbl.Make
 end
 
+(** {2 Additional modules} *)
+
+module Byte_buffer = CCByte_buffer
+module Byte_slice = CCByte_slice
 module Heap = CCHeap
 module Int = CCInt
 module Int32 = CCInt32