Add Stack.{top_opt,pop_opt} and Queue.{peek_opt,take_opt}

Changes

@@ -60,6 +60,9 @@ Working version
   -keyword=arg inputs
   (Valentin Gatien-Baron, review by Gabriel Scherer)
 
+- GPR#XXXX: Add Stack.{top_opt,pop_opt} and Queue.{peek_opt,take_opt}.
+  (Vladimir Keleshev, review by _)
+
 ### Other libraries:
 
 - GPR#1061: Add ?follow parameter to Unix.link. This allows hardlinking

stdlib/queue.ml

@@ -60,6 +60,11 @@ let peek q =
   | Nil -> raise Empty
   | Cons { content } -> content
 
+let peek_opt q =
+  match q.first with
+  | Nil -> None
+  | Cons { content } -> Some content
+
 let top =
   peek
 
@@ -74,6 +79,17 @@ let take q =
     q.first <- next;
     content
 
+let take_opt q =
+  match q.first with
+  | Nil -> None
+  | Cons { content; next = Nil } ->
+    clear q;
+    Some content
+  | Cons { content; next } ->
+    q.length <- q.length - 1;
+    q.first <- next;
+    Some content
+
 let pop =
   take
 

stdlib/queue.mli

@@ -43,6 +43,11 @@ val take : 'a t -> 'a
 (** [take q] removes and returns the first element in queue [q],
    or raises {!Empty} if the queue is empty. *)
 
+val take_opt : 'a t -> 'a option
+(** [take_opt q] removes and returns the first element in queue [q],
+   or returns [None] if the queue is empty.
+   @since 4.08 *)
+
 val pop : 'a t -> 'a
 (** [pop] is a synonym for [take]. *)
 
@@ -50,6 +55,11 @@ val peek : 'a t -> 'a
 (** [peek q] returns the first element in queue [q], without removing
    it from the queue, or raises {!Empty} if the queue is empty. *)
 
+val peek_opt : 'a t -> 'a option
+(** [peek_opt q] returns the first element in queue [q], without removing
+   it from the queue, or returns [None] if the queue is empty.
+   @since 4.08 *)
+
 val top : 'a t -> 'a
 (** [top] is a synonym for [peek]. *)
 

stdlib/stack.ml

@@ -30,10 +30,20 @@ let pop s =
   | hd::tl -> s.c <- tl; s.len <- s.len - 1; hd
   | []     -> raise Empty
 
+let pop_opt s =
+  match s.c with
+  | hd::tl -> s.c <- tl; s.len <- s.len - 1; Some hd
+  | []     -> None
+
 let top s =
   match s.c with
   | hd::_ -> hd
-  | []     -> raise Empty
+  | []    -> raise Empty
+
+let top_opt s =
+  match s.c with
+  | hd::_ -> Some hd
+  | []    -> None
 
 let is_empty s = (s.c = [])
 

stdlib/stack.mli

@@ -35,10 +35,20 @@ val pop : 'a t -> 'a
 (** [pop s] removes and returns the topmost element in stack [s],
    or raises {!Empty} if the stack is empty. *)
 
+val pop_opt : 'a t -> 'a option
+(** [pop_opt s] removes and returns the topmost element in stack [s],
+   or returns [None] if the stack is empty.
+   @since 4.08 *)
+
 val top : 'a t -> 'a
 (** [top s] returns the topmost element in stack [s],
    or raises {!Empty} if the stack is empty. *)
 
+val top_opt : 'a t -> 'a option
+(** [top_opt s] returns the topmost element in stack [s],
+   or [None] if the stack is empty.
+   @since 4.08 *)
+
 val clear : 'a t -> unit
 (** Discard all elements from a stack. *)
 

testsuite/tests/basic/opt_variants.ml

@@ -113,4 +113,22 @@ let () =
   W.add w r;
   assert (W.find_opt w r = Some r);
 
+  let stack = Stack.create () in
+  Stack.push 41 stack;
+  Stack.push 42 stack;
+  assert(Stack.top_opt stack = Some 42);
+  assert(Stack.pop_opt stack = Some 42);
+  assert(Stack.pop_opt stack = Some 41);
+  assert(Stack.pop_opt stack = None);
+  assert(Stack.top_opt stack = None);
+
+  let queue = Queue.create () in
+  Queue.add 41 queue;
+  Queue.add 42 queue;
+  assert(Queue.peek_opt queue = Some 41);
+  assert(Queue.take_opt queue = Some 41);
+  assert(Queue.take_opt queue = Some 42);
+  assert(Queue.take_opt queue = None);
+  assert(Queue.peek_opt queue = None);
+
   ()