Add Fke.rev_iter

lib/fke.ml

@@ -124,6 +124,21 @@ let iter : type a. (a -> unit) -> a t -> unit =
   in
   go f q
 
+let rev_iter : type a. (a -> unit) -> a t -> unit =
+  fun f q ->
+   let rec go : type a. (a -> unit) -> a t -> unit =
+    fun f -> function
+     | Shallow Zero -> ()
+     | Shallow (One x) -> f x
+     | Shallow (Two (y, x)) -> f x; f y
+     | Shallow (Three (z, y, x)) -> f x ; f y ; f z
+     | Deep {f= hd; m= (lazy q); r= tl; _} ->
+         go f (Shallow tl) ;
+         go (fun (y, x) -> f x; f y) q ;
+         go f (Shallow hd)
+   in
+   go f q
+
 let fold : type acc x. (acc -> x -> acc) -> acc -> x t -> acc =
  fun f a q ->
   let rec go : type acc x. (acc -> x -> acc) -> acc -> x t -> acc =

lib/sigs.ml

@@ -34,13 +34,21 @@ module type F = sig
   (** Same as {!pop} but it raises an exception if [q] is empty. *)
 
   val tail : 'a t -> ('a t * 'a) option
+  (** Get and remove the {b last} element. If [q] is empty, it returns [None]. *)
+
   val tail_exn : 'a t -> 'a t * 'a
+  (** Same as {!tail} but it raises an exception if [q] is empty. *)
 
   val iter : ('a -> unit) -> 'a t -> unit
   (** [iter f q] 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 rev_iter : ('a -> unit) -> 'a t -> unit
+  (** [rev_iter f q] applies [f] in turn to all elements of [q], from the most
+     recently entered to the least recently entered. The queue itself is
+     unchanged. *)
+
   val fold : ('acc -> 'x -> 'acc) -> 'acc -> 'x t -> 'acc
   (** [fold f a q] is equivalent to [List.fold_left f a l], where [l] is the
      list of [q]'s elements. The queue remains unchanged. *)