7.2 Formatting Numbers in C++

A picture is a textual representation of how a formatted number should look. The most basic picture simply describes the width of the formatted number using underscores to hold places. For example, to show that a number should have width eight, use a picture consisting of eight underscores. The underscores are numbered to show the width.

________
12345678

This will format the number 4.367, for example, as

4.367

To indicate where the decimal point should go, simply put the decimal point into the picture. A width eight number with two decimal places is specified with the following picture:

_____.__
12345678

(Note that the decimal point is included as one character in the width of the number format.) In this case, our number is formatted as

4.37

Rounding occurs automatically to make the number fit. Later, we'll show how you can set the rounding method.

7.2.1 Using Pictures

Here is one way to use a picture to print a number onto a stream:

RWDecimal<RWMP1Int> x = "4.367";
cout << RWDecimalFormat("_____.__")(x);// prints 4.37

This code constructs a formatter object from a picture string, and then invokes the function call operator with argument x. The function call operator has been overloaded to format an RWDecimal<T> into an RWCString. Finally the string is shifted out to standard output.

If you plan to use a particular picture over and over, it is more efficient to construct a single formatter object and reuse it. Here's how:

RWDecimalFormat format("_____.__");
cout << format(x) << format(y);// x and y are RWDecimals

7.2.2 Advanced Pictures

By using special characters in pictures you can indicate more precisely how the number should look. For example, you can show that a dollar sign is to be prepended to a number by putting a dollar sign in the picture:

____$.__  -->  $4.37
12345678

A leading zero indicates that leading space is filled in with zeros:

$0___.__  -->  $0004.37
12345678

A plus sign indicates that positive numbers are to be explicitly indicated:

+0___.__  -->  +0004.37
12345678

Use parentheses to show that negative numbers should be printed in parentheses:

(______)  ->  (3.21)
12345678

Other special symbols include L and C, for setting left and center justification, a minus sign to indicate that negative numbers should be shown with a minus sign, and a comma to indicate breaking digits into comma separated groups of three.

NOTE: Refer to the RWDecimalFormat entry in the Class Reference for a complete list of formatting options.

7.2.3 Code Positions in Pictures

The position of codes in pictures determines where those codes will have an effect. For example, if the dollar sign character is placed at the far left of a picture, a dollar sign will be placed at the very left edge of the formatted number. If the dollar sign is separated from the left edge of the picture by at least one underscore, the dollar sign will be shown just to the left of the digits in the formatted number:

$____.__  ->  "$   4.37"
12345678
____$.__  ->  "   $4.37"
12345678

This positioning convention also applies to placement of the minus sign for negative numbers:

-____.__  ->  "-   3.21"
12345678
__-__.__  ->  "   -3.21"
12345678
____.__-  ->  "   3.21-"
12345678

There are four possible positions for any code character: far left, near left, near right, and far right. The left and right positions are determined by which side of the decimal point the code character is shown on. For formats that do not have a fixed number of decimal places, you can use a # character to separate the left fields from the right. Whether the code is placed in the far or near position is determined by the use of underscores. Most code characters will have their effect determined by which of these four fields they are located in. Here's an example of using the fields to determine precisely where to place parentheses to show negative numbers:

C(__#__)  -->  ( 3.21 )
12345678       12345678

C__(#__)  -->   (3.21 )
12345678       12345678

C(__#)__  -->  ( 3.21) 
12345678       12345678

C__(#)__  -->   (3.21)  
12345678       12345678

7.2.4 Embedding Pictures in Sentences

You can show leading and trailing text in pictures. For example,

you owe _$,__.__ to us  -->  you owe $1,356.32 to us

A problem is that any leading text that contains a code character (like an L, a comma, or a C) will be interpreted itself as a picture. To resolve this, if the picture text contains an at sign (@), this is taken as the first character of the picture string:

Let's pay $@____ to Chuck  -->  Let's pay $231 to Chuck