Adding upstream version 14.2.21.upstream/14.2.21upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 415 insertions, 0 deletions

diff --git a/src/seastar/fmt/doc/syntax.rst b/src/seastar/fmt/doc/syntax.rst
new file mode 100644
index 00000000..fc27c5e2
--- /dev/null
+++ b/src/seastar/fmt/doc/syntax.rst
@@ -0,0 +1,415 @@
+.. _syntax:
+
+********************
+Format String Syntax
+********************
+
+Formatting functions such as :ref:`fmt::format() <format>` and
+:ref:`fmt::print() <print>` use the same format string syntax described in this
+section.
+
+Format strings contain "replacement fields" surrounded by curly braces ``{}``.
+Anything that is not contained in braces is considered literal text, which is
+copied unchanged to the output.  If you need to include a brace character in the
+literal text, it can be escaped by doubling: ``{{`` and ``}}``.
+
+The grammar for a replacement field is as follows:
+
+.. productionlist:: sf
+   replacement_field: "{" [`arg_id`] [":" `format_spec`] "}"
+   arg_id: `integer` | `identifier`
+   integer: `digit`+
+   digit: "0"..."9"
+   identifier: `id_start` `id_continue`*
+   id_start: "a"..."z" | "A"..."Z" | "_"
+   id_continue: `id_start` | `digit`
+
+In less formal terms, the replacement field can start with an *arg_id*
+that specifies the argument whose value is to be formatted and inserted into
+the output instead of the replacement field.
+The *arg_id* is optionally followed by a *format_spec*, which is preceded
+by a colon ``':'``.  These specify a non-default format for the replacement value.
+
+See also the :ref:`formatspec` section.
+
+If the numerical arg_ids in a format string are 0, 1, 2, ... in sequence,
+they can all be omitted (not just some) and the numbers 0, 1, 2, ... will be
+automatically inserted in that order.
+
+Named arguments can be referred to by their names or indices.
+
+Some simple format string examples::
+
+   "First, thou shalt count to {0}" // References the first argument
+   "Bring me a {}"                  // Implicitly references the first argument
+   "From {} to {}"                  // Same as "From {0} to {1}"
+
+The *format_spec* field contains a specification of how the value should be
+presented, including such details as field width, alignment, padding, decimal
+precision and so on.  Each value type can define its own "formatting
+mini-language" or interpretation of the *format_spec*.
+
+Most built-in types support a common formatting mini-language, which is
+described in the next section.
+
+A *format_spec* field can also include nested replacement fields in certain
+positions within it. These nested replacement fields can contain only an
+argument id; format specifications are not allowed. This allows the formatting
+of a value to be dynamically specified.
+
+See the :ref:`formatexamples` section for some examples.
+
+.. _formatspec:
+
+Format Specification Mini-Language
+==================================
+
+"Format specifications" are used within replacement fields contained within a
+format string to define how individual values are presented (see
+:ref:`syntax`).  Each formattable type may define how the format
+specification is to be interpreted.
+
+Most built-in types implement the following options for format specifications,
+although some of the formatting options are only supported by the numeric types.
+
+The general form of a *standard format specifier* is:
+
+.. productionlist:: sf
+   format_spec: [[`fill`]`align`][`sign`]["#"]["0"][`width`]["." `precision`][`type`]
+   fill: <a character other than '{', '}' or '\0'>
+   align: "<" | ">" | "=" | "^"
+   sign: "+" | "-" | " "
+   width: `integer` | "{" `arg_id` "}"
+   precision: `integer` | "{" `arg_id` "}"
+   type: `int_type` | "a" | "A" | "c" | "e" | "E" | "f" | "F" | "g" | "G" | "p" | "s"
+   int_type: "b" | "B" | "d" | "n" | "o" | "x" | "X"
+
+The *fill* character can be any character other than '{', '}' or '\\0'. The
+presence of a fill character is signaled by the character following it, which
+must be one of the alignment options.  If the second character of *format_spec*
+is not a valid alignment option, then it is assumed that both the fill character
+and the alignment option are absent.
+
+The meaning of the various alignment options is as follows:
+
++---------+----------------------------------------------------------+
+| Option  | Meaning                                                  |
++=========+==========================================================+
+| ``'<'`` | Forces the field to be left-aligned within the available |
+|         | space (this is the default for most objects).            |
++---------+----------------------------------------------------------+
+| ``'>'`` | Forces the field to be right-aligned within the          |
+|         | available space (this is the default for numbers).       |
++---------+----------------------------------------------------------+
+| ``'='`` | Forces the padding to be placed after the sign (if any)  |
+|         | but before the digits.  This is used for printing fields |
+|         | in the form '+000000120'. This alignment option is only  |
+|         | valid for numeric types.                                 |
++---------+----------------------------------------------------------+
+| ``'^'`` | Forces the field to be centered within the available     |
+|         | space.                                                   |
++---------+----------------------------------------------------------+
+
+Note that unless a minimum field width is defined, the field width will always
+be the same size as the data to fill it, so that the alignment option has no
+meaning in this case.
+
+The *sign* option is only valid for number types, and can be one of the
+following:
+
++---------+----------------------------------------------------------+
+| Option  | Meaning                                                  |
++=========+==========================================================+
+| ``'+'`` | indicates that a sign should be used for both            |
+|         | positive as well as negative numbers.                    |
++---------+----------------------------------------------------------+
+| ``'-'`` | indicates that a sign should be used only for negative   |
+|         | numbers (this is the default behavior).                  |
++---------+----------------------------------------------------------+
+| space   | indicates that a leading space should be used on         |
+|         | positive numbers, and a minus sign on negative numbers.  |
++---------+----------------------------------------------------------+
+
+The ``'#'`` option causes the "alternate form" to be used for the
+conversion.  The alternate form is defined differently for different
+types.  This option is only valid for integer and floating-point types.
+For integers, when binary, octal, or hexadecimal output is used, this
+option adds the prefix respective ``"0b"`` (``"0B"``), ``"0"``, or
+``"0x"`` (``"0X"``) to the output value.  Whether the prefix is
+lower-case or upper-case is determined by the case of the type
+specifier, for example, the prefix ``"0x"`` is used for the type ``'x'``
+and ``"0X"`` is used for ``'X'``.  For floating-point numbers the
+alternate form causes the result of the conversion to always contain a
+decimal-point character, even if no digits follow it. Normally, a
+decimal-point character appears in the result of these conversions
+only if a digit follows it. In addition, for ``'g'`` and ``'G'``
+conversions, trailing zeros are not removed from the result.
+
+.. ifconfig:: False
+
+   The ``','`` option signals the use of a comma for a thousands separator.
+   For a locale aware separator, use the ``'n'`` integer presentation type
+   instead.
+
+*width* is a decimal integer defining the minimum field width.  If not
+specified, then the field width will be determined by the content.
+
+Preceding the *width* field by a zero (``'0'``) character enables
+sign-aware zero-padding for numeric types.  This is equivalent to a *fill*
+character of ``'0'`` with an *alignment* type of ``'='``.
+
+The *precision* is a decimal number indicating how many digits should be
+displayed after the decimal point for a floating-point value formatted with
+``'f'`` and ``'F'``, or before and after the decimal point for a floating-point
+value formatted with ``'g'`` or ``'G'``.  For non-number types the field
+indicates the maximum field size - in other words, how many characters will be
+used from the field content. The *precision* is not allowed for integer,
+character, Boolean, and pointer values.
+
+Finally, the *type* determines how the data should be presented.
+
+The available string presentation types are:
+
++---------+----------------------------------------------------------+
+| Type    | Meaning                                                  |
++=========+==========================================================+
+| ``'s'`` | String format. This is the default type for strings and  |
+|         | may be omitted.                                          |
++---------+----------------------------------------------------------+
+| none    | The same as ``'s'``.                                     |
++---------+----------------------------------------------------------+
+
+The available character presentation types are:
+
++---------+----------------------------------------------------------+
+| Type    | Meaning                                                  |
++=========+==========================================================+
+| ``'c'`` | Character format. This is the default type for           |
+|         | characters and may be omitted.                           |
++---------+----------------------------------------------------------+
+| none    | The same as ``'c'``.                                     |
++---------+----------------------------------------------------------+
+
+The available integer presentation types are:
+
++---------+----------------------------------------------------------+
+| Type    | Meaning                                                  |
++=========+==========================================================+
+| ``'b'`` | Binary format. Outputs the number in base 2. Using the   |
+|         | ``'#'`` option with this type adds the prefix ``"0b"``   |
+|         | to the output value.                                     |
++---------+----------------------------------------------------------+
+| ``'B'`` | Binary format. Outputs the number in base 2. Using the   |
+|         | ``'#'`` option with this type adds the prefix ``"0B"``   |
+|         | to the output value.                                     |
++---------+----------------------------------------------------------+
+| ``'d'`` | Decimal integer. Outputs the number in base 10.          |
++---------+----------------------------------------------------------+
+| ``'o'`` | Octal format. Outputs the number in base 8.              |
++---------+----------------------------------------------------------+
+| ``'x'`` | Hex format. Outputs the number in base 16, using         |
+|         | lower-case letters for the digits above 9. Using the     |
+|         | ``'#'`` option with this type adds the prefix ``"0x"``   |
+|         | to the output value.                                     |
++---------+----------------------------------------------------------+
+| ``'X'`` | Hex format. Outputs the number in base 16, using         |
+|         | upper-case letters for the digits above 9. Using the     |
+|         | ``'#'`` option with this type adds the prefix ``"0X"``   |
+|         | to the output value.                                     |
++---------+----------------------------------------------------------+
+| ``'n'`` | Number. This is the same as ``'d'``, except that it uses |
+|         | the current locale setting to insert the appropriate     |
+|         | number separator characters.                             |
++---------+----------------------------------------------------------+
+| none    | The same as ``'d'``.                                     |
++---------+----------------------------------------------------------+
+
+Integer presentation types can also be used with character and Boolean values.
+Boolean values are formatted using textual representation, either ``true`` or
+``false``, if the presentation type is not specified.
+
+The available presentation types for floating-point values are:
+
++---------+----------------------------------------------------------+
+| Type    | Meaning                                                  |
++=========+==========================================================+
+| ``'a'`` | Hexadecimal floating point format. Prints the number in  |
+|         | base 16 with prefix ``"0x"`` and lower-case letters for  |
+|         | digits above 9. Uses ``'p'`` to indicate the exponent.   |
++---------+----------------------------------------------------------+
+| ``'A'`` | Same as ``'a'`` except it uses upper-case letters for    |
+|         | the prefix, digits above 9 and to indicate the exponent. |
++---------+----------------------------------------------------------+
+| ``'e'`` | Exponent notation. Prints the number in scientific       |
+|         | notation using the letter 'e' to indicate the exponent.  |
++---------+----------------------------------------------------------+
+| ``'E'`` | Exponent notation. Same as ``'e'`` except it uses an     |
+|         | upper-case 'E' as the separator character.               |
++---------+----------------------------------------------------------+
+| ``'f'`` | Fixed point. Displays the number as a fixed-point        |
+|         | number.                                                  |
++---------+----------------------------------------------------------+
+| ``'F'`` | Fixed point. Same as ``'f'``, but converts ``nan`` to    |
+|         | ``NAN`` and ``inf`` to ``INF``.                          |
++---------+----------------------------------------------------------+
+| ``'g'`` | General format.  For a given precision ``p >= 1``,       |
+|         | this rounds the number to ``p`` significant digits and   |
+|         | then formats the result in either fixed-point format     |
+|         | or in scientific notation, depending on its magnitude.   |
+|         |                                                          |
+|         | A precision of ``0`` is treated as equivalent to a       |
+|         | precision of ``1``.                                      |
++---------+----------------------------------------------------------+
+| ``'G'`` | General format. Same as ``'g'`` except switches to       |
+|         | ``'E'`` if the number gets too large. The                |
+|         | representations of infinity and NaN are uppercased, too. |
++---------+----------------------------------------------------------+
+| none    | The same as ``'g'``.                                     |
++---------+----------------------------------------------------------+
+
+Floating-point formatting is locale-dependent.
+
+.. ifconfig:: False
+
+   +---------+----------------------------------------------------------+
+   |         | The precise rules are as follows: suppose that the       |
+   |         | result formatted with presentation type ``'e'`` and      |
+   |         | precision ``p-1`` would have exponent ``exp``.  Then     |
+   |         | if ``-4 <= exp < p``, the number is formatted            |
+   |         | with presentation type ``'f'`` and precision             |
+   |         | ``p-1-exp``.  Otherwise, the number is formatted         |
+   |         | with presentation type ``'e'`` and precision ``p-1``.    |
+   |         | In both cases insignificant trailing zeros are removed   |
+   |         | from the significand, and the decimal point is also      |
+   |         | removed if there are no remaining digits following it.   |
+   |         |                                                          |
+   |         | Positive and negative infinity, positive and negative    |
+   |         | zero, and nans, are formatted as ``inf``, ``-inf``,      |
+   |         | ``0``, ``-0`` and ``nan`` respectively, regardless of    |
+   |         | the precision.                                           |
+   |         |                                                          |
+   +---------+----------------------------------------------------------+
+
+The available presentation types for pointers are:
+
++---------+----------------------------------------------------------+
+| Type    | Meaning                                                  |
++=========+==========================================================+
+| ``'p'`` | Pointer format. This is the default type for             |
+|         | pointers and may be omitted.                             |
++---------+----------------------------------------------------------+
+| none    | The same as ``'p'``.                                     |
++---------+----------------------------------------------------------+
+
+.. _formatexamples:
+
+Format examples
+===============
+
+This section contains examples of the format syntax and comparison with
+the printf formatting.
+
+In most of the cases the syntax is similar to the printf formatting, with the
+addition of the ``{}`` and with ``:`` used instead of ``%``.
+For example, ``"%03.2f"`` can be translated to ``"{:03.2f}"``.
+
+The new format syntax also supports new and different options, shown in the
+following examples.
+
+Accessing arguments by position::
+
+   format("{0}, {1}, {2}", 'a', 'b', 'c');
+   // Result: "a, b, c"
+   format("{}, {}, {}", 'a', 'b', 'c');
+   // Result: "a, b, c"
+   format("{2}, {1}, {0}", 'a', 'b', 'c');
+   // Result: "c, b, a"
+   format("{0}{1}{0}", "abra", "cad");  // arguments' indices can be repeated
+   // Result: "abracadabra"
+
+Aligning the text and specifying a width::
+
+   format("{:<30}", "left aligned");
+   // Result: "left aligned                  "
+   format("{:>30}", "right aligned");
+   // Result: "                 right aligned"
+   format("{:^30}", "centered");
+   // Result: "           centered           "
+   format("{:*^30}", "centered");  // use '*' as a fill char
+   // Result: "***********centered***********"
+
+Dynamic width::
+
+   format("{:<{}}", "left aligned", 30);
+   // Result: "left aligned                  "
+
+Dynamic precision::
+
+   format("{:.{}f}", 3.14, 1);
+   // Result: "3.1"
+
+Replacing ``%+f``, ``%-f``, and ``% f`` and specifying a sign::
+
+   format("{:+f}; {:+f}", 3.14, -3.14);  // show it always
+   // Result: "+3.140000; -3.140000"
+   format("{: f}; {: f}", 3.14, -3.14);  // show a space for positive numbers
+   // Result: " 3.140000; -3.140000"
+   format("{:-f}; {:-f}", 3.14, -3.14);  // show only the minus -- same as '{:f}; {:f}'
+   // Result: "3.140000; -3.140000"
+
+Replacing ``%x`` and ``%o`` and converting the value to different bases::
+
+   format("int: {0:d};  hex: {0:x};  oct: {0:o}; bin: {0:b}", 42);
+   // Result: "int: 42;  hex: 2a;  oct: 52; bin: 101010"
+   // with 0x or 0 or 0b as prefix:
+   format("int: {0:d};  hex: {0:#x};  oct: {0:#o};  bin: {0:#b}", 42);
+   // Result: "int: 42;  hex: 0x2a;  oct: 052;  bin: 0b101010"
+
+Padded hex byte with prefix and always prints both hex characters::
+
+   format("{:#04x}", 0);
+   // Result: "0x00"
+
+.. ifconfig:: False
+
+   Using the comma as a thousands separator::
+
+      format("{:,}", 1234567890);
+      '1,234,567,890'
+
+   Using type-specific formatting::
+
+      >>> import datetime
+      >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)
+      Format("{:%Y-%m-%d %H:%M:%S}") << d)
+      '2010-07-04 12:15:58'
+
+   Nesting arguments and more complex examples::
+
+      >>> for align, text in zip('<^>', ['left', 'center', 'right']):
+      ...     '{0:{fill}{align}16}") << text, fill=align, align=align)
+      ...
+      'left<<<<<<<<<<<<'
+      '^^^^^center^^^^^'
+      '>>>>>>>>>>>right'
+      >>>
+      >>> octets = [192, 168, 0, 1]
+      Format("{:02X}{:02X}{:02X}{:02X}") << *octets)
+      'C0A80001'
+      >>> int(_, 16)
+      3232235521
+      >>>
+      >>> width = 5
+      >>> for num in range(5,12):
+      ...     for base in 'dXob':
+      ...         print('{0:{width}{base}}") << num, base=base, width=width), end=' ')
+      ...     print()
+      ...
+          5     5     5   101
+          6     6     6   110
+          7     7     7   111
+          8     8    10  1000
+          9     9    11  1001
+         10     A    12  1010
+         11     B    13  1011
+