l4/pkg/ocaml/contrib/stdlib/queue.mli

   1 (***********************************************************************)
   2 (*                                                                     *)
   3 (*                           Objective Caml                            *)
   4 (*                                                                     *)
   5 (*            Xavier Leroy, projet Cristal, INRIA Rocquencourt         *)
   6 (*                                                                     *)
   7 (*  Copyright 1996 Institut National de Recherche en Informatique et   *)
   8 (*  en Automatique.  All rights reserved.  This file is distributed    *)
   9 (*  under the terms of the GNU Library General Public License, with    *)
  10 (*  the special exception on linking described in file ../LICENSE.     *)
  11 (*                                                                     *)
  12 (***********************************************************************)
  13
  14 (* $Id: queue.mli 4956 2002-06-27 08:48:26Z xleroy $ *)
  15
  16 (** First-in first-out queues.
  17
  18    This module implements queues (FIFOs), with in-place modification.
  19 *)
  20
  21 type 'a t
  22 (** The type of queues containing elements of type ['a]. *)
  23
  24
  25 exception Empty
  26 (** Raised when {!Queue.take} or {!Queue.peek} is applied to an empty queue. *)
  27
  28
  29 val create : unit -> 'a t
  30 (** Return a new queue, initially empty. *)
  31
  32 val add : 'a -> 'a t -> unit
  33 (** [add x q] adds the element [x] at the end of the queue [q]. *)
  34
  35 val push : 'a -> 'a t -> unit
  36 (** [push] is a synonym for [add]. *)
  37
  38 val take : 'a t -> 'a
  39 (** [take q] removes and returns the first element in queue [q],
  40    or raises [Empty] if the queue is empty. *)
  41
  42 val pop : 'a t -> 'a
  43 (** [pop] is a synonym for [take]. *)
  44
  45 val peek : 'a t -> 'a
  46 (** [peek q] returns the first element in queue [q], without removing
  47    it from the queue, or raises [Empty] if the queue is empty. *)
  48
  49 val top : 'a t -> 'a
  50 (** [top] is a synonym for [peek]. *)
  51
  52 val clear : 'a t -> unit
  53 (** Discard all elements from a queue. *)
  54
  55 val copy : 'a t -> 'a t
  56 (** Return a copy of the given queue. *)
  57
  58 val is_empty : 'a t -> bool
  59 (** Return [true] if the given queue is empty, [false] otherwise. *)
  60
  61 val length : 'a t -> int
  62 (** Return the number of elements in a queue. *)
  63
  64 val iter : ('a -> unit) -> 'a t -> unit
  65 (** [iter f q] applies [f] in turn to all elements of [q],
  66    from the least recently entered to the most recently entered.
  67    The queue itself is unchanged. *)
  68
  69 val fold : ('b -> 'a -> 'b) -> 'b -> 'a t -> 'b
  70 (** [fold f accu q] is equivalent to [List.fold_left f accu l],
  71    where [l] is the list of [q]'s elements. The queue remains
  72    unchanged. *)
  73
  74 val transfer : 'a t -> 'a t -> unit
  75 (** [transfer q1 q2] adds all of [q1]'s elements at the end of
  76    the queue [q2], then clears [q1]. It is equivalent to the
  77    sequence [iter (fun x -> add x q2) q1; clear q1], but runs
  78    in constant time. *)