Add stdlib function array.at_or (#1927)

* Add stdlib function array.at_or

This is to return value at given position of array or default in case
provided position is out of bound.

Co-authored-by: Yann Hamdaoui <yann.hamdaoui@gmail.com>

* Update manual snippets and snapshot tests

---------

Co-authored-by: Yann Hamdaoui <yann.hamdaoui@gmail.com>

cli/tests/snapshot/snapshots/snapshot__eval_stderr_array_range_reversed_indices.ncl.snap

@@ -4,9 +4,9 @@ expression: err
 ---
 error: contract broken by the caller of `range`
        invalid range
-    ┌─ <stdlib/std.ncl>:649:9
+    ┌─ <stdlib/std.ncl>:673:9
     │
-649 │       | std.contract.unstable.RangeFun Dyn
+673 │       | std.contract.unstable.RangeFun Dyn
     │         ---------------------------------- expected type
     │
     ┌─ [INPUTS_PATH]/errors/array_range_reversed_indices.ncl:3:19
@@ -21,5 +21,3 @@ note:
   │
 3 │ std.array.range 1 0
   │ ------------------- (1) calling range
-
-

cli/tests/snapshot/snapshots/snapshot__eval_stderr_array_range_step_negative_step.ncl.snap

@@ -4,9 +4,9 @@ expression: err
 ---
 error: contract broken by the caller of `range_step`
        invalid range step
-    ┌─ <stdlib/std.ncl>:624:9
+    ┌─ <stdlib/std.ncl>:648:9
     │
-624 │       | std.contract.unstable.RangeFun (std.contract.unstable.RangeStep -> Dyn)
+648 │       | std.contract.unstable.RangeFun (std.contract.unstable.RangeStep -> Dyn)
     │         ----------------------------------------------------------------------- expected type
     │
     ┌─ [INPUTS_PATH]/errors/array_range_step_negative_step.ncl:3:27
@@ -26,5 +26,3 @@ note:
   │
 3 │ std.array.range_step 0 10 (-1)
   │ ------------------------------ (1) calling range_step
-
-

core/stdlib/std.ncl

@@ -172,6 +172,30 @@
         "%
       = fun n l => %elem_at% l n,
 
+    at_or
+      : forall a. Number -> a -> Array a -> a
+      | std.number.Nat -> Dyn
+      | doc m%"
+          Retrieves the n-th element from an array, with indices starting at 0
+          or the provided value if the index is greater than the length of the
+          array.
+
+          # Examples
+
+          ```nickel
+          std.array.at_or 3 "default" [ "zero", "one", "two", "three" ] =>
+            "three"
+
+          std.array.at_or 3 "default" [ "zero", "one" ] =>
+            "default"
+          ```
+        "%
+      = fun n default_value array =>
+        if n < %length% array then
+          %elem_at% array n
+        else
+          default_value,
+
     concat
       : forall a. Array a -> Array a -> Array a
       | doc m%"

doc/manual/typing.md

@@ -588,9 +588,9 @@ calling to the statically typed `std.array.filter` from dynamically typed code:
 ```nickel #repl
 > std.array.filter (fun x => if x % 2 == 0 then x else null) [1,2,3,4,5,6]
 error: contract broken by the caller of `filter`
-    ┌─ <stdlib/std.ncl>:349:25
+    ┌─ <stdlib/std.ncl>:373:25
     │
-349 │       : forall a. (a -> Bool) -> Array a -> Array a
+373 │       : forall a. (a -> Bool) -> Array a -> Array a
     │                         ---- expected return type of a function provided by the caller
     │
     ┌─ <repl-input-6>:1:55