printfstatement

NAME
SYNTAX
DESCRIPTION
USAGE
ENGINEERING NOTATION
COMPUTING SIZES
NULL
EXAMPLES
BUGS
COPYRIGHT
SEE ALSO

NAME

printf, fprintf, sprintf − RWP*Load Simulator formatted output

SYNTAX

printfstatement ::=
  sprintf identifier , concatenation { , concatenation }
| sprintf || identifier , concatenation { , concatenation }
| fprintf identifier , concatenation { , concatenation }
| printf concatenation { , concatenation }

DESCRIPTION

The statements in the printf family are very similar to their equivalents in C, and will in fact use those to do actual formatting.

The first two statements using sprintf write to a string, the first to the beginning of the string, and the second with || after the keyword to the end of the string. Both will return an error if the string does not have sufficient length.

The latter two statements, fprintf and printf write to a named file respectively stdout.

USAGE

All four require at least one concatenation as argument which normally consists of characters to be output combined with conversion specifiers starting with a % character. To output a terminating newline, the newline must be part of this concatenation. The characters after the % character are interpreted as their equivalents in C with some minor changes:

The flags generally work like in C and e.g. 0, - are useful to 0-pad respectively to left-justify.

You can provide a field width as an integer or using * in which case the value will be taken as the next argument to the statement. You can similarly use . followed by an integer or * to provide a precision. Neither of these can use an integer followed by $ to ask for a specific argument.

Only a limited set of standard conversion specifiers are useful: d, i or x for integers, e, f, g for doubles and s for strings. In addition, you can use m, M, k, K for doubles to output values with SI prefixes.

ENGINEERING NOTATION

You can output double values using engineering notation, i.e. with an SI prefix such as k for kilo, n for nano, etc. This is done using the m or M conversion specifier, and is useful when the absolute value is in the range [1.0e-30;9.99e+32] or is exactly zero. The precision has the same effect as for the standard e conversion implying the output will be rounded and have one more significant digit than given by the precision. The precision must be 2 or higher.

The symbol for micro, µ, i.e. 1e-6 is by default using the UTF-8 encoding, which is the two hexadecimal values 0xc2 and 0xb5; you must use the $musymbol directive to change this if your terminal is not using the UTF-8 (or compatible) character set.

The difference between the two specifiers is that M outputs one space character between the number and the SI-prefix, while the m outputs the SI-prefix directly after the number.

The decimal point is not output if no significant digits are output after it. This can only happen if the precision is 2 and the absolute value to be output is at least 100.

COMPUTING SIZES

If the value to be output represents a number of bytes or a similar value assumed to be a power of 1024, you can use the K or k conversion specificer to create the output using the prefixes discussed at https://en.wikipedia.org/wiki/Binary_prefix. The specifiers should only be used if the value is expected to be positive and lower than 1e32.

If you use the K specificer, the output is using a prefix like the m specifier with an additional letter ’i’ after the prefix, indicating the prefix is binary and based on a power of 1024. The actual value output is therefore scaled by a power of 1.024. Examples prefixes are Ki for kibi with the value scaled by 1.024, Gi for gibi with the value scaled by 1.024^3, etc. Non-negative values less than 1024 are rounded to integer and output without an ’i’. Negative values or values larger than 1e32 are output using exponential notation, are not scaled to a power of 1024, and do not include the ’i’.

If you use the k specificer, the output is as if it were using the m specifier without any scaling, except non-negative values less than 1000 that are output rounded to integer. Values less than zero or larger than 1e32 are output using exponential notation,

In either case, there is no space between the value and the SI prefix.

NULL

In rwloadsim, integer and double can be null and such values will by default be output as the empty string. You can provide one of the flags z, b, n, N or t to change this behavior. The flag z will cause null to be output as zero, b will cause a blank, i.e. one or more space characters, n or N will cause the output ’null’ or ’NULL’. Finally, the flag t will cause an argument to be taken as a string that will be output if a value is null.

EXAMPLES

If you execute the following:

integer a := 42, b;
double x := 12.345678;
string s := "fourtytwo";

# Show 0-padding and output of null
printf "|%07d|%d|\n", a, b;
printf "|%07d|%nd|\n", a, b;

b:=4;
# Show left justification and
# how field width and precision
# are provided as parameters
printf "|%-*.*f|\n", a/3,b,x;

# Show append to existing string
# with negative field width causing
# left justification
sprintf || s,"=%*d|", -b, a;
printline s;


# Show computer notation
printf "The speed is %.2Kbps\n", 2.5e9;

the following output will be produced

|0000042||
|0000042|null|
|12.3457       |
fourtytwo=42  |
The speed is 2.33Gibps

The following example shows how NULL can be output as respectively the text null or the user provided text "nothing":

integer a;
printf "|%Nd|%td|\n", a, "nothing", a;

which will produce the following output:

|NULL|nothing|

This example shows how the m specifier can be used:

double tt := 12.34e-6;
printf "the time is %.3ms\n", tt;

which will produce this output with the µ symbol in its UTF-8 representation.

the time is 12.34µs

BUGS

Computing sizes include the R and Q prefixes that not yet are officially in use. Who knows when robi or even quebi size computers will be available?