The basic function for printing numbers under format control is {fn PRINTNUM}.  Its utility is considerably enhanced when used in conjunction with the {lisp PRINTOUT} package ({PageRef Tag PRINTOUT}), which implements a compact language for specifying complicated sequences of elementary printing operations, and makes fancy output formats easy to design and simple to program.


{FnDef {FnName PRINTNUM} {FnArgs FORMAT NUMBER FILE}
{Text
Prints {arg NUMBER} on {arg FILE} according to the format {arg FORMAT}.  {arg FORMAT} is a list structure with one of the forms described below.

{comment Interlisp-10 Specific:
{arg FORMAT} can also be a machine dependent format-code as returned by {fn NUMFORMATCODE} ({PageRef Fn NUMFORMATCODE}).If {arg NUMBER} does not fit in the field specified by {arg FORMAT}, the full print name is printed.  Then a {fn TAB} is executed so that the line position of the file after {fn PRINTNUM} is always the position prior to printing plus the indicated width.}
}}


If {arg FORMAT} is a list of the form {lisp (FIX {arg WIDTH} {arg RADIX} {arg PAD0} {arg LEFTFLUSH})}, this specifies a {lisp FIX} format.{index FIX format (in PRINTNUM) Term}  {arg NUMBER} is rounded to the nearest integer, and then printed in a field {arg WIDTH} characters long with radix set to {arg RADIX} (or 10 if {arg RADIX}={lisp NIL}; note that the setting of {fn RADIX} is {it not} used as the default).  If {arg PAD0} and {arg LEFTFLUSH} are both {lisp NIL}, the number is right-justified in the field, and the padding characters to the left of the leading digit are spaces.  If {arg PAD0} is {lisp T}, the character "{lisp 0}" is used for padding.  If {arg LEFTFLUSH} is {lisp T}, then the number is left-justified in the field, with trailing spaces to fill out {arg WIDTH} characters.


The following examples illustrate the effects of the {lisp FIX} format options on the number 9 (the vertical bars indicate the field width):


{Begin Labeledlist FIX format options examples}

{Label {arg FORMAT}:}
{Text {lisp (PRINTNUM {arg FORMAT} 9)} prints:}

{Label {lisp (FIX 2)}}
{Text {lisp | 9|}}

{Label {lisp (FIX 2 NIL T)}}
{Text {lisp |09|}}

{Label {lisp (FIX 12 8 T)}}
{Text {lisp |000000000011|}}

{Label {lisp (FIX 5 NIL NIL T)}}
{Text {lisp |9    |}}

{End Labeledlist FIX format options examples}



If {arg FORMAT} is a list of the form {lisp (FLOAT {arg WIDTH} {arg DECPART} {arg EXPPART} {arg PAD0} {arg ROUND})}, this specifies a {lisp FLOAT} format.{index FLOAT format (in PRINTNUM) Term}  {arg NUMBER} is printed as a decimal number in a field {arg WIDTH} characters wide, with {arg DECPART} digits to the right of the decimal point.  If {arg EXPPART} is not {lisp 0} (or {lisp NIL}), the number is printed in exponent notation, with the exponent occupying {arg EXPPART} characters in the field.  {arg EXPPART} should allow for the character {lisp E} and an optional sign to be printed before the exponent digits.  {Note Although written with Interlisp-10 in mind, this description of EXPPART does not agree with the Interlisp-10 implementation!  --bvm}  As with {lisp FIX} format, padding on the left is with spaces, unless {arg PAD0} is {lisp T}.  If {arg ROUND} is given, it indicates the digit position at which rounding is to take place, counting from the leading digit of the number.

Interlisp-D interprets {arg WIDTH}={lisp NIL} to mean no padding, i.e., to use however much space the number needs, and interprets {arg DECPART}={lisp NIL} to mean as many decimal places as needed.

{comment Interlisp-10 specific:  The interpretation of {arg WIDTH}={lisp NIL} and {arg DECPART}={lisp NIL} are not specified, and are currently a function of the implementation.  Interlisp-10 prohibits {arg WIDTH}={lisp NIL}, and treats {arg DECPART}={lisp NIL} as equivalent to {arg DECPART}={lisp 0}}

The following examples illustrate the effects of the {lisp FLOAT} format options on the number 27.689 (the vertical bars indicate the field width):

{Begin Labeledlist FLOAT format options examples}

{Label {arg FORMAT}:}
{Text {lisp (PRINTNUM {arg FORMAT} 27.689)} prints:}

{Label {lisp (FLOAT 7 2)}}
{Text {lisp |  27.69|}}

{Label {lisp (FLOAT 7 2 NIL T)}}
{Text {lisp |0027.69|}}

{Label {lisp (FLOAT 7 2 2)}}
{Text {lisp | 2.77E1|}}

{Label {lisp (FLOAT 11 2 4)}}
{Text {lisp |   2.77E+01|}

{comment Interlisp-10 specific:  As of this writing, the Interlisp-10 implementation actually does something less intuitive with the {arg EXPPART} field:  the placement of the decimal point is affected by {arg DECPART}, and padding never occurs.  These two examples in Interlisp-10 would actually print as {lisp |.28E+02|} and {lisp |27.69E+0000|}.}
}

{Label {lisp (FLOAT 7 2 NIL NIL 1)}}
{Text {lisp |  30.00|}}

{Label {lisp (FLOAT 7 2 NIL NIL 2)}}
{Text {lisp |  28.00|}}

{End Labeledlist FLOAT format options examples}



{VarDef {Name NILNUMPRINTFLG}
{Text
If {fn PRINTNUM}'s {arg NUMBER} argument is not a number and not {lisp NIL}, a {lisp NON-NUMERIC ARG} error is generated.  If {arg NUMBER} is {lisp NIL}, the effect depends on the setting of the variable {var NILNUMPRINTFLG}.  If {var NILNUMPRINTFLG} is {lisp NIL}, then the error occurs as usual.  If it is non-{lisp NIL}, then no error occurs, and the value of {var NILNUMPRINTFLG} is printed right-justified in the field described by {arg FORMAT}.  This option facilitates the printing of numbers in aggregates with missing values coded as {lisp NIL}.
}}