From d717eb537bcefc5f72296884925e82203d0285cd Mon Sep 17 00:00:00 2001
From: Hugo Locurcio <hugo.locurcio@hugo.pro>
Date: Fri, 27 Aug 2021 01:27:07 +0200
Subject: [PATCH] Add an `Array.pop_at()` method to pop an element at an
 arbitrary index

Negative indices are supported to pop an element relative from the end.
---
 core/array.cpp        | 31 ++++++++++++++++++++++++++++---
 core/array.h          |  1 +
 core/variant_call.cpp |  2 ++
 doc/classes/Array.xml |  8 ++++++++
 4 files changed, 39 insertions(+), 3 deletions(-)

diff --git a/core/array.cpp b/core/array.cpp
index 5183b5f99bc..f28f1b53409 100644
--- a/core/array.cpp
+++ b/core/array.cpp
@@ -363,8 +363,8 @@ void Array::push_front(const Variant &p_value) {
 
 Variant Array::pop_back() {
 	if (!_p->array.empty()) {
-		int n = _p->array.size() - 1;
-		Variant ret = _p->array.get(n);
+		const int n = _p->array.size() - 1;
+		const Variant ret = _p->array.get(n);
 		_p->array.resize(n);
 		return ret;
 	}
@@ -373,13 +373,38 @@ Variant Array::pop_back() {
 
 Variant Array::pop_front() {
 	if (!_p->array.empty()) {
-		Variant ret = _p->array.get(0);
+		const Variant ret = _p->array.get(0);
 		_p->array.remove(0);
 		return ret;
 	}
 	return Variant();
 }
 
+Variant Array::pop_at(int p_pos) {
+	if (_p->array.empty()) {
+		// Return `null` without printing an error to mimic `pop_back()` and `pop_front()` behavior.
+		return Variant();
+	}
+
+	if (p_pos < 0) {
+		// Relative offset from the end
+		p_pos = _p->array.size() + p_pos;
+	}
+
+	ERR_FAIL_INDEX_V_MSG(
+			p_pos,
+			_p->array.size(),
+			Variant(),
+			vformat(
+					"The calculated index %s is out of bounds (the array has %s elements). Leaving the array untouched and returning `null`.",
+					p_pos,
+					_p->array.size()));
+
+	const Variant ret = _p->array.get(p_pos);
+	_p->array.remove(p_pos);
+	return ret;
+}
+
 Variant Array::min() const {
 	Variant minval;
 	for (int i = 0; i < size(); i++) {
diff --git a/core/array.h b/core/array.h
index 562568872bf..caaa9f9db9e 100644
--- a/core/array.h
+++ b/core/array.h
@@ -90,6 +90,7 @@ public:
 	void push_front(const Variant &p_value);
 	Variant pop_back();
 	Variant pop_front();
+	Variant pop_at(int p_pos);
 
 	Array duplicate(bool p_deep = false) const;
 
diff --git a/core/variant_call.cpp b/core/variant_call.cpp
index 1c8f3af8858..f2deab56e84 100644
--- a/core/variant_call.cpp
+++ b/core/variant_call.cpp
@@ -559,6 +559,7 @@ struct _VariantCall {
 	VCALL_LOCALMEM1(Array, push_front);
 	VCALL_LOCALMEM0R(Array, pop_back);
 	VCALL_LOCALMEM0R(Array, pop_front);
+	VCALL_LOCALMEM1R(Array, pop_at);
 	VCALL_LOCALMEM1(Array, append);
 	VCALL_LOCALMEM1(Array, append_array);
 	VCALL_LOCALMEM1(Array, resize);
@@ -1892,6 +1893,7 @@ void register_variant_methods() {
 	ADDFUNC1R(ARRAY, BOOL, Array, has, NIL, "value", varray());
 	ADDFUNC0RNC(ARRAY, NIL, Array, pop_back, varray());
 	ADDFUNC0RNC(ARRAY, NIL, Array, pop_front, varray());
+	ADDFUNC1RNC(ARRAY, NIL, Array, pop_at, INT, "position", varray());
 	ADDFUNC0NC(ARRAY, NIL, Array, sort, varray());
 	ADDFUNC2NC(ARRAY, NIL, Array, sort_custom, OBJECT, "obj", STRING, "func", varray());
 	ADDFUNC0NC(ARRAY, NIL, Array, shuffle, varray());
diff --git a/doc/classes/Array.xml b/doc/classes/Array.xml
index 4aeb76f91bd..de600cfecc1 100644
--- a/doc/classes/Array.xml
+++ b/doc/classes/Array.xml
@@ -251,6 +251,14 @@
 				Returns the minimum value contained in the array if all elements are of comparable types. If the elements can't be compared, [code]null[/code] is returned.
 			</description>
 		</method>
+		<method name="pop_at">
+			<return type="Variant" />
+			<argument index="0" name="position" type="int" />
+			<description>
+				Removes and returns the element of the array at index [code]position[/code]. If negative, [code]position[/code] is considered relative to the end of the array. Leaves the array untouched and returns [code]null[/code] if the array is empty or if it's accessed out of bounds. An error message is printed when the array is accessed out of bounds, but not when the array is empty.
+				[b]Note:[/b] On large arrays, this method can be slower than [method pop_back] as it will reindex the array's elements that are located after the removed element. The larger the array and the lower the index of the removed element, the slower [method pop_at] will be.
+			</description>
+		</method>
 		<method name="pop_back">
 			<return type="Variant" />
 			<description>