changed signature of random and added documentation

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)
 

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)
 

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,

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
 })