bps::Decimal Class Reference

A class for decimal arithmetics. More...

Public Member Functions
Decimal	abs () const
Decimal	add (Mixed aOther) const
	Add two values and return result. More...
Decimal	ceil () const
	If the value is not integer, round up to next integer (towards +Infinity). More...
	Decimal ()
	Default constructor.
	Decimal (Mixed aValue)
	Initializing constructor. More...
Decimal	div (Mixed aOther) const
	Divide by other value and return result. More...
Decimal	down () const
	If the value is not integer, round down to next integer (towards 0). More...
Decimal	exp () const
	Calculate e to the power of this value and return the result. More...
Decimal	floor () const
	If the value is not integer, round down to next integer (towards -Infinity). More...
Decimal	idiv (Mixed aOther) const
	Divides this value by the other value and returns the integer part of the result. More...
Boolean	isEQ (Mixed aOther) const
	Compare with other value for equality. More...
Boolean	isFinite () const
	Check if value is neither infinite nor a NaN. More...
Boolean	isGE (Mixed aOther) const
	Compare if greater than or equal to other value. More...
Boolean	isGT (Mixed aOther) const
	Compare if greater than other value. More...
Boolean	isInfinite () const
	Check if value is infinite. More...
Boolean	isInteger () const
	Check if value is finite and has exponent=0. More...
Boolean	isLE (Mixed aOther) const
	Compare if less than or equal to other value. More...
Boolean	isLT (Mixed aOther) const
	Compare if less than other value. More...
Boolean	isNaN () const
	Check if value is not a number. More...
Boolean	isNE (Mixed aOther) const
	Compare with other value for un-equality. More...
Boolean	isNegative () const
	Check if value is negative. More...
Decimal	ln () const
	Calculate the natural logarithm (to base e) of this value and return the result. More...
Decimal	log10 () const
	Calculate the logarithm to base ten of this value and return the result. More...
Decimal	max (Mixed aOther) const
	Compare this value with the other and return the larger (nearer towards +Infinity). More...
Decimal	min (Mixed aOther) const
	Compare this value with the other and return the smaller (nearer towards -Infinity). More...
Decimal	mod (Mixed aOther) const
	Integer divide (see idiv) by other value and return remainder as result. More...
Decimal	mul (Mixed aOther) const
	Multiply with other value and return result. More...
Decimal	power (Mixed aOther) const
	Raises this value to the power of the other value and returns the result. More...
Decimal	rounded (Mixed aDecPlaces) const
	Round to an number of decimal places. More...
Decimal	sqrt () const
	Calculate the square root of this value and return the result. More...
Decimal	sub (Mixed aOther) const
	Subtract second value and return result. More...
String	toString () const
	Converts the value to a string. More...
String	toString (Number aDecPlaces, Number aMaxSize=36) const
	Converts a decimal value to a string of format [-]9.9. More...
Decimal	up () const
	If the value is not integer, round up to next integer (away from 0). More...

Static Public Attributes
static const Decimal	Pi = 3.141592653589793238462643383279502
	Ratio of the circumference of a circle to the diameter. More...

Properties
Number	value
	Value of the variable. More...

Detailed Description

A class for decimal arithmetics.

The arithmetic of the standard Number values in Javascript is mathematically correct, however for many applications the results are inconvenient. It becomes then an issue when real (non-integer) numbers are involved in calculations:

var x1 = 1000.43;
var y1 = 1000;
print(x1-y1);   // output: 0.42999999999995

Despite the result your computer is not broken, nor does it calculate inexact. The reason for this surprising output is that standard floating point works binary and with a finite number of digits, and there is a difference when the last digit must be rounded in calculations. Often you won't notice a delta like in the example above, but because it happens and gets multiplied with the number of operations, it's a serious problem even if the final result is rounded to few decimal places and so seems correct. But one day there could be a case where it is not.

And now the same calculation with the decimal class:

var x2 = bps.Decimal(1000.43);
var y2 = bps.Decimal(1000);
print(x2.sub(y2));   // output: 0.43 

USAGE HINTS

None of the regular methods change the variable value, only an assignment to the value property can change it. Also there is a technical difference between assigning to the variable, and assigning to the value property:

var a = bps.Decimal(3);
var b = bps.Decimal(9);
a.value = b;     // The value of the existing Decimal is changed to 9
a.value = 11;    // The value of the existing Decimal is changed to 11 
a = b;           // Variable a holds a new Decimal with value 9. The old Decimal is discarded.
a = 11;          // Variable a holds a new Number with value 11. The old Decimal is discarded.

Since the value stays unchanged by the regular methods, translating a calculation from Number to Decimal is easy, however the notation needs to be rearranged to emulate the use of brackets:

// Number example:
var n = 3;
print( 2 * (n + 5) );        // Output is 16, n is unchanged still 3
n = 2 * (n + 5);             // Now n is 16
 
// Same with Decimal:
var d = bps.Decimal(3);
print( d.add(5).mul(2) );    // Output is 16, d is unchanged still 3
d.value = d.add(5).mul(2);   // Now d is 16

Decimal's will automatically be converted to Number's in calculations using standard math operators, for example:

var x = bps.Decimal(-30);
var y = x + 10;        // y is a regular Number with value -20. 
x.value = 5 * 3;       // x still Decimal, but now with value 15.
print(x.toString(5));  // 15.00000
x = x * 2;             // now x is a Number with value 30.

While decimal arithmetic is best suited for commercial or financial purposes, binary arithmetic is faster because it is the native number representation for computers and is handled by hardware floating point processors. Decimal arithmetic would perform bad for heavy number crunching like in graphic libraries for example. (No rule without exception however: mainframes have decimal hardware processors, but you will most likely not use mainframes as client PC's).

IMPLEMENTATION AND CREDITS

Decimal uses IBM's decNumber library to implement a numeric variable according to the General Decimal Arithmetic Specification in ANSI C. This specification defines a decimal arithmetic which meets the requirements of commercial, financial, and human-oriented applications. It also matches the decimal arithmetic in the IEEE 754 Standard for Floating Point Arithmetic.

Decimal encapsulates decQuad and uses decimal128, a 128-bit decimal floating-point representation, to provide 34 decimal digits of precision in a compressed format. A Decimal variable occupies 16 bytes.

Many thanks to IBM and IBM Fellow Mike Cowlishaw from the UK Laboratories, for making decNumber package widely available under the terms of ICU v1.8.1.

Constructor & Destructor Documentation

Decimal()

bps::Decimal::Decimal

(

Mixed

aValue

)

Initializing constructor.

Parameters

aValue

A Number, Boolean or String with the initial value.

Member Function Documentation

abs()

Decimal bps::Decimal::abs

(

)

const

Returns

Absolute value.

add()

Decimal bps::Decimal::add

(

Mixed

aOther

)

const

Add two values and return result.

Parameters

[in]

aOther

The other value to add (a Decimal, Number, Boolean or String representing a number).

Returns

The result.

ceil()

Decimal bps::Decimal::ceil

(

)

const

If the value is not integer, round up to next integer (towards +Infinity).

Returns

Integer value.

div()

Decimal bps::Decimal::div

(

Mixed

aOther

)

const

Divide by other value and return result.

Parameters

[in]

aOther

The other value to divide by (a Decimal, Number, Boolean or String representing a number).

Returns

The result.

down()

Decimal bps::Decimal::down

(

)

const

If the value is not integer, round down to next integer (towards 0).

Returns

Integer value.

exp()

Decimal bps::Decimal::exp

(

)

const

Calculate e to the power of this value and return the result.

Returns

Result e ** this.

floor()

Decimal bps::Decimal::floor

(

)

const

If the value is not integer, round down to next integer (towards -Infinity).

Returns

Integer value.

idiv()

Decimal bps::Decimal::idiv

(

Mixed

aOther

)

const

Divides this value by the other value and returns the integer part of the result.

Parameters

[in]

aOther

The other value to divide by (a Decimal, Number, Boolean or String representing a number).

Returns

The result.

isEQ()

Boolean bps::Decimal::isEQ

(

Mixed

aOther

)

const

Compare with other value for equality.

Parameters

[in]

aOther

The other value to compare to (a Decimal, Number, Boolean or String representing a number).

Returns

True if equal, false if not equal.

isFinite()

Boolean bps::Decimal::isFinite

(

)

const

Check if value is neither infinite nor a NaN.

Returns

True if value is finite.

isGE()

Boolean bps::Decimal::isGE

(

Mixed

aOther

)

const

Compare if greater than or equal to other value.

Parameters

[in]

aOther

The other value to compare to (a Decimal, Number, Boolean or String representing a number).

Returns

True if greater or equal, false if less than other value.

isGT()

Boolean bps::Decimal::isGT

(

Mixed

aOther

)

const

Compare if greater than other value.

Parameters

[in]

aOther

The other value to compare to (a Decimal, Number, Boolean or String representing a number).

Returns

True if greater, false if less or equal other value.

isInfinite()

Boolean bps::Decimal::isInfinite

(

)

const

Check if value is infinite.

Returns

True if value is infinite.

isInteger()

Boolean bps::Decimal::isInteger

(

)

const

Check if value is finite and has exponent=0.

Returns

True if value is integer.

isLE()

Boolean bps::Decimal::isLE

(

Mixed

aOther

)

const

Compare if less than or equal to other value.

Parameters

[in]

aOther

The other value to compare to (a Decimal, Number, Boolean or String representing a number).

Returns

True if less or equal, false if greater than other value.

isLT()

Boolean bps::Decimal::isLT

(

Mixed

aOther

)

const

Compare if less than other value.

Parameters

[in]

aOther

The other value to compare to (a Decimal, Number, Boolean or String representing a number).

Returns

True if less, false if greater or equal other value.

isNaN()

Boolean bps::Decimal::isNaN

(

)

const

Check if value is not a number.

Returns

True if value is NaN.

isNE()

Boolean bps::Decimal::isNE

(

Mixed

aOther

)

const

Compare with other value for un-equality.

Parameters

[in]

aOther

The other value to compare to (a Decimal, Number, Boolean or String representing a number).

Returns

True if not equal, false if equal.

isNegative()

Boolean bps::Decimal::isNegative

(

)

const

Check if value is negative.

Returns

True if value is negative.

ln()

Decimal bps::Decimal::ln

(

)

const

Calculate the natural logarithm (to base e) of this value and return the result.

Returns

Natural logarithm of this value.

log10()

Decimal bps::Decimal::log10

(

)

const

Calculate the logarithm to base ten of this value and return the result.

Returns

Logarithm to base 10 of this value.

max()

Decimal bps::Decimal::max

(

Mixed

aOther

)

const

Compare this value with the other and return the larger (nearer towards +Infinity).

Parameters

[in]

aOther

The other value to compare (a Decimal, Number, Boolean or String representing a number).

Returns

Larger of the two values.

min()

Decimal bps::Decimal::min

(

Mixed

aOther

)

const

Compare this value with the other and return the smaller (nearer towards -Infinity).

Parameters

[in]

aOther

The other value to compare (a Decimal, Number, Boolean or String representing a number).

Returns

Smaller of the two values.

mod()

Decimal bps::Decimal::mod

(

Mixed

aOther

)

const

Integer divide (see idiv) by other value and return remainder as result.

Parameters

[in]

aOther

The other value to divide by (a Decimal, Number, Boolean or String representing a number).

Returns

The result.

mul()

Decimal bps::Decimal::mul

(

Mixed

aOther

)

const

Multiply with other value and return result.

Parameters

[in]

aOther

The other value to multiply (a Decimal, Number, Boolean or String representing a number).

Returns

The result.

power()

Decimal bps::Decimal::power

(

Mixed

aOther

)

const

Raises this value to the power of the other value and returns the result.

Parameters

[in]

aOther

The other value (a Decimal, Number, Boolean or String representing a number).

Returns

Result of this ** aOther.

rounded()

Decimal bps::Decimal::rounded

(

Mixed

aDecPlaces

)

const

Round to an number of decimal places.

Parameters

[in]

aDecPlaces

Number of decimal places to round to (a Decimal, Number, Boolean or String representing a integer).

Returns

Rounded value.

sqrt()

Decimal bps::Decimal::sqrt

(

)

const

Calculate the square root of this value and return the result.

Returns

Square root of this value.

sub()

Decimal bps::Decimal::sub

(

Mixed

aOther

)

const

Subtract second value and return result.

Parameters

[in]

aOther

The other value to subtract (a Decimal, Number, Boolean or String representing a number).

Returns

The result.

toString() [1/2]

String bps::Decimal::toString

(

)

const

Converts the value to a string.

Finite numbers will be converted to a string with exponential notation if the exponent is positive or if the magnitude is less than 1 and would require more than five zeros between the decimal point and the first significant digit.

Note that strings which are not simply numbers (one of Infinity, -Infinity, NaN) are possible.

Returns

String representation of the value.

toString() [2/2]

String bps::Decimal::toString	(	Number	aDecPlaces,
		Number	aMaxSize = 36
	)		const

Converts a decimal value to a string of format [-]9.9.

The printed value is rounded to the absolute number of decimal places.

• If the value is NaN, the string "NaN" is returned.
• If the value is infinite or the string does not fit into the given maximum size, a maximum size string of hashes is returned as "#####" for positive values or "-####" for negative values.
• if the value is finite and aDecPlaces is greater than 0, all fractional digits for the given decimal places are included.
• If the value is finite, aDecPlaces is less than 0, and all fractional digits are zero, the fractional part is removed and the value is represented as integer.

Parameters

[in]	aDecPlaces	Number of decimal places.
[in]	aMaxSize	Maximum string size.

Returns

String representation of the value.

up()

Decimal bps::Decimal::up

(

)

const

If the value is not integer, round up to next integer (away from 0).

Returns

Integer value.

Member Data Documentation

Pi

const Decimal bps::Decimal::Pi = 3.141592653589793238462643383279502

static

Ratio of the circumference of a circle to the diameter.

print( bps.Decimal.Pi ); // Show Pi

Property Documentation

value

Number bps::Decimal::value

readwrite

Value of the variable.

 

---

The documentation for this class was generated from the following file:

• bps.Decimal.js