Add Belt.List.getOrThrow, headOrThrow and tailOrThrow

Author: mediremi

CHANGELOG.md

@@ -53,6 +53,9 @@
   - `Belt.MutableMap.getExn` → `Belt.MutableMap.getOrThrow`
   - `Belt.Set.getExn` → `Belt.Set.getOrThrow`
   - `Belt.MutableSet.getExn` → `Belt.MutableSet.getOrThrow`
+  - `Belt.List.getExn` → `Belt.List.getOrThrow`
+  - `Belt.List.tailExn` → `Belt.List.tailOrThrow`
+  - `Belt.List.headExn` → `Belt.List.headOrThrow`
   - Old functions remain available but are marked as deprecated with guidance to use the new `OrThrow` variants.
   - https://github.com/rescript-lang/rescript/pull/7518, https://github.com/rescript-lang/rescript/pull/7554, https://github.com/rescript-lang/rescript/pull/7581
 

analysis/reanalyze/src/ExnLib.ml

@@ -10,7 +10,14 @@ let raisesLibTable : (Name.t, Exceptions.t) Hashtbl.t =
     ]
   in
   let beltList =
-    [("getExn", [notFound]); ("headExn", [notFound]); ("tailExn", [notFound])]
+    [
+      ("getExn", [notFound]);
+      ("getOrThrow", [notFound]);
+      ("headExn", [notFound]);
+      ("headOrThrow", [notFound]);
+      ("tailExn", [notFound]);
+      ("tailOrThrow", [notFound]);
+    ]
   in
   let beltMap = [("getExn", [notFound]); ("getOrThrow", [notFound])] in
   let beltMutableMap = beltMap in

runtime/Belt_List.res

@@ -86,24 +86,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` */
@@ -136,13 +140,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/Belt_List.resi

@@ -77,8 +77,26 @@ switch Belt.List.headExn(list{}) { // Raises an Error
 }
 ```
 */
+@deprecated("Use `headOrThrow` instead")
 let headExn: t<'a> => 'a
 
+/**
+Same as `Belt.List.head` but raises an exception if `someList` is empty. Use
+with care.
+
+## Examples
+
+```rescript
+Belt.List.headOrThrow(list{1, 2, 3})->assertEqual(1)
+
+switch Belt.List.headOrThrow(list{}) { // Raises an Error
+| exception _ => assert(true)
+| _ => assert(false)
+}
+```
+*/
+let headOrThrow: t<'a> => 'a
+
 /**
 Returns `None` if `someList` is empty, otherwise it returns `Some(tail)`
 where `tail` is everything except the first element of `someList`.
@@ -108,8 +126,26 @@ switch Belt.List.tailExn(list{}) { // Raises an Error
 }
 ```
 */
+@deprecated("Use `tailOrThrow` instead")
 let tailExn: t<'a> => t<'a>
 
+/**
+Same as `Belt.List.tail` but raises an exception if `someList` is empty. Use
+with care.
+
+## Examples
+
+```rescript
+Belt.List.tailOrThrow(list{1, 2, 3})->assertEqual(list{2, 3})
+
+switch Belt.List.tailOrThrow(list{}) { // Raises an Error
+| exception _ => assert(true)
+| _ => assert(false)
+}
+```
+*/
+let tailOrThrow: t<'a> => t<'a>
+
 /**
 Adds `value` to the beginning of `someList`.
 
@@ -156,8 +192,28 @@ switch abc->Belt.List.getExn(4) { // Raises an Error
 }
 ```
 */
+@deprecated("Use `getOrThrow` instead")
 let getExn: (t<'a>, int) => 'a
 
+/**
+Same as `Belt.List.get` but raises an exception if `index` is larger than the
+length. Use with care.
+
+## Examples
+
+```rescript
+let abc = list{"A", "B", "C"}
+
+abc->Belt.List.getOrThrow(1)->assertEqual("B")
+
+switch abc->Belt.List.getOrThrow(4) { // Raises an Error
+| exception _ => assert(true)
+| _ => assert(false)
+}
+```
+*/
+let getOrThrow: (t<'a>, int) => 'a
+
 /**
 Returns a list of length `numItems` with each element filled with value `v`. Returns an empty list if `numItems` is negative.