Merge pull request #132 from gasche/write-buffer-cleanup

lib/write: more regular usage protocol for ?buf parameters

CHANGES.md

@@ -9,6 +9,7 @@
   * `Bi_outbuf.t` in signatures is replaced with `Buffer.t`
   * `to_outbuf` becomes `to_buffer` and `stream_to_outbuf` becomes
     `stream_to_buffer`
+  (@Leonidas-from-XIV, #74, and @gasche, #132)
 - Removed `yojson-biniou` library
 - Removed deprecated `json` type aliasing type `t` which has been available
   since 1.6.0 (@Leonidas-from-XIV, #100).

lib/write.ml

@@ -441,20 +441,21 @@ let to_channel ?buf ?(len=4096) ?std oc x =
   let ob =
     match buf with
         None -> Buffer.create len
-      | Some ob -> ob
+      | Some ob -> Buffer.clear ob; ob
   in
   to_buffer ?std ob x;
-  Buffer.output_buffer oc ob
+  Buffer.output_buffer oc ob;
+  Buffer.clear ob
 
 let to_output ?buf ?(len=4096) ?std out x =
   let ob =
     match buf with
         None -> Buffer.create len
-      | Some ob -> ob
+      | Some ob -> Buffer.clear ob; ob
   in
   to_buffer ?std ob x;
   out#output (Buffer.contents ob) 0 (Buffer.length ob);
-  ()
+  Buffer.clear ob
 
 let to_file ?len ?std ?(newline = true) file x =
   let oc = open_out file in
@@ -487,7 +488,7 @@ let seq_to_channel ?buf ?(len=2096) ?std oc seq =
   let ob =
     match buf with
         None -> Buffer.create len
-      | Some ob -> ob
+      | Some ob -> Buffer.clear ob; ob
   in
   Seq.iter (fun json ->
     to_buffer ?std ob json;

lib/write.mli

@@ -23,27 +23,18 @@ val to_channel :
   ?std:bool ->
   out_channel -> t -> unit
   (** Write a compact JSON value to a channel.
-      @param buf allows to reuse an existing buffer created with
-      [Buffer.create] on the same channel.
-      [buf] is flushed right
-      before [to_channel] returns but the [out_channel] is
-      not flushed automatically.
+      Note: the [out_channel] is not flushed by this function.
 
-      See [to_string] for the role of the other optional arguments. *)
+      See [to_string] for the role of the optional arguments. *)
 
 val to_output :
   ?buf:Buffer.t ->
   ?len:int ->
   ?std:bool ->
   < output : string -> int -> int -> int; .. > -> t -> unit
   (** Write a compact JSON value to an OO channel.
-      @param buf allows to reuse an existing buffer created with
-      [Buffer.add_channel] on the same channel.
-      [buf] is flushed right
-      before [to_output] returns but the channel itself is
-      not flushed automatically.
 
-      See [to_string] for the role of the other optional arguments. *)
+      See [to_string] for the role of the optional arguments. *)
 
 val to_file :
   ?len:int ->