[BACKEND] Optional default in %array_at scripting function (#879)

As title

docs/source/config_reference/scripting/scripting_functions.rst

@@ -38,10 +38,11 @@ array_apply_fixed
 
 array_at
 ~~~~~~~~
-:spec: ``array_at(array: Array, idx: Integer) -> AnyArgument``
+:spec: ``array_at(array: Array, idx: Integer, default: Optional[AnyArgument]) -> AnyArgument``
 
 :description:
-  Return the element in the Array at index ``idx``.
+  Return the element in the Array at index ``idx``. If ``idx`` exceeds the array length,
+  either return ``default`` if provided or throw an error.
 
 array_contains
 ~~~~~~~~~~~~~~

src/ytdl_sub/script/functions/array_functions.py

@@ -73,12 +73,18 @@ class ArrayFunctions:
         return Array(output)
 
     @staticmethod
-    def array_at(array: Array, idx: Integer) -> AnyArgument:
+    def array_at(array: Array, idx: Integer, default: Optional[AnyArgument] = None) -> AnyArgument:
         """
         :description:
-          Return the element in the Array at index ``idx``.
+          Return the element in the Array at index ``idx``. If ``idx`` exceeds the array length,
+          either return ``default`` if provided or throw an error.
         """
-        return array.value[idx.value]
+        try:
+            return array.value[idx.value]
+        except IndexError:
+            if default is not None:
+                return default
+            raise
 
     @staticmethod
     def array_first(array: Array, fallback: AnyArgument) -> AnyArgument:

tests/unit/script/functions/test_array_functions.py

@@ -26,6 +26,14 @@ class TestArrayFunctions:
         output = single_variable_output("{%array_at(['a', 'b', 'c'], 1)}")
         assert output == "b"
 
+    def test_array_at_default(self):
+        output = single_variable_output("{%array_at(['a', 'b', 'c'], 30, 'd')}")
+        assert output == "d"
+
+    def test_array_at_error(self):
+        with pytest.raises(FunctionRuntimeException):
+            single_variable_output("{%array_at(['a', 'b', 'c'], 30)}")
+
     def test_array_flatten(self):
         output = single_variable_output("{%array_flatten(['a', ['b'], [['c']]])}")
         assert output == ["a", "b", "c"]

tests/unit/script/types/test_function.py

@@ -49,7 +49,11 @@ class TestFunction:
     @pytest.mark.parametrize(
         "function_str, expected_types, received_types",
         [
-            ("{%array_at({'a': 'dict?'}, 1)}", "array: Array, idx: Integer", "Map, Integer"),
+            (
+                "{%array_at({'a': 'dict?'}, 1)}",
+                "array: Array, idx: Integer, default: Optional[AnyArgument]",
+                "Map, Integer",
+            ),
             ("{%array_extend('not', 'array')}", "arrays: Array, ...", "String, String"),
             (
                 "{%replace('hi mom', 'mom', 'dad', 1, 0)}",