Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
None.
Inherited By:
None.
Purpose:
A TCanonicalNumberConverter object acts on a TCanonicalNumber object to convert it to and from binary floating-point. It stores the necessary base, rounding, and other information to make a conversion step complete. A TCanonicalNumber object has no arithmetic value because unless the base is specified, it is ambiguous which floating-point number the object represents. When acted on by the TCanonicalNumberConverter object, a TCanonicalNumber object can be numerically converted to and from binary floating-point.
The important TCanonicalNumberConverter attributes are: Base, RoundRule, TotalDigitCount DigitsFromDecimalPoint, PowerOfBaseScale, and RoundToMultiple.
Exceptions thrown by this class are: TCanonicalNumberException::kInvalidBase. TCanonicalNumberException::kInvalidMRoundValue
Clients of this class are 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 where possible.
deriving Classes:
May be derived if clients need their own conversion mechanisms, although this is not recommended.
The principal reason to derive would be to support conversion between machine binary and bases other than 2,8,10,16 which are already supported.
Adding support for a new base would require deriving all constructors which otherwise would throw an exception, and scrupulously calling the base constructors to handle the bases that they support.
TCanonicalNumber<->binary conversions should then be provided for all binary formats. To match the semantics of the base class conversions, they should incur only one rounding, be correctly rounded according to the current ERoundRule, and set the machine floating-point exception flags appropriately.
If the class is derived, all member functions of the class must be examined. Support for the semantics of all TCanonicalNumberConverter attributes should be consistent with the base class behavior.
Concurrency:
Multithread safe.
Resource Use:
No special requirements.
TCanonicalNumberConverter ()
Interface Category:
API.
Purpose:
Default constructor. Sets the default attributes as follows:
base =10,
roundRule =kCurrEnvSetting,
PowerOfScale =0,
TotalDigitCount =TCanonicalNumberConverter::kDontCare,
DigitsFromDecimalPoint =TCanonicalNumberConverter::kDontCare,
RoundToMultiple =0.0.
Calling Context:
Called by the stream-in operators and to create an object with default values.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
Use the setters to change TCanonicalNumberConverter attributes.
ERoundRule GetRoundRule () const
Interface Category:
API.
Purpose:
Queries the rounding rule used in conversions between binary and TCanonicalNumber.
Calling Context:
Called by a client trying to query the rounding rule used during conversions.
May be called directly.
Called by TNumberFormat classes.
Designed to work in non-default floating-point rounding modes.
Parameters:
Return Value:
Returns the round rule, an ERoundRule value.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
The RoundRules provided encompass the IEEE rounding modes and specialized cases.
long GetPowerOfBaseScale () const
Interface Category:
API.
Purpose:
Queries the power of base scaling used during conversions between binary and TCanonicalNumber.
Calling Context:
Called by a client trying to query the power of base scaling used during conversions.
May be called directly.
Called by TNumberFormat classes.
Designed to work in non-default floating-point rounding modes.
Parameters:
Return Value:
The power of base scaling used during conversions.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
The power of base scaling (also referred to as S) allows scaling the exponent of a TCanonicalNumber during the conversion process, rather than having to do it after the conversion and thus incur possible double-rounding.
unsigned short GetTotalDigitCount () const
Interface Category:
API.
Purpose:
Queries the total significand digit count during Binary->TCanonicalNumber conversions.
Calling Context:
Called by a client trying to query the total significand digit count during Binary->TCanonicalNumber conversions.
May be called directly.
Called by TNumberFormat classes.
Designed to work in non-default floating-point rounding modes. Parameters:
Return Value:
The total significand digit count for Binary->TCanonicalNumber conversions.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
The TotalDigitCount (also referred to as N) is used in Binary->TCanonicalNumber conversions as an instruction to generate at most N digits in the significand string.
short GetDigitsFromDecimalPoint () const
Interface Category:
API.
Purpose:
Queries the digits after the radix point in the significand string during Binary->TCanonicalNumber conversions.
Calling Context:
Called to query digits after the radix point in the significand string during Binary->TCanonicalNumber conversions.
May be called directly.
Called by TNumberFormat classes.
Designed to work in non-default floating-point rounding modes.
Parameters:
Return Value:
The digits after the radix point during Binary->TCanonicalNumber conversions.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
DigitsFromDecimalPoint (also referred to as D) is used in Binary->TCanonicalNumber conversions as follows:
- If roundToMultiple != 0, then ignore D, and do round to multiple of floating-point value M.
- If roundToMultiple ==0, then digitCountFromDecimalPoint =D, means
- If D >0, always round to D places to the right of decimal point (for example, round to the nearest hundredths).
- If D < 0, always round to D places to the left of decimal point (for example, round to the nearest hundreds).
- If D==0, always round to units place (round so there is no fraction part).
double GetRoundToMultiple () const
Interface Category:
API.
Purpose:
Queries the round-to-multiple factor used during Binary->decimal TCanonicalNumber conversions.
Calling Context:
Called to query the round-to-multiple factor used during Binary->decimal TCanonicalNumber conversions.
May be called directly.
Called by TNumberFormat classes.
Designed to work in non-default floating-point rounding modes.
Parameters:
Return Value:
The current rounding to the multiple.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
RoundToMultiple (also referred to as M) controls rounding to a multiple of a floating-point value in binary->decimal conversions only. This may be useful in places where it is not possible to do, Round(x/M) * M, to achieve the desired RoundToMultiple. For example, if x is very large, and M is 0.5, then x/M is still very close to M, and the desired RoundToMultiple, may not be achieved. Furthermore, in doing Round(x/M) the division causes a rounding, which may be undesirable. Only certain values of M are permissible. The only acceptable values of M are powers of 2's and 5's, and their products. For example, M =20, M =32, M =1/50 are acceptable values. But M =3, M =30, M =1/15, M =3.1415926 are unacceptable values and will be caught by the setter; in this case M is set to 0.0 and an exception is raised.
void SetRoundToMultiple (double)
Interface Category:
API.
Purpose:
Sets the round-to-multiple factor used during Binary->decimal TCanonicalNumber conversions.
Calling Context:
Called to set the round-to-multiple factor used during Binary->decimal TCanonicalNumber conversions.
May be called directly.
Called by TNumberFormat classes.
Designed to work in non-default floating-point rounding modes.
Parameters:
- double -The desired rounding to the multiple.
Return Value:
None.
Exceptions:
If SetRoundToMultiple is not a reasonable product of powers of 2 and 5 (including negative powers), TCanonicalNumberException::kInvalidMRoundValue is thrown.
Concurrency:
Multithread safe.
Other Considerations:
RoundToMultiple (also referred to as M) controls rounding to a multiple of a floating-point value in binary->decimal conversions only. This may be useful in places where it is not possible to do, Round(x/M) * M, to achieve the desired RoundToMultiple. For example, if x is very large, and M is 0.5, then x/M is still very close to M, and the desired RoundToMultiple, may not be achieved. Furthermore, in doing Round(x/M) the division causes a rounding, which may be undesirable. Only certain values of M are permissible. The only acceptable values of M are powers of 2's and 5's, and their products. For example, M =20, M =32, M =1/50 are acceptable values. But M =3, M =30, M =1/15, M =3.1415926 are unacceptable values and will be caught by the setter; in this case M is set to 0.0 and an exception is raised.
void SetDigitsFromDecimalPoint (short)
Interface Category:
API.
Purpose:
Sets the digits after the radix point in the significand string during Binary->TCanonicalNumber conversions.
Calling Context:
Called by a client trying to set the digits after the radix point in the significand string during Binary->TCanonicalNumber conversions.
May be called directly.
Called by TNumberFormat classes.
Designed to work in non-default floating-point rounding modes.
Parameters:
- short -The digits after the radix point during Binary->TCanonicalNumber conversions.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
DigitsFromDecimalPoint (also referred to as D) is used in Binary->TCanonicalNumber conversions as follows:
- If roundToMultiple != 0, then ignore D, and do round to multiple of floating-point value M.
- If roundToMultiple ==0, then digitCountFromDecimalPoint =D, means
- If D >0, always round to D places to the right of decimal point (for example, round to the nearest hundredths).
- If D < 0, always round to D places to the left of decimal point (for example, round to the nearest hundreds).
- If D==0, always round to units place (round so there is no fraction part).
void SetTotalDigitCount (unsigned short)
Interface Category:
API.
Purpose:
Sets the total significand digit count during Binary->TCanonicalNumber conversions.
Calling Context:
Called by a client trying to set the total significand digit count during Binary->TCanonicalNumber conversions.
May be called directly.
Called by TNumberFormat classes.
Designed to work in non-default floating-point rounding modes.
Parameters:
- unsigned short -The total significand digit count for Binary->TCanonicalNumber conversions.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
The TotalDigitCount (also referred to as N) is used in Binary->TCanonicalNumber conversions as an instruction to generate at most N digits in the significand string.
void SetPowerOfBaseScale (long)
Interface Category:
API.
Purpose:
Sets the power of base scaling used during conversions between binary and TCanonicalNumber.
Calling Context:
Called by a client trying to set the power of base scaling used during conversions.
May be called directly.
Called by TNumberFormat classes.
Designed to work in non-default floating-point rounding modes.
Parameters:
- long -The power of base scaling used during conversions.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
The power of base scaling (also referred to as S) allows scaling the exponent of a TCanonicalNumber during the conversion process, rather than having to do it after the conversion and thus incur possible double-rounding.
void SetRoundRule (ERoundRule)
Interface Category:
API.
Purpose:
Sets the rounding rule used in conversions between binary and TCanonicalNumber.
Calling Context:
Called by a client trying to set the rounding rule used during conversions.
May be called directly.
Called by TNumberFormat classes.
Designed to work in non-default floating-point rounding modes.
Parameters:
- ERoundRule -Rounding rule desired during conversions.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
The RoundRules provided encompass the IEEE rounding modes and specialized cases.
virtual void SetBase (short)
Interface Category:
API.
Purpose:
Sets the base used to interpret a TCanonicalNumber.
Calling Context:
Called by a client trying to set the base used to interpret a TCanonicalNumber.
May be called directly.
Called by TNumberFormat classes.
Designed to work in non-default floating-point rounding modes.
Parameters:
- short -The base to be used to interpret TCanonicalNumber (only 2,8,10, and 16 are allowed).
Return Value:
None.
Exceptions:
The only bases supported are 2,8,10, and 16. If an unsupported base is passed to SetBase, TCanonicalNumberException::kInvalidBase is thrown.
Concurrency:
Multithread safe.
Other Considerations:
To support another base, derive from TCanonicalNumberConverter, and provide your own numeric conversion scheme for that base, which is generally not recommended. 2,8,10, and 16 are currently supported.
virtual short GetBase () const
Interface Category:
API.
Purpose:
Queries the base used to interpret a TCanonicalNumber.
Calling Context:
Called by a client trying to query the base used to interpret a TCanonicalNumber.
May be called directly.
Called by TNumberFormat classes.
Designed to work in non-default floating-point rounding modes.
Parameters:
Return Value:
Returns the base (2,8,10, and 16 are the only ones supported).
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
To support another base, derive from TCanonicalNumberConverter, and provide your own numeric conversion scheme for that base, which is generally not recommended. 2,8,10, and 16 are currently supported.
- virtual void ToBinary (const TCanonicalNumber &, long double &) const
- virtual void ToBinary (const TCanonicalNumber &, double &) const
- virtual void ToBinary (const TCanonicalNumber &, float &) const
- virtual void ToBinary (const TCanonicalNumber &, long &) const
- virtual void ToBinary (const TCanonicalNumber &, unsigned long &) const
- virtual void ToBinary (const TCanonicalNumber &, int &) const
- virtual void ToBinary (const TCanonicalNumber &, unsigned int &) const
- virtual void ToBinary (const TCanonicalNumber &, short &) const
- virtual void ToBinary (const TCanonicalNumber &, unsigned short &) const
- virtual void ToBinary (const TCanonicalNumber &, char &) const
- virtual void ToBinary (const TCanonicalNumber &, unsigned char &) const
- virtual void ToBinary (const TCanonicalNumber &, signed char &) const
Interface Category:
API.
Purpose:
- Conversion from TCanonicalNumber to long double.
- Conversion from TCanonicalNumber to double.
- Conversion from TCanonicalNumber to float.
- Conversion from TCanonicalNumber to long.
- Conversion from TCanonicalNumber to unsigned long.
- Conversion from TCanonicalNumber to int.
- Conversion from TCanonicalNumber to unsigned int.
- Conversion from TCanonicalNumber to short.
- Conversion from TCanonicalNumber to unsigned short.
- Conversion from TCanonicalNumber to char.
- Conversion from TCanonicalNumber to unsigned char.
- Conversion from TCanonicalNumber to signed char.
Calling Context:
- Call to convert a TCanonicalNumber object to a floating-point binary value.
- Call to convert a TCanonicalNumber object to a floating-point binary value.
- Call to convert a TCanonicalNumber object to a floating-point binary value.
- Call to convert a TCanonicalNumber object to an integral format binary value.
- Call to convert a TCanonicalNumber object to an integral format binary value.
- Call to convert a TCanonicalNumber object to an integral format binary value.
- Call to convert a TCanonicalNumber object to an integral format binary value.
- Call to convert a TCanonicalNumber object to an integral format binary value.
- Call to convert a TCanonicalNumber object to an integral format binary value.
- Call to convert a TCanonicalNumber object to an integral format binary value.
- Call to convert a TCanonicalNumber object to an integral format binary value.
- Call to convert a TCanonicalNumber object to an integral format binary value.
Called by TNumberFormat classes, the only anticipated clients.
Designed to work in non-default floating-point rounding modes.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
Note that the base plays an integral role in interpreting the TCanonicalNumber for the conversion process. Besides the base, the other important attributes are:
- PowerOfBaseScale (also referred to as S), which controls the scaling of the exponent in TCanonicalNumber during the conversion.
- RoundRule,which controls the numeric rounding during the conversion.
- virtual void FromBinary (long double, TCanonicalNumber &) const
- virtual void FromBinary (double, TCanonicalNumber &) const
- virtual void FromBinary (float, TCanonicalNumber &) const
- virtual void FromBinary (const TDoubleLong &, TCanonicalNumber &) const
Interface Category:
API.
Purpose:
- Facilitates conversions from extended-format floating-point to TCanonicalNumber.
- Facilitates conversions from double-format floating-point to TCanonicalNumber.
- Facilitates conversions from float-format floating-point to TCanonicalNumber.
- Facilitates conversions from TDoubleLong (see PrimitiveTypes.h) to TCanonicalNumber.
Calling Context:
- Called to convert long double to TCanonicalNumber.
- Called to convert double to TCanonicalNumber.
- Called to convert float to TCanonicalNumber.
- Called to convert TDoubleLong to TCanonicalNumber.
Called by TNumberFormat classes, the only anticipated clients.
Designed to work in non-default floating-point rounding modes.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
Note that the base plays an integral role in setting up the TCanonicalNumber for the conversion process. Besides the base, the other important attributes are:
- TotalDigitCount (also referred to as N), which controls the total number of digits required in the significand string during the conversion.
- DigitCountFromDecimalPoint (also referred to as D), which controls rounding to a fixed number of digits from the decimal point in the significand string.
- PowerOfBaseScale (also referred to as S), which controls scaling of the exponent in TCanonicalNumber during the conversion.
- RoundRule, which controls the numeric rounding of TCanonicalNumber significand digits if truncation is necessary during the conversion.
- RoundToMultiple, not currently supported.
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.
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.
virtual ~ TCanonicalNumberConverter ()
Interface Category:
API.
Purpose:
Destructor.
Calling Context:
Called to destroy an object. Does nothing significant.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.