mentat/chrono/format/strftime/index.html

286 lines
21 KiB
HTML
Raw Normal View History

2018-08-22 17:04:13 +00:00
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="rustdoc">
<meta name="description" content="API documentation for the Rust `strftime` mod in crate `chrono`.">
<meta name="keywords" content="rust, rustlang, rust-lang, strftime">
<title>chrono::format::strftime - Rust</title>
<link rel="stylesheet" type="text/css" href="../../../normalize.css">
<link rel="stylesheet" type="text/css" href="../../../rustdoc.css" id="mainThemeStyle">
<link rel="stylesheet" type="text/css" href="../../../dark.css">
<link rel="stylesheet" type="text/css" href="../../../main.css" id="themeStyle">
<script src="../../../storage.js"></script>
</head>
<body class="rustdoc mod">
<!--[if lte IE 8]>
<div class="warning">
This old browser is unsupported and will most likely display funky
things.
</div>
<![endif]-->
<nav class="sidebar">
<div class="sidebar-menu">&#9776;</div>
<p class='location'>Module strftime</p><div class="sidebar-elems"><div class="block items"><ul><li><a href="#structs">Structs</a></li></ul></div><p class='location'><a href='../../index.html'>chrono</a>::<wbr><a href='../index.html'>format</a></p><script>window.sidebarCurrent = {name: 'strftime', ty: 'mod', relpath: '../'};</script><script defer src="../sidebar-items.js"></script></div>
</nav>
<div class="theme-picker">
<button id="theme-picker" aria-label="Pick another theme!">
<img src="../../../brush.svg" width="18" alt="Pick another theme!">
</button>
<div id="theme-choices"></div>
</div>
<script src="../../../theme.js"></script>
<nav class="sub">
<form class="search-form js-only">
<div class="search-container">
<input class="search-input" name="search"
autocomplete="off"
placeholder="Click or press S to search, ? for more options…"
type="search">
</div>
</form>
</nav>
<section id='main' class="content">
<h1 class='fqn'><span class='in-band'>Module <a href='../../index.html'>chrono</a>::<wbr><a href='../index.html'>format</a>::<wbr><a class="mod" href=''>strftime</a></span><span class='out-of-band'><span id='render-detail'>
<a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">
[<span class='inner'>&#x2212;</span>]
</a>
</span><a class='srclink' href='../../../src/chrono/format/strftime.rs.html#4-483' title='goto source code'>[src]</a></span></h1>
<div class='docblock'><p><code>strftime</code>/<code>strptime</code>-inspired date and time formatting syntax.</p>
<h2 id="specifiers" class="section-header"><a href="#specifiers">Specifiers</a></h2>
<p>The following specifiers are available both to formatting and parsing.</p>
<table><thead><tr><th> Spec. </th><th> Example </th><th> Description </th></tr></thead><tbody>
<tr><td> </td><td> </td><td> <strong>DATE SPECIFIERS:</strong> </td></tr>
<tr><td> <code>%Y</code> </td><td> <code>2001</code> </td><td> The full proleptic Gregorian year, zero-padded to 4 digits. [1] </td></tr>
<tr><td> <code>%C</code> </td><td> <code>20</code> </td><td> The proleptic Gregorian year divided by 100, zero-padded to 2 digits. [2] </td></tr>
<tr><td> <code>%y</code> </td><td> <code>01</code> </td><td> The proleptic Gregorian year modulo 100, zero-padded to 2 digits. [2] </td></tr>
<tr><td> </td><td> </td><td> </td></tr>
<tr><td> <code>%m</code> </td><td> <code>07</code> </td><td> Month number (01--12), zero-padded to 2 digits. </td></tr>
<tr><td> <code>%b</code> </td><td> <code>Jul</code> </td><td> Abbreviated month name. Always 3 letters. </td></tr>
<tr><td> <code>%B</code> </td><td> <code>July</code> </td><td> Full month name. Also accepts corresponding abbreviation in parsing. </td></tr>
<tr><td> <code>%h</code> </td><td> <code>Jul</code> </td><td> Same to <code>%b</code>. </td></tr>
<tr><td> </td><td> </td><td> </td></tr>
<tr><td> <code>%d</code> </td><td> <code>08</code> </td><td> Day number (01--31), zero-padded to 2 digits. </td></tr>
<tr><td> <code>%e</code> </td><td> <code>8</code> </td><td> Same to <code>%d</code> but space-padded. Same to <code>%_d</code>. </td></tr>
<tr><td> </td><td> </td><td> </td></tr>
<tr><td> <code>%a</code> </td><td> <code>Sun</code> </td><td> Abbreviated weekday name. Always 3 letters. </td></tr>
<tr><td> <code>%A</code> </td><td> <code>Sunday</code> </td><td> Full weekday name. Also accepts corresponding abbreviation in parsing. </td></tr>
<tr><td> <code>%w</code> </td><td> <code>0</code> </td><td> Sunday = 0, Monday = 1, ..., Saturday = 6. </td></tr>
<tr><td> <code>%u</code> </td><td> <code>7</code> </td><td> Monday = 1, Tuesday = 2, ..., Sunday = 7. (ISO 8601) </td></tr>
<tr><td> </td><td> </td><td> </td></tr>
<tr><td> <code>%U</code> </td><td> <code>28</code> </td><td> Week number starting with Sunday (00--53), zero-padded to 2 digits. [3] </td></tr>
<tr><td> <code>%W</code> </td><td> <code>27</code> </td><td> Same to <code>%U</code>, but week 1 starts with the first Monday in that year instead.</td></tr>
<tr><td> </td><td> </td><td> </td></tr>
<tr><td> <code>%G</code> </td><td> <code>2001</code> </td><td> Same to <code>%Y</code> but uses the year number in ISO 8601 week date. [4] </td></tr>
<tr><td> <code>%g</code> </td><td> <code>01</code> </td><td> Same to <code>%y</code> but uses the year number in ISO 8601 week date. [4] </td></tr>
<tr><td> <code>%V</code> </td><td> <code>27</code> </td><td> Same to <code>%U</code> but uses the week number in ISO 8601 week date (01--53). [4] </td></tr>
<tr><td> </td><td> </td><td> </td></tr>
<tr><td> <code>%j</code> </td><td> <code>189</code> </td><td> Day of the year (001--366), zero-padded to 3 digits. </td></tr>
<tr><td> </td><td> </td><td> </td></tr>
<tr><td> <code>%D</code> </td><td> <code>07/08/01</code> </td><td> Month-day-year format. Same to <code>%m/%d/%y</code>. </td></tr>
<tr><td> <code>%x</code> </td><td> <code>07/08/01</code> </td><td> Same to <code>%D</code>. </td></tr>
<tr><td> <code>%F</code> </td><td> <code>2001-07-08</code> </td><td> Year-month-day format (ISO 8601). Same to <code>%Y-%m-%d</code>. </td></tr>
<tr><td> <code>%v</code> </td><td> <code>8-Jul-2001</code> </td><td> Day-month-year format. Same to <code>%e-%b-%Y</code>. </td></tr>
<tr><td> </td><td> </td><td> </td></tr>
<tr><td> </td><td> </td><td> <strong>TIME SPECIFIERS:</strong> </td></tr>
<tr><td> <code>%H</code> </td><td> <code>00</code> </td><td> Hour number (00--23), zero-padded to 2 digits. </td></tr>
<tr><td> <code>%k</code> </td><td> <code>0</code> </td><td> Same to <code>%H</code> but space-padded. Same to <code>%_H</code>. </td></tr>
<tr><td> <code>%I</code> </td><td> <code>12</code> </td><td> Hour number in 12-hour clocks (01--12), zero-padded to 2 digits. </td></tr>
<tr><td> <code>%l</code> </td><td> <code>12</code> </td><td> Same to <code>%I</code> but space-padded. Same to <code>%_I</code>. </td></tr>
<tr><td> </td><td> </td><td> </td></tr>
<tr><td> <code>%P</code> </td><td> <code>am</code> </td><td> <code>am</code> or <code>pm</code> in 12-hour clocks. </td></tr>
<tr><td> <code>%p</code> </td><td> <code>AM</code> </td><td> <code>AM</code> or <code>PM</code> in 12-hour clocks. </td></tr>
<tr><td> </td><td> </td><td> </td></tr>
<tr><td> <code>%M</code> </td><td> <code>34</code> </td><td> Minute number (00--59), zero-padded to 2 digits. </td></tr>
<tr><td> <code>%S</code> </td><td> <code>60</code> </td><td> Second number (00--60), zero-padded to 2 digits. [5] </td></tr>
<tr><td> <code>%f</code> </td><td> <code>026490000</code> </td><td> The fractional seconds (in nanoseconds) since last whole second. [8] </td></tr>
<tr><td> <code>%.f</code> </td><td> <code>.026490</code></td><td> Similar to <code>.%f</code> but left-aligned. These all consume the leading dot. [8] </td></tr>
<tr><td> <code>%.3f</code></td><td> <code>.026</code> </td><td> Similar to <code>.%f</code> but left-aligned but fixed to a length of 3. [8] </td></tr>
<tr><td> <code>%.6f</code></td><td> <code>.026490</code> </td><td> Similar to <code>.%f</code> but left-aligned but fixed to a length of 6. [8] </td></tr>
<tr><td> <code>%.9f</code></td><td> <code>.026490000</code> </td><td> Similar to <code>.%f</code> but left-aligned but fixed to a length of 9. [8] </td></tr>
<tr><td> <code>%3f</code> </td><td> <code>026</code> </td><td> Similar to <code>%.3f</code> but without the leading dot. [8] </td></tr>
<tr><td> <code>%6f</code> </td><td> <code>026490</code> </td><td> Similar to <code>%.6f</code> but without the leading dot. [8] </td></tr>
<tr><td> <code>%9f</code> </td><td> <code>026490000</code> </td><td> Similar to <code>%.9f</code> but without the leading dot. [8] </td></tr>
<tr><td> </td><td> </td><td> </td></tr>
<tr><td> <code>%R</code> </td><td> <code>00:34</code> </td><td> Hour-minute format. Same to <code>%H:%M</code>. </td></tr>
<tr><td> <code>%T</code> </td><td> <code>00:34:60</code> </td><td> Hour-minute-second format. Same to <code>%H:%M:%S</code>. </td></tr>
<tr><td> <code>%X</code> </td><td> <code>00:34:60</code> </td><td> Same to <code>%T</code>. </td></tr>
<tr><td> <code>%r</code> </td><td> <code>12:34:60 AM</code> </td><td> Hour-minute-second format in 12-hour clocks. Same to <code>%I:%M:%S %p</code>. </td></tr>
<tr><td> </td><td> </td><td> </td></tr>
<tr><td> </td><td> </td><td> <strong>TIME ZONE SPECIFIERS:</strong> </td></tr>
<tr><td> <code>%Z</code> </td><td> <code>ACST</code> </td><td> <em>Formatting only:</em> Local time zone name. </td></tr>
<tr><td> <code>%z</code> </td><td> <code>+0930</code> </td><td> Offset from the local time to UTC (with UTC being <code>+0000</code>). </td></tr>
<tr><td> <code>%:z</code> </td><td> <code>+09:30</code> </td><td> Same to <code>%z</code> but with a colon. </td></tr>
<tr><td> <code>%#z</code> </td><td> <code>+09</code> </td><td> <em>Parsing only:</em> Same to <code>%z</code> but allows minutes to be missing or present. </td></tr>
<tr><td> </td><td> </td><td> </td></tr>
<tr><td> </td><td> </td><td> <strong>DATE &amp; TIME SPECIFIERS:</strong> </td></tr>
<tr><td><code>%c</code></td><td><code>Sun Jul 8 00:34:60 2001</code></td><td><code>ctime</code> date &amp; time format. Same to <code>%a %b %e %T %Y</code> sans <code>\n</code>.</td></tr>
<tr><td> <code>%+</code> </td><td> <code>2001-07-08T00:34:60.026490+09:30</code> </td><td> ISO 8601 / RFC 3339 date &amp; time format. [6] </td></tr>
<tr><td> </td><td> </td><td> </td></tr>
<tr><td> <code>%s</code> </td><td> <code>994518299</code> </td><td> UNIX timestamp, the number of seconds since 1970-01-01 00:00 UTC. [7] </td></tr>
<tr><td> </td><td> </td><td> </td></tr>
<tr><td> </td><td> </td><td> <strong>SPECIAL SPECIFIERS:</strong> </td></tr>
<tr><td> <code>%t</code> </td><td> </td><td> Literal tab (<code>\t</code>). </td></tr>
<tr><td> <code>%n</code> </td><td> </td><td> Literal newline (<code>\n</code>). </td></tr>
<tr><td> <code>%%</code> </td><td> </td><td> Literal percent sign. </td></tr>
</tbody></table>
<p>It is possible to override the default padding behavior of numeric specifiers <code>%?</code>.
This is not allowed for other specifiers and will result in the <code>BAD_FORMAT</code> error.</p>
<table><thead><tr><th>Modifier </th><th> Description</th></tr></thead><tbody>
<tr><td><code>%-?</code> </td><td> Suppresses any padding including spaces and zeroes. (e.g. <code>%j</code> = <code>012</code>, <code>%-j</code> = <code>12</code>)</td></tr>
<tr><td><code>%_?</code> </td><td> Uses spaces as a padding. (e.g. <code>%j</code> = <code>012</code>, <code>%_j</code> = <code>12</code>)</td></tr>
<tr><td><code>%0?</code> </td><td> Uses zeroes as a padding. (e.g. <code>%e</code> = <code>9</code>, <code>%0e</code> = <code>09</code>)</td></tr>
</tbody></table>
<p>Notes:</p>
<ol>
<li>
<p><code>%Y</code>:
Negative years are allowed in formatting but not in parsing.</p>
</li>
<li>
<p><code>%C</code>, <code>%y</code>:
This is floor division, so 100 BCE (year number -99) will print <code>-1</code> and <code>99</code> respectively.</p>
</li>
<li>
<p><code>%U</code>:
Week 1 starts with the first Sunday in that year.
It is possible to have week 0 for days before the first Sunday.</p>
</li>
<li>
<p><code>%G</code>, <code>%g</code>, <code>%V</code>:
Week 1 is the first week with at least 4 days in that year.
Week 0 does not exist, so this should be used with <code>%G</code> or <code>%g</code>.</p>
</li>
<li>
<p><code>%S</code>:
It accounts for leap seconds, so <code>60</code> is possible.</p>
</li>
<li>
<p><code>%+</code>:
Same to <code>%Y-%m-%dT%H:%M:%S%.f%:z</code>,
i.e. 0, 3, 6 or 9 fractional digits for seconds and colons in the time zone offset.</p>
<p>The typical <code>strftime</code> implementations have
different (and locale-dependent) formats for this specifier.
While Chrono's format for <code>%+</code> is far more stable,
it is best to avoid this specifier if you want to control the exact output.</p>
</li>
<li>
<p><code>%s</code>:
This is not padded and can be negative.
For the purpose of Chrono, it only accounts for non-leap seconds
so it slightly differs from ISO C <code>strftime</code> behavior.</p>
</li>
<li>
<p><code>%f</code>, <code>%.f</code>, <code>%.3f</code>, <code>%.6f</code>, <code>%.9f</code>, <code>%3f</code>, <code>%6f</code>, <code>%9f</code>:</p>
<p>The default <code>%f</code> is right-aligned and always zero-padded to 9 digits
for the compatibility with glibc and others,
so it always counts the number of nanoseconds since the last whole second.
E.g. 7ms after the last second will print <code>007000000</code>,
and parsing <code>7000000</code> will yield the same.</p>
<p>The variant <code>%.f</code> is left-aligned and print 0, 3, 6 or 9 fractional digits
according to the precision.
E.g. 70ms after the last second under <code>%.f</code> will print <code>.070</code> (note: not <code>.07</code>),
and parsing <code>.07</code>, <code>.070000</code> etc. will yield the same.
Note that they can print or read nothing if the fractional part is zero or
the next character is not <code>.</code>.</p>
<p>The variant <code>%.3f</code>, <code>%.6f</code> and <code>%.9f</code> are left-aligned and print 3, 6 or 9 fractional digits
according to the number preceding <code>f</code>.
E.g. 70ms after the last second under <code>%.3f</code> will print <code>.070</code> (note: not <code>.07</code>),
and parsing <code>.07</code>, <code>.070000</code> etc. will yield the same.
Note that they can read nothing if the fractional part is zero or
the next character is not <code>.</code> however will print with the specified length.</p>
<p>The variant <code>%3f</code>, <code>%6f</code> and <code>%9f</code> are left-aligned and print 3, 6 or 9 fractional digits
according to the number preceding <code>f</code>, but without the leading dot.
E.g. 70ms after the last second under <code>%3f</code> will print <code>070</code> (note: not <code>07</code>),
and parsing <code>07</code>, <code>070000</code> etc. will yield the same.
Note that they can read nothing if the fractional part is zero.</p>
</li>
</ol>
</div><h2 id='structs' class='section-header'><a href="#structs">Structs</a></h2>
<table>
<tr class=' module-item'>
<td><a class="struct" href="struct.StrftimeItems.html"
title='struct chrono::format::strftime::StrftimeItems'>StrftimeItems</a></td>
<td class='docblock-short'>
<p>Parsing iterator for <code>strftime</code>-like format strings.</p>
</td>
</tr></table></section>
<section id='search' class="content hidden"></section>
<section class="footer"></section>
<aside id="help" class="hidden">
<div>
<h1 class="hidden">Help</h1>
<div class="shortcuts">
<h2>Keyboard Shortcuts</h2>
<dl>
<dt><kbd>?</kbd></dt>
<dd>Show this help dialog</dd>
<dt><kbd>S</kbd></dt>
<dd>Focus the search field</dd>
<dt><kbd></kbd></dt>
<dd>Move up in search results</dd>
<dt><kbd></kbd></dt>
<dd>Move down in search results</dd>
<dt><kbd></kbd></dt>
<dd>Switch tab</dd>
<dt><kbd>&#9166;</kbd></dt>
<dd>Go to active search result</dd>
<dt><kbd>+</kbd></dt>
<dd>Expand all sections</dd>
<dt><kbd>-</kbd></dt>
<dd>Collapse all sections</dd>
</dl>
</div>
<div class="infos">
<h2>Search Tricks</h2>
<p>
Prefix searches with a type followed by a colon (e.g.
<code>fn:</code>) to restrict the search to a given type.
</p>
<p>
Accepted types are: <code>fn</code>, <code>mod</code>,
<code>struct</code>, <code>enum</code>,
<code>trait</code>, <code>type</code>, <code>macro</code>,
and <code>const</code>.
</p>
<p>
Search functions by type signature (e.g.
<code>vec -> usize</code> or <code>* -> vec</code>)
</p>
</div>
</div>
</aside>
<script>
window.rootPath = "../../../";
window.currentCrate = "chrono";
</script>
<script src="../../../main.js"></script>
<script defer src="../../../search-index.js"></script>
</body>
</html>