NumberUtils

Kind of class:	class
Inherits from:	none
Author:	Arthur Clemens
Classpath:	org.asapframework.util.NumberUtils
File last modified:	Friday, 13 October 2006, 00:45:34

► View source

▼ Hide source

/*
Copyright 2005-2006 by the authors of asapframework

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.
*/

/**
Number utility functions.
@author Arthur Clemens
*/

class org.asapframework.util.NumberUtils {
    
    /**
    Creates a random number within a given range.
    @param inStartRange : lowest number of the range
    @param inEndRange : highest number of the range
    @return A new random number.
    @example
    This example creates a random number between 10 and 20:
    <code>
    var scale:Number = NumberUtils.randomInRange(10, 20);
    </code>
    */
    public static function randomInRange (inStartRange:Number, inEndRange:Number) : Number {
        var d:Number = inEndRange - inStartRange;
        return inStartRange + (d - Math.random() * d);
    }
    
    /**
    Creates a random number within a list of ranges.
    Pass a list of Arrays, each one separated by a comma.
    @return A new random number.
    @example
    This example creates a random number in between -45 and 40, or between 40 and 45:
    <code>
    var rotation:Number = NumberUtils.randomInRanges([-45, -40], [40, 45]);
    </code>
    */
    public static function randomInRanges (inRanges:Array) : Number {
        var args:Array = arguments;
        var item:Number = Math.floor(Math.random() * args.length);
        var range:Array = args[item];
        return NumberUtils.randomInRange(range[0], range[1]);
    }
    
    /**
    Truncates floating point digits.
    @param inNumber : the number to truncate
    @param inDigits : the number of digits to keep after truncating
    @return A new number with truncated floating point digits.
    @example
    <code>
    var pi:Number = 3.14159265;
    pi = NumberUtils.truncate(pi, 2);
    // 3.14
    </code>
    */
    public static function truncate (inNumber:Number, inDigits:Number) : Number {
        if (inDigits < 0) {
            return inNumber;
        }
        var n:Number = 1;
        while (inDigits--) {
            n *= 10;
        }
        return Math.round(inNumber * n) / n;
    }
    
    /**
    Finds the x value of a point on a sine curve, of which only the y value is known. The closest x value is returned. This will range from -1 pi to 1 pi.
    @param inFindValue: y value of point to find on the sine curve
    @param inMinValue: min y value (bottom) of the sine curve
    @param inMaxValue: max y value (top) of the sine curve
    @return The offset value as multiplier of pi.
    @implementationNote Calls {@link #normalizedValue}.
    @example
    <code>
    NumberUtils.piOffset(1, -1, 1); // 1.5707963267949 ( = 0.5 * Math.PI )
    </code>
    */
    public static function piOffset (inFindValue:Number,
                                     inMinValue:Number,
                                     inMaxValue:Number) : Number {
        return Math.asin( 2 * NumberUtils.normalizedValue(inFindValue, inMinValue, inMaxValue) - 1 );
    }
    
    /**
    Finds the normalized value (between 0 and 1) of the number inValueToNormalize, related to the normalized range, defined by lowest range value inMinValue and highest range value inMaxValue.
    Normalizes a value, making it a value between 0 and 1
    @param inValueToNormalize: value to normalize
    @param inMinValue: min value
    @param inMaxValue: max value
    @return The normalized y value: a value between 0 and 1.
    @example
    <code>
    NumberUtils.normalizedValue(25, 0, 100); // 0.25
    NumberUtils.normalizedValue(0, -1, 1); // 0.5
    </code>
    */
    public static function normalizedValue (inValueToNormalize:Number,
                                            inMinValue:Number,
                                            inMaxValue:Number) : Number {
        var f:Number = 1 / (inMaxValue - inMinValue);
        return f * (inValueToNormalize - inMinValue);
    }
    
    /**
    Calculates the angle of a vector.
    @param inDx : the x component of the vector
    @param inDy : the y component of the vector
    @return The the angle of the passed vector in degrees.
    */
    public static function angle (inDx:Number, inDy:Number) : Number {
        return Math.atan2(inDy, inDx) * 180/Math.PI;
    }
    
}

Number utility functions.

Summary

Class methods

randomInRange (inStartRange:Number, inEndRange:Number) : Number
- Creates a random number within a given range.
randomInRanges (inRanges:Array) : Number
- Creates a random number within a list of ranges.
truncate (inNumber:Number, inDigits:Number) : Number
- Truncates floating point digits.
piOffset (inFindValue:Number, inMinValue:Number, inMaxValue:Number) : Number
- Finds the x value of a point on a sine curve, of which only the y value is known.
normalizedValue (inValueToNormalize:Number, inMinValue:Number, inMaxValue:Number) : Number
- Finds the normalized value (between 0 and 1) of the number inValueToNormalize, related to the normalized range, defined by lowest range value inMinValue and highest range value inMaxValue.
angle (inDx:Number, inDy:Number) : Number
- Calculates the angle of a vector.

Class methods

angle

static function angle (

inDx:Number, inDy:Number) : Number

Calculates the angle of a vector.

Parameters:

inDx:

the x component of the vector

inDy:

the y component of the vector

Returns:

The the angle of the passed vector in degrees.

normalizedValue

static function normalizedValue (

inValueToNormalize:Number, inMinValue:Number, inMaxValue:Number) : Number

Finds the normalized value (between 0 and 1) of the number inValueToNormalize, related to the normalized range, defined by lowest range value inMinValue and highest range value inMaxValue.
Normalizes a value, making it a value between 0 and 1

Parameters:

inValueToNormalize:

value to normalize

inMinValue :

min value

inMaxValue :

max value

Returns:

The normalized y value: a value between 0 and 1.

Example:

NumberUtils.normalizedValue(25, 0, 100); // 0.25
NumberUtils.normalizedValue(0, -1, 1); // 0.5

piOffset

static function piOffset (

inFindValue:Number, inMinValue:Number, inMaxValue:Number) : Number

Finds the x value of a point on a sine curve, of which only the y value is known. The closest x value is returned. This will range from -1 pi to 1 pi.

Parameters:

inFindValue:

y value of point to find on the sine curve

inMinValue :

min y value (bottom) of the sine curve

inMaxValue :

max y value (top) of the sine curve

Returns:

The offset value as multiplier of pi.

Implementation note:

Calls normalizedValue.

Example:

NumberUtils.piOffset(1, -1, 1); // 1.5707963267949 ( = 0.5 * Math.PI )

randomInRange

static function randomInRange (

inStartRange:Number, inEndRange:Number) : Number

Creates a random number within a given range.

Parameters:

inStartRange:

lowest number of the range

inEndRange :

highest number of the range

Returns:

A new random number.

Example:

This example creates a random number between 10 and 20:

var scale:Number = NumberUtils.randomInRange(10, 20);

randomInRanges

static function randomInRanges (

inRanges:Array) : Number

Creates a random number within a list of ranges.
Pass a list of Arrays, each one separated by a comma.

Returns:

A new random number.

Example:

This example creates a random number in between -45 and 40, or between 40 and 45:
```
var rotation:Number = NumberUtils.randomInRanges([-45, -40], [40, 45]);
```

truncate

static function truncate (

inNumber:Number, inDigits:Number) : Number

Truncates floating point digits.

Parameters:

inNumber:

the number to truncate

inDigits:

the number of digits to keep after truncating

Returns:

A new number with truncated floating point digits.

Example:

var pi:Number = 3.14159265;
pi = NumberUtils.truncate(pi, 2);
// 3.14