NumberUtil

Kind of class:public class
Package:org.casalib.util
Inherits from:none
Version:02/14/09
Author:Aaron Clinger, David Nelson, Mike Creighton
Classpath:org.casalib.util.NumberUtil
File last modified:Monday, 16 March 2009, 15:27:55
Provides utility functions for manipulating numbers.

Summary


Class methods
  • isEqual (val1:Number, val2:Number, precision:Number = 0) : Boolean
    • Determines if the two values are equal, with the option to define the precision.
  • min (val1:*, val2:*) : Number
    • Evaluates val1 and val2 and returns the smaller value.
  • max (val1:*, val2:*) : Number
    • Evaluates val1 and val2 and returns the larger value.
  • randomWithinRange (min:Number, max:Number) : Number
    • Creates a random number within the defined range.
  • randomIntegerWithinRange (min:int, max:int) : int
    • Creates a random integer within the defined range.
  • isEven (value:Number) : Boolean
    • Determines if the number is even.
  • isOdd (value:Number) : Boolean
    • Determines if the number is odd.
  • isInteger (value:Number) : Boolean
    • Determines if the number is an integer.
  • isPrime (value:Number) : Boolean
    • Determines if the number is prime.
  • roundDecimalToPlace (value:Number, place:uint) : Number
    • Rounds a number's decimal value to a specific place.
  • loopIndex (index:int, length:uint) : uint
    • Determines if index is included within the collection length otherwise the index loops to the beginning or end of the range and continues.
  • isBetween (value:Number, firstValue:Number, secondValue:Number) : Boolean
    • Determines if the value is included within a range.
  • constrain (value:Number, firstValue:Number, secondValue:Number) : Number
    • Determines if value falls within a range; if not it is snapped to the nearest range value.
  • createStepsBetween (begin:Number, end:Number, steps:Number) : Array
    • Creates evenly spaced numerical increments between two numbers.
  • interpolate (amount:Percent, minimum:Number, maximum:Number) : Number
    • Determines a value between two specified values.
  • normalize (value:Number, minimum:Number, maximum:Number) : Percent
    • Determines a percentage of a value in a given range.
  • map (value:Number, min1:Number, max1:Number, min2:Number, max2:Number) : Number
    • Maps a value from one coordinate space to another.
  • getWeightedAverage (value:Number, dest:Number, n:Number) : Number
    • Low pass filter alogrithm for easing a value toward a destination value.
  • format (value:Number, minLength:uint, thouDelim:String = null, fillChar:String = null) : String
    • Formats a number.
  • getOrdinalSuffix (value:int) : String
    • Finds the English ordinal suffix for the number given.
  • addLeadingZero (value:Number) : String
    • Adds a leading zero for numbers less than ten.

Class methods

addLeadingZero

public static function addLeadingZero (
value:Number) : String

Adds a leading zero for numbers less than ten.
Parameters:
value:
Number to add leading zero.
Returns:
  • Number as a String; if the number was less than ten the number will have a leading zero.
Example:
  • trace(NumberUtil.addLeadingZero(7)); // Traces 07
    trace(NumberUtil.addLeadingZero(11)); // Traces 11

constrain

public static function constrain (
value:Number, firstValue:Number, secondValue:Number) : Number

Determines if value falls within a range; if not it is snapped to the nearest range value.
Parameters:
value :
Number to determine if it is included in the range.
firstValue :
First value of the range.
secondValue:
Second value of the range.
Returns:
  • Returns either the number as passed, or its value once snapped to nearest range value.
Usage note:
  • The constraint values do not need to be in order.
Example:
  • trace(NumberUtil.constrain(3, 0, 5)); // Traces 3
    trace(NumberUtil.constrain(7, 0, 5)); // Traces 5

createStepsBetween

public static function createStepsBetween (
begin:Number, end:Number, steps:Number) : Array

Creates evenly spaced numerical increments between two numbers.
Parameters:
begin:
The starting value.
end :
The ending value.
steps:
The number of increments between the starting and ending values.
Returns:
  • Returns an Array composed of the increments between the two values.
Example:
  • trace(NumberUtil.createStepsBetween(0, 5, 4)); // Traces 1,2,3,4
    trace(NumberUtil.createStepsBetween(1, 3, 3)); // Traces 1.5,2,2.5

format

public static function format (
value:Number, minLength:uint, thouDelim:String = null, fillChar:String = null) : String

Formats a number.
Parameters:
value :
The number you wish to format.
minLength:
The minimum length of the number.
thouDelim:
The character used to seperate thousands.
fillChar :
The leading character used to make the number the minimum length.
Returns:
  • Returns the formated number as a String.
Example:
  • trace(NumberUtil.format(1234567, 8, ",")); // Traces 01,234,567

getOrdinalSuffix

public static function getOrdinalSuffix (
value:int) : String

Finds the English ordinal suffix for the number given.
Parameters:
value:
Number to find the ordinal suffix of.
Returns:
  • Returns the suffix for the number, 2 characters.
Example:
  • trace(32 + NumberUtil.getOrdinalSuffix(32)); // Traces 32nd

getWeightedAverage

public static function getWeightedAverage (
value:Number, dest:Number, n:Number) : Number

Low pass filter alogrithm for easing a value toward a destination value. Works best for tweening values when no definite time duration exists and when the destination value changes.

If (0.5 < n < 1), then the resulting values will overshoot (ping-pong) until they reach the destination value. When n is greater than 1, as its value increases, the time it takes to reach the destination also increases. A pleasing value for n is 5.
Parameters:
value:
The current value.
dest :
The destination value.
n :
The slowdown factor.
Returns:
  • The weighted average.

interpolate

public static function interpolate (
amount:Percent, minimum:Number, maximum:Number) : Number

Determines a value between two specified values.
Parameters:
amount :
The level of interpolation between the two values. If 0%, begin value is returned; if 100%, end value is returned.
minimum:
The lower value.
maximum:
The upper value.
Example:
  • trace(NumberUtil.interpolate(new Percent(0.5), 0, 10)); // Traces 5

isBetween

public static function isBetween (
value:Number, firstValue:Number, secondValue:Number) : Boolean

Determines if the value is included within a range.
Parameters:
value :
Number to determine if it is included in the range.
firstValue :
First value of the range.
secondValue:
Second value of the range.
Returns:
  • Returns true if the number falls within the range; otherwise false.
Usage note:
  • The range values do not need to be in order.
Example:
  • trace(NumberUtil.isBetween(3, 0, 5)); // Traces true
    trace(NumberUtil.isBetween(7, 0, 5)); // Traces false

isEqual

public static function isEqual (
val1:Number, val2:Number, precision:Number = 0) : Boolean

Determines if the two values are equal, with the option to define the precision.
Parameters:
val1 :
A value to compare.
val2 :
A value to compare.
precision:
The maximum amount the two values can differ and still be considered equal.
Returns:
  • Returns true the values are equal; otherwise false.
Example:
  • trace(NumberUtil.isEqual(3.042, 3, 0)); // Traces false
    trace(NumberUtil.isEqual(3.042, 3, 0.5)); // Traces true

isEven

public static function isEven (
value:Number) : Boolean

Determines if the number is even.
Parameters:
value:
A number to determine if it is divisible by 2.
Returns:
  • Returns true if the number is even; otherwise false.
Example:
  • trace(NumberUtil.isEven(7)); // Traces false
    trace(NumberUtil.isEven(12)); // Traces true

isInteger

public static function isInteger (
value:Number) : Boolean

Determines if the number is an integer.
Parameters:
value:
A number to determine if it contains no decimal values.
Returns:
  • Returns true if the number is an integer; otherwise false.
Example:
  • trace(NumberUtil.isInteger(13)); // Traces true
    trace(NumberUtil.isInteger(1.2345)); // Traces false

isOdd

public static function isOdd (
value:Number) : Boolean

Determines if the number is odd.
Parameters:
value:
A number to determine if it is not divisible by 2.
Returns:
  • Returns true if the number is odd; otherwise false.
Example:
  • trace(NumberUtil.isOdd(7)); // Traces true
    trace(NumberUtil.isOdd(12)); // Traces false

isPrime

public static function isPrime (
value:Number) : Boolean

Determines if the number is prime.
Parameters:
value:
A number to determine if it is only divisible by 1 and itself.
Returns:
  • Returns true if the number is prime; otherwise false.
Example:
  • trace(NumberUtil.isPrime(13)); // Traces true
    trace(NumberUtil.isPrime(4)); // Traces false

loopIndex

public static function loopIndex (
index:int, length:uint) : uint

Determines if index is included within the collection length otherwise the index loops to the beginning or end of the range and continues.
Parameters:
index :
Index to loop if needed.
length:
The total elements in the collection.
Returns:
  • A valid zero-based index.
Example:
  • var colors:Array = new Array("Red", "Green", "Blue");
    
    trace(colors[NumberUtil.loopIndex(2, colors.length)]); // Traces Blue
    trace(colors[NumberUtil.loopIndex(4, colors.length)]); // Traces Green
    trace(colors[NumberUtil.loopIndex(-6, colors.length)]); // Traces Red

map

public static function map (
value:Number, min1:Number, max1:Number, min2:Number, max2:Number) : Number

Maps a value from one coordinate space to another.
Parameters:
value:
Value from the input coordinate space to map to the output coordinate space.
min1 :
Starting value of the input coordinate space.
max1 :
Ending value of the input coordinate space.
min2 :
Starting value of the output coordinate space.
max2 :
Ending value of the output coordinate space.
Example:
  • trace(NumberUtil.map(0.75, 0, 1, 0, 100)); // Traces 75

max

public static function max (
val1:*, val2:*) : Number

Evaluates val1 and val2 and returns the larger value. Unlike Math.max this method will return the defined value if the other value is null or not a number.
Parameters:
val1:
A value to compare.
val2:
A value to compare.
Returns:
  • Returns the largest value, or the value out of the two that is defined and valid.
Example:
  • trace(NumberUtil.max(-5, null)); // Traces -5
    trace(NumberUtil.max(-5, "CASA")); // Traces -5
    trace(NumberUtil.max(-5, -13)); // Traces -5

min

public static function min (
val1:*, val2:*) : Number

Evaluates val1 and val2 and returns the smaller value. Unlike Math.min this method will return the defined value if the other value is null or not a number.
Parameters:
val1:
A value to compare.
val2:
A value to compare.
Returns:
  • Returns the smallest value, or the value out of the two that is defined and valid.
Example:
  • trace(NumberUtil.min(5, null)); // Traces 5
    trace(NumberUtil.min(5, "CASA")); // Traces 5
    trace(NumberUtil.min(5, 13)); // Traces 5

normalize

public static function normalize (
value:Number, minimum:Number, maximum:Number) : Percent

Determines a percentage of a value in a given range.
Parameters:
value :
The value to be converted.
minimum:
The lower value of the range.
maximum:
The upper value of the range.
Example:
  • trace(NumberUtil.normalize(8, 4, 20).decimalPercentage); // Traces 0.25

randomIntegerWithinRange

public static function randomIntegerWithinRange (
min:int, max:int) : int

Creates a random integer within the defined range.
Parameters:
min:
The minimum value the random integer can be.
min:
The maximum value the random integer can be.
Returns:
  • Returns a random integer within the range.

randomWithinRange

public static function randomWithinRange (
min:Number, max:Number) : Number

Creates a random number within the defined range.
Parameters:
min:
The minimum value the random number can be.
min:
The maximum value the random number can be.
Returns:
  • Returns a random number within the range.

roundDecimalToPlace

public static function roundDecimalToPlace (
value:Number, place:uint) : Number

Rounds a number's decimal value to a specific place.
Parameters:
value:
The number to round.
place:
The decimal place to round.
Returns:
  • Returns the value rounded to the defined place.
Example:
  • trace(NumberUtil.roundToPlace(3.14159, 2)); // Traces 3.14
    trace(NumberUtil.roundToPlace(3.14159, 3)); // Traces 3.142