1 | //! # Chrono: Date and Time for Rust |
2 | //! |
3 | //! It aims to be a feature-complete superset of |
4 | //! the [time](https://github.com/rust-lang-deprecated/time) library. |
5 | //! In particular, |
6 | //! |
7 | //! * Chrono strictly adheres to ISO 8601. |
8 | //! * Chrono is timezone-aware by default, with separate timezone-naive types. |
9 | //! * Chrono is space-optimal and (while not being the primary goal) reasonably efficient. |
10 | //! |
11 | //! There were several previous attempts to bring a good date and time library to Rust, |
12 | //! which Chrono builds upon and should acknowledge: |
13 | //! |
14 | //! * [Initial research on |
15 | //! the wiki](https://github.com/rust-lang/rust-wiki-backup/blob/master/Lib-datetime.md) |
16 | //! * Dietrich Epp's [datetime-rs](https://github.com/depp/datetime-rs) |
17 | //! * Luis de Bethencourt's [rust-datetime](https://github.com/luisbg/rust-datetime) |
18 | //! |
19 | //! ### Features |
20 | //! |
21 | //! Chrono supports various runtime environments and operating systems, and has |
22 | //! several features that may be enabled or disabled. |
23 | //! |
24 | //! Default features: |
25 | //! |
26 | //! - `alloc`: Enable features that depend on allocation (primarily string formatting) |
27 | //! - `std`: Enables functionality that depends on the standard library. This |
28 | //! is a superset of `alloc` and adds interoperation with standard library types |
29 | //! and traits. |
30 | //! - `clock`: Enables reading the system time (`now`) that depends on the standard library for |
31 | //! UNIX-like operating systems and the Windows API (`winapi`) for Windows. |
32 | //! |
33 | //! Optional features: |
34 | //! |
35 | //! - [`serde`][]: Enable serialization/deserialization via serde. |
36 | //! - `unstable-locales`: Enable localization. This adds various methods with a |
37 | //! `_localized` suffix. The implementation and API may change or even be |
38 | //! removed in a patch release. Feedback welcome. |
39 | //! |
40 | //! [`serde`]: https://github.com/serde-rs/serde |
41 | //! [wasm-bindgen]: https://github.com/rustwasm/wasm-bindgen |
42 | //! |
43 | //! See the [cargo docs][] for examples of specifying features. |
44 | //! |
45 | //! [cargo docs]: https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#choosing-features |
46 | //! |
47 | //! ## Overview |
48 | //! |
49 | //! ### Duration |
50 | //! |
51 | //! Chrono currently uses its own [`Duration`] type to represent the magnitude |
52 | //! of a time span. Since this has the same name as the newer, standard type for |
53 | //! duration, the reference will refer this type as `OldDuration`. |
54 | //! |
55 | //! Note that this is an "accurate" duration represented as seconds and |
56 | //! nanoseconds and does not represent "nominal" components such as days or |
57 | //! months. |
58 | //! |
59 | //! When the `oldtime` feature is enabled, [`Duration`] is an alias for the |
60 | //! [`time::Duration`](https://docs.rs/time/0.1.40/time/struct.Duration.html) |
61 | //! type from v0.1 of the time crate. time v0.1 is deprecated, so new code |
62 | //! should disable the `oldtime` feature and use the `chrono::Duration` type |
63 | //! instead. The `oldtime` feature is enabled by default for backwards |
64 | //! compatibility, but future versions of Chrono are likely to remove the |
65 | //! feature entirely. |
66 | //! |
67 | //! Chrono does not yet natively support |
68 | //! the standard [`Duration`](https://doc.rust-lang.org/std/time/struct.Duration.html) type, |
69 | //! but it will be supported in the future. |
70 | //! Meanwhile you can convert between two types with |
71 | //! [`Duration::from_std`](https://docs.rs/time/0.1.40/time/struct.Duration.html#method.from_std) |
72 | //! and |
73 | //! [`Duration::to_std`](https://docs.rs/time/0.1.40/time/struct.Duration.html#method.to_std) |
74 | //! methods. |
75 | //! |
76 | //! ### Date and Time |
77 | //! |
78 | //! Chrono provides a |
79 | //! [**`DateTime`**](./struct.DateTime.html) |
80 | //! type to represent a date and a time in a timezone. |
81 | //! |
82 | //! For more abstract moment-in-time tracking such as internal timekeeping |
83 | //! that is unconcerned with timezones, consider |
84 | //! [`time::SystemTime`](https://doc.rust-lang.org/std/time/struct.SystemTime.html), |
85 | //! which tracks your system clock, or |
86 | //! [`time::Instant`](https://doc.rust-lang.org/std/time/struct.Instant.html), which |
87 | //! is an opaque but monotonically-increasing representation of a moment in time. |
88 | //! |
89 | //! `DateTime` is timezone-aware and must be constructed from |
90 | //! the [**`TimeZone`**](./offset/trait.TimeZone.html) object, |
91 | //! which defines how the local date is converted to and back from the UTC date. |
92 | //! There are three well-known `TimeZone` implementations: |
93 | //! |
94 | //! * [**`Utc`**](./offset/struct.Utc.html) specifies the UTC time zone. It is most efficient. |
95 | //! |
96 | //! * [**`Local`**](./offset/struct.Local.html) specifies the system local time zone. |
97 | //! |
98 | //! * [**`FixedOffset`**](./offset/struct.FixedOffset.html) specifies |
99 | //! an arbitrary, fixed time zone such as UTC+09:00 or UTC-10:30. |
100 | //! This often results from the parsed textual date and time. |
101 | //! Since it stores the most information and does not depend on the system environment, |
102 | //! you would want to normalize other `TimeZone`s into this type. |
103 | //! |
104 | //! `DateTime`s with different `TimeZone` types are distinct and do not mix, |
105 | //! but can be converted to each other using |
106 | //! the [`DateTime::with_timezone`](./struct.DateTime.html#method.with_timezone) method. |
107 | //! |
108 | //! You can get the current date and time in the UTC time zone |
109 | //! ([`Utc::now()`](./offset/struct.Utc.html#method.now)) |
110 | //! or in the local time zone |
111 | //! ([`Local::now()`](./offset/struct.Local.html#method.now)). |
112 | //! |
113 | #![cfg_attr (not(feature = "clock" ), doc = "```ignore" )] |
114 | #![cfg_attr (feature = "clock" , doc = "```rust" )] |
115 | //! use chrono::prelude::*; |
116 | //! |
117 | //! let utc: DateTime<Utc> = Utc::now(); // e.g. `2014-11-28T12:45:59.324310806Z` |
118 | //! let local: DateTime<Local> = Local::now(); // e.g. `2014-11-28T21:45:59.324310806+09:00` |
119 | //! # let _ = utc; let _ = local; |
120 | //! ``` |
121 | //! |
122 | //! Alternatively, you can create your own date and time. |
123 | //! This is a bit verbose due to Rust's lack of function and method overloading, |
124 | //! but in turn we get a rich combination of initialization methods. |
125 | //! |
126 | #![cfg_attr (not(feature = "std" ), doc = "```ignore" )] |
127 | #![cfg_attr (feature = "std" , doc = "```rust" )] |
128 | //! use chrono::prelude::*; |
129 | //! use chrono::offset::LocalResult; |
130 | //! |
131 | //! # fn doctest() -> Option<()> { |
132 | //! |
133 | //! let dt = Utc.with_ymd_and_hms(2014, 7, 8, 9, 10, 11).unwrap(); // `2014-07-08T09:10:11Z` |
134 | //! assert_eq!(dt, NaiveDate::from_ymd_opt(2014, 7, 8)?.and_hms_opt(9, 10, 11)?.and_local_timezone(Utc).unwrap()); |
135 | //! |
136 | //! // July 8 is 188th day of the year 2014 (`o` for "ordinal") |
137 | //! assert_eq!(dt, NaiveDate::from_yo_opt(2014, 189)?.and_hms_opt(9, 10, 11)?.and_utc()); |
138 | //! // July 8 is Tuesday in ISO week 28 of the year 2014. |
139 | //! assert_eq!(dt, NaiveDate::from_isoywd_opt(2014, 28, Weekday::Tue)?.and_hms_opt(9, 10, 11)?.and_utc()); |
140 | //! |
141 | //! let dt = NaiveDate::from_ymd_opt(2014, 7, 8)?.and_hms_milli_opt(9, 10, 11, 12)?.and_local_timezone(Utc).unwrap(); // `2014-07-08T09:10:11.012Z` |
142 | //! assert_eq!(dt, NaiveDate::from_ymd_opt(2014, 7, 8)?.and_hms_micro_opt(9, 10, 11, 12_000)?.and_local_timezone(Utc).unwrap()); |
143 | //! assert_eq!(dt, NaiveDate::from_ymd_opt(2014, 7, 8)?.and_hms_nano_opt(9, 10, 11, 12_000_000)?.and_local_timezone(Utc).unwrap()); |
144 | //! |
145 | //! // dynamic verification |
146 | //! assert_eq!(Utc.with_ymd_and_hms(2014, 7, 8, 21, 15, 33), |
147 | //! LocalResult::Single(NaiveDate::from_ymd_opt(2014, 7, 8)?.and_hms_opt(21, 15, 33)?.and_utc())); |
148 | //! assert_eq!(Utc.with_ymd_and_hms(2014, 7, 8, 80, 15, 33), LocalResult::None); |
149 | //! assert_eq!(Utc.with_ymd_and_hms(2014, 7, 38, 21, 15, 33), LocalResult::None); |
150 | //! |
151 | //! // other time zone objects can be used to construct a local datetime. |
152 | //! // obviously, `local_dt` is normally different from `dt`, but `fixed_dt` should be identical. |
153 | //! let local_dt = Local.from_local_datetime(&NaiveDate::from_ymd_opt(2014, 7, 8).unwrap().and_hms_milli_opt(9, 10, 11, 12).unwrap()).unwrap(); |
154 | //! let fixed_dt = FixedOffset::east_opt(9 * 3600).unwrap().from_local_datetime(&NaiveDate::from_ymd_opt(2014, 7, 8).unwrap().and_hms_milli_opt(18, 10, 11, 12).unwrap()).unwrap(); |
155 | //! assert_eq!(dt, fixed_dt); |
156 | //! # let _ = local_dt; |
157 | //! # Some(()) |
158 | //! # } |
159 | //! # doctest().unwrap(); |
160 | //! ``` |
161 | //! |
162 | //! Various properties are available to the date and time, and can be altered individually. |
163 | //! Most of them are defined in the traits [`Datelike`](./trait.Datelike.html) and |
164 | //! [`Timelike`](./trait.Timelike.html) which you should `use` before. |
165 | //! Addition and subtraction is also supported. |
166 | //! The following illustrates most supported operations to the date and time: |
167 | //! |
168 | //! ```rust |
169 | //! use chrono::prelude::*; |
170 | //! use chrono::Duration; |
171 | //! |
172 | //! // assume this returned `2014-11-28T21:45:59.324310806+09:00`: |
173 | //! let dt = FixedOffset::east_opt(9*3600).unwrap().from_local_datetime(&NaiveDate::from_ymd_opt(2014, 11, 28).unwrap().and_hms_nano_opt(21, 45, 59, 324310806).unwrap()).unwrap(); |
174 | //! |
175 | //! // property accessors |
176 | //! assert_eq!((dt.year(), dt.month(), dt.day()), (2014, 11, 28)); |
177 | //! assert_eq!((dt.month0(), dt.day0()), (10, 27)); // for unfortunate souls |
178 | //! assert_eq!((dt.hour(), dt.minute(), dt.second()), (21, 45, 59)); |
179 | //! assert_eq!(dt.weekday(), Weekday::Fri); |
180 | //! assert_eq!(dt.weekday().number_from_monday(), 5); // Mon=1, ..., Sun=7 |
181 | //! assert_eq!(dt.ordinal(), 332); // the day of year |
182 | //! assert_eq!(dt.num_days_from_ce(), 735565); // the number of days from and including Jan 1, 1 |
183 | //! |
184 | //! // time zone accessor and manipulation |
185 | //! assert_eq!(dt.offset().fix().local_minus_utc(), 9 * 3600); |
186 | //! assert_eq!(dt.timezone(), FixedOffset::east_opt(9 * 3600).unwrap()); |
187 | //! assert_eq!(dt.with_timezone(&Utc), NaiveDate::from_ymd_opt(2014, 11, 28).unwrap().and_hms_nano_opt(12, 45, 59, 324310806).unwrap().and_local_timezone(Utc).unwrap()); |
188 | //! |
189 | //! // a sample of property manipulations (validates dynamically) |
190 | //! assert_eq!(dt.with_day(29).unwrap().weekday(), Weekday::Sat); // 2014-11-29 is Saturday |
191 | //! assert_eq!(dt.with_day(32), None); |
192 | //! assert_eq!(dt.with_year(-300).unwrap().num_days_from_ce(), -109606); // November 29, 301 BCE |
193 | //! |
194 | //! // arithmetic operations |
195 | //! let dt1 = Utc.with_ymd_and_hms(2014, 11, 14, 8, 9, 10).unwrap(); |
196 | //! let dt2 = Utc.with_ymd_and_hms(2014, 11, 14, 10, 9, 8).unwrap(); |
197 | //! assert_eq!(dt1.signed_duration_since(dt2), Duration::seconds(-2 * 3600 + 2)); |
198 | //! assert_eq!(dt2.signed_duration_since(dt1), Duration::seconds(2 * 3600 - 2)); |
199 | //! assert_eq!(Utc.with_ymd_and_hms(1970, 1, 1, 0, 0, 0).unwrap() + Duration::seconds(1_000_000_000), |
200 | //! Utc.with_ymd_and_hms(2001, 9, 9, 1, 46, 40).unwrap()); |
201 | //! assert_eq!(Utc.with_ymd_and_hms(1970, 1, 1, 0, 0, 0).unwrap() - Duration::seconds(1_000_000_000), |
202 | //! Utc.with_ymd_and_hms(1938, 4, 24, 22, 13, 20).unwrap()); |
203 | //! ``` |
204 | //! |
205 | //! ### Formatting and Parsing |
206 | //! |
207 | //! Formatting is done via the [`format`](./struct.DateTime.html#method.format) method, |
208 | //! which format is equivalent to the familiar `strftime` format. |
209 | //! |
210 | //! See [`format::strftime`](./format/strftime/index.html#specifiers) |
211 | //! documentation for full syntax and list of specifiers. |
212 | //! |
213 | //! The default `to_string` method and `{:?}` specifier also give a reasonable representation. |
214 | //! Chrono also provides [`to_rfc2822`](./struct.DateTime.html#method.to_rfc2822) and |
215 | //! [`to_rfc3339`](./struct.DateTime.html#method.to_rfc3339) methods |
216 | //! for well-known formats. |
217 | //! |
218 | //! Chrono now also provides date formatting in almost any language without the |
219 | //! help of an additional C library. This functionality is under the feature |
220 | //! `unstable-locales`: |
221 | //! |
222 | //! ```toml |
223 | //! chrono = { version = "0.4", features = ["unstable-locales"] } |
224 | //! ``` |
225 | //! |
226 | //! The `unstable-locales` feature requires and implies at least the `alloc` feature. |
227 | //! |
228 | //! ```rust |
229 | //! # #[allow (unused_imports)] |
230 | //! use chrono::prelude::*; |
231 | //! |
232 | //! # #[cfg (feature = "unstable-locales" )] |
233 | //! # fn test() { |
234 | //! let dt = Utc.with_ymd_and_hms(2014, 11, 28, 12, 0, 9).unwrap(); |
235 | //! assert_eq!(dt.format("%Y-%m-%d %H:%M:%S" ).to_string(), "2014-11-28 12:00:09" ); |
236 | //! assert_eq!(dt.format("%a %b %e %T %Y" ).to_string(), "Fri Nov 28 12:00:09 2014" ); |
237 | //! assert_eq!(dt.format_localized("%A %e %B %Y, %T" , Locale::fr_BE).to_string(), "vendredi 28 novembre 2014, 12:00:09" ); |
238 | //! |
239 | //! assert_eq!(dt.format("%a %b %e %T %Y" ).to_string(), dt.format("%c" ).to_string()); |
240 | //! assert_eq!(dt.to_string(), "2014-11-28 12:00:09 UTC" ); |
241 | //! assert_eq!(dt.to_rfc2822(), "Fri, 28 Nov 2014 12:00:09 +0000" ); |
242 | //! assert_eq!(dt.to_rfc3339(), "2014-11-28T12:00:09+00:00" ); |
243 | //! assert_eq!(format!("{:?}" , dt), "2014-11-28T12:00:09Z" ); |
244 | //! |
245 | //! // Note that milli/nanoseconds are only printed if they are non-zero |
246 | //! let dt_nano = NaiveDate::from_ymd_opt(2014, 11, 28).unwrap().and_hms_nano_opt(12, 0, 9, 1).unwrap().and_local_timezone(Utc).unwrap(); |
247 | //! assert_eq!(format!("{:?}" , dt_nano), "2014-11-28T12:00:09.000000001Z" ); |
248 | //! # } |
249 | //! # #[cfg (not(feature = "unstable-locales" ))] |
250 | //! # fn test() {} |
251 | //! # if cfg!(feature = "unstable-locales" ) { |
252 | //! # test(); |
253 | //! # } |
254 | //! ``` |
255 | //! |
256 | //! Parsing can be done with three methods: |
257 | //! |
258 | //! 1. The standard [`FromStr`](https://doc.rust-lang.org/std/str/trait.FromStr.html) trait |
259 | //! (and [`parse`](https://doc.rust-lang.org/std/primitive.str.html#method.parse) method |
260 | //! on a string) can be used for parsing `DateTime<FixedOffset>`, `DateTime<Utc>` and |
261 | //! `DateTime<Local>` values. This parses what the `{:?}` |
262 | //! ([`std::fmt::Debug`](https://doc.rust-lang.org/std/fmt/trait.Debug.html)) |
263 | //! format specifier prints, and requires the offset to be present. |
264 | //! |
265 | //! 2. [`DateTime::parse_from_str`](./struct.DateTime.html#method.parse_from_str) parses |
266 | //! a date and time with offsets and returns `DateTime<FixedOffset>`. |
267 | //! This should be used when the offset is a part of input and the caller cannot guess that. |
268 | //! It *cannot* be used when the offset can be missing. |
269 | //! [`DateTime::parse_from_rfc2822`](./struct.DateTime.html#method.parse_from_rfc2822) |
270 | //! and |
271 | //! [`DateTime::parse_from_rfc3339`](./struct.DateTime.html#method.parse_from_rfc3339) |
272 | //! are similar but for well-known formats. |
273 | //! |
274 | //! 3. [`Offset::datetime_from_str`](./offset/trait.TimeZone.html#method.datetime_from_str) is |
275 | //! similar but returns `DateTime` of given offset. |
276 | //! When the explicit offset is missing from the input, it simply uses given offset. |
277 | //! It issues an error when the input contains an explicit offset different |
278 | //! from the current offset. |
279 | //! |
280 | //! More detailed control over the parsing process is available via |
281 | //! [`format`](./format/index.html) module. |
282 | //! |
283 | //! ```rust |
284 | //! use chrono::prelude::*; |
285 | //! |
286 | //! let dt = Utc.with_ymd_and_hms(2014, 11, 28, 12, 0, 9).unwrap(); |
287 | //! let fixed_dt = dt.with_timezone(&FixedOffset::east_opt(9*3600).unwrap()); |
288 | //! |
289 | //! // method 1 |
290 | //! assert_eq!("2014-11-28T12:00:09Z" .parse::<DateTime<Utc>>(), Ok(dt.clone())); |
291 | //! assert_eq!("2014-11-28T21:00:09+09:00" .parse::<DateTime<Utc>>(), Ok(dt.clone())); |
292 | //! assert_eq!("2014-11-28T21:00:09+09:00" .parse::<DateTime<FixedOffset>>(), Ok(fixed_dt.clone())); |
293 | //! |
294 | //! // method 2 |
295 | //! assert_eq!(DateTime::parse_from_str("2014-11-28 21:00:09 +09:00" , "%Y-%m-%d %H:%M:%S %z" ), |
296 | //! Ok(fixed_dt.clone())); |
297 | //! assert_eq!(DateTime::parse_from_rfc2822("Fri, 28 Nov 2014 21:00:09 +0900" ), |
298 | //! Ok(fixed_dt.clone())); |
299 | //! assert_eq!(DateTime::parse_from_rfc3339("2014-11-28T21:00:09+09:00" ), Ok(fixed_dt.clone())); |
300 | //! |
301 | //! // method 3 |
302 | //! assert_eq!(Utc.datetime_from_str("2014-11-28 12:00:09" , "%Y-%m-%d %H:%M:%S" ), Ok(dt.clone())); |
303 | //! assert_eq!(Utc.datetime_from_str("Fri Nov 28 12:00:09 2014" , "%a %b %e %T %Y" ), Ok(dt.clone())); |
304 | //! |
305 | //! // oops, the year is missing! |
306 | //! assert!(Utc.datetime_from_str("Fri Nov 28 12:00:09" , "%a %b %e %T %Y" ).is_err()); |
307 | //! // oops, the format string does not include the year at all! |
308 | //! assert!(Utc.datetime_from_str("Fri Nov 28 12:00:09" , "%a %b %e %T" ).is_err()); |
309 | //! // oops, the weekday is incorrect! |
310 | //! assert!(Utc.datetime_from_str("Sat Nov 28 12:00:09 2014" , "%a %b %e %T %Y" ).is_err()); |
311 | //! ``` |
312 | //! |
313 | //! Again : See [`format::strftime`](./format/strftime/index.html#specifiers) |
314 | //! documentation for full syntax and list of specifiers. |
315 | //! |
316 | //! ### Conversion from and to EPOCH timestamps |
317 | //! |
318 | //! Use [`Utc.timestamp(seconds, nanoseconds)`](./offset/trait.TimeZone.html#method.timestamp) |
319 | //! to construct a [`DateTime<Utc>`](./struct.DateTime.html) from a UNIX timestamp |
320 | //! (seconds, nanoseconds that passed since January 1st 1970). |
321 | //! |
322 | //! Use [`DateTime.timestamp`](./struct.DateTime.html#method.timestamp) to get the timestamp (in seconds) |
323 | //! from a [`DateTime`](./struct.DateTime.html). Additionally, you can use |
324 | //! [`DateTime.timestamp_subsec_nanos`](./struct.DateTime.html#method.timestamp_subsec_nanos) |
325 | //! to get the number of additional number of nanoseconds. |
326 | //! |
327 | #![cfg_attr (not(feature = "std" ), doc = "```ignore" )] |
328 | #![cfg_attr (feature = "std" , doc = "```rust" )] |
329 | //! // We need the trait in scope to use Utc::timestamp(). |
330 | //! use chrono::{DateTime, TimeZone, Utc}; |
331 | //! |
332 | //! // Construct a datetime from epoch: |
333 | //! let dt = Utc.timestamp_opt(1_500_000_000, 0).unwrap(); |
334 | //! assert_eq!(dt.to_rfc2822(), "Fri, 14 Jul 2017 02:40:00 +0000" ); |
335 | //! |
336 | //! // Get epoch value from a datetime: |
337 | //! let dt = DateTime::parse_from_rfc2822("Fri, 14 Jul 2017 02:40:00 +0000" ).unwrap(); |
338 | //! assert_eq!(dt.timestamp(), 1_500_000_000); |
339 | //! ``` |
340 | //! |
341 | //! ### Naive date and time |
342 | //! |
343 | //! Chrono provides naive counterparts to `Date`, (non-existent) `Time` and `DateTime` |
344 | //! as [**`NaiveDate`**](./naive/struct.NaiveDate.html), |
345 | //! [**`NaiveTime`**](./naive/struct.NaiveTime.html) and |
346 | //! [**`NaiveDateTime`**](./naive/struct.NaiveDateTime.html) respectively. |
347 | //! |
348 | //! They have almost equivalent interfaces as their timezone-aware twins, |
349 | //! but are not associated to time zones obviously and can be quite low-level. |
350 | //! They are mostly useful for building blocks for higher-level types. |
351 | //! |
352 | //! Timezone-aware `DateTime` and `Date` types have two methods returning naive versions: |
353 | //! [`naive_local`](./struct.DateTime.html#method.naive_local) returns |
354 | //! a view to the naive local time, |
355 | //! and [`naive_utc`](./struct.DateTime.html#method.naive_utc) returns |
356 | //! a view to the naive UTC time. |
357 | //! |
358 | //! ## Limitations |
359 | //! |
360 | //! Only proleptic Gregorian calendar (i.e. extended to support older dates) is supported. |
361 | //! Be very careful if you really have to deal with pre-20C dates, they can be in Julian or others. |
362 | //! |
363 | //! Date types are limited in about +/- 262,000 years from the common epoch. |
364 | //! Time types are limited in the nanosecond accuracy. |
365 | //! |
366 | //! [Leap seconds are supported in the representation but |
367 | //! Chrono doesn't try to make use of them](./naive/struct.NaiveTime.html#leap-second-handling). |
368 | //! (The main reason is that leap seconds are not really predictable.) |
369 | //! Almost *every* operation over the possible leap seconds will ignore them. |
370 | //! Consider using `NaiveDateTime` with the implicit TAI (International Atomic Time) scale |
371 | //! if you want. |
372 | //! |
373 | //! Chrono inherently does not support an inaccurate or partial date and time representation. |
374 | //! Any operation that can be ambiguous will return `None` in such cases. |
375 | //! For example, "a month later" of 2014-01-30 is not well-defined |
376 | //! and consequently `Utc.ymd_opt(2014, 1, 30).unwrap().with_month(2)` returns `None`. |
377 | //! |
378 | //! Non ISO week handling is not yet supported. |
379 | //! For now you can use the [chrono_ext](https://crates.io/crates/chrono_ext) |
380 | //! crate ([sources](https://github.com/bcourtine/chrono-ext/)). |
381 | //! |
382 | //! Advanced time zone handling is not yet supported. |
383 | //! For now you can try the [Chrono-tz](https://github.com/chronotope/chrono-tz/) crate instead. |
384 | |
385 | #![doc (html_root_url = "https://docs.rs/chrono/latest/" , test(attr(deny(warnings))))] |
386 | #![cfg_attr (feature = "bench" , feature(test))] // lib stability features as per RFC #507 |
387 | #![deny (missing_docs)] |
388 | #![deny (missing_debug_implementations)] |
389 | #![warn (unreachable_pub)] |
390 | #![deny (dead_code)] |
391 | #![cfg_attr (not(any(feature = "std" , test)), no_std)] |
392 | // can remove this if/when rustc-serialize support is removed |
393 | // keeps clippy happy in the meantime |
394 | #![cfg_attr (feature = "rustc-serialize" , allow(deprecated))] |
395 | #![cfg_attr (docsrs, feature(doc_cfg))] |
396 | |
397 | #[cfg (feature = "oldtime" )] |
398 | #[cfg_attr (docsrs, doc(cfg(feature = "oldtime" )))] |
399 | extern crate time as oldtime; |
400 | #[cfg (not(feature = "oldtime" ))] |
401 | mod oldtime; |
402 | // this reexport is to aid the transition and should not be in the prelude! |
403 | pub use oldtime::{Duration, OutOfRangeError}; |
404 | |
405 | use core::fmt; |
406 | |
407 | #[cfg (feature = "__doctest" )] |
408 | #[cfg_attr (feature = "__doctest" , cfg(doctest))] |
409 | use doc_comment::doctest; |
410 | |
411 | #[cfg (feature = "__doctest" )] |
412 | #[cfg_attr (feature = "__doctest" , cfg(doctest))] |
413 | doctest!("../README.md" ); |
414 | |
415 | /// A convenience module appropriate for glob imports (`use chrono::prelude::*;`). |
416 | pub mod prelude { |
417 | #[doc (no_inline)] |
418 | #[allow (deprecated)] |
419 | pub use crate::Date; |
420 | #[cfg (feature = "clock" )] |
421 | #[cfg_attr (docsrs, doc(cfg(feature = "clock" )))] |
422 | #[doc (no_inline)] |
423 | pub use crate::Local; |
424 | #[cfg (feature = "unstable-locales" )] |
425 | #[cfg_attr (docsrs, doc(cfg(feature = "unstable-locales" )))] |
426 | #[doc (no_inline)] |
427 | pub use crate::Locale; |
428 | #[doc (no_inline)] |
429 | pub use crate::SubsecRound; |
430 | #[doc (no_inline)] |
431 | pub use crate::{DateTime, SecondsFormat}; |
432 | #[doc (no_inline)] |
433 | pub use crate::{Datelike, Month, Timelike, Weekday}; |
434 | #[doc (no_inline)] |
435 | pub use crate::{FixedOffset, Utc}; |
436 | #[doc (no_inline)] |
437 | pub use crate::{NaiveDate, NaiveDateTime, NaiveTime}; |
438 | #[doc (no_inline)] |
439 | pub use crate::{Offset, TimeZone}; |
440 | } |
441 | |
442 | mod date; |
443 | #[allow (deprecated)] |
444 | pub use date::{Date, MAX_DATE, MIN_DATE}; |
445 | |
446 | mod datetime; |
447 | #[cfg (feature = "rustc-serialize" )] |
448 | #[cfg_attr (docsrs, doc(cfg(feature = "rustc-serialize" )))] |
449 | pub use datetime::rustc_serialize::TsSeconds; |
450 | #[allow (deprecated)] |
451 | pub use datetime::{DateTime, SecondsFormat, MAX_DATETIME, MIN_DATETIME}; |
452 | |
453 | pub mod format; |
454 | /// L10n locales. |
455 | #[cfg (feature = "unstable-locales" )] |
456 | #[cfg_attr (docsrs, doc(cfg(feature = "unstable-locales" )))] |
457 | pub use format::Locale; |
458 | pub use format::{ParseError, ParseResult}; |
459 | |
460 | pub mod naive; |
461 | #[doc (no_inline)] |
462 | pub use naive::{Days, IsoWeek, NaiveDate, NaiveDateTime, NaiveTime, NaiveWeek}; |
463 | |
464 | pub mod offset; |
465 | #[cfg (feature = "clock" )] |
466 | #[cfg_attr (docsrs, doc(cfg(feature = "clock" )))] |
467 | #[doc (no_inline)] |
468 | pub use offset::Local; |
469 | #[doc (no_inline)] |
470 | pub use offset::{FixedOffset, LocalResult, Offset, TimeZone, Utc}; |
471 | |
472 | mod round; |
473 | pub use round::{DurationRound, RoundingError, SubsecRound}; |
474 | |
475 | mod weekday; |
476 | pub use weekday::{ParseWeekdayError, Weekday}; |
477 | |
478 | mod month; |
479 | pub use month::{Month, Months, ParseMonthError}; |
480 | |
481 | mod traits; |
482 | pub use traits::{Datelike, Timelike}; |
483 | |
484 | #[cfg (feature = "__internal_bench" )] |
485 | #[doc (hidden)] |
486 | pub use naive::__BenchYearFlags; |
487 | |
488 | /// Serialization/Deserialization with serde. |
489 | /// |
490 | /// This module provides default implementations for `DateTime` using the [RFC 3339][1] format and various |
491 | /// alternatives for use with serde's [`with` annotation][2]. |
492 | /// |
493 | /// *Available on crate feature 'serde' only.* |
494 | /// |
495 | /// [1]: https://tools.ietf.org/html/rfc3339 |
496 | /// [2]: https://serde.rs/field-attrs.html#with |
497 | #[cfg (feature = "serde" )] |
498 | #[cfg_attr (docsrs, doc(cfg(feature = "serde" )))] |
499 | pub mod serde { |
500 | pub use super::datetime::serde::*; |
501 | } |
502 | |
503 | /// Out of range error type used in various converting APIs |
504 | #[derive (Clone, Copy, Hash, PartialEq, Eq)] |
505 | pub struct OutOfRange { |
506 | _private: (), |
507 | } |
508 | |
509 | impl OutOfRange { |
510 | const fn new() -> OutOfRange { |
511 | OutOfRange { _private: () } |
512 | } |
513 | } |
514 | |
515 | impl fmt::Display for OutOfRange { |
516 | fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { |
517 | write!(f, "out of range" ) |
518 | } |
519 | } |
520 | |
521 | impl fmt::Debug for OutOfRange { |
522 | fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { |
523 | write!(f, "out of range" ) |
524 | } |
525 | } |
526 | |
527 | #[cfg (feature = "std" )] |
528 | impl std::error::Error for OutOfRange {} |
529 | |