fish-shell/sphinx_doc_src/cmds/printf.rst

.. _cmd-printf:

printf - display text according to a format string
==================================================

Synopsis
--------

::

    printf FORMAT [ARGUMENT ...]

Description
-----------
printf formats the string FORMAT with ARGUMENT, and displays the result.

The string FORMAT should contain format specifiers, each of which are replaced with successive arguments according to the specifier. Specifiers are detailed below, and are taken from the C library function ``printf(3)``.

Unlike ``echo``, ``printf`` does not append a new line unless it is specified as part of the string.

Valid format specifiers are:

- ``%%d``: Argument will be used as decimal integer (signed or unsigned)

- ``%%i``: Argument will be used as a signed integer

- ``%%o``: An octal unsigned integer

- ``%%u``: An unsigned decimal integer

- ``%%x`` or ``%%X``: An unsigned hexadecimal integer

- ``%%f``, ``%%g`` or ``%%G``: A floating-point number

- ``%%e`` or ``%%E``: A floating-point number in scientific (XXXeYY) notation

- ``%%s``: A string

- ``%%b``: As a string, interpreting backslash escapes, except that octal escapes are of the form \0 or \0ooo.

``%%`` signifies a literal "%".

Note that conversion may fail, e.g. "102.234" will not losslessly convert to an integer, causing printf to print an error.

printf also knows a number of backslash escapes:
- ``\"`` double quote
- ``\\`` backslash
- ``\a`` alert (bell)
- ``\b`` backspace
- ``\c`` produce no further output
- ``\e`` escape
- ``\f`` form feed
- ``\n`` new line
- ``\r`` carriage return
- ``\t`` horizontal tab
- ``\v`` vertical tab
- ``\ooo`` octal number (ooo is 1 to 3 digits)
- ``\xhh`` hexadecimal number (hhh is 1 to 2 digits)
- ``\uhhhh`` 16-bit Unicode character (hhhh is 4 digits)
- ``\Uhhhhhhhh`` 32-bit Unicode character (hhhhhhhh is 8 digits)

The ``format`` argument is re-used as many times as necessary to convert all of the given arguments. If a format specifier is not appropriate for the given argument, an error is printed. For example, ``printf '%d' "102.234"`` produces an error, as "102.234" cannot be formatted as an integer.

This file has been imported from the printf in GNU Coreutils version 6.9. If you would like to use a newer version of printf, for example the one shipped with your OS, try ``command printf``.

Example
-------


::

    printf '%s\\t%s\\n' flounder fish

Will print "flounder	fish" (separated with a tab character), followed by a newline character. This is useful for writing completions, as fish expects completion scripts to output the option followed by the description, separated with a tab character.


::

    printf '%s: %d' "Number of bananas in my pocket" 42

Will print "Number of bananas in my pocket: 42", _without_ a newline.
docs: Add labels to all commands This allows us to use :ref: references, which don't require hardcoding it as html [ci skip] 2019-03-31 17:05:09 +08:00			`.. _cmd-printf:`

Switch command docs from \section to reStructuredText 2018-12-17 09:39:33 +08:00			`printf - display text according to a format string`
Fix command section separator line lengths 2019-01-03 12:10:47 +08:00			`==================================================`
Switch command docs from \section to reStructuredText 2018-12-17 09:39:33 +08:00
Migrate the 'synopsis' sections to .rst format 2018-12-18 09:58:24 +08:00			`Synopsis`
			`--------`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
docs: update all command synopsis formatting Adds synopses for those commands missing them. Moves all synopsis sections to code blocks. This improves the appearance, although highlighting as fish code may not be the ideal appearance. 2019-09-17 17:59:04 +08:00			`::`
Migrate the 'synopsis' sections to .rst format 2018-12-18 09:58:24 +08:00
docs: update all command synopsis formatting Adds synopses for those commands missing them. Moves all synopsis sections to code blocks. This improves the appearance, although highlighting as fish code may not be the ideal appearance. 2019-09-17 17:59:04 +08:00			`printf FORMAT [ARGUMENT ...]`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Convert \\subsection sections into rst format 2018-12-19 10:44:30 +08:00			`Description`
Fix command section separator line lengths 2019-01-03 12:10:47 +08:00			`-----------`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00			`printf formats the string FORMAT with ARGUMENT, and displays the result.`

Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			The string FORMAT should contain format specifiers, each of which are replaced with successive arguments according to the specifier. Specifiers are detailed below, and are taken from the C library function ``printf(3)``.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			Unlike ``echo``, ``printf`` does not append a new line unless it is specified as part of the string.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
			`Valid format specifiers are:`

Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``%%d``: Argument will be used as decimal integer (signed or unsigned)
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``%%i``: Argument will be used as a signed integer
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``%%o``: An octal unsigned integer
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``%%u``: An unsigned decimal integer
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``%%x`` or ``%%X``: An unsigned hexadecimal integer
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``%%f``, ``%%g`` or ``%%G``: A floating-point number
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``%%e`` or ``%%E``: A floating-point number in scientific (XXXeYY) notation
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``%%s``: A string
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``%%b``: As a string, interpreting backslash escapes, except that octal escapes are of the form \0 or \0ooo.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			``%%`` signifies a literal "%".
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
			`Note that conversion may fail, e.g. "102.234" will not losslessly convert to an integer, causing printf to print an error.`

			`printf also knows a number of backslash escapes:`
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``\"`` double quote
			- ``\\`` backslash
			- ``\a`` alert (bell)
			- ``\b`` backspace
			- ``\c`` produce no further output
			- ``\e`` escape
			- ``\f`` form feed
			- ``\n`` new line
			- ``\r`` carriage return
			- ``\t`` horizontal tab
			- ``\v`` vertical tab
			- ``\ooo`` octal number (ooo is 1 to 3 digits)
			- ``\xhh`` hexadecimal number (hhh is 1 to 2 digits)
			- ``\uhhhh`` 16-bit Unicode character (hhhh is 4 digits)
			- ``\Uhhhhhhhh`` 32-bit Unicode character (hhhhhhhh is 8 digits)

			The ``format`` argument is re-used as many times as necessary to convert all of the given arguments. If a format specifier is not appropriate for the given argument, an error is printed. For example, ``printf '%d' "102.234"`` produces an error, as "102.234" cannot be formatted as an integer.

			This file has been imported from the printf in GNU Coreutils version 6.9. If you would like to use a newer version of printf, for example the one shipped with your OS, try ``command printf``.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Convert \\subsection sections into rst format 2018-12-19 10:44:30 +08:00			`Example`
Fix command section separator line lengths 2019-01-03 12:10:47 +08:00			`-------`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch \fish sections to rst format 2018-12-19 11:14:04 +08:00

			`::`

			`printf '%s\\t%s\\n' flounder fish`

Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00			`Will print "flounder fish" (separated with a tab character), followed by a newline character. This is useful for writing completions, as fish expects completion scripts to output the option followed by the description, separated with a tab character.`

Switch \fish sections to rst format 2018-12-19 11:14:04 +08:00

			`::`

Incorporate most new doc changes since branch Adds most documentation changes since 72c0213d42b77b2f01223b5515669840110ea9b9 2019-02-25 07:01:16 +08:00			`printf '%s: %d' "Number of bananas in my pocket" 42`
Switch \fish sections to rst format 2018-12-19 11:14:04 +08:00
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00			`Will print "Number of bananas in my pocket: 42", _without_ a newline.`