Rename Stdlib functions from Exn to OrThrow

Author: DZakh

runtime/Stdlib_List.res

@@ -106,24 +106,28 @@ let head = x =>
   | list{x, ..._} => Some(x)
   }
 
-let headExn = x =>
+let headOrThrow = x =>
   switch x {
   | list{} => throw(Not_found)
   | list{x, ..._} => x
   }
 
+let headExn = headOrThrow
+
 let tail = x =>
   switch x {
   | list{} => None
   | list{_, ...xs} => Some(xs)
   }
 
-let tailExn = x =>
+let tailOrThrow = x =>
   switch x {
   | list{} => throw(Not_found)
   | list{_, ...t} => t
   }
 
+let tailExn = tailOrThrow
+
 let add = (xs, x) => list{x, ...xs}
 
 /* Assume `n >=0` */
@@ -156,13 +160,15 @@ let get = (x, n) =>
     nthAux(x, n)
   }
 
-let getExn = (x, n) =>
+let getOrThrow = (x, n) =>
   if n < 0 {
     throw(Not_found)
   } else {
     nthAuxAssert(x, n)
   }
 
+let getExn = getOrThrow
+
 let rec partitionAux = (p, cell, precX, precY) =>
   switch cell {
   | list{} => ()

runtime/Stdlib_List.resi

@@ -90,8 +90,29 @@ switch List.headExn(list{}) {
 - Raises an Error if list is empty.
 
 */
+@deprecated("Use `headOrThrow` instead")
 let headExn: list<'a> => 'a
 
+/**
+`headOrThrow(list)` same as [`head`](#head).
+
+## Examples
+
+```rescript
+List.headOrThrow(list{1, 2, 3})->assertEqual(1)
+
+switch List.headOrThrow(list{}) {
+| exception Not_found => assert(true)
+| _ => assert(false)
+}
+```
+
+## Exceptions
+
+- Raises an Error if list is empty.
+*/
+let headOrThrow: list<'a> => 'a
+
 /**
 `tail(list)` returns `None` if `list` is empty, otherwise it returns `Some(tail)`
 where `tail` is everything except the first element of `list`.
@@ -124,8 +145,25 @@ switch List.tailExn(list{}) {
 
 - Raises an Error if list is empty.
 */
+@deprecated("Use `tailOrThrow` instead")
 let tailExn: list<'a> => list<'a>
 
+/**
+  `tailOrThrow(list)` same as [`tail`](#tail).
+  Raises an Error if list is empty.
+
+  ## Examples
+  ```res
+  List.tailOrThrow(list{1, 2, 3})->assertEqual(list{2, 3})
+
+  switch List.tailOrThrow(list{}) {
+  | _ => Console.log("never happens")
+  | exception _ => Console.log("error")
+  }
+  ```
+*/
+let tailOrThrow: list<'a> => list<'a>
+
 /**
 `add(list, value)` adds a `value` to the beginning of list `list`.
 
@@ -177,8 +215,26 @@ switch abc->List.getExn(4) {
 
 - Raises an Error if `index` is larger than the length of list.
 */
+@deprecated("Use `getOrThrow` instead")
 let getExn: (list<'a>, int) => 'a
 
+/**
+  `getOrThrow(list, index)` same as [`get`](#get).
+  Raises an Error if `index` is larger than the length of list.
+
+  ## Examples
+  ```res
+  let abc = list{"A", "B", "C"}
+  abc->List.getOrThrow(1)->assertEqual("B")
+
+  switch abc->List.getOrThrow(4) {
+  | _ => Console.log("never happens")
+  | exception _ => Console.log("error")
+  }
+  ```
+*/
+let getOrThrow: (list<'a>, int) => 'a
+
 /**
 `make(length, value)` returns a list of length `length` with each element filled
 with `value`. Returns an empty list if `value` is negative.

runtime/Stdlib_Null.res

@@ -29,12 +29,14 @@ let getOr = (value, default) =>
 
 let getWithDefault = getOr
 
-let getExn: t<'a> => 'a = value =>
+let getOrThrow: t<'a> => 'a = value =>
   switch value->toOption {
   | Some(x) => x
-  | None => throw(Invalid_argument("Null.getExn: value is null"))
+  | None => throw(Invalid_argument("Null.getOrThrow: value is null"))
   }
 
+let getExn = getOrThrow
+
 external getUnsafe: t<'a> => 'a = "%identity"
 
 let forEach = (value, f) =>

runtime/Stdlib_Null.resi

@@ -120,10 +120,34 @@ switch Null.getExn(%raw("null")) {
 
 ## Exceptions
 
-- Raises `Invalid_argument` if `value` is `null`,
+- Raises `Invalid_argument` if `value` is `null`
 */
+@deprecated("Use `getOrThrow` instead")
 let getExn: t<'a> => 'a
 
+/**
+`getOrThrow(value)` raises an exception if `null`, otherwise returns the value.
+
+```rescript
+Null.getOrThrow(Null.make(3))->assertEqual(3)
+
+switch Null.getOrThrow(%raw("'ReScript'")) {
+| exception Invalid_argument(_) => assert(false)
+| value => assertEqual(value, "ReScript")
+}
+
+switch Null.getOrThrow(%raw("null")) {
+| exception Invalid_argument(_) => assert(true)
+| _ => assert(false)
+}
+```
+
+## Exceptions
+
+- Raises `Invalid_argument` if `value` is `null`
+*/
+let getOrThrow: t<'a> => 'a
+
 /**
 `getUnsafe(value)` returns `value`.
 

runtime/Stdlib_Nullable.res

@@ -32,12 +32,14 @@ let getOr = (value, default) =>
 
 let getWithDefault = getOr
 
-let getExn: t<'a> => 'a = value =>
+let getOrThrow: t<'a> => 'a = value =>
   switch value->toOption {
   | Some(x) => x
-  | None => throw(Invalid_argument("Nullable.getExn: value is null or undefined"))
+  | None => throw(Invalid_argument("Nullable.getOrThrow: value is null or undefined"))
   }
 
+let getExn = getOrThrow
+
 external getUnsafe: t<'a> => 'a = "%identity"
 
 let forEach = (value, f) =>

runtime/Stdlib_Nullable.resi

@@ -157,8 +157,35 @@ switch Nullable.getExn(%raw("undefined")) {
 
 - Raises `Invalid_argument` if `value` is `null` or `undefined`
 */
+@deprecated("Use `getOrThrow` instead")
 let getExn: t<'a> => 'a
 
+/**
+`getOrThrow(value)` raises an exception if `null` or `undefined`, otherwise returns the value.
+
+```rescript
+switch Nullable.getOrThrow(%raw("'Hello'")) {
+| exception Invalid_argument(_) => assert(false)
+| value => assertEqual(value, "Hello")
+}
+
+switch Nullable.getOrThrow(%raw("null")) {
+| exception Invalid_argument(_) => assert(true)
+| _ => assert(false)
+}
+
+switch Nullable.getOrThrow(%raw("undefined")) {
+| exception Invalid_argument(_) => assert(true)
+| _ => assert(false)
+}
+```
+
+## Exceptions
+
+- Raises `Invalid_argument` if `value` is `null` or `undefined`
+*/
+let getOrThrow: t<'a> => 'a
+
 /**
 `getUnsafe(value)` returns `value`.
 

runtime/Stdlib_Option.res

@@ -35,18 +35,20 @@ let forEach = (opt, f) =>
   | None => ()
   }
 
-let getExn = (x, ~message=?) =>
+let getOrThrow = (x, ~message=?) =>
   switch x {
   | Some(x) => x
   | None =>
     Stdlib_Error.panic(
       switch message {
-      | None => "Option.getExn called for None value"
+      | None => "Option.getOrThrow called for None value"
       | Some(message) => message
       },
     )
   }
 
+let getExn = getOrThrow
+
 external getUnsafe: option<'a> => 'a = "%identity"
 
 let mapOr = (opt, default, f) =>

runtime/Stdlib_Option.resi

@@ -91,8 +91,32 @@ switch Option.getExn(None, ~message="was None!") {
 
 - Raises an error if `opt` is `None`
 */
+@deprecated("Use `getOrThrow` instead")
 let getExn: (option<'a>, ~message: string=?) => 'a
 
+/**
+`getOrThrow(opt, ~message=?)` returns `value` if `opt` is `Some(value)`, otherwise raises an exception with the message provided, or a generic message if no message was provided.
+
+```rescript
+Option.getOrThrow(Some(3))->assertEqual(3)
+
+switch Option.getOrThrow(None) {
+| exception _ => assert(true)
+| _ => assert(false)
+}
+
+switch Option.getOrThrow(None, ~message="was None!") {
+| exception _ => assert(true) // Raises an Error with the message "was None!"
+| _ => assert(false)
+}
+```
+
+## Exceptions
+
+- Raises an error if `opt` is `None`
+*/
+let getOrThrow: (option<'a>, ~message: string=?) => 'a
+
 /**
 `getUnsafe(opt)` returns `value` if `opt` is `Some(value)`, otherwise `undefined`.