as3-commons language components 1.0 source.

ArrayUtils.as

@@ -0,0 +1,196 @@
+/*
+ * Copyright 2007-2009 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.as3commons.lang {
+
+	/**
+	 * Contains utility methods for working with Array objects.
+	 *
+	 * @author Christophe Herreman
+	 * @author Simon Wacker
+	 * @author Martin Heidegger
+	 */
+	public class ArrayUtils {
+
+		/**
+		 * Clones an array.
+		 *
+		 * @param array the array to clone
+		 * @return a clone of the passed-in <code>array</code>
+		 */
+		public static function clone(array:Array):Array {
+			return array.concat();
+		}
+
+		/**
+		 * Shuffles the items of the given <code>array</code>
+		 *
+		 * @param array the array to shuffle
+		 */
+		public static function shuffle(array:Array):void {
+			var len:Number = array.length;
+			var rand:Number;
+			var temp:*;
+
+			for (var i:Number = len - 1; i >= 0; i--) {
+				rand = Math.floor(Math.random() * len);
+				temp = array[i];
+				array[i] = array[rand];
+				array[rand] = temp;
+			}
+		}
+
+		/**
+		 * Removes all occurances of a the given <code>item</code> out of the passed-in
+		 * <code>array</code>.
+		 *
+		 * @param array the array to remove the item out of
+		 * @param item the item to remove
+		 * @return List that contains the index of all removed occurances
+		 */
+		public static function removeItem(array:Array, item:*):Array {
+			var i:Number = array.length;
+			var result:Array = [];
+
+			while (--i - (-1)) {
+				if (array[i] === item) {
+					result.unshift(i);
+					array.splice(i, 1);
+				}
+			}
+			return result;
+		}
+
+		/**
+		 * Removes the last occurance of the given <code>item</code> out of the passed-in
+		 * <code>array</code>.
+		 *
+		 * @param array the array to remove the item out of
+		 * @param item the item to remove
+		 * @return <code>-1</code> if it could not be found, else the position where it has been deleted
+		 */
+		public static function removeLastOccurance(array:Array, item:*):Number {
+			var i:Number = array.length;
+
+			while (--i - (-1)) {
+				if (array[i] === item) {
+					array.splice(i, 1);
+					return i;
+				}
+			}
+			return -1;
+		}
+
+		/**
+		 * Removes the first occurance of the given <code>item</code> out of the passed-in
+		 * <code>array</code>.
+		 *
+		 * @param array the array to remove the item out of
+		 * @param item the item to remove
+		 * @return <code>-1</code> if it could not be found, else the position where it has been deleted
+		 */
+		public static function removeFirstOccurance(array:Array, item:*):Number {
+			var l:Number = array.length;
+			var i:Number = 0;
+
+			while (i < l) {
+				if (array[i] === item) {
+					array.splice(i, 1);
+					return i;
+				}
+				i -= -1;
+			}
+			return -1;
+		}
+
+		/**
+		 * Compares the two arrays <code>array1</code> and <code>array2</code>, whether they contain
+		 * the same values at the same positions.
+		 *
+		 * @param array1 the first array for the comparison
+		 * @param array2 the second array for the comparison
+		 * @return <code>true</code> if the two arrays contain the same values at the same
+		 * positions else <code>false</code>
+		 */
+		public static function isSame(array1:Array, array2:Array):Boolean {
+			var i:Number = array1.length;
+
+			if (i != array2.length) {
+				return false;
+			}
+
+			while (--i - (-1)) {
+				if (array1[i] !== array2[i]) {
+					return false;
+				}
+			}
+			return true;
+		}
+
+		/**
+		 * Returns all items of the given array that of the given type.
+		 *
+		 * @param items the array that contains the items to look in
+		 * @param type the class that the items should match
+		 * @return a new array with all items that match the given class
+		 */
+		public static function getItemsByType(items:Array, type:Class):Array {
+			var result:Array = [];
+
+			for (var i:int = 0; i < items.length; i++) {
+				if (items[i] is type) {
+					result.push(items[i]);
+				}
+			}
+			return result;
+		}
+
+		/**
+		 * Returns the index of the given item in the array based on equality via the equals method
+		 * of the IEquals interface.
+		 *
+		 * <p>If either the array or the item are null, -1 is returned.</p>
+		 *
+		 * @param array the array to search for the index of the item
+		 * @param item the item to search for
+		 * @return The index of the item, or -1 if the item was not found or if either the array or the item are null
+		 */
+		public static function indexOfEquals(array:Array, item:IEquals):int {
+			if (!array || !item) {
+				return -1;
+			}
+
+			var numItems:int = array.length;
+
+			for (var i:int = 0; i < numItems; i++) {
+				if (item.equals(array[i])) {
+					return i;
+				}
+			}
+			return -1;
+		}
+
+		/**
+		 * Returns a string from the given array, using the specified separator.
+		 *
+		 * @param array the array from which to return a string
+		 * @param separator the array element separator
+		 * @return a string representation of the given array
+		 */
+		public static function toString(array:Array, separator:String = ", "):String {
+			return (!array) ? "" : array.join(separator);
+		}
+	}
+}

Assert.as

@@ -0,0 +1,175 @@
+/*
+ * Copyright 2007-2009 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.as3commons.lang {
+
+	import flash.utils.Dictionary;
+
+	/**
+	 * Assertion utility class that assists in validating arguments.
+	 * Useful for identifying programmer errors early and clearly at runtime.
+	 *
+	 * @author Christophe Herreman
+	 */
+	public class Assert {
+
+		/**
+		 * Asserts a boolean expression to be <code>true</code>.
+		 * <pre class="code">Assert.isTrue(value, "The expression must be true");</pre>
+		 * @param expression a boolean expression
+		 * @param message the error message to use if the assertion fails
+		 * @throws org.as3commons.lang.IllegalArgumentError if the expression is not <code>true</code>
+		 */
+		public static function isTrue(expression:Boolean, message:String = ""):void {
+			if (!expression) {
+				if (message == "" || message == null) {
+					message = "[Assertion failed] - this expression must be true";
+				}
+				throw new IllegalArgumentError(message);
+			}
+		}
+
+		/**
+		 * Assert that an object is <code>null</code>.
+		 * <pre class="code">Assert.isNull(value, "The value must be null");</pre>
+		 * @param object the object to check
+		 * @param message the error message to use if the assertion fails
+		 * @throws org.as3commons.lang.IllegalArgumentError if the object is not <code>null</code>
+		 */
+		public static function notNull(object:Object, message:String = ""):void {
+			if (object == null) {
+				if (message == "" || message == null) {
+					message = "[Assertion failed] - this argument is required; it must not null";
+				}
+				throw new IllegalArgumentError(message);
+			}
+		}
+
+		/**
+		 * Assert that an object is an instance of a certain type..
+		 * <pre class="code">Assert.instanceOf(value, type, "The value must be an instance of 'type'");</pre>
+		 * @param object the object to check
+		 * @param message the error message to use if the assertion fails
+		 * @throws org.as3commons.lang.IllegalArgumentError if the object is not an instance of the given type
+		 */
+		public static function instanceOf(object:*, type:Class, message:String = ""):void {
+			if (!(object is type)) {
+				if (message == "" || message == null) {
+					message = "[Assertion failed] - this argument is not of type '" + type + "'";
+				}
+				throw new IllegalArgumentError(message);
+			}
+		}
+
+		/**
+		 * Asserts that a class is a subclass of another class.
+		 */
+		public static function subclassOf(clazz:Class, parentClass:Class, message:String = ""):void {
+			if (!ClassUtils.isSubclassOf(clazz, parentClass)) {
+				if (message == "" || message == null) {
+					message = "[Assertion failed] - this argument is not a subclass of '" + parentClass + "'";
+				}
+				throw new IllegalArgumentError(message);
+			}
+		}
+
+		/**
+		 * Assert that an object implements a certain interface.
+		 */
+		public static function implementationOf(object:*, interfaze:Class, message:String = ""):void {
+			if (!ClassUtils.isImplementationOf(ClassUtils.forInstance(object), interfaze)) {
+				if (message == "" || message == null) {
+					message = "[Assertion failed] - this argument does not implement the interface '" + interfaze + "'";
+				}
+				throw new IllegalArgumentError(message);
+			}
+		}
+
+		/**
+		 * Assert a boolean expression to be true. If false, an IllegalStateError is thrown.
+		 * @param expression a boolean expression
+		 * @param the error message if the assertion fails
+		 */
+		public static function state(expression:Boolean, message:String = ""):void {
+			if (!expression) {
+				if (message == "" || message == null) {
+					message = "[Assertion failed] - this state invariant must be true";
+				}
+				throw new IllegalStateError(message);
+			}
+		}
+
+		/**
+		 * Assert that the given String has valid text content; that is, it must not
+		 * be <code>null</code> and must contain at least one non-whitespace character.
+		 *
+		 * @param text the String to check
+		 * @param message the exception message to use if the assertion fails
+		 * @see StringUtils#hasText
+		 */
+		public static function hasText(string:String, message:String = ""):void {
+			if (StringUtils.isBlank(string)) {
+				if (message == "" || message == null) {
+					message = "[Assertion failed] - this String argument must have text; it must not be <code>null</code>, empty, or blank";
+				}
+				throw new IllegalArgumentError(message);
+			}
+		}
+
+		/**
+		 * Assert that the given Dictionary contains only keys of the given type.
+		 */
+		public static function dictionaryKeysOfType(dictionary:Dictionary, type:Class, message:String = ""):void {
+			for (var key:Object in dictionary) {
+				if (!(key is type)) {
+					if (message == "" || message == null) {
+						message = "[Assertion failed] - this Dictionary argument must have keys of type '" + type + "'";
+					}
+					throw new IllegalArgumentError(message);
+				}
+			}
+		}
+
+		/**
+		 * Assert that the array contains the passed in item.
+		 */
+		public static function arrayContains(array:Array, item:*, message:String = ""):void {
+			if (array.indexOf(item) == -1) {
+				if (message == "" || message == null) {
+					message = "[Assertion failed] - this Array argument does not contain the item '" + item + "'";
+				}
+				throw new IllegalArgumentError(message);
+			}
+		}
+
+		/**
+		 * Assert that all items in the array are of the given type.
+		 *
+		 * @param array the array to check
+		 * @param type the type of the array items
+		 * @param message the error message to use if the assertion fails
+		 */
+		public static function arrayItemsOfType(array:Array, type:Class, message:String = ""):void {
+			for each (var item:*in array) {
+				if (!(item is type)) {
+					if (message == "" || message == null) {
+						message = "[Assertion failed] - this Array must have items of type '" + type + "'";
+					}
+					throw new IllegalArgumentError(message);
+				}
+			}
+		}
+	}
+}