source: Deliverables/D2.2/8051/src/utilities/extArray.mli @ 1569

(** This module provides simple extensible arrays. *)

(** The type of extensible arrays with elements in ['a]. *)
type 'a t

(** [make n a] creates an extensible array with initial size [n]
    and default element [a]. The optional argument [buff] sets the
                initial buffer size (16 by default, set to 1 if [buff < 1]). *)  
val make : ?buff:int -> int -> 'a -> 'a t

(** [detault v] returns the default element of v, which fills unspecified
    cells when extending the array. *)
val default : 'a t -> 'a

(** [get v n] gets the element in [v] at [n]. Raises 
    [Invalid_argument "out of bounds"] if [n < 0] or [n >= length v]. *)
val get : 'a t -> int -> 'a

(** [set v n x] sets the element in [v] at [n] to [x]. Raises 
    [Invalid_argument "out of bounds"] if [n < 0], but fills the
                array as needed with [default v] if [n >= length v]. The final length
                is thus [max (length v) (n + 1)]. *)
val set : 'a t -> int -> 'a -> unit

(** [length v] returns the current length of the array. *)
val length : 'a t -> int

(** [chop v n] erases the last [n] elements of [v], or all the elements of [v]
    if [n >= length v]. The final length is thus [max 0 (length v - n)].
                Implementation note: this function does not free any memory. *)
val chop : 'a t -> int -> unit

(** [extend v n] adds [n] default elements at the end of the array. It is
    equivalent to [append v (default v); ... ; append v (default v)] [n]
                times. *)  
val extend : 'a t -> int -> unit

(** [ensure v n] will ensure [n >= 0] is inside the bounds of the array [v].
    To this end it will add [default v] elements at the end of [v] if necessary.
                It does nothing if [n < 0]. *) 
val ensure : 'a t -> int -> unit 

(** [append v a] appends [a] at the end of [v], with the length of [v] being
    thus raised by [1]. It is equivalent to [set v (length v) a]. *)
val append : 'a t -> 'a -> unit

(** [reclaim v] will shrink the memory imprint of [v] roughly to a multiple
    of [packet] (16 by default), without changinb [v]'s content. The effect
                depends on garbage collection. *)
val reclaim : ?packet:int -> 'a t -> unit

(** [iter f v] iterates [f] over the elements of [v]. *)
val iter : ('a -> unit) -> 'a t -> unit
(** [fold_left f x v] computes [f (... (f (f x (get v 0)) (get v 1)) ...)
    (get v (n-1))], where [n] is the length of [v]. *)
val fold_left : ('a -> 'b -> 'a) -> 'a -> 'b t -> 'a    

(** [fold_right f v x] computes [f (get v 0) (... (f (get v (n-1)) x)...)],
    where [n] is the length of [v]. *)
val fold_right : ('a -> 'b -> 'b) -> 'a t -> 'b -> 'b