.. highlightlang:: us

.. index:: printf

.. _printf:

printf
======

.. us.tag  printf NOTREADYENGLISH

:ref:`printf` prints formatted data into the command window.

.. function::  rsNChars = printf(ssFormat, arg1, ...)

.. us.return

**Return Value**

*rsNChars* is the number of output characters or -1 if an error occurred.

.. us.params

**Parameters**

.. uparam:: ssFormat

   *ssFormat* is a scalar string with embedded format specifications. A format
   specification has the following form::

      %{flags}[width][.precision][m|l|L]type

   %
      The format specification begins with a percent sign (%). To print a percent
      sign ``%%`` must be written.

   *flags*
      A *flag* is one of the following characters:

      .. list-table::
         :header-rows: 1

         * - Value
           - Meaning
         * - ``-``
           - causes the output to be left justified.
         * - ``+``
           - Prefix the output value with a sign (+ or -)
         * - ``#``
           - When used with the o, x, or X format, the # flag prefixes any nonzero output value with 0, 0x, or 0X, respectively. When used with the e, E, or f format, the # flag forces the output value to contain a decimal point in all cases. When used with the g or G format, the # flag forces the output value to contain a decimal point in all cases and prevents the truncation of trailing zeros.
         * - (blank) " "
           - Prefix the positiv output value with a blank
         * - ``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) and a precision specification is also present (for example, %04.d), the 0 is ignored.

   *width*
      *width* Optional number that specifies minimum number of characters output.

   *.precision*
      *precision* Optional number that specifies maximum number of characters
      printed for all or part of the output field, or minimum number of digits
      printed for integer values.

   .. bug de

   **m**
      causes the output to be done row by row for matrices and column vectors.

   **l,L**
      The characters ``"l"`` and ``"L"`` are ignored.

   *type*
      The *type*  character is the only required format field:

      .. list-table::
         :header-rows: 1

         * - Value
           - Meaning
         * - f
           - Real value having the form [-]dddd.dddd, where dddd is one or more decimal digits.
         * - e, E
           - The argument is a real 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 -.
         * - g, G
           - The argument is real. The output works in "e" or "E" format when the exponent of the argulment is smaller than 3 or larger than the precision is. Otherwise the output follows in "f" format.
         * - i, d, u
           - The argument is real. It will be converted to an integer.
         * - x, X, p
           - The argument is real. It will be converted to a hexamdecimal number.
         * - o
           - The argument is real. It will be converted an octal number.
         * - c
           - The argument is real. It will be converted to an ASCII character.
         * - s
           - The argument is a string.

.. us.example

**Example**

::

   * a = rand(1,5) * 100
   * printf("%10d\n%10.2f\n%10.2e\n%10.2g\n", a, a, a, a)
       86         8        43        84        98
        86.18      8.30     43.97     84.32     98.93
     8.62e+01  8.30e+00  4.40e+01  8.43e+01  9.89e+01
       86       8.3        44        84        99
     204.0000
   * printf("This is a string")
   This is a string    15.0000

.. seealso::
   :ref:`fprintf`,
   :ref:`sprintf`,
   :ref:`ltostr`

:sub:`id-1871575`