487 lines
44 KiB
HTML
487 lines
44 KiB
HTML
<!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 `chrono` crate.">
|
||
<meta name="keywords" content="rust, rustlang, rust-lang, chrono">
|
||
|
||
<title>chrono - Rust</title>
|
||
|
||
<link rel="stylesheet" type="text/css" href="../normalize.css">
|
||
<link rel="stylesheet" type="text/css" href="../rustdoc.css">
|
||
<link rel="stylesheet" type="text/css" href="../main.css">
|
||
|
||
|
||
|
||
|
||
</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">
|
||
|
||
<p class='location'>Crate chrono</p><div class="block items"><ul><li><a href="#reexports">Reexports</a></li><li><a href="#modules">Modules</a></li><li><a href="#structs">Structs</a></li><li><a href="#enums">Enums</a></li><li><a href="#traits">Traits</a></li></ul></div><p class='location'></p><script>window.sidebarCurrent = {name: 'chrono', ty: 'mod', relpath: '../'};</script>
|
||
</nav>
|
||
|
||
<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'>Crate <a class="mod" href=''>chrono</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'>−</span>]
|
||
</a>
|
||
</span><a class='srclink' href='../src/chrono/lib.rs.html#5-732' title='goto source code'>[src]</a></span></h1>
|
||
<div class='docblock'>
|
||
<h1 id='chrono-0225' class='section-header'><a href='#chrono-0225'>Chrono 0.2.25</a></h1>
|
||
<p>Date and time handling for Rust. (also known as <code>rust-chrono</code>)
|
||
It aims to be a feature-complete superset of
|
||
the <a href="https://github.com/rust-lang-deprecated/time">time</a> library.
|
||
In particular,</p>
|
||
|
||
<ul>
|
||
<li>Chrono strictly adheres to ISO 8601.</li>
|
||
<li>Chrono is timezone-aware by default, with separate timezone-naive types.</li>
|
||
<li>Chrono is space-optimal and (while not being the primary goal) reasonably efficient.</li>
|
||
</ul>
|
||
|
||
<p>There were several previous attempts to bring a good date and time library to Rust,
|
||
which Chrono builts upon and should acknowledge:</p>
|
||
|
||
<ul>
|
||
<li><a href="https://github.com/rust-lang/rust-wiki-backup/blob/master/Lib-datetime.md">Initial research on
|
||
the wiki</a></li>
|
||
<li>Dietrich Epp's <a href="https://github.com/depp/datetime-rs">datetime-rs</a></li>
|
||
<li>Luis de Bethencourt's <a href="https://github.com/luisbg/rust-datetime">rust-datetime</a></li>
|
||
</ul>
|
||
|
||
<h2 id='usage' class='section-header'><a href='#usage'>Usage</a></h2>
|
||
<p>Put this in your <code>Cargo.toml</code>:</p>
|
||
|
||
<pre><code class="language-toml">[dependencies]
|
||
chrono = "0.2"
|
||
</code></pre>
|
||
|
||
<p>Or, if you want <a href="https://github.com/serde-rs/serde">Serde</a> or
|
||
<a href="https://github.com/rust-lang-nursery/rustc-serialize">rustc-serialize</a> support,
|
||
include the features like this:</p>
|
||
|
||
<pre><code class="language-toml">[dependencies]
|
||
chrono = { version = "0.2", features = ["serde", "rustc-serialize"] }
|
||
</code></pre>
|
||
|
||
<p>Then put this in your crate root:</p>
|
||
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="kw">extern</span> <span class="kw">crate</span> <span class="ident">chrono</span>;</pre>
|
||
|
||
<h2 id='overview' class='section-header'><a href='#overview'>Overview</a></h2>
|
||
<h3 id='duration' class='section-header'><a href='#duration'>Duration</a></h3>
|
||
<p><a href="./struct.Duration.html"><strong><code>Duration</code></strong></a>
|
||
represents the magnitude of a time span. <code>Duration</code> used to be provided by Chrono.
|
||
It has been moved to the <code>time</code> crate as the
|
||
<a href="https://doc.rust-lang.org/time/time/struct.Duration.html"><code>time::Duration</code></a> type, but is
|
||
still re-exported from Chrono.</p>
|
||
|
||
<h3 id='date-and-time' class='section-header'><a href='#date-and-time'>Date and Time</a></h3>
|
||
<p>Chrono provides a
|
||
<a href="./datetime/struct.DateTime.html"><strong><code>DateTime</code></strong></a>
|
||
type to represent a date and a time in a timezone.</p>
|
||
|
||
<p>For more abstract moment-in-time tracking such as internal timekeeping
|
||
that is unconcerned with timezones, consider
|
||
<a href="https://doc.rust-lang.org/std/time/struct.SystemTime.html"><code>time::SystemTime</code></a>,
|
||
which tracks your system clock, or
|
||
<a href="https://doc.rust-lang.org/std/time/struct.Instant.html"><code>time::Instant</code></a>, which
|
||
is an opaque but monotonically-increasing representation of a moment in time.</p>
|
||
|
||
<p><code>DateTime</code> is timezone-aware and must be constructed from
|
||
the <a href="./offset/trait.TimeZone.html"><strong><code>TimeZone</code></strong></a> object,
|
||
which defines how the local date is converted to and back from the UTC date.
|
||
There are three well-known <code>TimeZone</code> implementations:</p>
|
||
|
||
<ul>
|
||
<li><p><a href="./offset/utc/struct.UTC.html"><strong><code>UTC</code></strong></a> specifies the UTC time zone. It is most efficient.</p></li>
|
||
<li><p><a href="./offset/local/struct.Local.html"><strong><code>Local</code></strong></a> specifies the system local time zone.</p></li>
|
||
<li><p><a href="./offset/fixed/struct.FixedOffset.html"><strong><code>FixedOffset</code></strong></a> specifies
|
||
an arbitrary, fixed time zone such as UTC+09:00 or UTC-10:30.
|
||
This often results from the parsed textual date and time.
|
||
Since it stores the most information and does not depend on the system environment,
|
||
you would want to normalize other <code>TimeZone</code>s into this type.</p></li>
|
||
</ul>
|
||
|
||
<p><code>DateTime</code>s with different <code>TimeZone</code> types are distinct and do not mix,
|
||
but can be converted to each other using
|
||
the <a href="./datetime/struct.DateTime.html#method.with_timezone"><code>DateTime::with_timezone</code></a> method.</p>
|
||
|
||
<p>You can get the current date and time in the UTC time zone
|
||
(<a href="./offset/utc/struct.UTC.html#method.now"><code>UTC::now()</code></a>)
|
||
or in the local time zone
|
||
(<a href="./offset/local/struct.Local.html#method.now"><code>Local::now()</code></a>).</p>
|
||
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="kw">use</span> <span class="ident">chrono</span>::<span class="kw-2">*</span>;
|
||
|
||
<span class="kw">let</span> <span class="ident">utc</span>: <span class="ident">DateTime</span><span class="op"><</span><span class="ident">UTC</span><span class="op">></span> <span class="op">=</span> <span class="ident">UTC</span>::<span class="ident">now</span>(); <span class="comment">// e.g. `2014-11-28T12:45:59.324310806Z`</span>
|
||
<span class="kw">let</span> <span class="ident">local</span>: <span class="ident">DateTime</span><span class="op"><</span><span class="ident">Local</span><span class="op">></span> <span class="op">=</span> <span class="ident">Local</span>::<span class="ident">now</span>(); <span class="comment">// e.g. `2014-11-28T21:45:59.324310806+09:00`</span></pre>
|
||
|
||
<p>Alternatively, you can create your own date and time.
|
||
This is a bit verbose due to Rust's lack of function and method overloading,
|
||
but in turn we get a rich combination of initialization methods.</p>
|
||
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="kw">use</span> <span class="ident">chrono</span>::<span class="kw-2">*</span>;
|
||
|
||
<span class="kw">let</span> <span class="ident">dt</span> <span class="op">=</span> <span class="ident">UTC</span>.<span class="ident">ymd</span>(<span class="number">2014</span>, <span class="number">7</span>, <span class="number">8</span>).<span class="ident">and_hms</span>(<span class="number">9</span>, <span class="number">10</span>, <span class="number">11</span>); <span class="comment">// `2014-07-08T09:10:11Z`</span>
|
||
<span class="comment">// July 8 is 188th day of the year 2014 (`o` for "ordinal")</span>
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">dt</span>, <span class="ident">UTC</span>.<span class="ident">yo</span>(<span class="number">2014</span>, <span class="number">189</span>).<span class="ident">and_hms</span>(<span class="number">9</span>, <span class="number">10</span>, <span class="number">11</span>));
|
||
<span class="comment">// July 8 is Tuesday in ISO week 28 of the year 2014.</span>
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">dt</span>, <span class="ident">UTC</span>.<span class="ident">isoywd</span>(<span class="number">2014</span>, <span class="number">28</span>, <span class="ident">Weekday</span>::<span class="ident">Tue</span>).<span class="ident">and_hms</span>(<span class="number">9</span>, <span class="number">10</span>, <span class="number">11</span>));
|
||
|
||
<span class="kw">let</span> <span class="ident">dt</span> <span class="op">=</span> <span class="ident">UTC</span>.<span class="ident">ymd</span>(<span class="number">2014</span>, <span class="number">7</span>, <span class="number">8</span>).<span class="ident">and_hms_milli</span>(<span class="number">9</span>, <span class="number">10</span>, <span class="number">11</span>, <span class="number">12</span>); <span class="comment">// `2014-07-08T09:10:11.012Z`</span>
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">dt</span>, <span class="ident">UTC</span>.<span class="ident">ymd</span>(<span class="number">2014</span>, <span class="number">7</span>, <span class="number">8</span>).<span class="ident">and_hms_micro</span>(<span class="number">9</span>, <span class="number">10</span>, <span class="number">11</span>, <span class="number">12_000</span>));
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">dt</span>, <span class="ident">UTC</span>.<span class="ident">ymd</span>(<span class="number">2014</span>, <span class="number">7</span>, <span class="number">8</span>).<span class="ident">and_hms_nano</span>(<span class="number">9</span>, <span class="number">10</span>, <span class="number">11</span>, <span class="number">12_000_000</span>));
|
||
|
||
<span class="comment">// dynamic verification</span>
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">UTC</span>.<span class="ident">ymd_opt</span>(<span class="number">2014</span>, <span class="number">7</span>, <span class="number">8</span>).<span class="ident">and_hms_opt</span>(<span class="number">21</span>, <span class="number">15</span>, <span class="number">33</span>),
|
||
<span class="ident">LocalResult</span>::<span class="ident">Single</span>(<span class="ident">UTC</span>.<span class="ident">ymd</span>(<span class="number">2014</span>, <span class="number">7</span>, <span class="number">8</span>).<span class="ident">and_hms</span>(<span class="number">21</span>, <span class="number">15</span>, <span class="number">33</span>)));
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">UTC</span>.<span class="ident">ymd_opt</span>(<span class="number">2014</span>, <span class="number">7</span>, <span class="number">8</span>).<span class="ident">and_hms_opt</span>(<span class="number">80</span>, <span class="number">15</span>, <span class="number">33</span>), <span class="ident">LocalResult</span>::<span class="prelude-val">None</span>);
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">UTC</span>.<span class="ident">ymd_opt</span>(<span class="number">2014</span>, <span class="number">7</span>, <span class="number">38</span>).<span class="ident">and_hms_opt</span>(<span class="number">21</span>, <span class="number">15</span>, <span class="number">33</span>), <span class="ident">LocalResult</span>::<span class="prelude-val">None</span>);
|
||
|
||
<span class="comment">// other time zone objects can be used to construct a local datetime.</span>
|
||
<span class="comment">// obviously, `local_dt` is normally different from `dt`, but `fixed_dt` should be identical.</span>
|
||
<span class="kw">let</span> <span class="ident">local_dt</span> <span class="op">=</span> <span class="ident">Local</span>.<span class="ident">ymd</span>(<span class="number">2014</span>, <span class="number">7</span>, <span class="number">8</span>).<span class="ident">and_hms_milli</span>(<span class="number">9</span>, <span class="number">10</span>, <span class="number">11</span>, <span class="number">12</span>);
|
||
<span class="kw">let</span> <span class="ident">fixed_dt</span> <span class="op">=</span> <span class="ident">FixedOffset</span>::<span class="ident">east</span>(<span class="number">9</span> <span class="op">*</span> <span class="number">3600</span>).<span class="ident">ymd</span>(<span class="number">2014</span>, <span class="number">7</span>, <span class="number">8</span>).<span class="ident">and_hms_milli</span>(<span class="number">18</span>, <span class="number">10</span>, <span class="number">11</span>, <span class="number">12</span>);
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">dt</span>, <span class="ident">fixed_dt</span>);</pre>
|
||
|
||
<p>Various properties are available to the date and time, and can be altered individually.
|
||
Most of them are defined in the traits <a href="./trait.Datelike.html"><code>Datelike</code></a> and
|
||
<a href="./trait.Timelike.html"><code>Timelike</code></a> which you should <code>use</code> before.
|
||
Addition and subtraction is also supported.
|
||
The following illustrates most supported operations to the date and time:</p>
|
||
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="kw">use</span> <span class="ident">chrono</span>::<span class="kw-2">*</span>;
|
||
|
||
<span class="comment">// assume this returned `2014-11-28T21:45:59.324310806+09:00`:</span>
|
||
<span class="kw">let</span> <span class="ident">dt</span> <span class="op">=</span> <span class="ident">Local</span>::<span class="ident">now</span>();
|
||
|
||
<span class="comment">// property accessors</span>
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>((<span class="ident">dt</span>.<span class="ident">year</span>(), <span class="ident">dt</span>.<span class="ident">month</span>(), <span class="ident">dt</span>.<span class="ident">day</span>()), (<span class="number">2014</span>, <span class="number">11</span>, <span class="number">28</span>));
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>((<span class="ident">dt</span>.<span class="ident">month0</span>(), <span class="ident">dt</span>.<span class="ident">day0</span>()), (<span class="number">10</span>, <span class="number">27</span>)); <span class="comment">// for unfortunate souls</span>
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>((<span class="ident">dt</span>.<span class="ident">hour</span>(), <span class="ident">dt</span>.<span class="ident">minute</span>(), <span class="ident">dt</span>.<span class="ident">second</span>()), (<span class="number">21</span>, <span class="number">45</span>, <span class="number">59</span>));
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">dt</span>.<span class="ident">weekday</span>(), <span class="ident">Weekday</span>::<span class="ident">Fri</span>);
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">dt</span>.<span class="ident">weekday</span>().<span class="ident">number_from_monday</span>(), <span class="number">5</span>); <span class="comment">// Mon=1, ..., Sat=7</span>
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">dt</span>.<span class="ident">ordinal</span>(), <span class="number">332</span>); <span class="comment">// the day of year</span>
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">dt</span>.<span class="ident">num_days_from_ce</span>(), <span class="number">735565</span>); <span class="comment">// the number of days from and including Jan 1, 1</span>
|
||
|
||
<span class="comment">// time zone accessor and manipulation</span>
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">dt</span>.<span class="ident">offset</span>().<span class="ident">local_minus_utc</span>(), <span class="ident">Duration</span>::<span class="ident">hours</span>(<span class="number">9</span>));
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">dt</span>.<span class="ident">timezone</span>(), <span class="ident">FixedOffset</span>::<span class="ident">east</span>(<span class="number">9</span> <span class="op">*</span> <span class="number">3600</span>));
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">dt</span>.<span class="ident">with_timezone</span>(<span class="kw-2">&</span><span class="ident">UTC</span>), <span class="ident">UTC</span>.<span class="ident">ymd</span>(<span class="number">2014</span>, <span class="number">11</span>, <span class="number">28</span>).<span class="ident">and_hms_nano</span>(<span class="number">12</span>, <span class="number">45</span>, <span class="number">59</span>, <span class="number">324310806</span>));
|
||
|
||
<span class="comment">// a sample of property manipulations (validates dynamically)</span>
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">dt</span>.<span class="ident">with_day</span>(<span class="number">29</span>).<span class="ident">unwrap</span>().<span class="ident">weekday</span>(), <span class="ident">Weekday</span>::<span class="ident">Sat</span>); <span class="comment">// 2014-11-29 is Saturday</span>
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">dt</span>.<span class="ident">with_day</span>(<span class="number">32</span>), <span class="prelude-val">None</span>);
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">dt</span>.<span class="ident">with_year</span>(<span class="op">-</span><span class="number">300</span>).<span class="ident">unwrap</span>().<span class="ident">num_days_from_ce</span>(), <span class="op">-</span><span class="number">109606</span>); <span class="comment">// November 29, 301 BCE</span>
|
||
|
||
<span class="comment">// arithmetic operations</span>
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">UTC</span>.<span class="ident">ymd</span>(<span class="number">2014</span>, <span class="number">11</span>, <span class="number">14</span>).<span class="ident">and_hms</span>(<span class="number">8</span>, <span class="number">9</span>, <span class="number">10</span>) <span class="op">-</span> <span class="ident">UTC</span>.<span class="ident">ymd</span>(<span class="number">2014</span>, <span class="number">11</span>, <span class="number">14</span>).<span class="ident">and_hms</span>(<span class="number">10</span>, <span class="number">9</span>, <span class="number">8</span>),
|
||
<span class="ident">Duration</span>::<span class="ident">seconds</span>(<span class="op">-</span><span class="number">2</span> <span class="op">*</span> <span class="number">3600</span> <span class="op">+</span> <span class="number">2</span>));
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">UTC</span>.<span class="ident">ymd</span>(<span class="number">1970</span>, <span class="number">1</span>, <span class="number">1</span>).<span class="ident">and_hms</span>(<span class="number">0</span>, <span class="number">0</span>, <span class="number">0</span>) <span class="op">+</span> <span class="ident">Duration</span>::<span class="ident">seconds</span>(<span class="number">1_000_000_000</span>),
|
||
<span class="ident">UTC</span>.<span class="ident">ymd</span>(<span class="number">2001</span>, <span class="number">9</span>, <span class="number">9</span>).<span class="ident">and_hms</span>(<span class="number">1</span>, <span class="number">46</span>, <span class="number">40</span>));
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">UTC</span>.<span class="ident">ymd</span>(<span class="number">1970</span>, <span class="number">1</span>, <span class="number">1</span>).<span class="ident">and_hms</span>(<span class="number">0</span>, <span class="number">0</span>, <span class="number">0</span>) <span class="op">-</span> <span class="ident">Duration</span>::<span class="ident">seconds</span>(<span class="number">1_000_000_000</span>),
|
||
<span class="ident">UTC</span>.<span class="ident">ymd</span>(<span class="number">1938</span>, <span class="number">4</span>, <span class="number">24</span>).<span class="ident">and_hms</span>(<span class="number">22</span>, <span class="number">13</span>, <span class="number">20</span>));</pre>
|
||
|
||
<p>Formatting is done via the <a href="./datetime/struct.DateTime.html#method.format"><code>format</code></a> method,
|
||
which format is equivalent to the familiar <code>strftime</code> format.
|
||
(See the <a href="./format/strftime/index.html#specifiers"><code>format::strftime</code> module documentation</a>
|
||
for full syntax.)</p>
|
||
|
||
<p>The default <code>to_string</code> method and <code>{:?}</code> specifier also give a reasonable representation.
|
||
Chrono also provides <a href="./datetime/struct.DateTime.html#method.to_rfc2822"><code>to_rfc2822</code></a> and
|
||
<a href="./datetime/struct.DateTime.html#method.to_rfc3339"><code>to_rfc3339</code></a> methods
|
||
for well-known formats.</p>
|
||
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="kw">use</span> <span class="ident">chrono</span>::<span class="kw-2">*</span>;
|
||
|
||
<span class="kw">let</span> <span class="ident">dt</span> <span class="op">=</span> <span class="ident">UTC</span>.<span class="ident">ymd</span>(<span class="number">2014</span>, <span class="number">11</span>, <span class="number">28</span>).<span class="ident">and_hms</span>(<span class="number">12</span>, <span class="number">0</span>, <span class="number">9</span>);
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">dt</span>.<span class="ident">format</span>(<span class="string">"%Y-%m-%d %H:%M:%S"</span>).<span class="ident">to_string</span>(), <span class="string">"2014-11-28 12:00:09"</span>);
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">dt</span>.<span class="ident">format</span>(<span class="string">"%a %b %e %T %Y"</span>).<span class="ident">to_string</span>(), <span class="string">"Fri Nov 28 12:00:09 2014"</span>);
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">dt</span>.<span class="ident">format</span>(<span class="string">"%a %b %e %T %Y"</span>).<span class="ident">to_string</span>(), <span class="ident">dt</span>.<span class="ident">format</span>(<span class="string">"%c"</span>).<span class="ident">to_string</span>());
|
||
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">dt</span>.<span class="ident">to_string</span>(), <span class="string">"2014-11-28 12:00:09 UTC"</span>);
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">dt</span>.<span class="ident">to_rfc2822</span>(), <span class="string">"Fri, 28 Nov 2014 12:00:09 +0000"</span>);
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">dt</span>.<span class="ident">to_rfc3339</span>(), <span class="string">"2014-11-28T12:00:09+00:00"</span>);
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="macro">format</span><span class="macro">!</span>(<span class="string">"{:?}"</span>, <span class="ident">dt</span>), <span class="string">"2014-11-28T12:00:09Z"</span>);</pre>
|
||
|
||
<p>Parsing can be done with three methods:</p>
|
||
|
||
<ol>
|
||
<li><p>The standard <a href="https://doc.rust-lang.org/std/str/trait.FromStr.html"><code>FromStr</code></a> trait
|
||
(and <a href="https://doc.rust-lang.org/std/primitive.str.html#method.parse"><code>parse</code></a> method
|
||
on a string) can be used for parsing <code>DateTime<FixedOffset></code>, <code>DateTime<UTC></code> and
|
||
<code>DateTime<Local></code> values. This parses what the <code>{:?}</code>
|
||
(<a href="https://doc.rust-lang.org/std/fmt/trait.Debug.html"><code>std::fmt::Debug</code></a>)
|
||
format specifier prints, and requires the offset to be present.</p></li>
|
||
<li><p><a href="./datetime/struct.DateTime.html#method.parse_from_str"><code>DateTime::parse_from_str</code></a> parses
|
||
a date and time with offsets and returns <code>DateTime<FixedOffset></code>.
|
||
This should be used when the offset is a part of input and the caller cannot guess that.
|
||
It <em>cannot</em> be used when the offset can be missing.
|
||
<a href="./datetime/struct.DateTime.html#method.parse_from_rfc2822"><code>DateTime::parse_from_rfc2822</code></a>
|
||
and
|
||
<a href="./datetime/struct.DateTime.html#method.parse_from_rfc3339"><code>DateTime::parse_from_rfc3339</code></a>
|
||
are similar but for well-known formats.</p></li>
|
||
<li><p><a href="./offset/trait.TimeZone.html#method.datetime_from_str"><code>Offset::datetime_from_str</code></a> is
|
||
similar but returns <code>DateTime</code> of given offset.
|
||
When the explicit offset is missing from the input, it simply uses given offset.
|
||
It issues an error when the input contains an explicit offset different
|
||
from the current offset.</p></li>
|
||
</ol>
|
||
|
||
<p>More detailed control over the parsing process is available via
|
||
<a href="./format/index.html"><code>format</code></a> module.</p>
|
||
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="kw">use</span> <span class="ident">chrono</span>::<span class="kw-2">*</span>;
|
||
|
||
<span class="kw">let</span> <span class="ident">dt</span> <span class="op">=</span> <span class="ident">UTC</span>.<span class="ident">ymd</span>(<span class="number">2014</span>, <span class="number">11</span>, <span class="number">28</span>).<span class="ident">and_hms</span>(<span class="number">12</span>, <span class="number">0</span>, <span class="number">9</span>);
|
||
<span class="kw">let</span> <span class="ident">fixed_dt</span> <span class="op">=</span> <span class="ident">dt</span>.<span class="ident">with_timezone</span>(<span class="kw-2">&</span><span class="ident">FixedOffset</span>::<span class="ident">east</span>(<span class="number">9</span><span class="kw-2">*</span><span class="number">3600</span>));
|
||
|
||
<span class="comment">// method 1</span>
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="string">"2014-11-28T12:00:09Z"</span>.<span class="ident">parse</span>::<span class="op"><</span><span class="ident">DateTime</span><span class="op"><</span><span class="ident">UTC</span><span class="op">>></span>(), <span class="prelude-val">Ok</span>(<span class="ident">dt</span>.<span class="ident">clone</span>()));
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="string">"2014-11-28T21:00:09+09:00"</span>.<span class="ident">parse</span>::<span class="op"><</span><span class="ident">DateTime</span><span class="op"><</span><span class="ident">UTC</span><span class="op">>></span>(), <span class="prelude-val">Ok</span>(<span class="ident">dt</span>.<span class="ident">clone</span>()));
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="string">"2014-11-28T21:00:09+09:00"</span>.<span class="ident">parse</span>::<span class="op"><</span><span class="ident">DateTime</span><span class="op"><</span><span class="ident">FixedOffset</span><span class="op">>></span>(), <span class="prelude-val">Ok</span>(<span class="ident">fixed_dt</span>.<span class="ident">clone</span>()));
|
||
|
||
<span class="comment">// method 2</span>
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">DateTime</span>::<span class="ident">parse_from_str</span>(<span class="string">"2014-11-28 21:00:09 +09:00"</span>, <span class="string">"%Y-%m-%d %H:%M:%S %z"</span>),
|
||
<span class="prelude-val">Ok</span>(<span class="ident">fixed_dt</span>.<span class="ident">clone</span>()));
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">DateTime</span>::<span class="ident">parse_from_rfc2822</span>(<span class="string">"Fri, 28 Nov 2014 21:00:09 +0900"</span>),
|
||
<span class="prelude-val">Ok</span>(<span class="ident">fixed_dt</span>.<span class="ident">clone</span>()));
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">DateTime</span>::<span class="ident">parse_from_rfc3339</span>(<span class="string">"2014-11-28T21:00:09+09:00"</span>), <span class="prelude-val">Ok</span>(<span class="ident">fixed_dt</span>.<span class="ident">clone</span>()));
|
||
|
||
<span class="comment">// method 3</span>
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">UTC</span>.<span class="ident">datetime_from_str</span>(<span class="string">"2014-11-28 12:00:09"</span>, <span class="string">"%Y-%m-%d %H:%M:%S"</span>), <span class="prelude-val">Ok</span>(<span class="ident">dt</span>.<span class="ident">clone</span>()));
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">UTC</span>.<span class="ident">datetime_from_str</span>(<span class="string">"Fri Nov 28 12:00:09 2014"</span>, <span class="string">"%a %b %e %T %Y"</span>), <span class="prelude-val">Ok</span>(<span class="ident">dt</span>.<span class="ident">clone</span>()));
|
||
|
||
<span class="comment">// oops, the year is missing!</span>
|
||
<span class="macro">assert</span><span class="macro">!</span>(<span class="ident">UTC</span>.<span class="ident">datetime_from_str</span>(<span class="string">"Fri Nov 28 12:00:09"</span>, <span class="string">"%a %b %e %T %Y"</span>).<span class="ident">is_err</span>());
|
||
<span class="comment">// oops, the format string does not include the year at all!</span>
|
||
<span class="macro">assert</span><span class="macro">!</span>(<span class="ident">UTC</span>.<span class="ident">datetime_from_str</span>(<span class="string">"Fri Nov 28 12:00:09"</span>, <span class="string">"%a %b %e %T"</span>).<span class="ident">is_err</span>());
|
||
<span class="comment">// oops, the weekday is incorrect!</span>
|
||
<span class="macro">assert</span><span class="macro">!</span>(<span class="ident">UTC</span>.<span class="ident">datetime_from_str</span>(<span class="string">"Sat Nov 28 12:00:09 2014"</span>, <span class="string">"%a %b %e %T %Y"</span>).<span class="ident">is_err</span>());</pre>
|
||
|
||
<h3 id='individual-date' class='section-header'><a href='#individual-date'>Individual date</a></h3>
|
||
<p>Chrono also provides an individual date type (<a href="./date/struct.Date.html"><strong><code>Date</code></strong></a>).
|
||
It also has time zones attached, and have to be constructed via time zones.
|
||
Most operations available to <code>DateTime</code> are also available to <code>Date</code> whenever appropriate.</p>
|
||
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="kw">use</span> <span class="ident">chrono</span>::<span class="kw-2">*</span>;
|
||
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">UTC</span>::<span class="ident">today</span>(), <span class="ident">UTC</span>::<span class="ident">now</span>().<span class="ident">date</span>());
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">Local</span>::<span class="ident">today</span>(), <span class="ident">Local</span>::<span class="ident">now</span>().<span class="ident">date</span>());
|
||
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">UTC</span>.<span class="ident">ymd</span>(<span class="number">2014</span>, <span class="number">11</span>, <span class="number">28</span>).<span class="ident">weekday</span>(), <span class="ident">Weekday</span>::<span class="ident">Fri</span>);
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">UTC</span>.<span class="ident">ymd_opt</span>(<span class="number">2014</span>, <span class="number">11</span>, <span class="number">31</span>), <span class="ident">LocalResult</span>::<span class="prelude-val">None</span>);
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">UTC</span>.<span class="ident">ymd</span>(<span class="number">2014</span>, <span class="number">11</span>, <span class="number">28</span>).<span class="ident">and_hms_milli</span>(<span class="number">7</span>, <span class="number">8</span>, <span class="number">9</span>, <span class="number">10</span>).<span class="ident">format</span>(<span class="string">"%H%M%S"</span>).<span class="ident">to_string</span>(),
|
||
<span class="string">"070809"</span>);</pre>
|
||
|
||
<p>There is no timezone-aware <code>Time</code> due to the lack of usefulness and also the complexity.</p>
|
||
|
||
<p><code>DateTime</code> has <a href="./datetime/struct.DateTime.html#method.date"><code>date</code></a> method
|
||
which returns a <code>Date</code> which represents its date component.
|
||
There is also a <a href="./datetime/struct.DateTime.html#method.time"><code>time</code></a> method,
|
||
which simply returns a naive local time described below.</p>
|
||
|
||
<h3 id='naive-date-and-time' class='section-header'><a href='#naive-date-and-time'>Naive date and time</a></h3>
|
||
<p>Chrono provides naive counterparts to <code>Date</code>, (non-existent) <code>Time</code> and <code>DateTime</code>
|
||
as <a href="./naive/date/struct.NaiveDate.html"><strong><code>NaiveDate</code></strong></a>,
|
||
<a href="./naive/time/struct.NaiveTime.html"><strong><code>NaiveTime</code></strong></a> and
|
||
<a href="./naive/datetime/struct.NaiveDateTime.html"><strong><code>NaiveDateTime</code></strong></a> respectively.</p>
|
||
|
||
<p>They have almost equivalent interfaces as their timezone-aware twins,
|
||
but are not associated to time zones obviously and can be quite low-level.
|
||
They are mostly useful for building blocks for higher-level types.</p>
|
||
|
||
<p>Timezone-aware <code>DateTime</code> and <code>Date</code> types have two methods returning naive versions:
|
||
<a href="./datetime/struct.DateTime.html#method.naive_local"><code>naive_local</code></a> returns
|
||
a view to the naive local time,
|
||
and <a href="./datetime/struct.DateTime.html#method.naive_utc"><code>naive_utc</code></a> returns
|
||
a view to the naive UTC time.</p>
|
||
|
||
<h2 id='limitations' class='section-header'><a href='#limitations'>Limitations</a></h2>
|
||
<p>Only proleptic Gregorian calendar (i.e. extended to support older dates) is supported.
|
||
Be very careful if you really have to deal with pre-20C dates, they can be in Julian or others.</p>
|
||
|
||
<p>Date types are limited in about +/- 262,000 years from the common epoch.
|
||
Time types are limited in the nanosecond accuracy.</p>
|
||
|
||
<p><a href="./naive/time/index.html#leap-second-handling">Leap seconds are supported in the representation but
|
||
Chrono doesn't try to make use of them</a>.
|
||
(The main reason is that leap seconds are not really predictable.)
|
||
Almost <em>every</em> operation over the possible leap seconds will ignore them.
|
||
Consider using <code>NaiveDateTime</code> with the implicit TAI (International Atomic Time) scale
|
||
if you want.</p>
|
||
|
||
<p>Chrono inherently does not support an inaccurate or partial date and time representation.
|
||
Any operation that can be ambiguous will return <code>None</code> in such cases.
|
||
For example, "a month later" of 2014-01-30 is not well-defined
|
||
and consequently <code>UTC.ymd(2014, 1, 30).with_month(2)</code> returns <code>None</code>.</p>
|
||
|
||
<p>Advanced time zone handling is not yet supported (but is planned in 0.3).</p>
|
||
</div><h2 id='reexports' class='section-header'><a href="#reexports">Reexports</a></h2>
|
||
<table><tr><td><code>pub use offset::<a class="trait" href="../chrono/offset/trait.TimeZone.html" title="trait chrono::offset::TimeZone">TimeZone</a>;</code></td></tr><tr><td><code>pub use offset::<a class="trait" href="../chrono/offset/trait.Offset.html" title="trait chrono::offset::Offset">Offset</a>;</code></td></tr><tr><td><code>pub use offset::<a class="enum" href="../chrono/offset/enum.LocalResult.html" title="enum chrono::offset::LocalResult">LocalResult</a>;</code></td></tr><tr><td><code>pub use offset::utc::<a class="struct" href="../chrono/offset/utc/struct.UTC.html" title="struct chrono::offset::utc::UTC">UTC</a>;</code></td></tr><tr><td><code>pub use offset::fixed::<a class="struct" href="../chrono/offset/fixed/struct.FixedOffset.html" title="struct chrono::offset::fixed::FixedOffset">FixedOffset</a>;</code></td></tr><tr><td><code>pub use offset::local::<a class="struct" href="../chrono/offset/local/struct.Local.html" title="struct chrono::offset::local::Local">Local</a>;</code></td></tr><tr><td><code>pub use naive::date::<a class="struct" href="../chrono/naive/date/struct.NaiveDate.html" title="struct chrono::naive::date::NaiveDate">NaiveDate</a>;</code></td></tr><tr><td><code>pub use naive::time::<a class="struct" href="../chrono/naive/time/struct.NaiveTime.html" title="struct chrono::naive::time::NaiveTime">NaiveTime</a>;</code></td></tr><tr><td><code>pub use naive::datetime::<a class="struct" href="../chrono/naive/datetime/struct.NaiveDateTime.html" title="struct chrono::naive::datetime::NaiveDateTime">NaiveDateTime</a>;</code></td></tr><tr><td><code>pub use date::<a class="struct" href="../chrono/date/struct.Date.html" title="struct chrono::date::Date">Date</a>;</code></td></tr><tr><td><code>pub use datetime::<a class="struct" href="../chrono/datetime/struct.DateTime.html" title="struct chrono::datetime::DateTime">DateTime</a>;</code></td></tr><tr><td><code>pub use format::<a class="struct" href="../chrono/format/struct.ParseError.html" title="struct chrono::format::ParseError">ParseError</a>;</code></td></tr><tr><td><code>pub use format::<a class="type" href="../chrono/format/type.ParseResult.html" title="type chrono::format::ParseResult">ParseResult</a>;</code></td></tr></table><h2 id='modules' class='section-header'><a href="#modules">Modules</a></h2>
|
||
<table>
|
||
<tr class=' module-item'>
|
||
<td><a class="mod" href="date/index.html"
|
||
title='mod chrono::date'>date</a></td>
|
||
<td class='docblock-short'>
|
||
<p>ISO 8601 calendar date with time zone.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="mod" href="datetime/index.html"
|
||
title='mod chrono::datetime'>datetime</a></td>
|
||
<td class='docblock-short'>
|
||
<p>ISO 8601 date and time with time zone.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="mod" href="duration/index.html"
|
||
title='mod chrono::duration'>duration</a></td>
|
||
<td class='docblock-short'>
|
||
<p>ISO 8601 duration.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="mod" href="format/index.html"
|
||
title='mod chrono::format'>format</a></td>
|
||
<td class='docblock-short'>
|
||
<p>Formatting utilities for date and time.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="mod" href="naive/index.html"
|
||
title='mod chrono::naive'>naive</a></td>
|
||
<td class='docblock-short'>
|
||
<p>Date and time types which do not concern about the timezones.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="mod" href="offset/index.html"
|
||
title='mod chrono::offset'>offset</a></td>
|
||
<td class='docblock-short'>
|
||
<p>The time zone, which calculates offsets from the local time to UTC.</p>
|
||
</td>
|
||
</tr></table><h2 id='structs' class='section-header'><a href="#structs">Structs</a></h2>
|
||
<table>
|
||
<tr class=' module-item'>
|
||
<td><a class="struct" href="struct.Duration.html"
|
||
title='struct chrono::Duration'>Duration</a></td>
|
||
<td class='docblock-short'>
|
||
<p>ISO 8601 time duration with nanosecond precision.
|
||
This also allows for the negative duration; see individual methods for details.</p>
|
||
</td>
|
||
</tr></table><h2 id='enums' class='section-header'><a href="#enums">Enums</a></h2>
|
||
<table>
|
||
<tr class=' module-item'>
|
||
<td><a class="enum" href="enum.Weekday.html"
|
||
title='enum chrono::Weekday'>Weekday</a></td>
|
||
<td class='docblock-short'>
|
||
<p>The day of week.</p>
|
||
</td>
|
||
</tr></table><h2 id='traits' class='section-header'><a href="#traits">Traits</a></h2>
|
||
<table>
|
||
<tr class=' module-item'>
|
||
<td><a class="trait" href="trait.Datelike.html"
|
||
title='trait chrono::Datelike'>Datelike</a></td>
|
||
<td class='docblock-short'>
|
||
<p>The common set of methods for date component.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="trait" href="trait.Timelike.html"
|
||
title='trait chrono::Timelike'>Timelike</a></td>
|
||
<td class='docblock-short'>
|
||
<p>The common set of methods for time component.</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>?</dt>
|
||
<dd>Show this help dialog</dd>
|
||
<dt>S</dt>
|
||
<dd>Focus the search field</dd>
|
||
<dt>⇤</dt>
|
||
<dd>Move up in search results</dd>
|
||
<dt>⇥</dt>
|
||
<dd>Move down in search results</dd>
|
||
<dt>⏎</dt>
|
||
<dd>Go to active search result</dd>
|
||
<dt>+</dt>
|
||
<dd>Collapse/expand 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> |