(** Associating values to handles using an immutable associator.
    @author Victor Nicollet *)

(** An associator object. *)
type 'a t 

(** A handle object. *)
type handle

(** Create an association object initially optimized for storing the specified
    number of objects. *)
val empty : int -> 'a t

(** Add an object to the association. The object is bound to a handle, which 
    is returned. *)
val add : 'a -> 'a t -> 'a t * handle

(** An exception thrown when a handle is not bound within an object. *)
exception UnboundHandle

(** Remove the object bound to a handle from an associator. *)
val remove : handle -> 'a t -> 'a t

(** Retrieve the object using a handle. *)
val get : handle -> 'a t -> 'a

(** Map a function on all objects within an associator. *)
val map : ('a -> 'b) -> 'a t -> 'b t

(** Map a function on all objects within an associator, and their handle. 
    The handles are valid for both associators. *)
val mapi : (handle -> 'a -> 'b) -> 'a t -> 'b t

(** Apply a function to all elements of an associator. *)
val iter : ('a -> unit) -> 'a t -> unit

(** Apply a function to all elements of an associator, and their handle. *)
val iteri : (handle -> 'a -> unit) -> 'a t -> unit

(** Fold over the elements of an associator and their handle. *)
val fold : (handle -> 'a -> 'b -> 'b) -> 'b -> 'a t -> 'b