Vector3: add new .clamp() function

.tests/Vector3/clamp.test.lua

@@ -0,0 +1,100 @@
+local Vector3 = require("worldeditadditions.utils.vector3")
+
+describe("Vector3.clamp", function()
+	it("should work by not changing values if it's already clamped", function()
+		local a = Vector3.new(5, 6, 7)
+		local pos1 = Vector3.new(0, 0, 0)
+		local pos2 = Vector3.new(10, 10, 10)
+		
+		local result = Vector3.clamp(a, pos1, pos2)
+		
+		assert.are.same(
+			Vector3.new(5, 6, 7),
+			result
+		)
+		
+		result.z = 999
+		
+		assert.are.same(Vector3.new(5, 6, 7), a)
+		assert.are.same(Vector3.new(0, 0, 0), pos1)
+		assert.are.same(Vector3.new(10, 10, 10), pos2)
+	end)
+	it("should work with positive vectors", function()
+		local a = Vector3.new(30, 3, 3)
+		local pos1 = Vector3.new(0, 0, 0)
+		local pos2 = Vector3.new(10, 10, 10)
+		
+		assert.are.same(
+			Vector3.new(10, 3, 3),
+			Vector3.clamp(a, pos1, pos2)
+		)
+	end)
+	it("should work with multiple positive vectors", function()
+		local a = Vector3.new(30, 99, 88)
+		local pos1 = Vector3.new(4, 4, 4)
+		local pos2 = Vector3.new(13, 13, 13)
+		
+		assert.are.same(
+			Vector3.new(13, 13, 13),
+			Vector3.clamp(a, pos1, pos2)
+		)
+	end)
+	it("should work with multiple positive vectors with an irregular defined region", function()
+		local a = Vector3.new(30, 99, 88)
+		local pos1 = Vector3.new(1, 5, 3)
+		local pos2 = Vector3.new(10, 15, 8)
+		
+		assert.are.same(
+			Vector3.new(10, 15, 8),
+			Vector3.clamp(a, pos1, pos2)
+		)
+	end)
+	it("should work with multiple negative vectors", function()
+		local a = Vector3.new(-30, -99, -88)
+		local pos1 = Vector3.new(4, 4, 4)
+		local pos2 = Vector3.new(13, 13, 13)
+		
+		assert.are.same(
+			Vector3.new(4, 4, 4),
+			Vector3.clamp(a, pos1, pos2)
+		)
+	end)
+	it("should work with multiple negative vectors with an irregular defined region", function()
+		local a = Vector3.new(-30, -99, -88)
+		local pos1 = Vector3.new(1, 5, 3)
+		local pos2 = Vector3.new(10, 15, 8)
+		
+		assert.are.same(
+			Vector3.new(1, 5, 3),
+			Vector3.clamp(a, pos1, pos2)
+		)
+	end)
+	it("should work with multiple negative vectors with an irregular defined region with mixed signs", function()
+		local a = Vector3.new(-30, -99, -88)
+		local pos1 = Vector3.new(-1, 5, 3)
+		local pos2 = Vector3.new(10, 15, 8)
+		
+		assert.are.same(
+			Vector3.new(-1, 5, 3),
+			Vector3.clamp(a, pos1, pos2)
+		)
+	end)
+	
+	
+	
+	
+	it("should return new Vector3 instances", function()
+		local a = Vector3.new(30, 3, 3)
+		local pos1 = Vector3.new(0, 0, 0)
+		local pos2 = Vector3.new(10, 10, 10)
+		
+		local result = Vector3.clamp(a, pos1, pos2)
+		assert.are.same(Vector3.new(10, 3, 3), result)
+		
+		result.y = 999
+		
+		assert.are.same(Vector3.new(30, 3, 3), a)
+		assert.are.same(Vector3.new(0, 0, 0), pos1)
+		assert.are.same(Vector3.new(10, 10, 10), pos2)
+	end)
+end)

worldeditadditions/utils/vector3.lua

@@ -295,6 +295,17 @@ function Vector3.is_contained(target, pos1, pos2)
 		and pos2.z >= target.z
 end
 
+--- Clamps the given point to fall within the region defined by 2 points.
+-- @param	a		Vector3		The target vector to clamp.
+-- @param	pos1	Vector3	pos1 of the defined region.
+-- @param	pos2	Vector3	pos2 of the defined region.
+-- @returns	Vector3	The target vector, clamped to fall within the defined region.
+function Vector3.clamp(a, pos1, pos2)
+	pos1, pos2 = Vector3.sort(pos1, pos2)
+	
+	return Vector3.min(Vector3.max(a, pos1), pos2)
+end
+
 
 --- Expands the defined region to include the given point.
 -- @param	target	Vector3	The target vector to include.