Option-returning variants of stdlib functions (ocaml#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.

Author: alainfrisch

Changes

@@ -25,6 +25,9 @@ Next version (4.05.0):
   List.compare_length_with to avoid full list length computations
   (Fabrice Le Fessant)
 
+- GPR#885: Option-returning variants of stdlib functions
+  (Alain Frisch, review by David Allsopp and Bart Jacobs)
+
 ### Tools:
 
 - PR#7333: ocamldoc, use the first sentence of text file as

otherlibs/num/big_int.ml

@@ -336,6 +336,9 @@ let int_of_big_int bi =
     if eq_big_int bi monster_big_int then monster_int
     else failwith "int_of_big_int";;
 
+let int_of_big_int_opt bi =
+  try Some (int_of_big_int bi) with Failure _ -> None
+
 let big_int_of_nativeint i =
   if i = 0n then
     zero_big_int
@@ -359,6 +362,9 @@ let nativeint_of_big_int bi =
     then Nativeint.neg i
     else failwith "nativeint_of_big_int"
 
+let nativeint_of_big_int_opt bi =
+  try Some (nativeint_of_big_int bi) with Failure _ -> None
+
 let big_int_of_int32 i = big_int_of_nativeint (Nativeint.of_int32 i)
 
 let int32_of_big_int bi =
@@ -367,6 +373,9 @@ let int32_of_big_int bi =
   then Nativeint.to_int32 i
   else failwith "int32_of_big_int"
 
+let int32_of_big_int_opt bi =
+  try Some (int32_of_big_int bi) with Failure _ -> None
+
 let big_int_of_int64 i =
   if Sys.word_size = 64 then
     big_int_of_nativeint (Int64.to_nativeint i)
@@ -406,6 +415,9 @@ let int64_of_big_int bi =
       else failwith "int64_of_big_int"
   end
 
+let int64_of_big_int_opt bi =
+  try Some (int64_of_big_int bi) with Failure _ -> None
+
 (* Coercion with nat type *)
 let nat_of_big_int bi =
  if bi.sign = -1
@@ -460,6 +472,9 @@ let sys_big_int_of_string s ofs len =
 let big_int_of_string s =
   sys_big_int_of_string s 0 (String.length s)
 
+let big_int_of_string_opt s =
+  try Some (big_int_of_string s) with Failure _ -> None
+
 let power_base_nat base nat off len =
   if base = 0 then nat_of_int 0 else
   if is_zero_nat nat off len || base = 1 then nat_of_int 1 else

otherlibs/num/big_int.mli

@@ -141,6 +141,16 @@ val big_int_of_string : string -> big_int
         (** Convert a string to a big integer, in decimal.
            The string consists of an optional [-] or [+] sign,
            followed by one or several decimal digits. *)
+(* TODO: document error condition. *)
+
+val big_int_of_string_opt: string -> big_int option
+(** Convert a string to a big integer, in decimal.
+    The string consists of an optional [-] or [+] sign,
+    followed by one or several decimal digits. Other the function
+    returns [None].
+    @since 4.05
+*)
+
 
 (** {6 Conversions to and from other numerical types} *)
 
@@ -161,6 +171,13 @@ val int_of_big_int : big_int -> int
            Raises [Failure "int_of_big_int"] if the big integer
            is not representable as a small integer. *)
 
+val int_of_big_int_opt: big_int -> int option
+(** Convert a big integer to a small integer (type [int]).  Return
+    [None] if the big integer is not representable as a small
+    integer.
+    @since 4.05
+*)
+
 val big_int_of_int32 : int32 -> big_int
 (** Convert a 32-bit integer to a big integer. *)
 
@@ -175,16 +192,35 @@ val int32_of_big_int : big_int -> int32
             Raises [Failure] if the big integer is outside the
             range \[-2{^31}, 2{^31}-1\]. *)
 
+val int32_of_big_int_opt: big_int -> int32 option
+(** Convert a big integer to a 32-bit integer.  Return [None] if the
+    big integer is outside the range \[-2{^31}, 2{^31}-1\].
+    @since 4.05
+*)
+
 val nativeint_of_big_int : big_int -> nativeint
         (** Convert a big integer to a native integer.
             Raises [Failure] if the big integer is outside the
             range [[Nativeint.min_int, Nativeint.max_int]]. *)
 
+val nativeint_of_big_int_opt: big_int -> nativeint option
+(** Convert a big integer to a native integer. Return [None] if the
+    big integer is outside the range [[Nativeint.min_int,
+    Nativeint.max_int]];
+    @since 4.05
+*)
+
 val int64_of_big_int : big_int -> int64
         (** Convert a big integer to a 64-bit integer.
             Raises [Failure] if the big integer is outside the
             range \[-2{^63}, 2{^63}-1\]. *)
 
+val int64_of_big_int_opt: big_int -> int64 option
+(** Convert a big integer to a 64-bit integer. Return [None] if the
+    big integer is outside the range \[-2{^63}, 2{^63}-1\].
+    @since 4.05
+*)
+
 val float_of_big_int : big_int -> float
         (** Returns a floating-point number approximating the
            given big integer. *)

otherlibs/num/num.ml

@@ -354,6 +354,11 @@ let int_of_num = function
 | Big_int bi -> int_of_big_int bi
 | Ratio r -> int_of_ratio r
 
+let int_of_num_opt = function
+  Int i -> Some i
+| Big_int bi -> int_of_big_int_opt bi
+| Ratio r -> (try Some (int_of_ratio r) with Failure _ -> None)
+
 and num_of_int i =
   if i = monster_int
   then Big_int (big_int_of_int i)
@@ -370,12 +375,18 @@ and num_of_nat nat =
   then Int (nth_digit_nat nat 0)
   else Big_int (big_int_of_nat nat)
 
+let nat_of_num_opt x =
+  try Some (nat_of_num x) with Failure _ -> None
+
 (* Coercion with big_int type *)
 let big_int_of_num = function
   Int i -> big_int_of_int i
 | Big_int bi -> bi
 | Ratio r -> big_int_of_ratio r
 
+let big_int_of_num_opt x =
+  try Some (big_int_of_num x) with Failure _ -> None
+
 let string_of_big_int_for_num bi =
   if !approx_printing_flag
      then approx_big_int !floating_precision bi
@@ -389,6 +400,7 @@ let string_of_normalized_num = function
 | Ratio r -> string_of_ratio r
 let string_of_num n =
     string_of_normalized_num (cautious_normalize_num_when_printing n)
+
 let num_of_string s =
   try
     let flag = !normalize_ratio_flag in
@@ -401,6 +413,9 @@ let num_of_string s =
   with Failure _ ->
     failwith "num_of_string"
 
+let num_of_string_opt s =
+  try Some (num_of_string s) with Failure _ -> None
+
 (* Coercion with float type *)
 let float_of_num = function
   Int i -> float i

otherlibs/num/num.mli

@@ -159,14 +159,27 @@ val num_of_string : string -> num
    Raise [Failure "num_of_string"] if the given string is not
    a valid representation of an integer *)
 
+val num_of_string_opt: string -> num option
+(** Convert a string to a number.
+    Return [None] if the given string is not
+    a valid representation of an integer.
+
+    @since 4.05
+*)
+
 (** {6 Coercions between numerical types} *)
 
+(* TODO: document the functions below (truncating behavior and error conditions). *)
+
 val int_of_num : num -> int
+val int_of_num_opt: num -> int option
 val num_of_int : int -> num
 val nat_of_num : num -> nat
+val nat_of_num_opt: num -> nat option
 val num_of_nat : nat -> num
 val num_of_big_int : big_int -> num
 val big_int_of_num : num -> big_int
+val big_int_of_num_opt: num -> big_int option
 val ratio_of_num : num -> ratio
 val num_of_ratio : ratio -> num
 val float_of_num : num -> float

otherlibs/threads/pervasives.ml

@@ -246,10 +246,21 @@ let bool_of_string = function
   | "false" -> false
   | _ -> invalid_arg "bool_of_string"
 
+let bool_of_string_opt = function
+  | "true" -> Some true
+  | "false" -> Some false
+  | _ -> None
+
 let string_of_int n =
   format_int "%d" n
 
 external int_of_string : string -> int = "caml_int_of_string"
+
+let int_of_string_opt s =
+  (* TODO: provide this directly as a non-raising primitive. *)
+  try Some (int_of_string s)
+  with Failure _ -> None
+
 external string_get : string -> int -> char = "%string_safe_get"
 
 let valid_float_lexem s =
@@ -267,6 +278,11 @@ let string_of_float f = valid_float_lexem (format_float "%.12g" f);;
 
 external float_of_string : string -> float = "caml_float_of_string"
 
+let float_of_string_opt s =
+  (* TODO: provide this directly as a non-raising primitive. *)
+  try Some (float_of_string s)
+  with Failure _ -> None
+
 (* List operations -- more in module List *)
 
 let rec ( @ ) l1 l2 =
@@ -563,7 +579,9 @@ let prerr_newline () = output_char stderr '\n'; flush stderr
 
 let read_line () = flush stdout; input_line stdin
 let read_int () = int_of_string(read_line())
+let read_int_opt () = int_of_string_opt(read_line())
 let read_float () = float_of_string(read_line())
+let read_float_opt () = float_of_string_opt(read_line())
 
 (* Operations on large files *)
 

stdlib/bytes.ml

@@ -116,7 +116,7 @@ let rec unsafe_blits dst pos sep seplen = function
 let concat sep = function
     [] -> empty
   | l -> let seplen = length sep in
-          unsafe_blits 
+          unsafe_blits
             (create (sum_lengths 0 seplen l))
             0 sep seplen l
 
@@ -226,11 +226,22 @@ let rec index_rec s lim i c =
 
 let index s c = index_rec s (length s) 0 c
 
+let rec index_rec_opt s lim i c =
+  if i >= lim then None else
+  if unsafe_get s i = c then Some i else index_rec_opt s lim (i + 1) c
+
+let index_opt s c = index_rec_opt s (length s) 0 c
+
 let index_from s i c =
   let l = length s in
   if i < 0 || i > l then invalid_arg "String.index_from / Bytes.index_from" else
   index_rec s l i c
 
+let index_from_opt s i c =
+  let l = length s in
+  if i < 0 || i > l then invalid_arg "String.index_from_opt / Bytes.index_from_opt" else
+  index_rec_opt s l i c
+
 let rec rindex_rec s i c =
   if i < 0 then raise Not_found else
   if unsafe_get s i = c then i else rindex_rec s (i - 1) c
@@ -243,6 +254,18 @@ let rindex_from s i c =
   else
     rindex_rec s i c
 
+let rec rindex_rec_opt s i c =
+  if i < 0 then None else
+  if unsafe_get s i = c then Some i else rindex_rec_opt s (i - 1) c
+
+let rindex_opt s c = rindex_rec_opt s (length s - 1) c
+
+let rindex_from_opt s i c =
+  if i < -1 || i >= length s then
+    invalid_arg "String.rindex_from_opt / Bytes.rindex_from_opt"
+  else
+    rindex_rec_opt s i c
+
 
 let contains_from s i c =
   let l = length s in

stdlib/bytes.mli

@@ -193,12 +193,22 @@ val index : bytes -> char -> int
 
     Raise [Not_found] if [c] does not occur in [s]. *)
 
+val index_opt: bytes -> char -> int option
+(** [index_opt s c] returns the index of the first occurrence of byte [c]
+    in [s] or [None] if [c] does not occur in [s].
+    @since 4.05 *)
+
 val rindex : bytes -> char -> int
 (** [rindex s c] returns the index of the last occurrence of byte [c]
     in [s].
 
     Raise [Not_found] if [c] does not occur in [s]. *)
 
+val rindex_opt: bytes -> char -> int option
+(** [rindex_opt s c] returns the index of the last occurrence of byte [c]
+    in [s] or [None] if [c] does not occur in [s].
+    @since 4.05 *)
+
 val index_from : bytes -> int -> char -> int
 (** [index_from s i c] returns the index of the first occurrence of
     byte [c] in [s] after position [i].  [Bytes.index s c] is
@@ -207,6 +217,14 @@ val index_from : bytes -> int -> char -> int
     Raise [Invalid_argument] if [i] is not a valid position in [s].
     Raise [Not_found] if [c] does not occur in [s] after position [i]. *)
 
+val index_from_opt: bytes -> int -> char -> int option
+(** [index_from _opts i c] returns the index of the first occurrence of
+    byte [c] in [s] after position [i] or [None] if [c] does not occur in [s] after position [i].
+    [Bytes.index_opt s c] is equivalent to [Bytes.index_from_opt s 0 c].
+
+    Raise [Invalid_argument] if [i] is not a valid position in [s].
+    @since 4.05 *)
+
 val rindex_from : bytes -> int -> char -> int
 (** [rindex_from s i c] returns the index of the last occurrence of
     byte [c] in [s] before position [i+1].  [rindex s c] is equivalent
@@ -215,6 +233,15 @@ val rindex_from : bytes -> int -> char -> int
     Raise [Invalid_argument] if [i+1] is not a valid position in [s].
     Raise [Not_found] if [c] does not occur in [s] before position [i+1]. *)
 
+val rindex_from_opt: bytes -> int -> char -> int option
+(** [rindex_from_opt s i c] returns the index of the last occurrence
+    of byte [c] in [s] before position [i+1] or [None] if [c] does not
+    occur in [s] before position [i+1].  [rindex_opt s c] is equivalent to
+    [rindex_from s (Bytes.length s - 1) c].
+
+    Raise [Invalid_argument] if [i+1] is not a valid position in [s].
+    @since 4.05 *)
+
 val contains : bytes -> char -> bool
 (** [contains s c] tests if byte [c] appears in [s]. *)