Class: TCanonicalNumber

Declaration: CanonicalNumber.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

TCanonicalNumber objects are used as intermediates in conversion between binary types and text. The TCanonicalNumber object is a unique text representation (sign, exponent, significandString) of a generic binary numeric value. By itself, the TCanonicalNumber has no arithmetic value, (because unless the base is specified, it is ambiguous which floating-point number the TCanonicalNumber object represents). But when acted on by a TCanonicalNumberConverter object, TCanonicalNumber objects can be converted to and from binary floating-point. The important TCanonicalNumber attributes are: sign : The sign-bit is bool, true if and only if IsSignNegative() (see <Numerics.h>). exponent : The exponent of the TCanonicalNumber is a long integral value. significand : A string of byte-encoded digits, each of type TCanonicalNumber::Digit, with the implicit decimal point after the first digit in the stream. Byte-encoded means that the digit values are bytes, as opposed to ASCII text. An example makes this clear: If the base is 10, and you want the number PI =3.1415926 to be represented as a TCanonicalNumber, the appropriate TCanonicalNumber object has attributes (Sign=0, Exp=0, String=[3,1,4,1,5,9,2,6]). The client of this class is the NumberFormat Framework provided by Text and international, and developers who write their own Binary<->Decimal, Binary<->Hexadecimal, and other converters. Together with the header, FPEnvironment.h, providing numerical environmental access and the header, Numerics.h, providing numerical functions, CanonicalNumber.h supersedes the ANSI C / NCEG math interface.

Instantiation:

Allocate on the stack or the heap, preferably on the stack.

Deriving Classes:

Do not derive.

Concurrency:

Multithread safe.

Resource Use:

No special requirements.

Member Function: TCanonicalNumber::~TCanonicalNumber

~ TCanonicalNumber ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TCanonicalNumber::GetSignBit

bool GetSignBit () const

Interface Category:

API.

Purpose:

Queries the sign-bit of a TCanonicalNumber.

Calling Context:

Called to query the attributes of a TCanonicalNumber. May be called directly. Called by TNumberFormat classes. Designed to work in non-default floating-point rounding modes.

Parameters:

Takes no parameters.

Return Value:

Returns true if and only if the sign-bit is set, corresponding to IsSignNegative() in<Numerics.h>. For example, a TCanonicalNumber representing 3.14 would GetSignBit() ==false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TCanonicalNumber::GetSignificandLength

size_t GetSignificandLength () const

Interface Category:

API.

Purpose:

Gets the significandLength of a TCanonicalNumber.

Calling Context:

Called to get the attributes of a TCanonicalNumber. May be called directly. Called by TNumberFormat classes. Designed to work in non-default floating-point rounding modes.

Parameters:

Takes no parameters.

Return Value:

The significand length.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TCanonicalNumber::GetExponent

long GetExponent () const

Interface Category:

API.

Purpose:

Gets the exponent of a TCanonicalNumber.

Calling Context:

Called to get the attributes of a TCanonicalNumber. May be called directly. Called by TNumberFormat classes. Designed to work in non-default floating-point rounding modes.

Parameters:

Takes no parameters.

Return Value:

The exponent of a TCanonicalNumber, accounting for the location of the radix point in the significand.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

If the significand is 0, then the TCanonicalNumber is also 0. In this case, calling GetExponent doesn't yield any significant information.

Member Function: TCanonicalNumber::SetInfinity

void SetInfinity ()

Interface Category:

API.

Purpose:

Sets a TCanonicalNumber to the equivalent of +kInfinity in Numerics.h.

Calling Context:

Called to set a TCanonicalNumber to represent floating-point +kInfinity. May be called directly. Called by TNumberFormat classes. Designed to work in non-default floating-point rounding modes.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Note that this member function sets the sign to positive infinity; so ensure that SetSignBit is called after SetInfinity if negative infinity is desired.

Member Function: TCanonicalNumber::operator<<=

TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & -The stream the object is streamed in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TCanonicalNumber::operator>>=

TStream & operator >>=(TStream &) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & -The stream the object is streamed out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TCanonicalNumber::IsNan

bool IsNan () const

Interface Category:

API.

Purpose:

Tests if a TCanonicalNumber is equivalent to floating-point +NaN or -NaN.

Calling Context:

Called to test if a TCanonicalNumber is equivalent to +NaN or -NaN. May be called directly. Called by TNumberFormat classes. Designed to work in non-default floating-point rounding modes.

Parameters:

Takes no parameters.

Return Value:

Returns true if and only if the TCanonicalNumber is equivalent to +NaN or -NaN.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

NaN (Not-a-Number) is a result of an invalid operation or a division by zero in the floating-point domain.

Member Function: TCanonicalNumber::IsInfinity

bool IsInfinity () const

Interface Category:

API.

Purpose:

Tests if a TCanonicalNumber is equivalent to floating-point +INF or -INF.

Calling Context:

May be called directly. Called by TNumberFormat classes. Designed to work in non-default floating-point rounding modes. Called to test if a TCanonicalNumber is equivalent to +INF or -INF.

Parameters:

Takes no parameters.

Return Value:

Returns true if and only if the TCanonicalNumber is equivalent to +INF or -INF.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Infinities arise in two fashions: -From an exact mathematical infinity (such as 1/0). -When the magnitude of a floating-point number is too large for the storage format. The sign of infinity is meaningful.

Member Function: TCanonicalNumber::IsZero

bool IsZero () const

Interface Category:

API.

Purpose:

Tests if a TCanonicalNumber is equal to floating-point +0.0 or -0.0.

Calling Context:

Called to test if a TCanonicalNumber ==+0.0 or -0.0. May be called directly. Called by TNumberFormat classes. Designed to work in non-default floating-point rounding modes.

Parameters:

Takes no parameters.

Return Value:

Returns true if and only if the TCanonicalNumber ==+0.0 or -0.0. A TCanonicalNumber is 0 if and only if the first digit of the significand is 0, the sign is the only other relevant attribute of a zero TCanonicalNumber object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Ordinarily, the sign of 0 doesn't matter except for function discontinuities at zero and branch cuts in the complex domain.

Member Function: TCanonicalNumber::SetNan

void SetNan (unsigned short)

Interface Category:

API.

Purpose:

Sets a TCanonicalNumber to the equivalent of +kNaN (see Numerics.h). NaN (Not-a-Number) is a result of an invalid operation or a division by zero in the floating-point domain.

Calling Context:

Called to set a TCanonicalNumber to represent floating-point +NaN. May be called directly. Called by TNumberFormat classes. Designed to work in non-default floating-point rounding modes.

Parameters:

unsigned short -The parameter currently has no effect.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Note that this member function sets the sign to positive NaN; so ensure that SetSignBit is called after SetNan if negative NaN is desired. The nanCode may someday be used to encode the type of error that resulted; there is currently no support for nanCode.

Member Function: TCanonicalNumber::SetExponent

void SetExponent (long)

Interface Category:

API.

Purpose:

Sets the exponent of a TCanonicalNumber.

Calling Context:

Called to set the attributes of a TCanonicalNumber. May be called directly. Called by TNumberFormat classes. Designed to work in non-default floating-point rounding modes.

Parameters:

long -The TCanonicalNumber exponent, accounting for the location of the radix point in the significand.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

If the significand is 0, then the TCanonicalNumber is also 0. In this case, calling SetExponent() is of no consequence.

Member Function: TCanonicalNumber::SetSignificand

void SetSignificand (const Digit [], size_t)

Interface Category:

API.

Purpose:

Sets the significand of a TCanonicalNumber.

Calling Context:

Called set the attributes of a TCanonicalNumber. May be called directly. Called by TNumberFormat classes. Designed to work in non-default floating-point rounding modes.

Parameters:

const Digit [] -The parameter significand is copied to the internal TCanonicalNumber significand.
size_t -Specifies the length of the buffer passed as parameter.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

If a NULL buffer is passed in, no information is transferred. For this member function, there is no limit on the length of the digit stream. The digit stream can potentially be infinite; although a finite amount of digit information is stored internally, all excess rounding numeric information is carefully retained as necessary. Hence, the user need not worry about the size of the internal buffer used by TCanonicalNumber.

Member Function: TCanonicalNumber::GetSignificand

void GetSignificand (Digit []) const

Interface Category:

API.

Purpose:

Gets the significand of a TCanonicalNumber.

Calling Context:

Called to get the attributes of a TCanonicalNumber. May be called directly. Called by TNumberFormat classes. Designed to work in non-default floating-point rounding modes.

Parameters:

Digit [] -The internally stored significand is copied to this preallocated buffer (theSignificand). The buffer length should be >=TCanonicalNumber::GetSignificandLength.

Return Value:

None.

Exceptions:

Throws an assertion exception if the preallocated buffer pointer is NULL.

Concurrency:

Multithread safe.

Other Considerations:

If a NULL buffer is passed in, an assertion exception is thrown and no information is transferred.

Member Function: TCanonicalNumber::SetSignBit

void SetSignBit (bool)

Interface Category:

API.

Purpose:

Sets the sign-bit of a TCanonicalNumber.

Calling Context:

Called to set the attributes of a TCanonicalNumber. May be called directly. Called by TNumberFormat classes. Designed to work in non-default floating-point rounding modes.

Parameters:

bool -Returns true if and only if the sign-bit is set, as in IsSignMinus() in<Numerics.h>.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TCanonicalNumber::operator[]

TCanonicalNumberRef operator [] (unsigned short)

Interface Category:

API.

Purpose:

The subscript operator allows array-type read/write access to TCanonicalNumber significand digits, rather than passing them in as one vector in TCanonicalNumber::SetSignificand. This is useful for instances where the TCanonicalNumber digits need to be read/written one at a time.

Calling Context:

Called to read/write the significand digits of a TCanonicalNumber. Should not be called directly. Called by TNumberFormat classes. Designed to work in non-default floating-point rounding modes.

Parameters:

unsigned short -Specifies which index to read/write.

Return Value:

When used to read, it returns the significand digit at the location specified by the index.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

When writing, there is no limit on the length of the digit stream. The digit stream can potentially be infinite; although a finite amount of digit information is stored internally, all excess rounding numeric information is carefully retained as necessary. Reading digits beyond the significand length results in the digit 0 being returned. Hence, the user need not worry about the size of the internal buffer used by TCanonicalNumber.

Member Function: TCanonicalNumber::operator==

bool operator ==(const TCanonicalNumber &) const

Interface Category:

API.

Purpose:

Tests if two TCanonicalNumbers are equal.

Calling Context:

Called to test if two TCanonicalNumbers are equal. May be called directly. Called by TNumberFormat classes. Designed to work in non-default floating-point rounding modes.

Parameters:

const TCanonicalNumber & -The number to compare the current object with.

Return Value:

Returns true if and only if the two TCanonicalNumbers are equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

All attributes are taken into account (sign, exponent, significand).

Member Function: TCanonicalNumber::TCanonicalNumber

TCanonicalNumber ()
TCanonicalNumber (bool, const Digit [], size_t, long)

Interface Category:

API.

Purpose:

Default constructor. TCanonicalNumber is initialized to NaN (Not a Number).
Constructs a TCanonicalNumber from components (sign, significandString, significandLength, exponent).

Calling Context:

Called by the stream-in operators and to create an object with default values.
Called by anyone who wants to initialize at construction time, rather than through explicit setters.

Parameters:

Takes no parameters.
bool isSignMinus -Returns true if and only if the numeric equivalent floating-point has its sign-bit set.
const Digit [] -The byte-encoded significand string (implicit radix point after the first digit).
size_t -The length of the significand string.
long -The exponent of the TCanonicalNumber.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Note: - signbit is true if and only if IsSignNegative() in <Numerics.h>; for example, false for positive numbers. - significand is byte-encoded, not ASCII text; for example, [3,1,4] and not ["3","1","4"]. - significand has an implicit radix point, not explicit. - exponent takes into account the normalized significand; for example, the location of the radix point in the significand.

Click the icon to mail questions or corrections about this material to Taligent personnel.