From b6c04082b02e62c6ebde18dcc63061311a7cdaae Mon Sep 17 00:00:00 2001
From: grunkgrunk <danielgrunkin@gmail.com>
Date: Fri, 3 Nov 2017 22:04:27 +0100
Subject: [PATCH] changed signature of random and added documentation

---
 docs/vector-light.rst | 16 ++++++++++++++++
 docs/vector.rst       | 15 +++++++++++++++
 vector-light.lua      | 20 +++++++++++++++-----
 vector.lua            | 22 +++++++++++++++-------
 4 files changed, 61 insertions(+), 12 deletions(-)

diff --git a/docs/vector-light.rst b/docs/vector-light.rst
index c326d15..7c9da56 100644
--- a/docs/vector-light.rst
+++ b/docs/vector-light.rst
@@ -92,6 +92,22 @@ Convert the vector to polar coordinates, i.e., the angle and the radius/lenth.
 
    vector.fromPolar(phase1+phase2, abs1*abs2)
 
+.. function:: vector.randomDirection(len_min, len_max)
+
+ :param number len_min: Minimum length of the vector.
+ :param number len_max: Maximum length of the vector.
+ :returns: ``x``, ``y``: A vector pointing in a random direction with a random length between len_min and len_max.
+
+**Examples**::
+   -- length is a random value between 1 and 5
+   x,y = vector.randomDirection(1,5)
+
+   -- length is 1
+   x,y = vector.randomDirection()
+
+   -- length is 100
+   x,y = vector.randomDirection(100)
+
 
 .. function:: vector.mul(s, x,y)
 
diff --git a/docs/vector.rst b/docs/vector.rst
index 4ea141e..6e5e509 100644
--- a/docs/vector.rst
+++ b/docs/vector.rst
@@ -114,6 +114,21 @@ The ``angle`` is measured against the vector (1,0), i.e., the x axis.
 
     a = vector.polar(math.pi,10)
 
+.. function:: vector.randomDirection(len_min, len_max)
+
+  :param number len_min: Minimum length of the vector.
+  :param number len_max: Maximum length of the vector.
+  :returns: A vector pointing in a random direction with a random length between len_min and len_max.
+
+**Examples**::
+    -- length is a random value between 1 and 5
+    rnd = vector.randomDirection(1,5)
+
+    -- length is 1
+    rnd = vector.randomDirection()
+
+    -- length is 100
+    rnd = vector.randomDirection(100)
 
 .. function:: vector.isvector(v)
 
diff --git a/vector-light.lua b/vector-light.lua
index 6a0b9eb..0818dcd 100644
--- a/vector-light.lua
+++ b/vector-light.lua
@@ -83,8 +83,18 @@ local function fromPolar(angle, radius)
 	return cos(angle)*radius, sin(angle)*radius
 end
 
-local function random()
-	return fromPolar(math.random()*2*math.pi)
+local function randomDirection(len_min, len_max)
+	len_min = len_min or 1
+	len_max = len_max or len_min
+
+	assert(len_max > 0, "randomDirection: len_max must be greater than zero")
+	assert(len_max >= len_min, "randomDirection: len_max must be greater than or equal to len_min")
+
+	local range = len_max - len_min
+	local rnd = math.random() * range
+
+	local x,y = fromPolar(math.random()*2*math.pi)
+	return x * (rnd + len_min), y * (rnd + len_min)
 end
 
 local function toPolar(x, y)
@@ -144,9 +154,9 @@ end
 return {
 	str = str,
 
-	fromPolar = fromPolar,
-	toPolar   = toPolar,
-	random    = random,
+	fromPolar       = fromPolar,
+	toPolar         = toPolar,
+	randomDirection = randomDirection,
 
 	-- arithmetic
 	mul    = mul,
diff --git a/vector.lua b/vector.lua
index 7eaf053..63da2d1 100644
--- a/vector.lua
+++ b/vector.lua
@@ -40,8 +40,16 @@ local function fromPolar(angle, radius)
 	return new(cos(angle) * radius, sin(angle) * radius)
 end
 
-local function random()
-	return fromPolar(math.random()*2*math.pi)
+local function randomDirection(len_min, len_max)
+	len_min = len_min or 1
+	len_max = len_max or len_min
+
+	assert(len_max > 0, "randomDirection: len_max must be greater than zero")
+	assert(len_max >= len_min, "randomDirection: len_max must be greater than or equal to len_min")
+
+	local range = len_max - len_min
+	local rnd = math.random() * range
+	return fromPolar(math.random()*2*math.pi) * (rnd + len_min)
 end
 
 local function isvector(v)
@@ -201,11 +209,11 @@ end
 
 -- the module
 return setmetatable({
-	new       = new,
-	fromPolar = fromPolar,
-	random    = random,
-	isvector  = isvector,
-	zero      = zero
+	new             = new,
+	fromPolar       = fromPolar,
+	randomDirection = randomDirection,
+	isvector        = isvector,
+	zero            = zero
 }, {
 	__call = function(_, ...) return new(...) end
 })