| <!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="`strftime`/`strptime`-inspired date and time formatting syntax."><meta name="keywords" content="rust, rustlang, rust-lang, strftime"><title>chrono::format::strftime - Rust</title><link rel="preload" as="font" type="font/woff2" crossorigin href="../../../SourceSerif4-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../../FiraSans-Regular.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../../FiraSans-Medium.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../../SourceCodePro-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../../SourceSerif4-Bold.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../../SourceCodePro-Semibold.ttf.woff2"><link rel="stylesheet" href="../../../normalize.css"><link rel="stylesheet" href="../../../rustdoc.css" id="mainThemeStyle"><link rel="stylesheet" href="../../../ayu.css" disabled><link rel="stylesheet" href="../../../dark.css" disabled><link rel="stylesheet" href="../../../light.css" id="themeStyle"><script id="default-settings" ></script><script src="../../../storage.js"></script><script defer src="../../../main.js"></script><noscript><link rel="stylesheet" href="../../../noscript.css"></noscript><link rel="alternate icon" type="image/png" href="../../../favicon-16x16.png"><link rel="alternate icon" type="image/png" href="../../../favicon-32x32.png"><link rel="icon" type="image/svg+xml" href="../../../favicon.svg"></head><body class="rustdoc mod"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle">☰</button><a class="sidebar-logo" href="../../../chrono/index.html"><div class="logo-container"><img class="rust-logo" src="../../../rust-logo.svg" alt="logo"></div></a><h2></h2></nav><nav class="sidebar"><a class="sidebar-logo" href="../../../chrono/index.html"><div class="logo-container"><img class="rust-logo" src="../../../rust-logo.svg" alt="logo"></div></a><h2 class="location"><a href="#">Module strftime</a></h2><div class="sidebar-elems"><section><ul class="block"><li><a href="#structs">Structs</a></li></ul></section></div></nav><main><div class="width-limiter"><nav class="sub"><form class="search-form"><div class="search-container"><span></span><input class="search-input" name="search" autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"><div id="help-button" title="help" tabindex="-1"><a href="../../../help.html">?</a></div><div id="settings-menu" tabindex="-1"><a href="../../../settings.html" title="settings"><img width="22" height="22" alt="Change settings" src="../../../wheel.svg"></a></div></div></form></nav><section id="main-content" class="content"><div class="main-heading"><h1 class="fqn">Module <a href="../../index.html">chrono</a>::<wbr><a href="../index.html">format</a>::<wbr><a class="mod" href="#">strftime</a><button id="copy-path" onclick="copy_path(this)" title="Copy item path to clipboard"><img src="../../../clipboard.svg" width="19" height="18" alt="Copy item path"></button></h1><span class="out-of-band"><a class="srclink" href="../../../src/chrono/format/strftime.rs.html#4-720">source</a> · <a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">[<span class="inner">−</span>]</a></span></div><details class="rustdoc-toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p><code>strftime</code>/<code>strptime</code>-inspired date and time formatting syntax.</p> |
| <h3 id="specifiers"><a href="#specifiers">Specifiers</a></h3> |
| <p>The following specifiers are available both to formatting and parsing.</p> |
| <div><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. chrono supports years from -262144 to 262143. Note: years before 1 BCE or after 9999 CE, require an initial sign (+/-).</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. <sup id="fnref1"><a href="#fn1">1</a></sup></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. <sup id="fnref1"><a href="#fn1">1</a></sup></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 as <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 as <code>%d</code> but space-padded. Same as <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. <sup id="fnref2"><a href="#fn2">2</a></sup></td></tr> |
| <tr><td><code>%W</code></td><td><code>27</code></td><td>Same as <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 as <code>%Y</code> but uses the year number in ISO 8601 week date. <sup id="fnref3"><a href="#fn3">3</a></sup></td></tr> |
| <tr><td><code>%g</code></td><td><code>01</code></td><td>Same as <code>%y</code> but uses the year number in ISO 8601 week date. <sup id="fnref3"><a href="#fn3">3</a></sup></td></tr> |
| <tr><td><code>%V</code></td><td><code>27</code></td><td>Same as <code>%U</code> but uses the week number in ISO 8601 week date (01–53). <sup id="fnref3"><a href="#fn3">3</a></sup></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 as <code>%m/%d/%y</code>.</td></tr> |
| <tr><td><code>%x</code></td><td><code>07/08/01</code></td><td>Locale’s date representation (e.g., 12/31/99).</td></tr> |
| <tr><td><code>%F</code></td><td><code>2001-07-08</code></td><td>Year-month-day format (ISO 8601). Same as <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 as <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 as <code>%H</code> but space-padded. Same as <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 as <code>%I</code> but space-padded. Same as <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. <sup id="fnref4"><a href="#fn4">4</a></sup></td></tr> |
| <tr><td><code>%f</code></td><td><code>026490000</code></td><td>The fractional seconds (in nanoseconds) since last whole second. <sup id="fnref5"><a href="#fn5">5</a></sup></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. <sup id="fnref5"><a href="#fn5">5</a></sup></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. <sup id="fnref5"><a href="#fn5">5</a></sup></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. <sup id="fnref5"><a href="#fn5">5</a></sup></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. <sup id="fnref5"><a href="#fn5">5</a></sup></td></tr> |
| <tr><td><code>%3f</code></td><td><code>026</code></td><td>Similar to <code>%.3f</code> but without the leading dot. <sup id="fnref5"><a href="#fn5">5</a></sup></td></tr> |
| <tr><td><code>%6f</code></td><td><code>026490</code></td><td>Similar to <code>%.6f</code> but without the leading dot. <sup id="fnref5"><a href="#fn5">5</a></sup></td></tr> |
| <tr><td><code>%9f</code></td><td><code>026490000</code></td><td>Similar to <code>%.9f</code> but without the leading dot. <sup id="fnref5"><a href="#fn5">5</a></sup></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 as <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 as <code>%H:%M:%S</code>.</td></tr> |
| <tr><td><code>%X</code></td><td><code>00:34:60</code></td><td>Locale’s time representation (e.g., 23:13:48).</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 as <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>Local time zone name. Skips all non-whitespace characters during parsing. Identical to <code>%:z</code> when formatting. <sup id="fnref6"><a href="#fn6">6</a></sup></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 as <code>%z</code> but with a colon.</td></tr> |
| <tr><td><code>%::z</code></td><td><code>+09:30:00</code></td><td>Offset from the local time to UTC with seconds.</td></tr> |
| <tr><td><code>%:::z</code></td><td><code>+09</code></td><td>Offset from the local time to UTC without minutes.</td></tr> |
| <tr><td><code>%#z</code></td><td><code>+09</code></td><td><em>Parsing only:</em> Same as <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 & TIME SPECIFIERS:</strong></td></tr> |
| <tr><td><code>%c</code></td><td><code>Sun Jul 8 00:34:60 2001</code></td><td>Locale’s date and time (e.g., Thu Mar 3 23:05:25 2005).</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 & time format. <sup id="fnref7"><a href="#fn7">7</a></sup></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. <sup id="fnref8"><a href="#fn8">8</a></sup></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> |
| </div> |
| <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> |
| <div><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> |
| </div> |
| <p>Notes:</p> |
| <div class="footnotes"><hr><ol><li id="fn1"><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. <a href="#fnref1">↩</a></p></li><li id="fn2"><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. <a href="#fnref2">↩</a></p></li><li id="fn3"><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>. <a href="#fnref3">↩</a></p></li><li id="fn4"><p><code>%S</code>: |
| It accounts for leap seconds, so <code>60</code> is possible. <a href="#fnref4">↩</a></p></li><li id="fn5"><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>: |
| <br> |
| 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. |
| <br> |
| <br> |
| 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>. |
| <br> |
| <br> |
| 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. |
| <br> |
| <br> |
| 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. <a href="#fnref5">↩</a></p></li><li id="fn6"><p><code>%Z</code>: |
| Since <code>chrono</code> is not aware of timezones beyond their offsets, this specifier |
| <strong>only prints the offset</strong> when used for formatting. The timezone abbreviation |
| will NOT be printed. See <a href="https://github.com/chronotope/chrono/issues/960">this issue</a> |
| for more information. |
| <br> |
| <br> |
| Offset will not be populated from the parsed data, nor will it be validated. |
| Timezone is completely ignored. Similar to the glibc <code>strptime</code> treatment of |
| this format code. |
| <br> |
| <br> |
| It is not possible to reliably convert from an abbreviation to an offset, |
| for example CDT can mean either Central Daylight Time (North America) or |
| China Daylight Time. <a href="#fnref6">↩</a></p></li><li id="fn7"><p><code>%+</code>: Same as <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. |
| <br> |
| <br> |
| This format also supports having a <code>Z</code> or <code>UTC</code> in place of <code>%:z</code>. They |
| are equivalent to <code>+00:00</code>. |
| <br> |
| <br> |
| Note that all <code>T</code>, <code>Z</code>, and <code>UTC</code> are parsed case-insensitively. |
| <br> |
| <br> |
| 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. <a href="#fnref7">↩</a></p></li><li id="fn8"><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. <a href="#fnref8">↩</a></p></li></ol></div></div></details><h2 id="structs" class="small-section-header"><a href="#structs">Structs</a></h2><div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="struct" href="struct.StrftimeItems.html" title="chrono::format::strftime::StrftimeItems struct">StrftimeItems</a></div><div class="item-right docblock-short">Parsing iterator for <code>strftime</code>-like format strings.</div></div></div></section></div></main><div id="rustdoc-vars" data-root-path="../../../" data-current-crate="chrono" data-themes="ayu,dark,light" data-resource-suffix="" data-rustdoc-version="1.66.0-nightly (5c8bff74b 2022-10-21)" ></div></body></html> |
