Merge branch 'feature/random'

src/nexus/IDisposable.as

@@ -0,0 +1,21 @@
+// Copyright 2012 Malachi Griffie <[email protected]>
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+package nexus
+{
+
+/**
+ * Use the Dispose method of this interface to explicitly release unmanaged resources in conjunction with
+ * the garbage collector. The consumer of an object can call this method when the object is no longer needed.
+ */
+public interface IDisposable
+{
+	/**
+	 * Performs tasks associated with freeing, releasing, or resetting unmanaged resources.
+	 */
+	function dispose():void;
+}
+
+}

src/nexus/math/IPRNG.as

@@ -0,0 +1,21 @@
+// Copyright 2012 Malachi Griffie <[email protected]>
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+package nexus.math
+{
+
+/**
+ * ...
+ */
+public interface IPRNG
+{
+	function get currentState():uint;
+
+	function get period():uint;
+
+	function next():uint;
+}
+
+}

src/nexus/math/ISeededPRNG.as

@@ -0,0 +1,18 @@
+// Copyright 2012 Malachi Griffie <[email protected]>
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+package nexus.math
+{
+
+/**
+ * ...
+ */
+public interface ISeededPRNG extends IPRNG
+{
+	function get seed():uint;
+	function set seed(value:uint):void;
+}
+
+}

src/nexus/math/LehmerGenerator.as

@@ -0,0 +1,58 @@
+// Copyright 2012 Malachi Griffie <[email protected]>
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+package nexus.math
+{
+
+import flash.utils.*;
+
+/**
+ * Variant on Linear Congruential Generator.
+ * @see http://en.wikipedia.org/wiki/Lehmer_random_number_generator
+ */
+public final class LehmerGenerator implements ISeededPRNG
+{
+	private var m_seed:uint;
+	private var m_currentState:uint;
+	private var m_numbersGenerated:int;
+
+	public function LehmerGenerator(seed:int=1)
+	{
+		this.seed = seed;
+	}
+
+	[Inline]
+	public final function get seed():uint { return m_seed; }
+	public final function set seed(value:uint):void
+	{
+		//if(value > 0 && value < 2147483647)
+		//{
+		m_seed = value;
+		m_currentState = m_seed;
+		m_numbersGenerated = 0;
+		//}
+		//else
+		//{
+			//throw new ArgumentError("Seed must be between 0 and 2147483647");
+		//}
+	}
+
+	[Inline]
+	public final function get currentState():uint { return m_currentState; }
+
+	[Inline]
+	public function get period():uint { return 2147483647 /*int.MAX_VALUE*/; }
+
+	[Inline]
+	public final function get numbersGenerated():int { return m_numbersGenerated; }
+
+	public function next():uint
+	{
+		++m_numbersGenerated;
+		return m_currentState = ((m_currentState * 16807) % 2147483647);
+		//return m_state = ((m_state * 279470273) % 4294967291);
+	}
+}
+}

src/nexus/math/NativeRandomGenerator.as

@@ -0,0 +1,34 @@
+// Copyright 2012 Malachi Griffie <[email protected]>
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+package nexus.math
+{
+
+import flash.utils.*;
+
+/**
+ * Random number generator using the built-in Math.random() function
+ */
+public final class NativeRandomGenerator implements IPRNG
+{
+	private var m_currentState:uint;
+
+	public function NativeRandomGenerator()
+	{
+
+	}
+
+	[Inline]
+	public function get period():uint { return 2147483647 /*int.MAX_VALUE*/; }
+
+	[Inline]
+	public final function get currentState():uint { return m_currentState; }
+
+	public function next():uint
+	{
+		return m_currentState = Math.random() * 2147483647;
+	}
+}
+}

src/nexus/math/Random.as

@@ -0,0 +1,128 @@
+// Copyright 2012 Malachi Griffie <[email protected]>
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+package nexus.math
+{
+
+import flash.utils.*;
+
+/**
+ * Given a random number generator, this class provides convenience methods for
+ * random number generation and other random operations.
+ */
+public class Random
+{
+	//--------------------------------------
+	//	CLASS CONSTANTS
+	//--------------------------------------
+
+	private static const s_random : Random = new Random(new NativeRandomGenerator());
+	public static function get instance():Random
+	{
+		return s_random;
+	}
+
+	//--------------------------------------
+	//	INSTANCE VARIABLES
+	//--------------------------------------
+
+	private var m_generator : IPRNG;
+
+	//--------------------------------------
+	//	CONSTRUCTOR
+	//--------------------------------------
+
+	public function Random(generator:IPRNG)
+	{
+		m_generator = generator;
+	}
+
+	//--------------------------------------
+	//	GETTER/SETTERS
+	//--------------------------------------
+
+	//--------------------------------------
+	//	PUBLIC INSTANCE METHODS
+	//--------------------------------------
+
+	/**
+	 * Generates a random floating point in the range [min, max).
+	 * If max is NaN, Infinity, or -Infinity, a number in the range [min, 1) is returned
+	 * If min is NaN, Infinity, or -Infinity, a number in the range [0, max) is returned
+	 * @param	min		The lowest value to return, inclusive
+	 * @param	max		The highest value to return, exclusive
+	 * @return A number in the range [min, max)
+	 */
+	public function float( min : Number = NaN, max : Number = NaN ) : Number
+	{
+		min = isNaN(min) || !isFinite(min) ? 0 : min;
+		max = isNaN(max) || !isFinite(max) ? 1 : max;
+		return ((m_generator.next() / m_generator.period) * (max - min)) + min;
+	}
+
+	/**
+	 * Generates a random integer in the range [min, max]
+	 * @param	min		The lowest value to return, inclusive
+	 * @param	max		The highest value to return, inclusive
+	 * @return A number in the range [min, max]
+	 */
+	public function integer( min : int = 1, max : int = int.MAX_VALUE ) : int
+	{
+		return Math.floor((m_generator.next() / m_generator.period) * (max - min + 1)) + min;
+	}
+
+	/**
+	 * Returns a random true/false value, with a 50% chance of either
+	 */
+	public function boolean() : Boolean
+	{
+		return (m_generator.next() / m_generator.period) < 0.5;
+	}
+
+	/**
+	 * Given a floating-point value, return either the value's floor or its ceiling
+	 * chosen randomly according to whether the value is closer to the floor or
+	 * the ceiling.
+	 * @example <code>randomRound(4.3)</code> should return 4 70% of the time
+	 * and 5 30% of the time.
+	 */
+	public function weightedRound( value : Number ) : int
+	{
+		var floor : int = Math.floor(value);
+		return (m_generator.next() / m_generator.period) > (value - floor) ? floor : floor + 1;
+	}
+
+	/**
+	 * Returns one of the items passed in at random.
+	 * @param items A vararg list of objects to choose from. If a single argument is passed, it
+	 * is assumed to be a Vector or Array (or otherwise have a <code>length</code> property and
+	 * be able to be accessed with the index operators).
+	 */
+	public function choice(...items):Object
+	{
+		var choice : int;
+		if(items.length == 1)
+		{
+			choice = integer(0, items[0].length - 1);
+			return items[0][choice];
+		}
+		else
+		{
+			choice = integer(0, items.length - 1);
+			return items[choice];
+		}
+	}
+
+	public function toString(verbose:Boolean=false):String
+	{
+		return "[Random" + m_generator + "]";
+	}
+
+	//--------------------------------------
+	//	PRIVATE & PROTECTED INSTANCE METHODS
+	//--------------------------------------
+}
+
+}

src/nexus/security/crypto/SHA1HashFunction.as

@@ -28,7 +28,6 @@ public class SHA1HashFunction implements IHashFunction
 	 */
 	public function hash(bytes:ByteArray):ByteArray
 	{
-		//would be really nice if the blooddy lib just returned a damn byte array
 		return ByteUtils.hexToBytes(SHA1.hashBytes(bytes));
 	}