Add vector.combine (#11920)

4 files changed, 20 insertions, 0 deletions

diff --git a/builtin/common/tests/vector_spec.lua b/builtin/common/tests/vector_spec.lua
index 25880236b..6a0b81a89 100644
--- a/builtin/common/tests/vector_spec.lua
+++ b/builtin/common/tests/vector_spec.lua
@@ -128,6 +128,14 @@ describe("vector", function()
 		assert.equal(vector.new(4.1, 5.9, 5.5), a:apply(f))
 	end)
 
+	it("combine()", function()
+		local a = vector.new(1, 2, 3)
+		local b = vector.new(3, 2, 1)
+		assert.equal(vector.add(a, b), vector.combine(a, b, function(x, y) return x + y end))
+		assert.equal(vector.new(3, 2, 3), vector.combine(a, b, math.max))
+		assert.equal(vector.new(1, 2, 1), vector.combine(a, b, math.min))
+	end)
+
 	it("equals()", function()
 		local function assertE(a, b)
 			assert.is_true(vector.equals(a, b))
diff --git a/builtin/common/vector.lua b/builtin/common/vector.lua
index 90010f6de..a08472e32 100644
--- a/builtin/common/vector.lua
+++ b/builtin/common/vector.lua
@@ -110,6 +110,14 @@ function vector.apply(v, func)
 	)
 end
 
+function vector.combine(a, b, func)
+	return fast_new(
+		func(a.x, b.x),
+		func(a.y, b.y),
+		func(a.z, b.z)
+	)
+end
+
 function vector.distance(a, b)
 	local x = a.x - b.x
 	local y = a.y - b.y
diff --git a/doc/client_lua_api.txt b/doc/client_lua_api.txt
index e3cc2dd16..d08cd9b5e 100644
--- a/doc/client_lua_api.txt
+++ b/doc/client_lua_api.txt
@@ -580,6 +580,7 @@ Spatial Vectors
 * `vector.floor(v)`: returns a vector, each dimension rounded down
 * `vector.round(v)`: returns a vector, each dimension rounded to nearest int
 * `vector.apply(v, func)`: returns a vector
+* `vector.combine(v, w, func)`: returns a vector
 * `vector.equals(v1, v2)`: returns a boolean
 
 For the following functions `x` can be either a vector or a number:
diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 339ce8a27..e95c5ced8 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -3409,6 +3409,9 @@ vectors are written like this: `(x, y, z)`:
 * `vector.apply(v, func)`:
     * Returns a vector where the function `func` has been applied to each
       component.
+* `vector.combine(v, w, func)`:
+	* Returns a vector where the function `func` has combined both components of `v` and `w`
+	  for each component
 * `vector.equals(v1, v2)`:
     * Returns a boolean, `true` if the vectors are identical.
 * `vector.sort(v1, v2)`: