From c030acfd7e286d0e35ffd9e2414e305bba6e22ed Mon Sep 17 00:00:00 2001
From: Starbeamrainbowlabs <sbrl@starbeamrainbowlabs.com>
Date: Mon, 27 Dec 2021 02:18:56 +0000
Subject: [PATCH] Vector3: add new .clamp() function

---
 .tests/Vector3/clamp.test.lua        | 100 +++++++++++++++++++++++++++
 worldeditadditions/utils/vector3.lua |  11 +++
 2 files changed, 111 insertions(+)
 create mode 100644 .tests/Vector3/clamp.test.lua

diff --git a/.tests/Vector3/clamp.test.lua b/.tests/Vector3/clamp.test.lua
new file mode 100644
index 0000000..a866e76
--- /dev/null
+++ b/.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)
diff --git a/worldeditadditions/utils/vector3.lua b/worldeditadditions/utils/vector3.lua
index c1d1f85..8558453 100644
--- a/worldeditadditions/utils/vector3.lua
+++ b/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.