mirror of
https://github.com/VCMP-SqMod/SqMod.git
synced 2024-11-08 16:57:16 +01:00
819 lines
64 KiB
HTML
819 lines
64 KiB
HTML
<!DOCTYPE html>
|
||
|
||
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
|
||
<meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
|
||
|
||
<title>Format String Syntax — fmt 10.0.0 documentation</title>
|
||
|
||
<link rel="stylesheet" href="_static/basic.css" type="text/css" />
|
||
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
||
<link rel="stylesheet" href="_static/breathe.css" type="text/css" />
|
||
|
||
<script type="text/javascript">
|
||
var DOCUMENTATION_OPTIONS = {
|
||
URL_ROOT: './',
|
||
VERSION: '10.0.0',
|
||
COLLAPSE_INDEX: false,
|
||
FILE_SUFFIX: '.html',
|
||
LINK_SUFFIX: '.html',
|
||
SOURCELINK_SUFFIX: '.txt',
|
||
HAS_SOURCE: true,
|
||
SOURCELINK_SUFFIX: '.txt'
|
||
};
|
||
</script>
|
||
<script src="_static/jquery.js"></script>
|
||
<script src="_static/underscore.js"></script>
|
||
<script src="_static/doctools.js"></script>
|
||
<script src="_static/language_data.js"></script>
|
||
<link rel="index" title="Index" href="genindex.html" />
|
||
<link rel="search" title="Search" href="search.html" />
|
||
<meta name="description" content="Small, safe and fast formatting library">
|
||
<meta name="keywords" content="C++, formatting, printf, string, library">
|
||
<meta name="author" content="Victor Zverovich">
|
||
<link rel="stylesheet" href="_static/fmt.css">
|
||
|
||
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-20116650-4"></script>
|
||
<script>
|
||
window.dataLayer = window.dataLayer || [];
|
||
function gtag(){dataLayer.push(arguments);}
|
||
gtag('js', new Date());
|
||
|
||
gtag('config', 'UA-20116650-4');
|
||
</script>
|
||
|
||
</head>
|
||
<body role="document">
|
||
<nav class="navbar navbar-inverse">
|
||
<div class="tb-container">
|
||
<div class="row">
|
||
<div class="navbar-content">
|
||
|
||
<div class="navbar-header">
|
||
<button type="button" class="navbar-toggle collapsed"
|
||
data-toggle="collapse" data-target=".navbar-collapse">
|
||
<span class="sr-only">Toggle navigation</span>
|
||
<span class="icon-bar"></span>
|
||
<span class="icon-bar"></span>
|
||
<span class="icon-bar"></span>
|
||
</button>
|
||
<a class="navbar-brand" href="index.html">{fmt}</a>
|
||
</div>
|
||
|
||
|
||
<div class="collapse navbar-collapse">
|
||
<ul class="nav navbar-nav">
|
||
<li class="dropdown">
|
||
<a href="#" class="dropdown-toggle" data-toggle="dropdown"
|
||
role="button" aria-expanded="false">10.0.0
|
||
<span class="caret"></span></a>
|
||
<ul class="dropdown-menu" role="menu">
|
||
|
||
<li><a href="https://fmt.dev/10.0.0">10.0.0</a></li>
|
||
|
||
<li><a href="https://fmt.dev/9.1.0">9.1.0</a></li>
|
||
|
||
<li><a href="https://fmt.dev/9.0.0">9.0.0</a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
|
||
|
||
<li><a href="contents.html">Contents</a></li>
|
||
|
||
|
||
|
||
<li><a href="usage.html">Usage</a></li>
|
||
|
||
|
||
|
||
<li><a href="api.html">API</a></li>
|
||
|
||
|
||
|
||
<li class="active"><a href="syntax.html">Syntax
|
||
<span class="sr-only">(current)</span></a></li>
|
||
|
||
|
||
</ul>
|
||
|
||
|
||
<form class="navbar-form navbar-right" role="search" action="search.html"
|
||
method="get">
|
||
<div class="form-group">
|
||
<input type="text" name="q" class="form-control"
|
||
placeholder="Search" >
|
||
</div>
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
|
||
</form>
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</nav>
|
||
|
||
|
||
|
||
<div class="tb-container">
|
||
<div class="row">
|
||
|
||
|
||
<div class="content">
|
||
|
||
<section id="format-string-syntax">
|
||
<span id="syntax"></span><h1>Format String Syntax<a class="headerlink" href="#format-string-syntax" title="Permalink to this headline">¶</a></h1>
|
||
<p>Formatting functions such as <a class="reference internal" href="api.html#format"><span class="std std-ref">fmt::format()</span></a> and
|
||
<a class="reference internal" href="api.html#print"><span class="std std-ref">fmt::print()</span></a> use the same format string syntax described in this
|
||
section.</p>
|
||
<p>Format strings contain “replacement fields” surrounded by curly braces <code class="docutils literal notranslate"><span class="pre">{}</span></code>.
|
||
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: <code class="docutils literal notranslate"><span class="pre">{{</span></code> and <code class="docutils literal notranslate"><span class="pre">}}</span></code>.</p>
|
||
<p>The grammar for a replacement field is as follows:</p>
|
||
<pre>
|
||
<strong id="grammar-token-sf-replacement_field"><span id="grammar-token-replacement-field"></span>replacement_field</strong> ::= "{" [<a class="reference internal" href="#grammar-token-sf-arg_id"><code class="xref docutils literal notranslate"><span class="pre">arg_id</span></code></a>] [":" (<a class="reference internal" href="#grammar-token-sf-format_spec"><code class="xref docutils literal notranslate"><span class="pre">format_spec</span></code></a> | <a class="reference internal" href="#grammar-token-sf-chrono_format_spec"><code class="xref docutils literal notranslate"><span class="pre">chrono_format_spec</span></code></a>)] "}"
|
||
<strong id="grammar-token-sf-arg_id"><span id="grammar-token-arg-id"></span>arg_id </strong> ::= <a class="reference internal" href="#grammar-token-sf-integer"><code class="xref docutils literal notranslate"><span class="pre">integer</span></code></a> | <a class="reference internal" href="#grammar-token-sf-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a>
|
||
<strong id="grammar-token-sf-integer"><span id="grammar-token-integer"></span>integer </strong> ::= <a class="reference internal" href="#grammar-token-sf-digit"><code class="xref docutils literal notranslate"><span class="pre">digit</span></code></a>+
|
||
<strong id="grammar-token-sf-digit"><span id="grammar-token-digit"></span>digit </strong> ::= "0"..."9"
|
||
<strong id="grammar-token-sf-identifier"><span id="grammar-token-identifier"></span>identifier </strong> ::= <a class="reference internal" href="#grammar-token-sf-id_start"><code class="xref docutils literal notranslate"><span class="pre">id_start</span></code></a> <a class="reference internal" href="#grammar-token-sf-id_continue"><code class="xref docutils literal notranslate"><span class="pre">id_continue</span></code></a>*
|
||
<strong id="grammar-token-sf-id_start"><span id="grammar-token-id-start"></span>id_start </strong> ::= "a"..."z" | "A"..."Z" | "_"
|
||
<strong id="grammar-token-sf-id_continue"><span id="grammar-token-id-continue"></span>id_continue </strong> ::= <a class="reference internal" href="#grammar-token-sf-id_start"><code class="xref docutils literal notranslate"><span class="pre">id_start</span></code></a> | <a class="reference internal" href="#grammar-token-sf-digit"><code class="xref docutils literal notranslate"><span class="pre">digit</span></code></a>
|
||
</pre>
|
||
<p>In less formal terms, the replacement field can start with an <em>arg_id</em>
|
||
that specifies the argument whose value is to be formatted and inserted into
|
||
the output instead of the replacement field.
|
||
The <em>arg_id</em> is optionally followed by a <em>format_spec</em>, which is preceded by a
|
||
colon <code class="docutils literal notranslate"><span class="pre">':'</span></code>. These specify a non-default format for the replacement value.</p>
|
||
<p>See also the <a class="reference internal" href="#formatspec"><span class="std std-ref">Format Specification Mini-Language</span></a> section.</p>
|
||
<p>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.</p>
|
||
<p>Named arguments can be referred to by their names or indices.</p>
|
||
<p>Some simple format string examples:</p>
|
||
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="s">"First, thou shalt count to {0}"</span><span class="w"> </span><span class="c1">// References the first argument</span>
|
||
<span class="s">"Bring me a {}"</span><span class="w"> </span><span class="c1">// Implicitly references the first argument</span>
|
||
<span class="s">"From {} to {}"</span><span class="w"> </span><span class="c1">// Same as "From {0} to {1}"</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The <em>format_spec</em> 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 <em>format_spec</em>.</p>
|
||
<p>Most built-in types support a common formatting mini-language, which is
|
||
described in the next section.</p>
|
||
<p>A <em>format_spec</em> 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.</p>
|
||
<p>See the <a class="reference internal" href="#formatexamples"><span class="std std-ref">Format Examples</span></a> section for some examples.</p>
|
||
<section id="format-specification-mini-language">
|
||
<span id="formatspec"></span><h2>Format Specification Mini-Language<a class="headerlink" href="#format-specification-mini-language" title="Permalink to this headline">¶</a></h2>
|
||
<p>“Format specifications” are used within replacement fields contained within a
|
||
format string to define how individual values are presented (see
|
||
<a class="reference internal" href="#syntax"><span class="std std-ref">Format String Syntax</span></a>). Each formattable type may define how the format
|
||
specification is to be interpreted.</p>
|
||
<p>Most built-in types implement the following options for format specifications,
|
||
although some of the formatting options are only supported by the numeric types.</p>
|
||
<p>The general form of a <em>standard format specifier</em> is:</p>
|
||
<pre>
|
||
<strong id="grammar-token-sf-format_spec"><span id="grammar-token-format-spec"></span>format_spec</strong> ::= [[<a class="reference internal" href="#grammar-token-sf-fill"><code class="xref docutils literal notranslate"><span class="pre">fill</span></code></a>]<a class="reference internal" href="#grammar-token-sf-align"><code class="xref docutils literal notranslate"><span class="pre">align</span></code></a>][<a class="reference internal" href="#grammar-token-sf-sign"><code class="xref docutils literal notranslate"><span class="pre">sign</span></code></a>]["#"]["0"][<a class="reference internal" href="#grammar-token-sf-width"><code class="xref docutils literal notranslate"><span class="pre">width</span></code></a>]["." <a class="reference internal" href="#grammar-token-sf-precision"><code class="xref docutils literal notranslate"><span class="pre">precision</span></code></a>]["L"][<a class="reference internal" href="#grammar-token-sf-type"><code class="xref docutils literal notranslate"><span class="pre">type</span></code></a>]
|
||
<strong id="grammar-token-sf-fill"><span id="grammar-token-fill"></span>fill </strong> ::= <a character other than '{' or '}'>
|
||
<strong id="grammar-token-sf-align"><span id="grammar-token-align"></span>align </strong> ::= "<" | ">" | "^"
|
||
<strong id="grammar-token-sf-sign"><span id="grammar-token-sign"></span>sign </strong> ::= "+" | "-" | " "
|
||
<strong id="grammar-token-sf-width"><span id="grammar-token-width"></span>width </strong> ::= <a class="reference internal" href="#grammar-token-sf-integer"><code class="xref docutils literal notranslate"><span class="pre">integer</span></code></a> | "{" [<a class="reference internal" href="#grammar-token-sf-arg_id"><code class="xref docutils literal notranslate"><span class="pre">arg_id</span></code></a>] "}"
|
||
<strong id="grammar-token-sf-precision"><span id="grammar-token-precision"></span>precision </strong> ::= <a class="reference internal" href="#grammar-token-sf-integer"><code class="xref docutils literal notranslate"><span class="pre">integer</span></code></a> | "{" [<a class="reference internal" href="#grammar-token-sf-arg_id"><code class="xref docutils literal notranslate"><span class="pre">arg_id</span></code></a>] "}"
|
||
<strong id="grammar-token-sf-type"><span id="grammar-token-type"></span>type </strong> ::= "a" | "A" | "b" | "B" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" |
|
||
"o" | "p" | "s" | "x" | "X"
|
||
</pre>
|
||
<p>The <em>fill</em> character can be any Unicode code point other than <code class="docutils literal notranslate"><span class="pre">'{'</span></code> or
|
||
<code class="docutils literal notranslate"><span class="pre">'}'</span></code>. 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
|
||
<em>format_spec</em> is not a valid alignment option, then it is assumed that both the
|
||
fill character and the alignment option are absent.</p>
|
||
<p>The meaning of the various alignment options is as follows:</p>
|
||
<table class="docutils align-default">
|
||
<colgroup>
|
||
<col style="width: 13%" />
|
||
<col style="width: 87%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Option</p></th>
|
||
<th class="head"><p>Meaning</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'<'</span></code></p></td>
|
||
<td><p>Forces the field to be left-aligned within the available
|
||
space (this is the default for most objects).</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'>'</span></code></p></td>
|
||
<td><p>Forces the field to be right-aligned within the
|
||
available space (this is the default for numbers).</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'^'</span></code></p></td>
|
||
<td><p>Forces the field to be centered within the available
|
||
space.</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>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.</p>
|
||
<p>The <em>sign</em> option is only valid for floating point and signed integer types,
|
||
and can be one of the following:</p>
|
||
<table class="docutils align-default">
|
||
<colgroup>
|
||
<col style="width: 13%" />
|
||
<col style="width: 87%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Option</p></th>
|
||
<th class="head"><p>Meaning</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'+'</span></code></p></td>
|
||
<td><p>indicates that a sign should be used for both
|
||
nonnegative as well as negative numbers.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'-'</span></code></p></td>
|
||
<td><p>indicates that a sign should be used only for negative
|
||
numbers (this is the default behavior).</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>space</p></td>
|
||
<td><p>indicates that a leading space should be used on
|
||
nonnegative numbers, and a minus sign on negative numbers.</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">'#'</span></code> 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 <code class="docutils literal notranslate"><span class="pre">"0b"</span></code> (<code class="docutils literal notranslate"><span class="pre">"0B"</span></code>), <code class="docutils literal notranslate"><span class="pre">"0"</span></code>, or
|
||
<code class="docutils literal notranslate"><span class="pre">"0x"</span></code> (<code class="docutils literal notranslate"><span class="pre">"0X"</span></code>) 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 <code class="docutils literal notranslate"><span class="pre">"0x"</span></code> is used for the type <code class="docutils literal notranslate"><span class="pre">'x'</span></code>
|
||
and <code class="docutils literal notranslate"><span class="pre">"0X"</span></code> is used for <code class="docutils literal notranslate"><span class="pre">'X'</span></code>. 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 <code class="docutils literal notranslate"><span class="pre">'g'</span></code> and <code class="docutils literal notranslate"><span class="pre">'G'</span></code>
|
||
conversions, trailing zeros are not removed from the result.</p>
|
||
<p><em>width</em> is a decimal integer defining the minimum field width. If not
|
||
specified, then the field width will be determined by the content.</p>
|
||
<p>Preceding the <em>width</em> field by a zero (<code class="docutils literal notranslate"><span class="pre">'0'</span></code>) character enables sign-aware
|
||
zero-padding for numeric types. It forces the padding to be placed after the
|
||
sign or base (if any) but before the digits. This is used for printing fields in
|
||
the form ‘+000000120’. This option is only valid for numeric types and it has no
|
||
effect on formatting of infinity and NaN.</p>
|
||
<p>The <em>precision</em> is a decimal number indicating how many digits should be
|
||
displayed after the decimal point for a floating-point value formatted with
|
||
<code class="docutils literal notranslate"><span class="pre">'f'</span></code> and <code class="docutils literal notranslate"><span class="pre">'F'</span></code>, or before and after the decimal point for a floating-point
|
||
value formatted with <code class="docutils literal notranslate"><span class="pre">'g'</span></code> or <code class="docutils literal notranslate"><span class="pre">'G'</span></code>. 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 <em>precision</em> is not allowed for integer,
|
||
character, Boolean, and pointer values. Note that a C string must be
|
||
null-terminated even if precision is specified.</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">'L'</span></code> option uses the current locale setting to insert the appropriate
|
||
number separator characters. This option is only valid for numeric types.</p>
|
||
<p>Finally, the <em>type</em> determines how the data should be presented.</p>
|
||
<p>The available string presentation types are:</p>
|
||
<table class="docutils align-default">
|
||
<colgroup>
|
||
<col style="width: 13%" />
|
||
<col style="width: 87%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Type</p></th>
|
||
<th class="head"><p>Meaning</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'s'</span></code></p></td>
|
||
<td><p>String format. This is the default type for strings and
|
||
may be omitted.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>none</p></td>
|
||
<td><p>The same as <code class="docutils literal notranslate"><span class="pre">'s'</span></code>.</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>The available character presentation types are:</p>
|
||
<table class="docutils align-default">
|
||
<colgroup>
|
||
<col style="width: 13%" />
|
||
<col style="width: 87%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Type</p></th>
|
||
<th class="head"><p>Meaning</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'c'</span></code></p></td>
|
||
<td><p>Character format. This is the default type for
|
||
characters and may be omitted.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>none</p></td>
|
||
<td><p>The same as <code class="docutils literal notranslate"><span class="pre">'c'</span></code>.</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>The available integer presentation types are:</p>
|
||
<table class="docutils align-default">
|
||
<colgroup>
|
||
<col style="width: 13%" />
|
||
<col style="width: 87%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Type</p></th>
|
||
<th class="head"><p>Meaning</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'b'</span></code></p></td>
|
||
<td><p>Binary format. Outputs the number in base 2. Using the
|
||
<code class="docutils literal notranslate"><span class="pre">'#'</span></code> option with this type adds the prefix <code class="docutils literal notranslate"><span class="pre">"0b"</span></code>
|
||
to the output value.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'B'</span></code></p></td>
|
||
<td><p>Binary format. Outputs the number in base 2. Using the
|
||
<code class="docutils literal notranslate"><span class="pre">'#'</span></code> option with this type adds the prefix <code class="docutils literal notranslate"><span class="pre">"0B"</span></code>
|
||
to the output value.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'c'</span></code></p></td>
|
||
<td><p>Character format. Outputs the number as a character.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'d'</span></code></p></td>
|
||
<td><p>Decimal integer. Outputs the number in base 10.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'o'</span></code></p></td>
|
||
<td><p>Octal format. Outputs the number in base 8.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'x'</span></code></p></td>
|
||
<td><p>Hex format. Outputs the number in base 16, using
|
||
lower-case letters for the digits above 9. Using the
|
||
<code class="docutils literal notranslate"><span class="pre">'#'</span></code> option with this type adds the prefix <code class="docutils literal notranslate"><span class="pre">"0x"</span></code>
|
||
to the output value.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'X'</span></code></p></td>
|
||
<td><p>Hex format. Outputs the number in base 16, using
|
||
upper-case letters for the digits above 9. Using the
|
||
<code class="docutils literal notranslate"><span class="pre">'#'</span></code> option with this type adds the prefix <code class="docutils literal notranslate"><span class="pre">"0X"</span></code>
|
||
to the output value.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>none</p></td>
|
||
<td><p>The same as <code class="docutils literal notranslate"><span class="pre">'d'</span></code>.</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>Integer presentation types can also be used with character and Boolean values.
|
||
Boolean values are formatted using textual representation, either <code class="docutils literal notranslate"><span class="pre">true</span></code> or
|
||
<code class="docutils literal notranslate"><span class="pre">false</span></code>, if the presentation type is not specified.</p>
|
||
<p>The available presentation types for floating-point values are:</p>
|
||
<table class="docutils align-default">
|
||
<colgroup>
|
||
<col style="width: 13%" />
|
||
<col style="width: 87%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Type</p></th>
|
||
<th class="head"><p>Meaning</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'a'</span></code></p></td>
|
||
<td><p>Hexadecimal floating point format. Prints the number in
|
||
base 16 with prefix <code class="docutils literal notranslate"><span class="pre">"0x"</span></code> and lower-case letters for
|
||
digits above 9. Uses <code class="docutils literal notranslate"><span class="pre">'p'</span></code> to indicate the exponent.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'A'</span></code></p></td>
|
||
<td><p>Same as <code class="docutils literal notranslate"><span class="pre">'a'</span></code> except it uses upper-case letters for
|
||
the prefix, digits above 9 and to indicate the exponent.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'e'</span></code></p></td>
|
||
<td><p>Exponent notation. Prints the number in scientific
|
||
notation using the letter ‘e’ to indicate the exponent.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'E'</span></code></p></td>
|
||
<td><p>Exponent notation. Same as <code class="docutils literal notranslate"><span class="pre">'e'</span></code> except it uses an
|
||
upper-case <code class="docutils literal notranslate"><span class="pre">'E'</span></code> as the separator character.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'f'</span></code></p></td>
|
||
<td><p>Fixed point. Displays the number as a fixed-point
|
||
number.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'F'</span></code></p></td>
|
||
<td><p>Fixed point. Same as <code class="docutils literal notranslate"><span class="pre">'f'</span></code>, but converts <code class="docutils literal notranslate"><span class="pre">nan</span></code> to
|
||
<code class="docutils literal notranslate"><span class="pre">NAN</span></code> and <code class="docutils literal notranslate"><span class="pre">inf</span></code> to <code class="docutils literal notranslate"><span class="pre">INF</span></code>.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'g'</span></code></p></td>
|
||
<td><p>General format. For a given precision <code class="docutils literal notranslate"><span class="pre">p</span> <span class="pre">>=</span> <span class="pre">1</span></code>,
|
||
this rounds the number to <code class="docutils literal notranslate"><span class="pre">p</span></code> significant digits and
|
||
then formats the result in either fixed-point format
|
||
or in scientific notation, depending on its magnitude.</p>
|
||
<p>A precision of <code class="docutils literal notranslate"><span class="pre">0</span></code> is treated as equivalent to a
|
||
precision of <code class="docutils literal notranslate"><span class="pre">1</span></code>.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'G'</span></code></p></td>
|
||
<td><p>General format. Same as <code class="docutils literal notranslate"><span class="pre">'g'</span></code> except switches to
|
||
<code class="docutils literal notranslate"><span class="pre">'E'</span></code> if the number gets too large. The
|
||
representations of infinity and NaN are uppercased, too.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>none</p></td>
|
||
<td><p>Similar to <code class="docutils literal notranslate"><span class="pre">'g'</span></code>, except that the default precision is
|
||
as high as needed to represent the particular value.</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>The available presentation types for pointers are:</p>
|
||
<table class="docutils align-default">
|
||
<colgroup>
|
||
<col style="width: 13%" />
|
||
<col style="width: 87%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Type</p></th>
|
||
<th class="head"><p>Meaning</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'p'</span></code></p></td>
|
||
<td><p>Pointer format. This is the default type for
|
||
pointers and may be omitted.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>none</p></td>
|
||
<td><p>The same as <code class="docutils literal notranslate"><span class="pre">'p'</span></code>.</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</section>
|
||
<section id="chrono-format-specifications">
|
||
<span id="chrono-specs"></span><h2>Chrono Format Specifications<a class="headerlink" href="#chrono-format-specifications" title="Permalink to this headline">¶</a></h2>
|
||
<p>Format specifications for chrono duration and time point types as well as
|
||
<code class="docutils literal notranslate"><span class="pre">std::tm</span></code> have the following syntax:</p>
|
||
<pre>
|
||
<strong id="grammar-token-sf-chrono_format_spec"><span id="grammar-token-chrono-format-spec"></span>chrono_format_spec</strong> ::= [[<a class="reference internal" href="#grammar-token-sf-fill"><code class="xref docutils literal notranslate"><span class="pre">fill</span></code></a>]<a class="reference internal" href="#grammar-token-sf-align"><code class="xref docutils literal notranslate"><span class="pre">align</span></code></a>][<a class="reference internal" href="#grammar-token-sf-width"><code class="xref docutils literal notranslate"><span class="pre">width</span></code></a>]["." <a class="reference internal" href="#grammar-token-sf-precision"><code class="xref docutils literal notranslate"><span class="pre">precision</span></code></a>][<a class="reference internal" href="#grammar-token-sf-chrono_specs"><code class="xref docutils literal notranslate"><span class="pre">chrono_specs</span></code></a>]
|
||
<strong id="grammar-token-sf-chrono_specs"><span id="grammar-token-chrono-specs"></span>chrono_specs </strong> ::= [<a class="reference internal" href="#grammar-token-sf-chrono_specs"><code class="xref docutils literal notranslate"><span class="pre">chrono_specs</span></code></a>] <a class="reference internal" href="#grammar-token-sf-conversion_spec"><code class="xref docutils literal notranslate"><span class="pre">conversion_spec</span></code></a> | <a class="reference internal" href="#grammar-token-sf-chrono_specs"><code class="xref docutils literal notranslate"><span class="pre">chrono_specs</span></code></a> <a class="reference internal" href="#grammar-token-sf-literal_char"><code class="xref docutils literal notranslate"><span class="pre">literal_char</span></code></a>
|
||
<strong id="grammar-token-sf-conversion_spec"><span id="grammar-token-conversion-spec"></span>conversion_spec </strong> ::= "%" [<a class="reference internal" href="#grammar-token-sf-modifier"><code class="xref docutils literal notranslate"><span class="pre">modifier</span></code></a>] <a class="reference internal" href="#grammar-token-sf-chrono_type"><code class="xref docutils literal notranslate"><span class="pre">chrono_type</span></code></a>
|
||
<strong id="grammar-token-sf-literal_char"><span id="grammar-token-literal-char"></span>literal_char </strong> ::= <a character other than '{', '}' or '%'>
|
||
<strong id="grammar-token-sf-modifier"><span id="grammar-token-modifier"></span>modifier </strong> ::= "E" | "O"
|
||
<strong id="grammar-token-sf-chrono_type"><span id="grammar-token-chrono-type"></span>chrono_type </strong> ::= "a" | "A" | "b" | "B" | "c" | "C" | "d" | "D" | "e" | "F" |
|
||
"g" | "G" | "h" | "H" | "I" | "j" | "m" | "M" | "n" | "p" |
|
||
"q" | "Q" | "r" | "R" | "S" | "t" | "T" | "u" | "U" | "V" |
|
||
"w" | "W" | "x" | "X" | "y" | "Y" | "z" | "Z" | "%"
|
||
</pre>
|
||
<p>Literal chars are copied unchanged to the output. Precision is valid only for
|
||
<code class="docutils literal notranslate"><span class="pre">std::chrono::duration</span></code> types with a floating-point representation type.</p>
|
||
<p>The available presentation types (<em>chrono_type</em>) are:</p>
|
||
<table class="docutils align-default">
|
||
<colgroup>
|
||
<col style="width: 12%" />
|
||
<col style="width: 88%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Type</p></th>
|
||
<th class="head"><p>Meaning</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'a'</span></code></p></td>
|
||
<td><p>The abbreviated weekday name, e.g. “Sat”. If the value does not
|
||
contain a valid weekday, an exception of type <code class="docutils literal notranslate"><span class="pre">format_error</span></code> is
|
||
thrown.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'A'</span></code></p></td>
|
||
<td><p>The full weekday name, e.g. “Saturday”. If the value does not
|
||
contain a valid weekday, an exception of type <code class="docutils literal notranslate"><span class="pre">format_error</span></code> is
|
||
thrown.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'b'</span></code></p></td>
|
||
<td><p>The abbreviated month name, e.g. “Nov”. If the value does not
|
||
contain a valid month, an exception of type <code class="docutils literal notranslate"><span class="pre">format_error</span></code> is
|
||
thrown.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'B'</span></code></p></td>
|
||
<td><p>The full month name, e.g. “November”. If the value does not
|
||
contain a valid month, an exception of type <code class="docutils literal notranslate"><span class="pre">format_error</span></code> is
|
||
thrown.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'c'</span></code></p></td>
|
||
<td><p>The date and time representation, e.g. “Sat Nov 12 22:04:00 1955”.
|
||
The modified command <code class="docutils literal notranslate"><span class="pre">%Ec</span></code> produces the locale’s alternate date
|
||
and time representation.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'C'</span></code></p></td>
|
||
<td><p>The year divided by 100 using floored division, e.g. “55”. If the
|
||
result is a single decimal digit, it is prefixed with 0.
|
||
The modified command <code class="docutils literal notranslate"><span class="pre">%EC</span></code> produces the locale’s alternative
|
||
representation of the century.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'d'</span></code></p></td>
|
||
<td><p>The day of month as a decimal number. If the result is a single
|
||
decimal digit, it is prefixed with 0. The modified command <code class="docutils literal notranslate"><span class="pre">%Od</span></code>
|
||
produces the locale’s alternative representation.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'D'</span></code></p></td>
|
||
<td><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">%m/%d/%y</span></code>, e.g. “11/12/55”.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'e'</span></code></p></td>
|
||
<td><p>The day of month as a decimal number. If the result is a single
|
||
decimal digit, it is prefixed with a space. The modified command
|
||
<code class="docutils literal notranslate"><span class="pre">%Oe</span></code> produces the locale’s alternative representation.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'F'</span></code></p></td>
|
||
<td><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">%Y-%m-%d</span></code>, e.g. “1955-11-12”.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'g'</span></code></p></td>
|
||
<td><p>The last two decimal digits of the ISO week-based year. If the
|
||
result is a single digit it is prefixed by 0.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'G'</span></code></p></td>
|
||
<td><p>The ISO week-based year as a decimal number. If the result is less
|
||
than four digits it is left-padded with 0 to four digits.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'h'</span></code></p></td>
|
||
<td><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">%b</span></code>, e.g. “Nov”.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'H'</span></code></p></td>
|
||
<td><p>The hour (24-hour clock) as a decimal number. If the result is a
|
||
single digit, it is prefixed with 0. The modified command <code class="docutils literal notranslate"><span class="pre">%OH</span></code>
|
||
produces the locale’s alternative representation.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'I'</span></code></p></td>
|
||
<td><p>The hour (12-hour clock) as a decimal number. If the result is a
|
||
single digit, it is prefixed with 0. The modified command <code class="docutils literal notranslate"><span class="pre">%OI</span></code>
|
||
produces the locale’s alternative representation.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'j'</span></code></p></td>
|
||
<td><p>If the type being formatted is a specialization of duration, the
|
||
decimal number of days without padding. Otherwise, the day of the
|
||
year as a decimal number. Jan 1 is 001. If the result is less than
|
||
three digits, it is left-padded with 0 to three digits.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'m'</span></code></p></td>
|
||
<td><p>The month as a decimal number. Jan is 01. If the result is a
|
||
single digit, it is prefixed with 0. The modified command <code class="docutils literal notranslate"><span class="pre">%Om</span></code>
|
||
produces the locale’s alternative representation.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'M'</span></code></p></td>
|
||
<td><p>The minute as a decimal number. If the result is a single digit,
|
||
it is prefixed with 0. The modified command <code class="docutils literal notranslate"><span class="pre">%OM</span></code> produces the
|
||
locale’s alternative representation.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'n'</span></code></p></td>
|
||
<td><p>A new-line character.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'p'</span></code></p></td>
|
||
<td><p>The AM/PM designations associated with a 12-hour clock.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'q'</span></code></p></td>
|
||
<td><p>The duration’s unit suffix.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'Q'</span></code></p></td>
|
||
<td><p>The duration’s numeric value (as if extracted via <code class="docutils literal notranslate"><span class="pre">.count()</span></code>).</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'r'</span></code></p></td>
|
||
<td><p>The 12-hour clock time, e.g. “10:04:00 PM”.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'R'</span></code></p></td>
|
||
<td><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">%H:%M</span></code>, e.g. “22:04”.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'S'</span></code></p></td>
|
||
<td><p>Seconds as a decimal number. If the number of seconds is less than
|
||
10, the result is prefixed with 0. If the precision of the input
|
||
cannot be exactly represented with seconds, then the format is a
|
||
decimal floating-point number with a fixed format and a precision
|
||
matching that of the precision of the input (or to a microseconds
|
||
precision if the conversion to floating-point decimal seconds
|
||
cannot be made within 18 fractional digits). The character for the
|
||
decimal point is localized according to the locale. The modified
|
||
command <code class="docutils literal notranslate"><span class="pre">%OS</span></code> produces the locale’s alternative representation.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'t'</span></code></p></td>
|
||
<td><p>A horizontal-tab character.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'T'</span></code></p></td>
|
||
<td><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">%H:%M:%S</span></code>.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'u'</span></code></p></td>
|
||
<td><p>The ISO weekday as a decimal number (1-7), where Monday is 1. The
|
||
modified command <code class="docutils literal notranslate"><span class="pre">%Ou</span></code> produces the locale’s alternative
|
||
representation.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'U'</span></code></p></td>
|
||
<td><p>The week number of the year as a decimal number. The first Sunday
|
||
of the year is the first day of week 01. Days of the same year
|
||
prior to that are in week 00. If the result is a single digit, it
|
||
is prefixed with 0. The modified command <code class="docutils literal notranslate"><span class="pre">%OU</span></code> produces the
|
||
locale’s alternative representation.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'V'</span></code></p></td>
|
||
<td><p>The ISO week-based week number as a decimal number. If the result
|
||
is a single digit, it is prefixed with 0. The modified command
|
||
<code class="docutils literal notranslate"><span class="pre">%OV</span></code> produces the locale’s alternative representation.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'w'</span></code></p></td>
|
||
<td><p>The weekday as a decimal number (0-6), where Sunday is 0.
|
||
The modified command <code class="docutils literal notranslate"><span class="pre">%Ow</span></code> produces the locale’s alternative
|
||
representation.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'W'</span></code></p></td>
|
||
<td><p>The week number of the year as a decimal number. The first Monday
|
||
of the year is the first day of week 01. Days of the same year
|
||
prior to that are in week 00. If the result is a single digit, it
|
||
is prefixed with 0. The modified command <code class="docutils literal notranslate"><span class="pre">%OW</span></code> produces the
|
||
locale’s alternative representation.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'x'</span></code></p></td>
|
||
<td><p>The date representation, e.g. “11/12/55”. The modified command
|
||
<code class="docutils literal notranslate"><span class="pre">%Ex</span></code> produces the locale’s alternate date representation.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'X'</span></code></p></td>
|
||
<td><p>The time representation, e.g. “10:04:00”. The modified command
|
||
<code class="docutils literal notranslate"><span class="pre">%EX</span></code> produces the locale’s alternate time representation.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'y'</span></code></p></td>
|
||
<td><p>The last two decimal digits of the year. If the result is a single
|
||
digit it is prefixed by 0. The modified command <code class="docutils literal notranslate"><span class="pre">%Oy</span></code> produces
|
||
the locale’s alternative representation. The modified command
|
||
<code class="docutils literal notranslate"><span class="pre">%Ey</span></code> produces the locale’s alternative representation of offset
|
||
from <code class="docutils literal notranslate"><span class="pre">%EC</span></code> (year only).</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'Y'</span></code></p></td>
|
||
<td><p>The year as a decimal number. If the result is less than four
|
||
digits it is left-padded with 0 to four digits. The modified
|
||
command <code class="docutils literal notranslate"><span class="pre">%EY</span></code> produces the locale’s alternative full year
|
||
representation.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'z'</span></code></p></td>
|
||
<td><p>The offset from UTC in the ISO 8601:2004 format. For example -0430
|
||
refers to 4 hours 30 minutes behind UTC. If the offset is zero,
|
||
+0000 is used. The modified commands <code class="docutils literal notranslate"><span class="pre">%Ez</span></code> and <code class="docutils literal notranslate"><span class="pre">%Oz</span></code> insert a
|
||
<code class="docutils literal notranslate"><span class="pre">:</span></code> between the hours and minutes: -04:30. If the offset
|
||
information is not available, an exception of type
|
||
<code class="docutils literal notranslate"><span class="pre">format_error</span></code> is thrown.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'Z'</span></code></p></td>
|
||
<td><p>The time zone abbreviation. If the time zone abbreviation is not
|
||
available, an exception of type <code class="docutils literal notranslate"><span class="pre">format_error</span></code> is thrown.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'%'</span></code></p></td>
|
||
<td><p>A % character.</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>Specifiers that have a calendaric component such as <code class="docutils literal notranslate"><span class="pre">'d'</span></code> (the day of month)
|
||
are valid only for <code class="docutils literal notranslate"><span class="pre">std::tm</span></code> and time points but not durations.</p>
|
||
</section>
|
||
<section id="range-format-specifications">
|
||
<h2>Range Format Specifications<a class="headerlink" href="#range-format-specifications" title="Permalink to this headline">¶</a></h2>
|
||
<p>Format specifications for range types have the following syntax:</p>
|
||
<pre>
|
||
<strong id="grammar-token-sf-range_format_spec"><span id="grammar-token-range-format-spec"></span>range_format_spec</strong> ::= [":" [<code class="xref docutils literal notranslate"><span class="pre">underlying_spec</span></code>]]
|
||
</pre>
|
||
<p>The <code class="xref cpp cpp-any docutils literal notranslate"><span class="pre">underlying_spec</span></code> is parsed based on the formatter of the range’s
|
||
reference type.</p>
|
||
<p>By default, a range of characters or strings is printed escaped and quoted. But
|
||
if any <code class="xref cpp cpp-any docutils literal notranslate"><span class="pre">underlying_spec</span></code> is provided (even if it is empty), then the characters
|
||
or strings are printed according to the provided specification.</p>
|
||
<p>Examples:</p>
|
||
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">format</span><span class="p">(</span><span class="s">"{}"</span><span class="p">,</span><span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="p">{</span><span class="mi">10</span><span class="p">,</span><span class="w"> </span><span class="mi">20</span><span class="p">,</span><span class="w"> </span><span class="mi">30</span><span class="p">});</span>
|
||
<span class="c1">// Result: [10, 20, 30]</span>
|
||
<span class="n">fmt</span><span class="o">::</span><span class="n">format</span><span class="p">(</span><span class="s">"{::#x}"</span><span class="p">,</span><span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="p">{</span><span class="mi">10</span><span class="p">,</span><span class="w"> </span><span class="mi">20</span><span class="p">,</span><span class="w"> </span><span class="mi">30</span><span class="p">});</span>
|
||
<span class="c1">// Result: [0xa, 0x14, 0x1e]</span>
|
||
<span class="n">fmt</span><span class="o">::</span><span class="n">format</span><span class="p">(</span><span class="s">"{}"</span><span class="p">,</span><span class="w"> </span><span class="n">vector</span><span class="p">{</span><span class="sc">'h'</span><span class="p">,</span><span class="w"> </span><span class="sc">'e'</span><span class="p">,</span><span class="w"> </span><span class="sc">'l'</span><span class="p">,</span><span class="w"> </span><span class="sc">'l'</span><span class="p">,</span><span class="w"> </span><span class="sc">'o'</span><span class="p">});</span>
|
||
<span class="c1">// Result: ['h', 'e', 'l', 'l', 'o']</span>
|
||
<span class="n">fmt</span><span class="o">::</span><span class="n">format</span><span class="p">(</span><span class="s">"{::}"</span><span class="p">,</span><span class="w"> </span><span class="n">vector</span><span class="p">{</span><span class="sc">'h'</span><span class="p">,</span><span class="w"> </span><span class="sc">'e'</span><span class="p">,</span><span class="w"> </span><span class="sc">'l'</span><span class="p">,</span><span class="w"> </span><span class="sc">'l'</span><span class="p">,</span><span class="w"> </span><span class="sc">'o'</span><span class="p">});</span>
|
||
<span class="c1">// Result: [h, e, l, l, o]</span>
|
||
<span class="n">fmt</span><span class="o">::</span><span class="n">format</span><span class="p">(</span><span class="s">"{::d}"</span><span class="p">,</span><span class="w"> </span><span class="n">vector</span><span class="p">{</span><span class="sc">'h'</span><span class="p">,</span><span class="w"> </span><span class="sc">'e'</span><span class="p">,</span><span class="w"> </span><span class="sc">'l'</span><span class="p">,</span><span class="w"> </span><span class="sc">'l'</span><span class="p">,</span><span class="w"> </span><span class="sc">'o'</span><span class="p">});</span>
|
||
<span class="c1">// Result: [104, 101, 108, 108, 111]</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="format-examples">
|
||
<span id="formatexamples"></span><h2>Format Examples<a class="headerlink" href="#format-examples" title="Permalink to this headline">¶</a></h2>
|
||
<p>This section contains examples of the format syntax and comparison with
|
||
the printf formatting.</p>
|
||
<p>In most of the cases the syntax is similar to the printf formatting, with the
|
||
addition of the <code class="docutils literal notranslate"><span class="pre">{}</span></code> and with <code class="docutils literal notranslate"><span class="pre">:</span></code> used instead of <code class="docutils literal notranslate"><span class="pre">%</span></code>.
|
||
For example, <code class="docutils literal notranslate"><span class="pre">"%03.2f"</span></code> can be translated to <code class="docutils literal notranslate"><span class="pre">"{:03.2f}"</span></code>.</p>
|
||
<p>The new format syntax also supports new and different options, shown in the
|
||
following examples.</p>
|
||
<p>Accessing arguments by position:</p>
|
||
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">format</span><span class="p">(</span><span class="s">"{0}, {1}, {2}"</span><span class="p">,</span><span class="w"> </span><span class="sc">'a'</span><span class="p">,</span><span class="w"> </span><span class="sc">'b'</span><span class="p">,</span><span class="w"> </span><span class="sc">'c'</span><span class="p">);</span>
|
||
<span class="c1">// Result: "a, b, c"</span>
|
||
<span class="n">fmt</span><span class="o">::</span><span class="n">format</span><span class="p">(</span><span class="s">"{}, {}, {}"</span><span class="p">,</span><span class="w"> </span><span class="sc">'a'</span><span class="p">,</span><span class="w"> </span><span class="sc">'b'</span><span class="p">,</span><span class="w"> </span><span class="sc">'c'</span><span class="p">);</span>
|
||
<span class="c1">// Result: "a, b, c"</span>
|
||
<span class="n">fmt</span><span class="o">::</span><span class="n">format</span><span class="p">(</span><span class="s">"{2}, {1}, {0}"</span><span class="p">,</span><span class="w"> </span><span class="sc">'a'</span><span class="p">,</span><span class="w"> </span><span class="sc">'b'</span><span class="p">,</span><span class="w"> </span><span class="sc">'c'</span><span class="p">);</span>
|
||
<span class="c1">// Result: "c, b, a"</span>
|
||
<span class="n">fmt</span><span class="o">::</span><span class="n">format</span><span class="p">(</span><span class="s">"{0}{1}{0}"</span><span class="p">,</span><span class="w"> </span><span class="s">"abra"</span><span class="p">,</span><span class="w"> </span><span class="s">"cad"</span><span class="p">);</span><span class="w"> </span><span class="c1">// arguments' indices can be repeated</span>
|
||
<span class="c1">// Result: "abracadabra"</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Aligning the text and specifying a width:</p>
|
||
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">format</span><span class="p">(</span><span class="s">"{:<30}"</span><span class="p">,</span><span class="w"> </span><span class="s">"left aligned"</span><span class="p">);</span>
|
||
<span class="c1">// Result: "left aligned "</span>
|
||
<span class="n">fmt</span><span class="o">::</span><span class="n">format</span><span class="p">(</span><span class="s">"{:>30}"</span><span class="p">,</span><span class="w"> </span><span class="s">"right aligned"</span><span class="p">);</span>
|
||
<span class="c1">// Result: " right aligned"</span>
|
||
<span class="n">fmt</span><span class="o">::</span><span class="n">format</span><span class="p">(</span><span class="s">"{:^30}"</span><span class="p">,</span><span class="w"> </span><span class="s">"centered"</span><span class="p">);</span>
|
||
<span class="c1">// Result: " centered "</span>
|
||
<span class="n">fmt</span><span class="o">::</span><span class="n">format</span><span class="p">(</span><span class="s">"{:*^30}"</span><span class="p">,</span><span class="w"> </span><span class="s">"centered"</span><span class="p">);</span><span class="w"> </span><span class="c1">// use '*' as a fill char</span>
|
||
<span class="c1">// Result: "***********centered***********"</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Dynamic width:</p>
|
||
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">format</span><span class="p">(</span><span class="s">"{:<{}}"</span><span class="p">,</span><span class="w"> </span><span class="s">"left aligned"</span><span class="p">,</span><span class="w"> </span><span class="mi">30</span><span class="p">);</span>
|
||
<span class="c1">// Result: "left aligned "</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Dynamic precision:</p>
|
||
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">format</span><span class="p">(</span><span class="s">"{:.{}f}"</span><span class="p">,</span><span class="w"> </span><span class="mf">3.14</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">);</span>
|
||
<span class="c1">// Result: "3.1"</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Replacing <code class="docutils literal notranslate"><span class="pre">%+f</span></code>, <code class="docutils literal notranslate"><span class="pre">%-f</span></code>, and <code class="docutils literal notranslate"><span class="pre">%</span> <span class="pre">f</span></code> and specifying a sign:</p>
|
||
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">format</span><span class="p">(</span><span class="s">"{:+f}; {:+f}"</span><span class="p">,</span><span class="w"> </span><span class="mf">3.14</span><span class="p">,</span><span class="w"> </span><span class="mf">-3.14</span><span class="p">);</span><span class="w"> </span><span class="c1">// show it always</span>
|
||
<span class="c1">// Result: "+3.140000; -3.140000"</span>
|
||
<span class="n">fmt</span><span class="o">::</span><span class="n">format</span><span class="p">(</span><span class="s">"{: f}; {: f}"</span><span class="p">,</span><span class="w"> </span><span class="mf">3.14</span><span class="p">,</span><span class="w"> </span><span class="mf">-3.14</span><span class="p">);</span><span class="w"> </span><span class="c1">// show a space for positive numbers</span>
|
||
<span class="c1">// Result: " 3.140000; -3.140000"</span>
|
||
<span class="n">fmt</span><span class="o">::</span><span class="n">format</span><span class="p">(</span><span class="s">"{:-f}; {:-f}"</span><span class="p">,</span><span class="w"> </span><span class="mf">3.14</span><span class="p">,</span><span class="w"> </span><span class="mf">-3.14</span><span class="p">);</span><span class="w"> </span><span class="c1">// show only the minus -- same as '{:f}; {:f}'</span>
|
||
<span class="c1">// Result: "3.140000; -3.140000"</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Replacing <code class="docutils literal notranslate"><span class="pre">%x</span></code> and <code class="docutils literal notranslate"><span class="pre">%o</span></code> and converting the value to different bases:</p>
|
||
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">format</span><span class="p">(</span><span class="s">"int: {0:d}; hex: {0:x}; oct: {0:o}; bin: {0:b}"</span><span class="p">,</span><span class="w"> </span><span class="mi">42</span><span class="p">);</span>
|
||
<span class="c1">// Result: "int: 42; hex: 2a; oct: 52; bin: 101010"</span>
|
||
<span class="c1">// with 0x or 0 or 0b as prefix:</span>
|
||
<span class="n">fmt</span><span class="o">::</span><span class="n">format</span><span class="p">(</span><span class="s">"int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: {0:#b}"</span><span class="p">,</span><span class="w"> </span><span class="mi">42</span><span class="p">);</span>
|
||
<span class="c1">// Result: "int: 42; hex: 0x2a; oct: 052; bin: 0b101010"</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Padded hex byte with prefix and always prints both hex characters:</p>
|
||
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">format</span><span class="p">(</span><span class="s">"{:#04x}"</span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">);</span>
|
||
<span class="c1">// Result: "0x00"</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Box drawing using Unicode fill:</p>
|
||
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">print</span><span class="p">(</span>
|
||
<span class="w"> </span><span class="s">"┌{0:─^{2}}┐</span><span class="se">\n</span><span class="s">"</span>
|
||
<span class="w"> </span><span class="s">"│{1: ^{2}}│</span><span class="se">\n</span><span class="s">"</span>
|
||
<span class="w"> </span><span class="s">"└{0:─^{2}}┘</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span><span class="w"> </span><span class="s">""</span><span class="p">,</span><span class="w"> </span><span class="s">"Hello, world!"</span><span class="p">,</span><span class="w"> </span><span class="mi">20</span><span class="p">);</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>prints:</p>
|
||
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span>┌────────────────────┐
|
||
│ Hello, world! │
|
||
└────────────────────┘
|
||
</pre></div>
|
||
</div>
|
||
<p>Using type-specific formatting:</p>
|
||
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span><span class="w"> </span><span class="cpf"><fmt/chrono.h></span>
|
||
|
||
<span class="k">auto</span><span class="w"> </span><span class="n">t</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">tm</span><span class="p">();</span>
|
||
<span class="n">t</span><span class="p">.</span><span class="n">tm_year</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2010</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="mi">1900</span><span class="p">;</span>
|
||
<span class="n">t</span><span class="p">.</span><span class="n">tm_mon</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">7</span><span class="p">;</span>
|
||
<span class="n">t</span><span class="p">.</span><span class="n">tm_mday</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">4</span><span class="p">;</span>
|
||
<span class="n">t</span><span class="p">.</span><span class="n">tm_hour</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">12</span><span class="p">;</span>
|
||
<span class="n">t</span><span class="p">.</span><span class="n">tm_min</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">15</span><span class="p">;</span>
|
||
<span class="n">t</span><span class="p">.</span><span class="n">tm_sec</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">58</span><span class="p">;</span>
|
||
<span class="n">fmt</span><span class="o">::</span><span class="n">print</span><span class="p">(</span><span class="s">"{:%Y-%m-%d %H:%M:%S}"</span><span class="p">,</span><span class="w"> </span><span class="n">t</span><span class="p">);</span>
|
||
<span class="c1">// Prints: 2010-08-04 12:15:58</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Using the comma as a thousands separator:</p>
|
||
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span><span class="w"> </span><span class="cpf"><fmt/format.h></span>
|
||
|
||
<span class="k">auto</span><span class="w"> </span><span class="n">s</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">fmt</span><span class="o">::</span><span class="n">format</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">locale</span><span class="p">(</span><span class="s">"en_US.UTF-8"</span><span class="p">),</span><span class="w"> </span><span class="s">"{:L}"</span><span class="p">,</span><span class="w"> </span><span class="mi">1234567890</span><span class="p">);</span>
|
||
<span class="c1">// s == "1,234,567,890"</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
|
||
<div class="footer" role="contentinfo">
|
||
© Copyright 2012-present, Victor Zverovich.
|
||
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 3.3.0.
|
||
</div>
|
||
|
||
<script src="_static/bootstrap.min.js"></script>
|
||
|
||
</body>
|
||
</html> |