DADiSP Worksheet Functions > Function Categories > Annotation > NFORMAT

 

NFORMAT

Purpose:

Formats a list of scalars.

Syntax:

NFORMAT("control", arg1, arg2, ..., argN)

"control"

-

Format control string. Conforms to C/C++ language sprintf specifications. Control strings may contain ordinary characters, escape sequences, and format specifications. The ordinary characters are copied to the output string in order of their appearance. Escape sequences are introduced by a backslash (\). Format specifications in the control string are introduced by a percent sign (%), and are matched to the specified arguments in order. If there are more arguments than there are format specifications, the extra arguments are ignored.

argN

-

Scalar or string value that matches the control string.

For the control string, the Format Specification Fields are specified in the following form:

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

 

Flags are optional characters that control justification of output and printing of signs, blanks, decimal points, and octal and hexadecimal prefixes. More than one flag can appear in a format specification.

Flag 

Meaning

-

Left justify

+

Explicit sign (+ or -) before number.

0

If width is prefixed with 0, zeros are added until the minimum width is reached. If 0 and - appear, the 0 is ignored. If 0 is specified with an integer format (i,u,x,X,o,d), the 0 is ignored.

blank

Insert blank before positive number.

#

When used with the o,x,or X format, the # prefixes any nonzero output value with 0, 0x, or 0X. When used with the e, E, or f format, the # forces the output value to contain a decimal point in all cases. When used with the g or G format, the # forces the output value to contain a decimal point in all cases and prevents the truncation of trailing zeros.

 

Width is an optional number that specifies the minimum number of characters output.

 

Precision is an optional number that specifies the maximum number of characters printed for all or part of the output field, or minimum number of digits printed for integer values. The following table indicates the behavior of precision based on type.

 

Type  

Behavior

d, I, u, o, x, X

Precision specifies the minimum number of digits to be printed. If number of digits in the argument is less than precision, the output value is padded on the left with zeros. The value is not truncated when the number of digits exceeds precision.

e, E

Precision specifies the number of digits to be printed after the decimal point. The last printed digit is rounded.

f

Precision specifies the number of digits to be printed after the decimal point. If a decimal point appears, at least one digit appears before it. The value is rounded to the appropriate number of digits.

g, G

Precision specifies the maximum number of significant digits printed. If specified as 0, is treated as 1.

s

Precision specifies the maximum number of characters to be printed.

 

Type is a required character that determines whether the associated argument is interpreted as a character, string, or a number.

 

Type Characters   

Output Format

d, I

Signed decimal integer.

u, o

Unsigned decimal integer.

x, X

Unsigned hex integer using "abcdef" or "ABCDEF"

f

Signed value having the form [-]dddd.dddd, where dddd is one or more decimal digits.

e

Signed value having the form [-]d.dddd e [sign]ddd, where d is a single decimal digit, dddd is one or more decimal digits, ddd is exactly three decimal digits, and sign is + or -.

E

Identical to the e format, except that E, rather than e, introduces the exponent.

g

Signed value printed in f or e format, whichever is more compact or the given value and precision. The e format is used only when the exponent of the value is less than -4 or greater than or equal to the precision argument. Trailing zeros are truncated, and the decimal point appears only if one or more digits follow it.

G

Identical to the g format, except that E, rather than e, introduces the exponent.

c

Single character.

s

String. Characters printed up to the first null character or until the precision value is reached.

Returns:

A string.

Example:

nformat("Max: %4.2F Min: %4.2F", max, min)

 

returns a string like "Max: 47.20 Min: 22.03"

Remarks:

NFORMAT is a variation of the SPRINTF function that is constrained to scalars. See SPRINTF for generalized formatting.

 

See any standard C/C++ language reference for further information.

See Also:

PRINTF

SFORMAT

SPRINTF