belt_MutableQueue.mli

(**************************************************************************)
(*                                                                        *)
(*                                 OCaml                                  *)
(*                                                                        *)
(*             Xavier Leroy, projet Cristal, INRIA Rocquencourt           *)
(*                                                                        *)
(*   Copyright 1996 Institut National de Recherche en Informatique et     *)
(*     en Automatique.                                                    *)
(*                                                                        *)
(*   All rights reserved.  This file is distributed under the terms of    *)
(*   the GNU Lesser General Public License version 2.1, with the          *)
(*   special exception on linking described in the file LICENSE.          *)
(*                                                                        *)
(**************************************************************************)
(* Adapted significantly by ReScript Authors *)

(**
  A FIFO (first in first out) queue data structure.
*)

type 'a t
(**
   The type of queues containing elements of `type('a)`.
*)

val make : unit -> 'a t
(** 
  Returns a new queue, initially empty.
*)

val clear : 'a t -> unit
(**
  Discard all elements from the queue.
*)

val isEmpty : 'a t -> bool
(**
  Returns `true` if the given queue is empty, `false` otherwise.
*)

val fromArray : 'a array -> 'a t
(**
  `fromArray` a is equivalent to `Array.forEach(a, add(q, a));`
*)

val add : 'a t -> 'a -> unit
(**
  `add(q, x)` adds the element `x` at the end of the queue `q`.
*)

val peek : 'a t -> 'a option
(**
  `peekOpt(q)` returns the first element in queue `q`, without removing it from the queue.
*)

val peekUndefined : 'a t -> 'a Js.undefined
(**
  `peekUndefined(q)` returns `undefined` if not found.
*)

val peekExn : 'a t -> 'a
(**
  raise an exception if `q` is empty
*)

val pop : 'a t -> 'a option
(**
  `pop(q)` removes and returns the first element in queue `q`.
*)

val popUndefined : 'a t -> 'a Js.undefined
(**
  `popUndefined(q)` removes and returns the first element in queue `q`. it will return `undefined` if it is already empty.
*)

val popExn : 'a t -> 'a
(**
  `popExn(q)` raise an exception if q is empty.
*)

val copy : 'a t -> 'a t
(**
  `copy(q)` returns a fresh queue.
*)

val size : 'a t -> int
(**
  Returns the number of elements in a queue.
*)

val mapU : 'a t -> (('a -> 'b)[@bs]) -> 'b t
val map : 'a t -> ('a -> 'b) -> 'b t
val forEachU : 'a t -> (('a -> unit)[@bs]) -> unit

val forEach : 'a t -> ('a -> unit) -> unit
(**
  `forEach(q, f) applies`f`in turn to all elements of`q`, from the least
  recently entered to the most recently entered. The queue itself is unchanged.
*)

val reduceU : 'a t -> 'b -> (('b -> 'a -> 'b)[@bs]) -> 'b

val reduce : 'a t -> 'b -> ('b -> 'a -> 'b) -> 'b
(**
  `reduce(q, accu, f)` is equivalent to `List.reduce(l, accu, f)`, where `l` is the list of `q`'s elements. The queue remains unchanged.
*)

val transfer : 'a t -> 'a t -> unit
(**
  `transfer(q1, q2)` adds all of `q1`'s elements at the end of the queue `q2`, then clears `q1`. It is equivalent to the sequence `forEach((x) => add(x, q2), q1);`; clear `q1`, but runs in constant time.
*)

val toArray : 'a t -> 'a array
(**
  First added will be in the beginning of the array.
*)