feat(sdk): add MutArray.popAt() and MutArray.removeFirst() to std…

… library (#3925)

Closes #3833

- [X] `MutArray.popAt()`
- [x] `MutArray.removeFirst()`

*By submitting this pull request, I confirm that my contribution is made under the terms of the [Wing Cloud Contribution License](https://github.com/winglang/wing/blob/main/CONTRIBUTION_LICENSE.md)*.

docs/docs/04-standard-library/02-std/api-reference.md

@@ -1099,7 +1099,9 @@ Mutable Array.
 | <code><a href="#@winglang/sdk.std.MutArray.join">join</a></code> | Returns a new string containing the concatenated values in this array, separated by commas or a specified separator string. |
 | <code><a href="#@winglang/sdk.std.MutArray.lastIndexOf">lastIndexOf</a></code> | Returns the index of the last occurrence of searchElement found. |
 | <code><a href="#@winglang/sdk.std.MutArray.pop">pop</a></code> | Remove value from end of array. |
+| <code><a href="#@winglang/sdk.std.MutArray.popAt">popAt</a></code> | Removes value from the given index of an array. |
 | <code><a href="#@winglang/sdk.std.MutArray.push">push</a></code> | Add value to end of array. |
+| <code><a href="#@winglang/sdk.std.MutArray.removeFirst">removeFirst</a></code> | Removes first occurence of a given value in an array. |
 | <code><a href="#@winglang/sdk.std.MutArray.set">set</a></code> | Sets a new value at the given index of an array. |
 
 ---
@@ -1241,6 +1243,22 @@ pop(): <T>
 
 Remove value from end of array.
 
+##### `popAt` <a name="popAt" id="@winglang/sdk.std.MutArray.popAt"></a>
+
+```wing
+popAt(index: num): <T>
+```
+
+Removes value from the given index of an array.
+
+###### `index`<sup>Required</sup> <a name="index" id="@winglang/sdk.std.MutArray.popAt.parameter.index"></a>
+
+- *Type:* num
+
+the index to remove the value at.
+
+---
+
 ##### `push` <a name="push" id="@winglang/sdk.std.MutArray.push"></a>
 
 ```wing
@@ -1257,6 +1275,22 @@ value to add.
 
 ---
 
+##### `removeFirst` <a name="removeFirst" id="@winglang/sdk.std.MutArray.removeFirst"></a>
+
+```wing
+removeFirst(value: <T>): bool
+```
+
+Removes first occurence of a given value in an array.
+
+###### `value`<sup>Required</sup> <a name="value" id="@winglang/sdk.std.MutArray.removeFirst.parameter.value"></a>
+
+- *Type:* <a href="#@winglang/sdk.std.T1">&lt;T&gt;</a>
+
+the value to remove.
+
+---
+
 ##### `set` <a name="set" id="@winglang/sdk.std.MutArray.set"></a>
 
 ```wing

examples/tests/sdk_tests/std/array.w

@@ -59,6 +59,39 @@ test "pushAndPop()" {
   assert(a.at(0) == "hello");
 }
 
+//-----------------------------------------------------------------------------
+// popAt()
+
+test "popAt()" {
+  let assertThrows = (expected: str, block: (): void) => {
+    let var error = false;
+    try {
+      block();
+    } catch actual {
+      assert(actual == expected);
+      error = true;
+    }
+    assert(error);
+  };
+
+  let INDEX_OUT_OF_BOUNDS_ERROR = "Index out of bounds";
+  let mutArr = MutArray<str>["hello", "world"];
+
+  let item = mutArr.popAt(0);
+
+  assert(item == "hello");
+  assert(mutArr.length == 1);
+  assert(mutArr.at(0) == "world");
+
+  assertThrows(INDEX_OUT_OF_BOUNDS_ERROR, () => {
+    mutArr.popAt(-3);
+  });
+
+  assertThrows(INDEX_OUT_OF_BOUNDS_ERROR, () => {
+    mutArr.popAt(3);
+  });
+}
+
 //-----------------------------------------------------------------------------
 // concat()
 let array = Array<str>["hello"];
@@ -307,4 +340,22 @@ test "insert()" {
 
   assert(mutArr.length == 5);
   assert(mutArr.at(4) == 25);
+}
+
+//-----------------------------------------------------------------------------
+// removeFirst()
+
+test "removeFirst()" {
+  let mutArr = MutArray<num>[3, 6, 9, 3];
+
+  let r1 = mutArr.removeFirst(3);
+
+  assert(r1 == true);
+  assert(mutArr.length == 3);
+  assert(mutArr == MutArray<num> [6, 9, 3]);
+
+  let r2 = mutArr.removeFirst(-42);
+
+  assert(r2 == false);
+  assert(mutArr.length == 3);
 }

libs/wingsdk/src/std/array.ts

@@ -250,6 +250,20 @@ export class MutArray {
     throw new Error("Abstract");
   }
 
+  /**
+   * Removes value from the given index of an array
+   *
+   * @macro ((obj, args) => { if (args[0] < 0 || args[0] >= $self$.length) throw new Error("Index out of bounds"); return obj.splice(args[0], 1)[0]; })($self$, [$args$])
+   *
+   * @param index the index to remove the value at
+   * @returns the value removed
+   * @throws index out of bounds error if the given index does not exist for the array
+   */
+  public popAt(index: number): T1 {
+    index;
+    throw new Error("Macro");
+  }
+
   /**
    * Sets a new value at the given index of an array
    *
@@ -279,4 +293,17 @@ export class MutArray {
     value;
     throw new Error("Macro");
   }
+
+  /**
+   * Removes first occurence of a given value in an array
+   *
+   * @macro ((obj, args) => { if (obj.indexOf(args[0]) !== -1) { obj.splice(obj.indexOf(args[0]), 1); return true; } return false; })($self$, [$args$])
+   *
+   * @param value the value to remove
+   * @returns true if value was removed
+   */
+  public removeFirst(value: T1): boolean {
+    value;
+    throw new Error("Macro");
+  }
 }