# NumberUtil

Kind of class: public class org.casalib.util none 02/14/09 Aaron Clinger, David Nelson, Mike Creighton org.casalib.util.NumberUtil 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.

## Class methods

value:Number) : String

Parameters:
value:
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

### 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```