Option-returning variants of stdlib functions (#885)

Provide an xxx_opt alternative for functions raising Not_found
and many instances of Failure/Invalid_arg.

The only exception is the rarely used Buffer.add_substitute, where
the [Not_found] can really be interpreted as an error condition.

Most new functions are implemented directly (instead of wrapping the
raising version).  This is for performance reasons and also to avoid
destroying the stacktrace (if the function is used in an exception
handler).  One could instead implement the raising versions on top of
the new functions, but there might be a small penalty.

1 files changed, 7 insertions, 0 deletions

diff --git a/stdlib/hashtbl.mli b/stdlib/hashtbl.mli
index 6d9cd00dd4..a5666b1500 100644
--- a/stdlib/hashtbl.mli
+++ b/stdlib/hashtbl.mli
@@ -87,6 +87,11 @@ val find : ('a, 'b) t -> 'a -> 'b
 (** [Hashtbl.find tbl x] returns the current binding of [x] in [tbl],
    or raises [Not_found] if no such binding exists. *)
 
+val find_opt : ('a, 'b) t -> 'a -> 'b option
+(** [Hashtbl.find_opt tbl x] returns the current binding of [x] in [tbl],
+    or [None] if no such binding exists.
+    @since 4.05 *)
+
 val find_all : ('a, 'b) t -> 'a -> 'b list
 (** [Hashtbl.find_all tbl x] returns the list of all data
    associated with [x] in [tbl].
@@ -276,6 +281,7 @@ module type S =
     val add : 'a t -> key -> 'a -> unit
     val remove : 'a t -> key -> unit
     val find : 'a t -> key -> 'a
+    val find_opt : 'a t -> key -> 'a option
     val find_all : 'a t -> key -> 'a list
     val replace : 'a t -> key -> 'a -> unit
     val mem : 'a t -> key -> bool
@@ -328,6 +334,7 @@ module type SeededS =
     val add : 'a t -> key -> 'a -> unit
     val remove : 'a t -> key -> unit
     val find : 'a t -> key -> 'a
+    val find_opt : 'a t -> key -> 'a option
     val find_all : 'a t -> key -> 'a list
     val replace : 'a t -> key -> 'a -> unit
     val mem : 'a t -> key -> bool