RWDecimalFormat
Module: Currency Group: Formatting
Does not inherit
- Local Index
- Synopsis
- Description
- Example
- Attributes
- Picture Strings
- Formatting Wide Numbers
- Public Constructors
- Public Member Functions
- Public Member Operators
- Global Operators
Local Index
Members
Non-Members
Synopsis
#include <rw/decio.h>
int main(){cout << RWDecimalFormat("$_____.__")("2.243") << endl;}
Description
The RWDecimalFormat class encapsulates formatting information for converting a decimal number to a string. You can construct and modify the attributes of a formatted object in two ways:
Specify a picture string. The string gives a textual representation of the look of the format. A sample picture is "$0___.__". Using this sample picture, the number 3.14159 is formatted as "$0003.14".
Set attributes directly, using member functions. This allows maximum flexibility.
You can also use a hybrid approach by initially constructing an RWDecimalFormat object using a picture string and then "fine tuning" the formatting parameters using the member functions to change attributes directly.
Once a formatted object is constructed, you use the function call operator() to convert from decimal numbers to strings.
Example
#include <iostream.h>
#include <rw/currency/decimal.h>
#include <rw/decio.h>
int main(){
RWDecimal<RWMP2Int> USbucks = "232.455"; // an amount in US$
RWDecimal<RWMP2Int> UStoCDN = "0.7921"; // today's exchange
// rate
RWDecimal<RWMP2Int> CDNbucks = USbucks*UStoCDN;
// set up the US dollars format. Use banker's rounding, turn
// currency symbol on, and set currency symbol
RWDecimalFormat USformat("________.__");
USformat.setNearLeftText("US$");
USformat.setRounding(RWDecimalBase::Bankers);
// the Canadian dollars format is the same as the US$ except
// for the currency symbol.
RWDecimalFormat CDNformat = USformat;
CDNformat.setNearLeftText("CDN$");
cout << "Initially, amount is: " << USformat(USbucks) << endl;
cout << "After exchange" << CDNformat(CDNbucks) << endl;
return 0;
}
Program output
Initially, amount is: US$232.46 After exchange CDN$184.13
Attributes
The attributes used by the formatting object are shown in the following table. Two sets of attributes are maintained by the RWDecimalFormat class: one for formatting positive numbers and one for formatting negative numbers. Member functions that set an attribute have names like setAttribute; member functions that obtain the current value of an attribute have names like attribute(). Each of these functions takes a parameter indicating whether the attribute for formatting positive values, negative values, or both is to be operated on:
Table 3: Attributes
| Attribute | Description | Default |
allDecimals | If false, the number of decimal places printed is given by the decimalPlaces attribute, otherwise all digits are printed. | false |
decimalPlaces | If allDecimals is false, this is the number of decimal places to print. Negative numbers are allowed. | 0 |
decimalSeparator | The decimal point symbol. | "." |
doRounding | If true, round the number before display. | false |
farLeftText | Text on the extreme left. | "" |
farRightText | Text on the extreme right. | "" |
fixedWidth | If false, the natural width of the number is used; if true, the width is fixed to the value of the width attribute | false |
justification | How to justify the number in the width provided (LEFT, RIGHT, or CENTER are allowed). | LEFT |
leftFillChar | Fill space to left of number with this character. | ' ' |
leftDigitSeparator | String that separates digits left of decimal point into groups. | "" |
leftGroupSize | Number of digits per group left of the decimal point | 3 |
nearLeftText | String which goes just to the left of the number. Most often used for printing a currency symbol. | "" |
nearRightText | String which goes just to the right of the number. Most often used for printing a currency symbol. | "" |
rightDigitSeparator | String which separates digits right of decimal point into groups. | "" |
rightFillChar | Fill space to right of number with this character. | ' ' |
rightGroupSize | Number of digits per group right of the decimal point. | 3 |
roundMethod | The rounding mode used to truncate decimal places (PLAIN, LEFT, RIGHT, BANKERS, TRUNCATE are allowed). | PLAIN |
roundPlaces | Number of decimal places to round if doRounding attribute is true. Negative numbers are allowed. If the allDecimals attribute is false, and the decimalPlaces attribute is less than roundPlaces, then the number is rounded to the number of digits indicated by decimalPlaces. | 0 |
showDecimalPoint | If true, the decimal point is printed when exactly zero decimal places are displayed. | false |
width | If the fixedWidth attribute is true, this determines the width of the formatted number. | 0 |
Picture Strings
A picture string uses text characters and their relative positions to indicate how to set formatting attributes. The width attribute is set to the length of the picture string. Other attributes are changed depending on the characters in the picture. The table below lists valid formatting characters. Most formatting characters can be placed in one of four positions:
At the far left of the picture string. Attributes here have their effect at the left of the number.
Immediately to the left of the separator character. Attributes here have their effect just to the left of the number's digits.
Immediately to the right of the separator character. Attributes here have their effect just to the right of the number's digits.
At the far right of the picture string. Attributes here have their effect at the right edge of the number.
Table 4: Valid formatting characters
| Char | Affect | Illustration | Example number | Formatted number |
@ | Indicates start of picture format string. Everything before the @ is taken as leading text. | Num=@____ | 4.32 | "Num=4.32" |
_ | Padding to make the width correct. | _________ | 12.346 | " 12.346" |
. | Indicates where the decimal point goes, and separates left from right formatting. | ______.__ | 12.346 | " 12.35" |
# | Separates left from right formatting. | _(_#_)_ | -12.3 | " (12.3)" |
( | Use '()' as the negative sign. | (____.__) | -12.3 | "( 12.3)" |
) | Use '()' as the negative sign. | _(___._)_ | -12.3 | " (12.3) " |
- | Use '-' as the negative sign, with position as indicated. | -_____.__ _____.__- | -12.34 -12.34 | "- 12.34" " 12.34-" |
+ | Use '+' as the plus sign, with position as indicated. | _+____.__ | 12.34 | " +12.34" |
0 | Set padding character to '0', rather than blank. Affects either before or after the decimal point. | +0___.__0 | 12.34 | "+0012.340" |
L | Left justify the number. | L_____.__ | 12.34 | " 12.34 " |
C | Center justify the number. | C_____.__ | 12.34 | " 12.34 " |
, | Separate characters before/after the decimal point into groups of three. | ,_____.__ | 1234.98 | " 1,234.98" |
$ | Add the currency symbol '$' in the position indicated. | $_____.__ | 12.34 | "$ 12.34" |
Formatting Wide Numbers
If the width attribute is smaller than needed for the number to be output, the output is marked with one or more width overflow characters (currently "*" is used). If the number would have to be truncated to the left of the decimal point in order to fit in the specified width, then the entire field is filled with width overflow characters. If the number can be made to fit by truncating at or to the right of the decimal place, then the number is output with a single trailing overflow character to indicate that truncation took place. For example, the following statements produce the strings shown:
RWDecimalFormat("________")("1234.567") -> " 1234.567"
RWDecimalFormat("______")("1234.567") -> " 1234.*"
RWDecimalFormat("___")("1234.567") -> "***"
Public Constructors
RWDecimalFormat();
Constructs an RWDecimalFormat with default attributes.
RWDecimalFormat(const char *picture);
Constructs an RWDecimalFormat object using the picture string provided.
Public Member Functions
bool allDecimals(Sign) const; int decimalPlaces(Sign) const; RWCString decimalSeparator(); bool doRounding(Sign) const; RWCString farLeftText(Sign) const; RWCString farRightText(Sign) const; bool fixedWidth(Sign) const; Justification justification(Sign) const; char leftFillChar(Sign) const; char rightFillChar(Sign) const; RWCString leftDigitSeparator(Sign) const; int leftGroupSize(Sign) const; RWCString nearLeftText(Sign) const; RWCString nearRightText(Sign) const; RWCString rightDigitSeparator(Sign) const; int rightGroupSize(Sign) const; RWDecimalBase::RoundingMethod roundMethod(Sign) const; int roundPlaces(Sign) const; bool showDecimalPoint(Sign) const; int width(Sign) const;
These functions return the current value of the indicated attribute. If the Sign parameter is RWDecimalFormat::POSITIVE, the attribute value for formatting positive numbers is returned. If the Sign parameter is RWDecimalFormat::NEGATIVE, the attribute value for formatting negative numbers is returned. If the value of Sign is RWDecimalFormat::BOTH and the attribute values for formatting positive and negative values are different, an exception is thrown. Otherwise, the common value is returned. See Attributes above for details on how each attribute affects formatting.
void setAllDecimals(bool, Sign=BOTH); void setDecimalPlaces(int, Sign=BOTH); void setDecimalSeparator(const RWCString&, Sign=BOTH); void setDoRounding(bool, Sign=BOTH); void setFarLeftText(const RWCString&, Sign=BOTH); void setFarRightText(const RWCString&, Sign=BOTH); void setFixedWidth(bool, Sign=BOTH); void setJustification(Justification, Sign=BOTH); void setLeftDigitSeparator(const RWCString&, Sign=BOTH); void setLeftFillChar(char, Sign=BOTH); void setLeftGroupSize(int, Sign=BOTH); void setNearLeftText(const RWCString&, Sign=BOTH); void setNearRightText(const RWCString&, Sign=BOTH); void setRightDigitSeparator(const RWCString&, Sign=BOTH); void setRightFillChar(char, Sign=BOTH); void setRightGroupSize(int, Sign=BOTH); void setRoundMethod(RWDecimalBase::RoundingMethod, Sign=BOTH); void setRoundPlaces(int, Sign=BOTH); void setShowDecimalPoint(bool, Sign=BOTH); void setWidth(unsigned int, Sign=BOTH);
These functions set the attribute associated with this formatter object. If the Sign parameter is RWDecimalFormat::POSITIVE, the attribute value for formatting positive numbers is set. If the Sign parameter is RWDecimalFormat::NEGATIVE, the attribute value for formatting negative numbers is set. If the value of Sign is RWDecimalFormat::BOTH, the attribute value for formatting both positive and negative numbers is set. See Attributes above to learn how each attribute affects formatting.
void setLocale(const RWLocaleSnapshot& newLocale);
Changes the interpretation of commas and decimal points in the picture strings of RWDecimalFormat. This method should only be called if the current locale, initialized at the start of a program, is not desired. This method does not affect the input/output parsing of RWDecimal and RWDecimalPortable objects; it only affects output for the current RWDecimalFormat object. For more information, see Section 9.1, "Localization," in the Currency Module User's Guide.
Public Member Operators
RWCString operator()(const char *number);
Formats the number and returns the resulting string. The number must consist of an optional plus or minus sign followed by a sequence of digits. The digit sequence may contain a decimal point.
RWCString operator()(const RWDecimal<T>&); RWCString operator()(const RWFixedDecimal<T>&);
Formats the number and returns the resulting string. The six functions shown below are for backwards compatibility only:
RWCString operator()(const RWDecimal52&); RWCString operator()(const RWDecimal64&); RWCString operator()(const RWDecimal96&); RWCString operator()(const RWFixedDecimal52&); RWCString operator()(const RWFixedDecimal64&); RWCString operator()(const RWFixedDecimal96&);
Global Operators
RWCString operator<<(const RWDecimalFormat&, const RWDecimal<T>& x); RWCString operator<<(const RWDecimalFormat&, const RWFixedDecimal<T>&);
Formats the number using the format indicated and returns a string. Since there is an automatic type conversion from char* to RWDecimalFormat you can use this operator in expressions such as:
RWCString s = "$___.__" << x;
© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.