Numeric Utilities Reference

Related documents

• MVCS index

Table of contents

• Introduction
• Functions
  • addAverage()
  • adjust360()
  • angleDiff()
  • average()
  • clamp()
  • epsilonEqual()
  • fmtNum()
  • fmtRange()
  • getDigit()
  • getDigits()
  • iDigits()
  • integrate()
  • interpolate()
  • isAngleIn()
  • isApproximately()
  • isBetween()
  • isValidNumInputString()
  • lineLength()
  • round()
  • roundDown()
  • roundDownMult()
  • roundMult()
  • roundUp()
  • roundUpMult()
  • weightedAverage()
• Constants
  • EPSILON

Introduction

The numeric utility functions and constants are useful for manipulating numbers. All utility functions and constants are properties of the global/window object and may be used without importing.

Functions

addAverage()

Import

Global

Syntax

addAverage(avg, value)
addAverage(avg, value, n)

Add a new value to an average. If present, n is the total number of samples, including this one; it defaults to 1, in which case the result is value. Returns the updated average. For example:

avg = addAverage(avg, value, ++n)

Parameters

• avg
  A number. The average of the previous (n-1) numbers.
• value
  A number. The new value that will be accumulated in the average.
• n (optional)
  A number. If omitted, 1 is assumed. The count of numbers in the average, including the new value.

Return value

A number. The updated average.

adjust360()

Import

Global

Syntax

adjust360(deg)

Return deg adjusted so that the angle is equivalent and > 0 but ≤ 360.

Parameters

• deg
  A number in degrees.

Return value

The adjusted number.

angleDiff()

Import

Global

Syntax

angleDiff(a, b)

Return the shortest angle difference in degrees (±180) from a to b. Positive values mean b is clockwise from a. Negative values mean b is counter-clockwise from a.

Parameters

• a
  A number in degrees.
• b
  A number in degrees.

Return value

A number in degrees between -180 and 180.

average()

Import

Global

Syntax

average(...args)

Returns the average of all the arguments. If there are no arguments, returns NaN.

Parameters

• args
  Numbers to average.

Return value

A number. The average of all the arguments, or NaN if there are none.

clamp()

Import

Global

Syntax

clamp(value, min, max)

Returns the value constrained to be within the range min to max.

Parameters

• value
  A number to clamp.
• min
  A number. The minimum returned value.
• max
  A number. The maximum returned value.

Return value

A number. The value clamped to be within the range min to max.

epsilonEqual()

Import

Global

Syntax

epsilonEqual(a, b)

Returns true if numbers a and b differ by less than EPSILON (strictly less than).

Parameters

• a
  A number.
• b
  A number.

Return value

A Boolean. True if the absolute difference between a and b is less than EPSILON.

fmtNum()

Import

Global

Syntax

fmtNum(num)
fmtNum(num, digits)

Returns num as a string with thousands separators. num is converted with Number() first; if the result is NaN, the string '-' is returned. If digits is present and greater than 0, then the result is rounded to that number of digits and that number of digits appear to the right of the decimal.

Parameters

• num
  A number, or a value that can be converted to one with Number().
• digits (optional)
  A non-negative integer number. The number of digits to the right of the decimal point. The default is 0.

Return value

A string containing the formatted num, or '-' if num is not a number.

fmtRange()

Import

Global

Syntax

fmtRange(start, end)
fmtRange(start, end, unit)
fmtRange(start, end, unit, sep)

Returns a string representing a numeric range from start to end. If unit is present, it is a string containing a unit abbreviation that is included in the range. If sep is present, it is a string containing a separator that is placed between the start and end values in the formatted range. The default separator is '-'. For example:

fmtRange(0, 10)

returns 0 - 10. If unit is present it is prefixed with a literal   (non-breaking space entity), unless unit is '%' or '"', in which case it is appended directly. For example:

fmtRange(0, 10, 'kg.', 'to')

returns 0 kg. to 10 kg.. If start is equal to end, then only the start and any unit is returned.

Parameters

• start
  A number. The start of the range.
• end
  A number. The end of the range.
• unit (optional)
  A string. A unit abbreviation to use with the start and end values.
• sep (optional)
  A string to use between the start and end values if they are different.

Return value

A string containing the formatted range.

getDigit()

Import

Global

Syntax

getDigit(value, digit)

Extracts a single decimal digit from value. A digit value of zero specifies the rightmost integer digit, increasing for digits to the left of the decimal point and decreasing for digits to the right of the decimal point. For example:

getDigit(12.34, -1) == 3

Parameters

• value
  The number to extract a digit from.
• digit
  An integer that specifies the position of the digit to the left (positive, higher order) or right (negative) of the decimal point. If digit is zero, it specifies the lowest-order integer digit.

Return value

An integer number.

getDigits()

Import

Global

Syntax

getDigits(value, digit, len)

Extracts decimal digits from value. A digit value of zero specifies the rightmost integer digit, increasing for digits to the left of the decimal point and decreasing for digits to the right of the decimal point. len specifies the number of digits to extract from the starting point moving right. For example:

getDigits(12.34, 1, 2) == 12

Parameters

• value
  The number to extract digits from.
• digit
  An integer that specifies the starting (highest-order) position of the digits to the left (positive) or right (negative) of the decimal point. If digit is zero, it specifies the lowest-order integer digit.
• len
  The number the number of digits to extract, including the starting point.

Return value

An integer number.

iDigits()

Import

Global

Syntax

iDigits(value)

Returns the number of integer digits in value, that is, the number of digits in the absolute value of value truncated to an integer. For example, iDigits(0.5) is 1. Returns NaN if value is not finite.

Parameters

• value
  The number to count the digits in.

Return value

An integer number, or NaN if value is not finite.

integrate()

Import

Global

Syntax

integrate(fn, from, to, incr)

Return the sum of a function over a numeric interval. The function fn(start, size) is called with a start value beginning at from, then is repeatedly called with new start values by adding incr to the last start value, stopping when the entire interval between from and to is covered. integrate() returns the sum of the values returned by calling fn().

The size argument to fn() indicates the size of the sub-interval. For all sub-intervals except the last, this is the incr value. If incr does not evenly divide the interval from from to to, then the last call to fn() will be the size of the partial sub-interval remaining.

The from value can be greater than the to value provided incr is negative.

Parameters

• fn
  A function to compute a summed value in an interval. The function has the signature fn(start, size). The parameters are:
  • start
    A number that's the starting value of the interval to compute the value of.
  • size
    The size of the sub-interval from start to the end of this sub-interval. All sub-intervals are of size incr except for the last, which may be less than incr if incr does not device the distance between the to and from values evenly.
    fn returns a numeric value to be added to the final summation.
• from
  A numeric value for the start of the summation interval.
• to
  A numeric value for the end of the summation interval.
• incr
  A numeric value for the increment between each summation point.

Return value

A number that's the sum of all the returned values of fn() for all sub-intervals.

interpolate()

Import

Global

Syntax

interpolate(x, x1, y1, x2, y2)

Returns the Y value associated with the x value by linearly interpolating a line on a two-dimensional plane between points (x1, y1) and (x2, y2). The x value must be between x1 and x2.

Parameters

• x
  The numeric X value of the point to interpolate.
• x1
  The X value of the start of the line.
• y1
  The Y value of the start of the line.
• x2
  The X value of the end of the line.
• y2
  The Y value of the end of the line.

Return value

The numeric Y value of the x value on a line between (x1, y1) and (x2, y2).

isAngleIn()

Import

Global

Syntax

isAngleIn(a, start, end)

Return true if angle a in degrees is between start moving clockwise to end.

Parameters

• a
  A number in degrees.
• start
  A number in degrees for the start of the angle interval.
• end
  A number in degrees for the end of the angle interval.

Return value

A Boolean that's true if a is in the angle between start moving clockwise to end.

isApproximately()

Import

Global

Syntax

isApproximately(value1, value2, ratio)

Returns true if value2 is within approximation bounds of value1. The test is abs(value1 - value2) <= value1 * ratio, so the approximation bounds are value1 ± (ratio * value1) only when value1 and ratio are non-negative. The result is always false if value1 or ratio is negative.

For example:

isApproximately(1, 1.1, 0.2) === true

Parameters

• value1
  The numeric value that's the base of the approximation interval.
• value2
  The numeric value to test being within the approximation interval.
• ratio
  The fraction of value1 that is the approximation bounds.

Return value

A boolean that's true if value2 falls within the approximation bounds of value1.

isBetween()

Import

Global

Syntax

isBetween(value, min, max)

Returns true if value is greater than or equal to min and less than or equal to max.

Parameters

• value
  The numeric value to test.
• min
  The minimum value in the range.
• max
  The maximum value in the range.

Return value

A boolean that's true if value falls within the specified range.

isValidNumInputString()

Import

Global

Syntax

isValidNumInputString(str)

Return true if the str string is valid number or a prefix of a valid number.

Parameters

• str
  A string to test.

Return value

A boolean.

lineLength()

Import

Global

Syntax

lineLength(x1, y1, x2, y2)

Returns the length of the line from (x1, y1) to (x2, y2).

Parameters

• x1
  The X value of the start of the line.
• y1
  The Y value of the start of the line.
• x2
  The X value of the end of the line.
• y2
  The Y value of the end of the line.

Return value

A number. The line length.

round()

Import

Global

Syntax

round(value)
round(value, digits)

If digits is zero or omitted, rounds to the nearest integer value. Otherwise, if digits is a positive integer, it rounds to the nearest digits places to the right of the decimal point. For example:

round(12.34, 1) === 12.3

If digits is a negative integer, it rounds to the nearest -digits places to the left of the decimal point. For example:

round(123.45, -1) === 120

Parameters

• value
  The value that is to be rounded.
• digits (optional)
  An integer number. If not present, zero is assumed. If zero, the value is rounded to the nearest integer. If positive, the value is rounded to the nearest digits places to the right of the decimal point. If negative, the value is rounded to the nearest -digits places to the left of the decimal point.

Return value

The rounded number.

roundDown()

Import

Global

Syntax

roundDown(value)
roundDown(value, digits)

If digits is zero or omitted, rounds down to the next integer value. Negative numbers round lower. For example:

roundDown(-12.34) === -13

If digits is a positive integer, it rounds down to the next digits places to the right of the decimal point. For example:

roundDown(12.34, 1) === 12.3

If digits is a negative integer, it rounds down to the next -digits places to the left of the decimal point. For example:

roundDown(123.45, -1) === 120

Parameters

• value
  The value that is to be rounded.
• digits (optional)
  An integer number. If not present, zero is assumed. If zero, the value is rounded down to the next lower integer. If positive, the value is rounded to the next lower digits places to the right of the decimal point. If negative, the value is rounded to the next lower -digits places to the left of the decimal point.

Return value

The rounded number.

roundDownMult()

Import

Global

Syntax

roundDownMult(value, mult)

Rounds down to the next multiple of mult. For example:

roundDownMult(123.45, 20) === 120

and

roundDownMult(123.45, .5) === 123

Parameters

• value
  The value that is to be rounded.
• mult
  The multiple to round to.

Return value

The rounded number.

roundMult()

Import

Global

Syntax

roundMult(value)
roundMult(value, mult)

Rounds to the nearest multiple of mult. If mult is 0, omitted, or 1, the result is Math.round(value). For example:

roundMult(123.45, 20) === 120

and

roundMult(123.45, .5) === 123.5

If mult is a string, it contains a number to be used as the multiple followed by a 'd', or 'u' to round up or down, respectively. For example:

roundMult(123.45, '20u') === 140

and

roundMult(123.45, '.5d') === 123

Parameters

• value
  The value that is to be rounded.
• mult (optional)
  The multiple to round to or a string containing the multiple to be rounded to followed by 'd', or 'u'. If 'd', then the function rounds down to the next lower multiple. If 'u', then the function rounds up to the next higher multiple. If the string only contains a number, then that number is used as the multiple. If mult is omitted, then mult is assumed to be 1.

Return value

The rounded number.

roundUp()

Import

Global

Syntax

roundUp(value)
roundUp(value, digits)

If digits is zero or omitted, rounds up to the next integer value. Negative numbers round higher. For example:

roundUp(-12.34) === -12

If digits is a positive integer, it rounds up to the next digits places to the right of the decimal point. For example:

roundUp(12.34, 1) === 12.4

If digits is a negative integer, it rounds up to the next -digits places to the left of the decimal point. For example:

roundUp(123.45, -1) === 130

Parameters

• value
  The value that is to be rounded.
• digits (optional)
  An integer number. If not present, zero is assumed. If zero, the value is rounded up to the next higher integer. If positive, the value is rounded to the next higher digits places to the right of the decimal point. If negative, the value is rounded to the next higher -digits places to the left of the decimal point.

Return value

The rounded number.

roundUpMult()

Import

Global

Syntax

roundUpMult(value, mult)

Rounds up to the next multiple of mult. For example:

roundUpMult(123.45, 20) === 140

and

roundUpMult(123.45, .5) === 123.5

Parameters

• value
  The value that is to be rounded.
• mult
  The multiple to round to.

Return value

The rounded number.

weightedAverage()

Import

Global

Syntax

weightedAverage(values, weights)

Returns the average of the numbers in the values array. Each value is weighted by the corresponding weight in the weights array. The weights do not need to add up to 1.

Parameters

• values
  An array of numbers to average.
• weights
  An array of numbers representing the weight of the corresponding value index.

Return value

A number. The weighted average of all the values.

Constants

Import

Global

EPSILON

The value used to assume rough equality in epsilonEqual(). This is a small number but quite a bit bigger than Number.MIN_VALUE. It is a practical smallest number for printed non-exponential fractions and is used to prevent useless arithmetic differences due to the way JavaScript numbers are represented.