RWDecimalFormat

• Data Type and Member Function Indexes
• Synopsis
• Related Java Class
• Description
• Example
• Attributes
• Picture Strings
• Formatting Wide Numbers
• Public Constructors
• Public Member Functions
• Public Member Operators
• Global Operators

Member Functions
allDecimals() decimalPlaces() decimalSeparator() doRounding() farLeftText() farRightText() fixedWidth() justification() leftDigitSeparator() leftFillChar() leftGroupSize()	nearLeftText() nearRightText() operator<<() operator()() rightDigitSeparator() rightFillChar() rightGroupSize() roundMethod() roundPlaces() setAllDecimals() setDecimalPlaces()	setDecimalSeparator() setDoRounding() setFarLeftText() setFarRightText() setFixedWidth() setJustification() setLeftDigitSeparator() setLeftFillChar() setLeftGroupSize() setLocale() setNearLeftText()	setNearRightText() setRightDigitSeparator() setRightFillChar() setRightGroupSize() setRoundMethod() setRoundPlaces() setShowDecimalPoint() setWidth() showDecimalPoint() width()

#include <rw/decio.h>
main(){cout << RWDecimalFormat("$_____.__")("2.243") << endl;}

com.roguewave.money.currency.v1_0.MoneyFormat

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:

1. 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".

2. 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.

#include <iostream.h>
#include <rw/money/decimal.h>
#include <rw/decio.h>
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

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 take a parameter indicating whether the attribute for formatting positive values, negative values, or both is to be operated on:

Table 3 -- Attributes

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

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")      -> "***"

RWDecimalFormat();

Constructs an RWDecimalFormat with default attributes.

RWDecimalFormat(const char *picture);

Constructs an RWDecimalFormat object using the picture string provided.

RWBoolean
allDecimals(Sign) const;
int
decimalPlaces(Sign) const;
RWCString
decimalSeparator(Sign) const;
RWBoolean
doRounding(Sign) const;
RWCString
farLeftText(Sign) const;
RWCString
farRightText(Sign) const;
RWBoolean
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;
RWBoolean
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 the "Attributes" section above for details on how each attribute affects formatting.

void
setAllDecimals(RWBoolean, Sign=BOTH);
void
setDecimalPlaces(int, Sign=BOTH);
void
setDecimalSeparator(const RWCString&, Sign=BOTH);
void
setDoRounding(RWBoolean, Sign=BOTH);
void
setFarLeftText(const RWCString&, Sign=BOTH);
void
setFarRightText(const RWCString&, Sign=BOTH);
void
setFixedWidth(RWBoolean, 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(RWBoolean, 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 the "Attributes" section for details on 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. See Section 9.1 of the User's Guide for further information.

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&);

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 1999, Rogue Wave Software, Inc.
Send mail to report errors or comment on the documentation.