printf and sprintf Formatting

Boxer's Macro Language has two functions that support formatted printing.  printf and sprintf are functions that allow output to be formatted before being sent to a destination. For sprintf, the destination is a supplied string variable.  For printf, the destination is the currently edited text file. 

The implementation of these functions is very similar to their implementation in the C programming language.  Just a few of the most esoteric formatting options have been left unimplemented in Boxer's Macro Language.  If you are already familiar with the formatting offered by printf and sprintf, you will probably not need to consult this reference section.

The formatting of the output is controlled by a format string. The format string is a character string containing two types of objects: ordinary characters which are copied directly to the destination, and conversion specifications, each of which is introduced with the % symbol.

A conversion specification has the following form:

       %[flags][width][.precision][type]

The fields of the conversion specification have the following meanings:

flags (optional)

-

Left-justifies the result, pads on the right with blanks. If not supplied, it right-justifies the result, padding on the left with zeros or blanks.

+

Signed conversion results will always begin with a plus (+) or minus (-) sign.

space

If the value is non-negative, the output begins with a space instead of a plus; negative values begin with a minus.

width (optional)

n

At least n characters are printed. If the output value has fewer than n characters, the output is padded with spaces.

0n

At least n characters are printed. If the output value has fewer than n characters, it is filled on the left with zeros.

precision (optional)

(none)       Precision set to default:

              1 for d, i, o, u, x, X types

              6 for e, E, f types

              all significant digits for g, G types

              print to first null character for s types

              No effect on c types

.0           For d, i, o, u, x types, precision is set to default

            For e, E, f types, no decimal point is printed.

.n           n characters or n decimal places are printed.

            If the output value has more than n characters, the output might be truncated

            or rounded. (Whether or not this happens depends on the type character.)

No numeric characters will be output for a field (i.e., the field will be blank) if the following conditions are all met:

How precision affects the conversion performed for each type:

Type         Effect of precision (.n) on conversion

-------------------------------------------------------------------------------------------

d           Indicates that at least n digits are printed. If input argument has fewer than

i           n digits, output value is left-padded x with zeros. If input argument has more

o           than n digits, the output value is not truncated.

u

x

X

e           Specifies that n characters are printed after the decimal point, and the last

E           digit printed is rounded.

f

g           Specifies that at most n significant digits are printed.

G

c           Has no effect on the output.

s           Specifies that no more than n characters are printed.

type (required)

The type parameter specifies what kind of conversion printf or sprintf performs. The following conversion characters are supported:

%

Prints the percent character (%).

c

Prints a single character.

s

Prints a string.

d

Prints a signed decimal integer.

i

Prints a signed decimal integer (same as d)

o

Prints a signed octal integer.

u

Prints an unsigned decimal integer.

x

Prints an unsigned hexadecimal integer using a-f as may be required.

X

Prints an unsigned hexadecimal integer using A-F as may be required.

f

Prints a floating point value of the form [-]9999.9999.

e

Prints a floating point value of the form [-]9.9999e[+|-]999.

E

Prints a floating point value of the form [-]9.9999E[+|-]999.

g

Prints a signed value in either f or e form, based on the value and precision. Trailing zeros and the decimal point are printed only if necessary.

G

Prints the same as g, but uses 'E' for the exponent if an exponent is needed.

Example Format Strings

format string          output

--------------------------------------------------------------------------------------------

"save 25%%"            save 25%

"%-25s"                outputs a string left justified in a 25-character wide field

"%8d"                  output a decimal value right justified in an 8-character wide field

"%10.2f"               outputs a floating point value with 2 decimal places in a 10-character

                      wide field

"%08X"                 output a hexadecimal value with leading zeros in an 8-character wide

                      field

"\"yes\""              "yes"

Example Macro

This macro illustrates the use of printf with a formatting string that includes the %c, %d, %x and %o format specifiers.  The  decimalvalue (%d) will be right justified in a field of three characters.  The hexadecimal value (%x) will be printed in a field of three characters with a leading zero.  The octal value (%o) will be printed in a field of three characters with leading zeros.  Notice that the variable i is placed on the argument list once for each format specifier that appears in the format string.

macro chart()

{­

// open a temporary new file

New;

// loop from the space character to value 255

for (int i = ' '; i <= 255; i++)

       printf("char: '%c'   dec: %3d  hex: %02X  oct: %03o\n", i, i, i, i);

}