(* $Id: netbuffer.mli 1476 2010-08-31 00:05:15Z gerd $
 * ----------------------------------------------------------------------
 *
 *)


(** A Netbuffer.t is a buffer that can grow and shrink dynamically. *)

type t

val create : int -> t
    (** Creates a netbuffer which allocates initially this number of bytes. 
     * The logical length is zero.
     *)

val contents : t -> string
    (** Returns the contents of the buffer as fresh string. *)

val length : t -> int
    (** Returns the logical length of the buffer *)

(** {2 Extracting strings} *)

val get : t -> int -> char
    (** [get nb pos]: Get the character at [pos] *)

val nth : t -> int -> char
    (** Alias for [get] *)

val sub : t -> int -> int -> string
    (** [sub nb k n]: returns the n characters starting at position [n] from 
     * netbuffer [nb] as fresh string
     *)

val blit_to_string : t -> int -> string -> int -> int -> unit
    (** [blit_to_string nb srcpos dest destpos len]: Copies the [len] bytes at
     * position [srcpos] from [nb] to the string [dest] at position [destpos].
     *)

val blit : t -> int -> string -> int -> int -> unit
    (** Compatibility name for [blit_to_string], now deprecated *)

(** {2 Appending strings} *)

val add_string : t -> string -> unit
    (** [add_string nb s]: Adds a copy of the string [s] to the logical end of
     * the netbuffer [nb]. If necessary, [nb] grows.
     *)

val add_sub_string : t -> string -> int -> int -> unit
    (** [add_sub_string nb s k n]: Adds the substring of [s] starting at position
     * [k] with length [n] to the logical end of the netbuffer [nb]. If necessary,
     * [nb] grows.
     *
     * This is semantically the same as
     * [add_string nb (String.sub s k n)], but the extra copy is avoided.
     *)

val add_substring : t -> string -> int -> int -> unit
    (** Alias for add_sub_string *)

val add_char : t -> char -> unit
    (** [add_char nb c]: Adds a single char at the end of the buffer *)

val add_char_2 : t -> char -> char -> unit
    (** [add_char_2 nb c1 c2]: Adds two chars at the end of the buffer *)

val add_char_4 : t -> char -> char -> char -> char -> unit
    (** [add_char_4 nb c1 c2 c3 c4]: Adds four chars at the end of the buffer *)

val add_inplace : ?len:int -> t -> (string -> int -> int -> int) -> int
    (** [add_inplace nb f]: Calls the function [f] to add bytes to the
     * netbuffer [nb]. The arguments of [f] are the buffer, the position
     * in the buffer, and the maximum length. The function [f] must return
     * the actual number of added bytes; this number is also returned by
     * [add_inplace].
     *
     * Example: let n = add_inplace nb (Pervasives.input ch)
     *
     * The argument [len] is the number of bytes to add (second argument of
     * [f]). It defaults to the number of free bytes in the buffer after space
     * for at least one byte has been allocated.
     *)

val add_buffer : t -> t -> unit
  (** [add_buffer nb1 nb2]: Adds the contents of [nb2] to the end of [nb1] *)

val area_for_additions : ?len:int -> t -> (string * int * int)
val advance : t -> int -> unit
  (** These two functions work together, so that the effect of [add_inplace]
      can be obtained in two steps. First, the user calls
      {[
        let (s,pos,len) = area_for_additions nb
      ]}
      to get the area where to put new data of length [n], with [n <= len].
      After this the data is made valid by
      {[
        advance n
      ]}
   *)


(** {2 Inserting strings} *)

val insert_string : t -> int -> string -> unit
    (** [insert_string nb p s]: Inserts the value of string [s] at position
     * [p] into the netbuffer [nb]
     *)

val insert_sub_string : t -> int -> string -> int -> int -> unit
    (** [insert_string nb p s k n]: Inserts a substring of string [s] at position
     * [p] into the netbuffer [nb]. The substring is denoted by position [k]
     * and has length [n]
     *)

val insert_char : t -> int -> char -> unit
    (** [insert_char nb p c]: Inserts character [c] at position [p] into
     * the netbuffer [nb]
     *)

(** {2 Overwriting strings} *)

val set : t -> int -> char -> unit
    (** [set nb pos c]: Sets the character at [pos] to [c] *)

val put_string : t -> int -> string -> unit
    (** [put_string nb pos s]: Copies the string [s] to the position [pos]
        of netbuffer [nb]
     *)

val blit_from_string : string -> int -> t -> int -> int -> unit
    (** [blit_from_string src srcpos dest destpos len]: Copies the [len] bytes
     * at position [srcpos] from the string [src] to the netbuffer [dest] at
     * position [destpos].
     *
     * It is possible to copy the string beyond the end of the buffer. The
     * buffer is automatically enlarged in this case.
     *)

(** {2 Deleting} *)

val delete : t -> int -> int -> unit
    (** [delete nb k n]: Deletes the [n] bytes at position [k] of netbuffer 
     * [nb] in-place.
     *
     * The netbuffer does not shrink, however, i.e. the free space is not
     * given back to the memory manager.
     *)

val clear : t -> unit
    (** Deletes all contents from the buffer. As [delete], the netbuffer does
     * not shrink.
     *)

val reset : t -> unit
    (** Empty the buffer, deallocate the internal string, and replace it
        with a new string of length [n] that was allocated by
        {!Netbuffer.create} [n].
     *)

val try_shrinking : t -> unit
    (** [try_shrinking nb]: If the length of the buffer is less than half of
     * the allocated space, the netbuffer is reallocated in order to save
     * memory.
     *)

(** {2 Searching} *)

val index_from : t -> int -> char -> int
    (** [index_from nb k c]: Searches the character [c] in the netbuffer beginning
     * at position [k]. If found, the position of the left-most occurence is
     * returned. Otherwise, [Not_found] is raised.
     *)

(** {2 Memory} *)

val blit_to_memory : t -> int -> Netsys_mem.memory -> int -> int -> unit
    (** [blit_to_memory nb srcpos dest destpos len]: Copies the [len] bytes at
     *  position [srcpos] from [nb] to the membuffer [dest] at position
	[destpos].
     *)

val add_sub_memory : t -> Netsys_mem.memory -> int -> int -> unit
  (** Same as [add_sub_string], but gets data from a memory buffer *)


(** {2 Miscelleneous} *)

val unsafe_buffer : t -> string
    (** {b Warning! This is a low-level function!}
     * Returns the current string that internally holds the buffer.
     * The byte positions 0 to length - 1 actually store the contents of
     * the buffer. You can directly read and modify the buffer. Note that
     * there is no protection if you read or write positions beyond the
     * length of the buffer.
     *)

val print_buffer : t -> unit
    (** For the toploop *)


(* MISSING: searching substrings *)