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)
@@ -146,7 +156,7 @@ return {
 
 	fromPolar       = fromPolar,
 	toPolar         = toPolar,
-	random    = random,
+	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)
@@ -203,7 +211,7 @@ end
 return setmetatable({
 	new             = new,
 	fromPolar       = fromPolar,
-	random    = random,
+	randomDirection = randomDirection,
 	isvector        = isvector,
 	zero            = zero
 }, {