FreeMat - PRINTF Formated Output Function (C-Style)

PRINTF Formated Output Function (C-Style)

Usage

Prints values to the output. The general syntax for its use is

  printf(format,a1,a2,...)

Here format is the format string, which is a string that controls the format of the output. The values of the variables a_i are substituted into the output as required. It is an error if there are not enough variables to satisfy the format string. Note that this printf command is not vectorized! Each variable must be a scalar. It is important to point out that the printf function does not add a newline (or carriage return) to the output by default. That can lead to some confusing behavior if you do not know what to expect. For example, the command printf('Hello') does not appear to produce any output. In fact, it does produce the text, but it then gets overwritten by the prompt. To see the text, you need printf('Hello\n'). This seems odd, but allows you to assemble a line using multiple printf commands, including the '\n' when you are done with the line. You can also use the '\r' character as an explicit carriage return (with no line feed). This allows you to write to the same line many times (to show a progress string, for example).

Format of the format string

The format string is a character string, beginning and ending in its initial shift state, if any. The format string is composed of zero or more directives: ordinary characters (not %), which are copied unchanged to the output stream; and conversion specifications, each of which results in fetching zero or more subsequent arguments. Each conversion specification is introduced by the character %, and ends with a conversion specifier. In between there may be (in this order) zero or more flags, an optional minimum field width, and an optional precision. The arguments must correspond properly (after type promotion) with the conversion specifier, and are used in the order given.

The flag characters

The character % is followed by zero or more of the following flags:

\# The value should be converted to an ``alternate form''. For o conversions, the first character of the output string is made zero (by prefixing a 0 if it was not zero already). For x and X conversions, a nonzero result has the string '0x' (or '0X' for X conversions) prepended to it. For a, A, e, E, f, F, g, and G conversions, the result will always contain a decimal point, even if no digits follow it (normally, a decimal point appears in the results of those conversions only if a digit follows). For g and G conversions, trailing zeros are not removed from the result as they would otherwise be. For other conversions, the result is undefined.
0 The value should be zero padded. For d, i, o, u, x, X, a, A, e, E, f, F, g, and G conversions, the converted value is padded on the left with zeros rather than blanks. If the 0 and - flags both appear, the 0 flag is ignored. If a precision is given with a numeric conversion (d, i, o, u, x, and X), the 0 flag is ignored. For other conversions, the behavior is undefined.
- The converted value is to be left adjusted on the field boundary. (The default is right justification.) Except for n conversions, the converted value is padded on the right with blanks, rather than on the left with blanks or zeros. A - overrides a 0 if both are given.
' ' (a space) A blank should be left before a positive number (or empty string) produced by a signed conversion.
+ A sign (+ or -) always be placed before a number produced by a signed conversion. By default a sign is used only for negative numbers. A + overrides a space if both are used.

The field width

An optional decimal digit string (with nonzero first digit) specifying a minimum field width. If the converted value has fewer characters than the field width, it will be padded with spaces on the left (or right, if the left-adjustment flag has been given). A negative field width is taken as a '-' flag followed by a positive field width. In no case does a non-existent or small field width cause truncation of a field; if the result of a conversion is wider than the field width, the field is expanded to contain the conversion result.

The precision

An optional precision, in the form of a period ('.') followed by an optional decimal digit string. If the precision is given as just '.', or the precision is negative, the precision is taken to be zero. This gives the minimum number of digits to appear for d, i, o, u, x, and X conversions, the number of digits to appear after the radix character for a, A, e, E, f, and F conversions, the maximum number of significant digits for g and G conversions, or the maximum number of characters to be printed from a string for s conversions.

The conversion specifier

A character that specifies the type of conversion to be applied. The conversion specifiers and their meanings are:

d,i The int argument is converted to signed decimal notation. The precision, if any, gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is padded on the left with zeros. The default precision is 1. When 0 is printed with an explicit precision 0, the output is empty.
o,u,x,X The unsigned int argument is converted to unsigned octal (o), unsigned decimal (u), or unsigned hexadecimal (x and X) notation. The letters abcdef are used for x conversions; the letters ABCDEF are used for X conversions. The precision, if any, gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is padded on the left with zeros. The default precision is 1. When 0 is printed with an explicit precision 0, the output is empty.
e,E The double argument is rounded and converted in the style [-]d.ddde dd where there is one digit before the decimal-point character and the number of digits after it is equal to the precision; if the precision is missing, it is taken as 6; if the precision is zero, no decimal-point character appears. An E conversion uses the letter E (rather than e) to introduce the exponent. The exponent always contains at least two digits; if the value is zero, the exponent is 00.
f,F The double argument is rounded and converted to decimal notation in the style [-]ddd.ddd, where the number of digits after the decimal-point character is equal to the precision specification. If the precision is missing, it is taken as 6; if the precision is explicitly zero, no decimal-point character appears. If a decimal point appears, at least one digit appears before it.
g,G The double argument is converted in style f or e (or F or E for G conversions). The precision specifies the number of significant digits. If the precision is missing, 6 digits are given; if the precision is zero, it is treated as 1. Style e is used if the exponent from its conversion is less than -4 or greater than or equal to the precision. Trailing zeros are removed from the fractional part of the result; a decimal point appears only if it is followed by at least one digit.
c The int argument is converted to an unsigned char, and the resulting character is written.
s The string argument is printed.
% A '%' is written. No argument is converted. The complete conversion specification is '%%'.

Example

Here are some examples of the use of printf with various arguments. First we print out an integer and double value.

--> printf('intvalue is %d, floatvalue is %f\n',3,1.53);
intvalue is 3, floatvalue is 1.530000

Next, we print out a string value.

--> printf('string value is %s\n','hello');
string value is hello

Now, we print out an integer using 12 digits, zeros up front.

--> printf('integer padded is %012d\n',32);
integer padded is 000000000032

Print out a double precision value with a sign, a total of 18 characters (zero prepended if necessary), a decimal point, and 12 digit precision.

--> printf('float value is %+018.12f\n',pi);
float value is +0003.141592653590

FreeMat v4.0 - Online Documentation