rwsf::Decimal Class Reference

Represents an arbitrary precision decimal fraction. More...

#include <rwsf/core/Decimal.h>

Inheritance diagram for rwsf::Decimal:

Public Member Functions
	Decimal ()
	Decimal (const char *s)
	Decimal (const std::string &s)
	Decimal (long before)
	Decimal (int before)
std::string	asString () const
std::string	asString (const rwsf::Locale &) const
unsigned	hash () const
bool	isNumber () const
bool	isZero ()
size_t	numSignificantDigits () const
const Decimal &	operator*= (const Decimal &rhs)
const Decimal &	operator+= (const Decimal &rhs)
const Decimal &	operator-= (const Decimal &rhs)
size_t	precision () const
size_t	scale () const
void	trimZeros ()

Static Public Member Functions
static std::string	decimalSeparator (const rwsf::Locale &loc)
static std::string	decimalSeparator ()
static std::string	thousandsSeparator (const rwsf::Locale &loc)
static std::string	thousandsSeparator ()

Static Public Attributes
static const Decimal	NaN
static const Decimal	null

Related Functions
(Note that these are not member functions.)
Decimal	round (const Decimal &input, long digits, DecimalBase::RoundingMethod method)

Additional Inherited Members
Public Types inherited from rwsf::DecimalBase
enum	RoundingMethod {   PLAIN, UP, DOWN, BANKERS,   TRUNCATE }

Detailed Description

This class represents an arbitrary precision decimal fraction. Trailing zeros and significant digits are maintained in the created Decimal object.

Several functions are available to perform mathematical operations on the Decimal object, including arithmetic, rounding, significant digits, and conversion to string. All valid operands follow standard mathematical rules in arithmetic and rounding operations.

Significant digits (aka significant figures or "sig figs") are supported and are calculated according to the mathematical definition:

• For a Decimal D in the form [0]*N*.N*, where N can be the digits 0-9, the number of significant digits is equal to the number of N digits. This is essentially the total number of digits minus the number of leading zeroes.

NaN (Not a Number) and null entities are also supported:

• A null Decimal represents an entity that must be tracked yet does not exist in terms of the mathematical operations being performed with it. Note that this is very different from 0. 0 is a valid, discrete integer. A null Decimal is more like a blank placeholder.
• A NaN Decimal represents an entity that cannot be identified as a discrete number (such as infinity). Common operations that result in NaN entities are: dividing by 0, the logarithm of a number less than or equal to 0, the tangent or secant of pi/2, and so on. A NaN Decimal can also result by trying to represent a number with a fractional component too small for the given precision. (E.g., The number 2.345 cannot be represented with a precision of 2. A precision of 4 would be needed for this to be a valid Decimal object.)

These non-number entities follow standard mathematical guidelines when used in arithmetic operations:

• A null Decimal in any operation with a valid Decimal D results in identity for D (e.g., D + null = D, D * null = D).
• A NaN Decimal is any operation results in NaN, no matter what the other operand is.

Constructor & Destructor Documentation

rwsf::Decimal::Decimal

(

)

Constructs an rwsf::Decimal with a value of null.

rwsf::Decimal::Decimal

(

const char *

s

)

Constructs an rwsf::Decimal from the null-terminated character string s. Acceptable inputs consist of:

• positive number, such as "123"
• negative number, expressed as "-123" or "(123)"
• percentage, such as "90%", resulting in the decimal equivalent value, is this case ".90"
• "NaN", resulting in a NaN rwsf::Decimal.
• "null", resulting in a null rwsf::Decimal.

Here are some other qualifications about the input:

• If the string cannot be successfully parsed as a number, a null rwsf::Decimal is constructed.
• If the number in the string cannot be exactly represented (for example, it has too many significant digits), a NaN rwsf::Decimal is constructed.
• The string may contain embedded commas to separate groups of digits and may have a leading dollar sign.

Note

If the string s has trailing zeros (e.g., 1.200), those trailing zeroes will be maintained as part of the constructed rwsf::Decimal, and the number of significant figures will be set accordingly.

rwsf::Decimal::Decimal

(

const std::string &

s

)

Constructs an rwsf::Decimal from the null-terminated character string s. Acceptable inputs consist of:

• positive number, such as "123"
• negative number, expressed as "-123" or "(123)"
• percentage, such as "90%", resulting in the decimal equivalent value, is this case ".90"
• "NaN", resulting in a NaN rwsf::Decimal.
• "null", resulting in a null rwsf::Decimal.

Here are some other qualifications about the input:

• If the string cannot be successfully parsed as a number, a null rwsf::Decimal is constructed.
• If the number in the string cannot be exactly represented (for example, it has too many significant digits), a NaN rwsf::Decimal is constructed.
• The string may contain embedded commas to separate groups of digits and may have a leading dollar sign.

Note

If the string s has trailing zeros (e.g., 1.200), those trailing zeroes will be maintained as part of the constructed rwsf::Decimal, and the number of significant figures will be set accordingly.

rwsf::Decimal::Decimal

(

long

before

)

Constructs an rwsf::Decimal by parsing the input long before. This construction always succeeds. That is, a valid long reliably results in a valid rwsf::Decimal.

rwsf::Decimal::Decimal

(

int

before

)

Constructs an rwsf::Decimal by parsing the input integer before. This construction always succeeds. That is, a valid int reliably results in a valid RWDecimal.

Member Function Documentation

std::string rwsf::Decimal::asString

(

)

const

Returns the stored decimal value as a string. The format is standard, e.g., -23.21 or 0.32 or 432.

std::string rwsf::Decimal::asString

(

const rwsf::Locale &

)

const

Returns the stored decimal value as a string. The format is standard, e.g., -23.21 or 0.32 or 432.

static std::string rwsf::Decimal::decimalSeparator ( const rwsf::Locale &  loc )

static

Returns the decimal separator (e.g., "." in the U.S., "," in Europe) for the given Locale loc.

static std::string rwsf::Decimal::decimalSeparator ( )

static

Returns the decimal separator (e.g., "." in the U.S., "," in Europe) for the local Locale.

unsigned rwsf::Decimal::hash

(

)

const

Returns a value suitable for hashing.

bool rwsf::Decimal::isNumber

(

)

const

Returns true if self represents a valid decimal value. Returns false if self is null or NaN.

bool rwsf::Decimal::isZero

(

)

Returns true if the Decimal represents a 0 value, false otherwise.

size_t rwsf::Decimal::numSignificantDigits

(

)

const

Returns the number of significant digits (also known as significant figures) in the stored decimal (See class description for more information on significant digits.)

const Decimal& rwsf::Decimal::operator*=

(

const Decimal &

rhs

)

Arithmetic operator. Performs the operation between self and the rhs, and then stores the results in self.

Note

This operator trims all trailing zeroes.

const Decimal& rwsf::Decimal::operator+=

(

const Decimal &

rhs

)

Arithmetic operator. Performs the operation between self and the rhs, and then stores the results in self.

Note

This operator trims all trailing zeroes.

const Decimal& rwsf::Decimal::operator-=

(

const Decimal &

rhs

)

Arithmetic operator. Performs the operation between self and the rhs, and then stores the results in self.

Note

This operator trims all trailing zeroes.

size_t rwsf::Decimal::precision

(

)

const

Returns the floating point precision of the stored decimal. This is equal to the number of digits in the decimal value.

size_t rwsf::Decimal::scale

(

)

const

Returns the number of digits to the right of the decimal point.

static std::string rwsf::Decimal::thousandsSeparator ( const rwsf::Locale &  loc )

static

Returns the thousands separator (e.g., "," in the U.S., "." in Europe) for the given Locale loc.

static std::string rwsf::Decimal::thousandsSeparator ( )

static

Returns the thousands separator (e.g., "," in the U.S., "." in Europe) for the local Locale.

void rwsf::Decimal::trimZeros

(

)

Removes any leading zeros before the first non-zero number, and any trailing zeros after the last non-zero number.

Friends And Related Function Documentation

Decimal round ( const Decimal &  input, long  digits, DecimalBase::RoundingMethod  method  )

related

Rounds the floating-point decimal input to the nearest integer based on the rounding rule given in method (See rwsf::DecimalBase::RoundingMethod for the description of the different rounding rules available).

Note

Rounding maintains trailing zeros, so round("1.2",2) yields 1.20.

Member Data Documentation

const Decimal rwsf::Decimal::NaN

static

A built-in constant to help with comparisons, tests, or to set up non-numeric values.

const Decimal rwsf::Decimal::null

static

A built-in constant to help with comparisons, tests, or to set up non-numeric values.