| 1 |
// This is a part of Chrono. |
| 2 |
// See README.md and LICENSE.txt for details. |
| 3 |
|
| 4 |
//! The time zone, which calculates offsets from the local time to UTC. |
| 5 |
//! |
| 6 |
//! There are four operations provided by the `TimeZone` trait: |
| 7 |
//! |
| 8 |
//! 1. Converting the local `NaiveDateTime` to `DateTime<Tz>` |
| 9 |
//! 2. Converting the UTC `NaiveDateTime` to `DateTime<Tz>` |
| 10 |
//! 3. Converting `DateTime<Tz>` to the local `NaiveDateTime` |
| 11 |
//! 4. Constructing `DateTime<Tz>` objects from various offsets |
| 12 |
//! |
| 13 |
//! 1 is used for constructors. 2 is used for the `with_timezone` method of date and time types. |
| 14 |
//! 3 is used for other methods, e.g. `year()` or `format()`, and provided by an associated type |
| 15 |
//! which implements `Offset` (which then passed to `TimeZone` for actual implementations). |
| 16 |
//! Technically speaking `TimeZone` has a total knowledge about given timescale, |
| 17 |
//! but `Offset` is used as a cache to avoid the repeated conversion |
| 18 |
//! and provides implementations for 1 and 3. |
| 19 |
//! An `TimeZone` instance can be reconstructed from the corresponding `Offset` instance. |
| 20 |
|
| 21 |
use core::fmt; |
| 22 |
|
| 23 |
use crate::format::{parse, ParseResult, Parsed, StrftimeItems}; |
| 24 |
use crate::naive::{NaiveDate, NaiveDateTime, NaiveTime}; |
| 25 |
use crate::Weekday; |
| 26 |
#[allow(deprecated)] |
| 27 |
use crate::{Date, DateTime}; |
| 28 |
|
| 29 |
pub(crate) mod fixed; |
| 30 |
pub use self::fixed::FixedOffset; |
| 31 |
|
| 32 |
#[cfg(feature = "clock")] |
| 33 |
pub(crate) mod local; |
| 34 |
#[cfg(feature = "clock")] |
| 35 |
pub use self::local::Local; |
| 36 |
|
| 37 |
pub(crate) mod utc; |
| 38 |
pub use self::utc::Utc; |
| 39 |
|
| 40 |
/// The result of mapping a local time to a concrete instant in a given time zone. |
| 41 |
/// |
| 42 |
/// The calculation to go from a local time (wall clock time) to an instant in UTC can end up in |
| 43 |
/// three cases: |
| 44 |
/// * A single, simple result. |
| 45 |
/// * An ambiguous result when the clock is turned backwards during a transition due to for example |
| 46 |
/// DST. |
| 47 |
/// * No result when the clock is turned forwards during a transition due to for example DST. |
| 48 |
/// |
| 49 |
/// When the clock is turned backwards it creates a _fold_ in local time, during which the local |
| 50 |
/// time is _ambiguous_. When the clock is turned forwards it creates a _gap_ in local time, during |
| 51 |
/// which the local time is _missing_, or does not exist. |
| 52 |
/// |
| 53 |
/// Chrono does not return a default choice or invalid data during time zone transitions, but has |
| 54 |
/// the `MappedLocalTime` type to help deal with the result correctly. |
| 55 |
/// |
| 56 |
/// The type of `T` is usually a [`DateTime`] but may also be only an offset. |
| 57 |
pub type MappedLocalTime<T> = LocalResult<T>; |
| 58 |
#[derive(Clone, PartialEq, Debug, Copy, Eq, Hash)] |
| 59 |
|
| 60 |
/// Old name of [`MappedLocalTime`]. See that type for more documentation. |
| 61 |
pub enum LocalResult<T> { |
| 62 |
/// The local time maps to a single unique result. |
| 63 |
Single(T), |
| 64 |
|
| 65 |
/// The local time is _ambiguous_ because there is a _fold_ in the local time. |
| 66 |
/// |
| 67 |
/// This variant contains the two possible results, in the order `(earliest, latest)`. |
| 68 |
Ambiguous(T, T), |
| 69 |
|
| 70 |
/// The local time does not exist because there is a _gap_ in the local time. |
| 71 |
/// |
| 72 |
/// This variant may also be returned if there was an error while resolving the local time, |
| 73 |
/// caused by for example missing time zone data files, an error in an OS API, or overflow. |
| 74 |
None, |
| 75 |
} |
| 76 |
|
| 77 |
impl<T> MappedLocalTime<T> { |
| 78 |
/// Returns `Some` if the time zone mapping has a single result. |
| 79 |
/// |
| 80 |
/// # Errors |
| 81 |
/// |
| 82 |
/// Returns `None` if local time falls in a _fold_ or _gap_ in the local time, or if there was |
| 83 |
/// an error. |
| 84 |
#[must_use] |
| 85 |
pub fn single(self) -> Option<T> { |
| 86 |
match self { |
| 87 |
MappedLocalTime::Single(t) => Some(t), |
| 88 |
_ => None, |
| 89 |
} |
| 90 |
} |
| 91 |
|
| 92 |
/// Returns the earliest possible result of a the time zone mapping. |
| 93 |
/// |
| 94 |
/// # Errors |
| 95 |
/// |
| 96 |
/// Returns `None` if local time falls in a _gap_ in the local time, or if there was an error. |
| 97 |
#[must_use] |
| 98 |
pub fn earliest(self) -> Option<T> { |
| 99 |
match self { |
| 100 |
MappedLocalTime::Single(t) | MappedLocalTime::Ambiguous(t, _) => Some(t), |
| 101 |
_ => None, |
| 102 |
} |
| 103 |
} |
| 104 |
|
| 105 |
/// Returns the latest possible result of a the time zone mapping. |
| 106 |
/// |
| 107 |
/// # Errors |
| 108 |
/// |
| 109 |
/// Returns `None` if local time falls in a _gap_ in the local time, or if there was an error. |
| 110 |
#[must_use] |
| 111 |
pub fn latest(self) -> Option<T> { |
| 112 |
match self { |
| 113 |
MappedLocalTime::Single(t) | MappedLocalTime::Ambiguous(_, t) => Some(t), |
| 114 |
_ => None, |
| 115 |
} |
| 116 |
} |
| 117 |
|
| 118 |
/// Maps a `MappedLocalTime<T>` into `MappedLocalTime<U>` with given function. |
| 119 |
#[must_use] |
| 120 |
pub fn map<U, F: FnMut(T) -> U>(self, mut f: F) -> MappedLocalTime<U> { |
| 121 |
match self { |
| 122 |
MappedLocalTime::None => MappedLocalTime::None, |
| 123 |
MappedLocalTime::Single(v) => MappedLocalTime::Single(f(v)), |
| 124 |
MappedLocalTime::Ambiguous(min, max) => MappedLocalTime::Ambiguous(f(min), f(max)), |
| 125 |
} |
| 126 |
} |
| 127 |
|
| 128 |
/// Maps a `MappedLocalTime<T>` into `MappedLocalTime<U>` with given function. |
| 129 |
/// |
| 130 |
/// Returns `MappedLocalTime::None` if the function returns `None`. |
| 131 |
#[must_use] |
| 132 |
pub(crate) fn and_then<U, F: FnMut(T) -> Option<U>>(self, mut f: F) -> MappedLocalTime<U> { |
| 133 |
match self { |
| 134 |
MappedLocalTime::None => MappedLocalTime::None, |
| 135 |
MappedLocalTime::Single(v) => match f(v) { |
| 136 |
Some(new) => MappedLocalTime::Single(new), |
| 137 |
None => MappedLocalTime::None, |
| 138 |
}, |
| 139 |
MappedLocalTime::Ambiguous(min, max) => match (f(min), f(max)) { |
| 140 |
(Some(min), Some(max)) => MappedLocalTime::Ambiguous(min, max), |
| 141 |
_ => MappedLocalTime::None, |
| 142 |
}, |
| 143 |
} |
| 144 |
} |
| 145 |
} |
| 146 |
|
| 147 |
#[allow(deprecated)] |
| 148 |
impl<Tz: TimeZone> MappedLocalTime<Date<Tz>> { |
| 149 |
/// Makes a new `DateTime` from the current date and given `NaiveTime`. |
| 150 |
/// The offset in the current date is preserved. |
| 151 |
/// |
| 152 |
/// Propagates any error. Ambiguous result would be discarded. |
| 153 |
#[inline] |
| 154 |
#[must_use] |
| 155 |
pub fn and_time(self, time: NaiveTime) -> MappedLocalTime<DateTime<Tz>> { |
| 156 |
match self { |
| 157 |
MappedLocalTime::Single(d) => { |
| 158 |
d.and_time(time).map_or(MappedLocalTime::None, MappedLocalTime::Single) |
| 159 |
} |
| 160 |
_ => MappedLocalTime::None, |
| 161 |
} |
| 162 |
} |
| 163 |
|
| 164 |
/// Makes a new `DateTime` from the current date, hour, minute and second. |
| 165 |
/// The offset in the current date is preserved. |
| 166 |
/// |
| 167 |
/// Propagates any error. Ambiguous result would be discarded. |
| 168 |
#[inline] |
| 169 |
#[must_use] |
| 170 |
pub fn and_hms_opt(self, hour: u32, min: u32, sec: u32) -> MappedLocalTime<DateTime<Tz>> { |
| 171 |
match self { |
| 172 |
MappedLocalTime::Single(d) => { |
| 173 |
d.and_hms_opt(hour, min, sec).map_or(MappedLocalTime::None, MappedLocalTime::Single) |
| 174 |
} |
| 175 |
_ => MappedLocalTime::None, |
| 176 |
} |
| 177 |
} |
| 178 |
|
| 179 |
/// Makes a new `DateTime` from the current date, hour, minute, second and millisecond. |
| 180 |
/// The millisecond part can exceed 1,000 in order to represent the leap second. |
| 181 |
/// The offset in the current date is preserved. |
| 182 |
/// |
| 183 |
/// Propagates any error. Ambiguous result would be discarded. |
| 184 |
#[inline] |
| 185 |
#[must_use] |
| 186 |
pub fn and_hms_milli_opt( |
| 187 |
self, |
| 188 |
hour: u32, |
| 189 |
min: u32, |
| 190 |
sec: u32, |
| 191 |
milli: u32, |
| 192 |
) -> MappedLocalTime<DateTime<Tz>> { |
| 193 |
match self { |
| 194 |
MappedLocalTime::Single(d) => d |
| 195 |
.and_hms_milli_opt(hour, min, sec, milli) |
| 196 |
.map_or(MappedLocalTime::None, MappedLocalTime::Single), |
| 197 |
_ => MappedLocalTime::None, |
| 198 |
} |
| 199 |
} |
| 200 |
|
| 201 |
/// Makes a new `DateTime` from the current date, hour, minute, second and microsecond. |
| 202 |
/// The microsecond part can exceed 1,000,000 in order to represent the leap second. |
| 203 |
/// The offset in the current date is preserved. |
| 204 |
/// |
| 205 |
/// Propagates any error. Ambiguous result would be discarded. |
| 206 |
#[inline] |
| 207 |
#[must_use] |
| 208 |
pub fn and_hms_micro_opt( |
| 209 |
self, |
| 210 |
hour: u32, |
| 211 |
min: u32, |
| 212 |
sec: u32, |
| 213 |
micro: u32, |
| 214 |
) -> MappedLocalTime<DateTime<Tz>> { |
| 215 |
match self { |
| 216 |
MappedLocalTime::Single(d) => d |
| 217 |
.and_hms_micro_opt(hour, min, sec, micro) |
| 218 |
.map_or(MappedLocalTime::None, MappedLocalTime::Single), |
| 219 |
_ => MappedLocalTime::None, |
| 220 |
} |
| 221 |
} |
| 222 |
|
| 223 |
/// Makes a new `DateTime` from the current date, hour, minute, second and nanosecond. |
| 224 |
/// The nanosecond part can exceed 1,000,000,000 in order to represent the leap second. |
| 225 |
/// The offset in the current date is preserved. |
| 226 |
/// |
| 227 |
/// Propagates any error. Ambiguous result would be discarded. |
| 228 |
#[inline] |
| 229 |
#[must_use] |
| 230 |
pub fn and_hms_nano_opt( |
| 231 |
self, |
| 232 |
hour: u32, |
| 233 |
min: u32, |
| 234 |
sec: u32, |
| 235 |
nano: u32, |
| 236 |
) -> MappedLocalTime<DateTime<Tz>> { |
| 237 |
match self { |
| 238 |
MappedLocalTime::Single(d) => d |
| 239 |
.and_hms_nano_opt(hour, min, sec, nano) |
| 240 |
.map_or(MappedLocalTime::None, MappedLocalTime::Single), |
| 241 |
_ => MappedLocalTime::None, |
| 242 |
} |
| 243 |
} |
| 244 |
} |
| 245 |
|
| 246 |
impl<T: fmt::Debug> MappedLocalTime<T> { |
| 247 |
/// Returns a single unique conversion result or panics. |
| 248 |
/// |
| 249 |
/// `unwrap()` is best combined with time zone types where the mapping can never fail like |
| 250 |
/// [`Utc`] and [`FixedOffset`]. Note that for [`FixedOffset`] there is a rare case where a |
| 251 |
/// resulting [`DateTime`] can be out of range. |
| 252 |
/// |
| 253 |
/// # Panics |
| 254 |
/// |
| 255 |
/// Panics if the local time falls within a _fold_ or a _gap_ in the local time, and on any |
| 256 |
/// error that may have been returned by the type implementing [`TimeZone`]. |
| 257 |
#[must_use] |
| 258 |
#[track_caller] |
| 259 |
pub fn unwrap(self) -> T { |
| 260 |
match self { |
| 261 |
MappedLocalTime::None => panic!("No such local time"), |
| 262 |
MappedLocalTime::Single(t) => t, |
| 263 |
MappedLocalTime::Ambiguous(t1, t2) => { |
| 264 |
panic!("Ambiguous local time, ranging from {:?} to {:?}", t1, t2) |
| 265 |
} |
| 266 |
} |
| 267 |
} |
| 268 |
} |
| 269 |
|
| 270 |
/// The offset from the local time to UTC. |
| 271 |
pub trait Offset: Sized + Clone + fmt::Debug { |
| 272 |
/// Returns the fixed offset from UTC to the local time stored. |
| 273 |
fn fix(&self) -> FixedOffset; |
| 274 |
} |
| 275 |
|
| 276 |
/// The time zone. |
| 277 |
/// |
| 278 |
/// The methods here are the primary constructors for the [`DateTime`] type. |
| 279 |
pub trait TimeZone: Sized + Clone { |
| 280 |
/// An associated offset type. |
| 281 |
/// This type is used to store the actual offset in date and time types. |
| 282 |
/// The original `TimeZone` value can be recovered via `TimeZone::from_offset`. |
| 283 |
type Offset: Offset; |
| 284 |
|
| 285 |
/// Make a new `DateTime` from year, month, day, time components and current time zone. |
| 286 |
/// |
| 287 |
/// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE. |
| 288 |
/// |
| 289 |
/// Returns `MappedLocalTime::None` on invalid input data. |
| 290 |
fn with_ymd_and_hms( |
| 291 |
&self, |
| 292 |
year: i32, |
| 293 |
month: u32, |
| 294 |
day: u32, |
| 295 |
hour: u32, |
| 296 |
min: u32, |
| 297 |
sec: u32, |
| 298 |
) -> MappedLocalTime<DateTime<Self>> { |
| 299 |
match NaiveDate::from_ymd_opt(year, month, day).and_then(|d| d.and_hms_opt(hour, min, sec)) |
| 300 |
{ |
| 301 |
Some(dt) => self.from_local_datetime(&dt), |
| 302 |
None => MappedLocalTime::None, |
| 303 |
} |
| 304 |
} |
| 305 |
|
| 306 |
/// Makes a new `Date` from year, month, day and the current time zone. |
| 307 |
/// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE. |
| 308 |
/// |
| 309 |
/// The time zone normally does not affect the date (unless it is between UTC-24 and UTC+24), |
| 310 |
/// but it will propagate to the `DateTime` values constructed via this date. |
| 311 |
/// |
| 312 |
/// Panics on the out-of-range date, invalid month and/or day. |
| 313 |
#[deprecated(since = "0.4.23", note = "use `with_ymd_and_hms()` instead")] |
| 314 |
#[allow(deprecated)] |
| 315 |
fn ymd(&self, year: i32, month: u32, day: u32) -> Date<Self> { |
| 316 |
self.ymd_opt(year, month, day).unwrap() |
| 317 |
} |
| 318 |
|
| 319 |
/// Makes a new `Date` from year, month, day and the current time zone. |
| 320 |
/// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE. |
| 321 |
/// |
| 322 |
/// The time zone normally does not affect the date (unless it is between UTC-24 and UTC+24), |
| 323 |
/// but it will propagate to the `DateTime` values constructed via this date. |
| 324 |
/// |
| 325 |
/// Returns `None` on the out-of-range date, invalid month and/or day. |
| 326 |
#[deprecated(since = "0.4.23", note = "use `with_ymd_and_hms()` instead")] |
| 327 |
#[allow(deprecated)] |
| 328 |
fn ymd_opt(&self, year: i32, month: u32, day: u32) -> MappedLocalTime<Date<Self>> { |
| 329 |
match NaiveDate::from_ymd_opt(year, month, day) { |
| 330 |
Some(d) => self.from_local_date(&d), |
| 331 |
None => MappedLocalTime::None, |
| 332 |
} |
| 333 |
} |
| 334 |
|
| 335 |
/// Makes a new `Date` from year, day of year (DOY or "ordinal") and the current time zone. |
| 336 |
/// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE. |
| 337 |
/// |
| 338 |
/// The time zone normally does not affect the date (unless it is between UTC-24 and UTC+24), |
| 339 |
/// but it will propagate to the `DateTime` values constructed via this date. |
| 340 |
/// |
| 341 |
/// Panics on the out-of-range date and/or invalid DOY. |
| 342 |
#[deprecated( |
| 343 |
since = "0.4.23", |
| 344 |
note = "use `from_local_datetime()` with a `NaiveDateTime` instead" |
| 345 |
)] |
| 346 |
#[allow(deprecated)] |
| 347 |
fn yo(&self, year: i32, ordinal: u32) -> Date<Self> { |
| 348 |
self.yo_opt(year, ordinal).unwrap() |
| 349 |
} |
| 350 |
|
| 351 |
/// Makes a new `Date` from year, day of year (DOY or "ordinal") and the current time zone. |
| 352 |
/// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE. |
| 353 |
/// |
| 354 |
/// The time zone normally does not affect the date (unless it is between UTC-24 and UTC+24), |
| 355 |
/// but it will propagate to the `DateTime` values constructed via this date. |
| 356 |
/// |
| 357 |
/// Returns `None` on the out-of-range date and/or invalid DOY. |
| 358 |
#[deprecated( |
| 359 |
since = "0.4.23", |
| 360 |
note = "use `from_local_datetime()` with a `NaiveDateTime` instead" |
| 361 |
)] |
| 362 |
#[allow(deprecated)] |
| 363 |
fn yo_opt(&self, year: i32, ordinal: u32) -> MappedLocalTime<Date<Self>> { |
| 364 |
match NaiveDate::from_yo_opt(year, ordinal) { |
| 365 |
Some(d) => self.from_local_date(&d), |
| 366 |
None => MappedLocalTime::None, |
| 367 |
} |
| 368 |
} |
| 369 |
|
| 370 |
/// Makes a new `Date` from ISO week date (year and week number), day of the week (DOW) and |
| 371 |
/// the current time zone. |
| 372 |
/// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE. |
| 373 |
/// The resulting `Date` may have a different year from the input year. |
| 374 |
/// |
| 375 |
/// The time zone normally does not affect the date (unless it is between UTC-24 and UTC+24), |
| 376 |
/// but it will propagate to the `DateTime` values constructed via this date. |
| 377 |
/// |
| 378 |
/// Panics on the out-of-range date and/or invalid week number. |
| 379 |
#[deprecated( |
| 380 |
since = "0.4.23", |
| 381 |
note = "use `from_local_datetime()` with a `NaiveDateTime` instead" |
| 382 |
)] |
| 383 |
#[allow(deprecated)] |
| 384 |
fn isoywd(&self, year: i32, week: u32, weekday: Weekday) -> Date<Self> { |
| 385 |
self.isoywd_opt(year, week, weekday).unwrap() |
| 386 |
} |
| 387 |
|
| 388 |
/// Makes a new `Date` from ISO week date (year and week number), day of the week (DOW) and |
| 389 |
/// the current time zone. |
| 390 |
/// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE. |
| 391 |
/// The resulting `Date` may have a different year from the input year. |
| 392 |
/// |
| 393 |
/// The time zone normally does not affect the date (unless it is between UTC-24 and UTC+24), |
| 394 |
/// but it will propagate to the `DateTime` values constructed via this date. |
| 395 |
/// |
| 396 |
/// Returns `None` on the out-of-range date and/or invalid week number. |
| 397 |
#[deprecated( |
| 398 |
since = "0.4.23", |
| 399 |
note = "use `from_local_datetime()` with a `NaiveDateTime` instead" |
| 400 |
)] |
| 401 |
#[allow(deprecated)] |
| 402 |
fn isoywd_opt(&self, year: i32, week: u32, weekday: Weekday) -> MappedLocalTime<Date<Self>> { |
| 403 |
match NaiveDate::from_isoywd_opt(year, week, weekday) { |
| 404 |
Some(d) => self.from_local_date(&d), |
| 405 |
None => MappedLocalTime::None, |
| 406 |
} |
| 407 |
} |
| 408 |
|
| 409 |
/// Makes a new `DateTime` from the number of non-leap seconds |
| 410 |
/// since January 1, 1970 0:00:00 UTC (aka "UNIX timestamp") |
| 411 |
/// and the number of nanoseconds since the last whole non-leap second. |
| 412 |
/// |
| 413 |
/// The nanosecond part can exceed 1,000,000,000 in order to represent a |
| 414 |
/// [leap second](crate::NaiveTime#leap-second-handling), but only when `secs % 60 == 59`. |
| 415 |
/// (The true "UNIX timestamp" cannot represent a leap second unambiguously.) |
| 416 |
/// |
| 417 |
/// # Panics |
| 418 |
/// |
| 419 |
/// Panics on the out-of-range number of seconds and/or invalid nanosecond, |
| 420 |
/// for a non-panicking version see [`timestamp_opt`](#method.timestamp_opt). |
| 421 |
#[deprecated(since = "0.4.23", note = "use `timestamp_opt()` instead")] |
| 422 |
fn timestamp(&self, secs: i64, nsecs: u32) -> DateTime<Self> { |
| 423 |
self.timestamp_opt(secs, nsecs).unwrap() |
| 424 |
} |
| 425 |
|
| 426 |
/// Makes a new `DateTime` from the number of non-leap seconds |
| 427 |
/// since January 1, 1970 0:00:00 UTC (aka "UNIX timestamp") |
| 428 |
/// and the number of nanoseconds since the last whole non-leap second. |
| 429 |
/// |
| 430 |
/// The nanosecond part can exceed 1,000,000,000 in order to represent a |
| 431 |
/// [leap second](crate::NaiveTime#leap-second-handling), but only when `secs % 60 == 59`. |
| 432 |
/// (The true "UNIX timestamp" cannot represent a leap second unambiguously.) |
| 433 |
/// |
| 434 |
/// # Errors |
| 435 |
/// |
| 436 |
/// Returns `MappedLocalTime::None` on out-of-range number of seconds and/or |
| 437 |
/// invalid nanosecond, otherwise always returns `MappedLocalTime::Single`. |
| 438 |
/// |
| 439 |
/// # Example |
| 440 |
/// |
| 441 |
/// ``` |
| 442 |
/// use chrono::{TimeZone, Utc}; |
| 443 |
/// |
| 444 |
/// assert_eq!(Utc.timestamp_opt(1431648000, 0).unwrap().to_string(), "2015-05-15 00:00:00 UTC"); |
| 445 |
/// ``` |
| 446 |
fn timestamp_opt(&self, secs: i64, nsecs: u32) -> MappedLocalTime<DateTime<Self>> { |
| 447 |
match DateTime::from_timestamp(secs, nsecs) { |
| 448 |
Some(dt) => MappedLocalTime::Single(self.from_utc_datetime(&dt.naive_utc())), |
| 449 |
None => MappedLocalTime::None, |
| 450 |
} |
| 451 |
} |
| 452 |
|
| 453 |
/// Makes a new `DateTime` from the number of non-leap milliseconds |
| 454 |
/// since January 1, 1970 0:00:00 UTC (aka "UNIX timestamp"). |
| 455 |
/// |
| 456 |
/// Panics on out-of-range number of milliseconds for a non-panicking |
| 457 |
/// version see [`timestamp_millis_opt`](#method.timestamp_millis_opt). |
| 458 |
#[deprecated(since = "0.4.23", note = "use `timestamp_millis_opt()` instead")] |
| 459 |
fn timestamp_millis(&self, millis: i64) -> DateTime<Self> { |
| 460 |
self.timestamp_millis_opt(millis).unwrap() |
| 461 |
} |
| 462 |
|
| 463 |
/// Makes a new `DateTime` from the number of non-leap milliseconds |
| 464 |
/// since January 1, 1970 0:00:00 UTC (aka "UNIX timestamp"). |
| 465 |
/// |
| 466 |
/// |
| 467 |
/// Returns `MappedLocalTime::None` on out-of-range number of milliseconds |
| 468 |
/// and/or invalid nanosecond, otherwise always returns |
| 469 |
/// `MappedLocalTime::Single`. |
| 470 |
/// |
| 471 |
/// # Example |
| 472 |
/// |
| 473 |
/// ``` |
| 474 |
/// use chrono::{MappedLocalTime, TimeZone, Utc}; |
| 475 |
/// match Utc.timestamp_millis_opt(1431648000) { |
| 476 |
/// MappedLocalTime::Single(dt) => assert_eq!(dt.timestamp(), 1431648), |
| 477 |
/// _ => panic!("Incorrect timestamp_millis"), |
| 478 |
/// }; |
| 479 |
/// ``` |
| 480 |
fn timestamp_millis_opt(&self, millis: i64) -> MappedLocalTime<DateTime<Self>> { |
| 481 |
match DateTime::from_timestamp_millis(millis) { |
| 482 |
Some(dt) => MappedLocalTime::Single(self.from_utc_datetime(&dt.naive_utc())), |
| 483 |
None => MappedLocalTime::None, |
| 484 |
} |
| 485 |
} |
| 486 |
|
| 487 |
/// Makes a new `DateTime` from the number of non-leap nanoseconds |
| 488 |
/// since January 1, 1970 0:00:00 UTC (aka "UNIX timestamp"). |
| 489 |
/// |
| 490 |
/// Unlike [`timestamp_millis_opt`](#method.timestamp_millis_opt), this never fails. |
| 491 |
/// |
| 492 |
/// # Example |
| 493 |
/// |
| 494 |
/// ``` |
| 495 |
/// use chrono::{TimeZone, Utc}; |
| 496 |
/// |
| 497 |
/// assert_eq!(Utc.timestamp_nanos(1431648000000000).timestamp(), 1431648); |
| 498 |
/// ``` |
| 499 |
fn timestamp_nanos(&self, nanos: i64) -> DateTime<Self> { |
| 500 |
self.from_utc_datetime(&DateTime::from_timestamp_nanos(nanos).naive_utc()) |
| 501 |
} |
| 502 |
|
| 503 |
/// Makes a new `DateTime` from the number of non-leap microseconds |
| 504 |
/// since January 1, 1970 0:00:00 UTC (aka "UNIX timestamp"). |
| 505 |
/// |
| 506 |
/// # Example |
| 507 |
/// |
| 508 |
/// ``` |
| 509 |
/// use chrono::{TimeZone, Utc}; |
| 510 |
/// |
| 511 |
/// assert_eq!(Utc.timestamp_micros(1431648000000).unwrap().timestamp(), 1431648); |
| 512 |
/// ``` |
| 513 |
fn timestamp_micros(&self, micros: i64) -> MappedLocalTime<DateTime<Self>> { |
| 514 |
match DateTime::from_timestamp_micros(micros) { |
| 515 |
Some(dt) => MappedLocalTime::Single(self.from_utc_datetime(&dt.naive_utc())), |
| 516 |
None => MappedLocalTime::None, |
| 517 |
} |
| 518 |
} |
| 519 |
|
| 520 |
/// Parses a string with the specified format string and returns a |
| 521 |
/// `DateTime` with the current offset. |
| 522 |
/// |
| 523 |
/// See the [`crate::format::strftime`] module on the |
| 524 |
/// supported escape sequences. |
| 525 |
/// |
| 526 |
/// If the to-be-parsed string includes an offset, it *must* match the |
| 527 |
/// offset of the TimeZone, otherwise an error will be returned. |
| 528 |
/// |
| 529 |
/// See also [`DateTime::parse_from_str`] which gives a [`DateTime`] with |
| 530 |
/// parsed [`FixedOffset`]. |
| 531 |
/// |
| 532 |
/// See also [`NaiveDateTime::parse_from_str`] which gives a [`NaiveDateTime`] without |
| 533 |
/// an offset, but can be converted to a [`DateTime`] with [`NaiveDateTime::and_utc`] or |
| 534 |
/// [`NaiveDateTime::and_local_timezone`]. |
| 535 |
#[deprecated( |
| 536 |
since = "0.4.29", |
| 537 |
note = "use `DateTime::parse_from_str` or `NaiveDateTime::parse_from_str` with `and_utc()` or `and_local_timezone()` instead" |
| 538 |
)] |
| 539 |
fn datetime_from_str(&self, s: &str, fmt: &str) -> ParseResult<DateTime<Self>> { |
| 540 |
let mut parsed = Parsed::new(); |
| 541 |
parse(&mut parsed, s, StrftimeItems::new(fmt))?; |
| 542 |
parsed.to_datetime_with_timezone(self) |
| 543 |
} |
| 544 |
|
| 545 |
/// Reconstructs the time zone from the offset. |
| 546 |
fn from_offset(offset: &Self::Offset) -> Self; |
| 547 |
|
| 548 |
/// Creates the offset(s) for given local `NaiveDate` if possible. |
| 549 |
fn offset_from_local_date(&self, local: &NaiveDate) -> MappedLocalTime<Self::Offset>; |
| 550 |
|
| 551 |
/// Creates the offset(s) for given local `NaiveDateTime` if possible. |
| 552 |
fn offset_from_local_datetime(&self, local: &NaiveDateTime) -> MappedLocalTime<Self::Offset>; |
| 553 |
|
| 554 |
/// Converts the local `NaiveDate` to the timezone-aware `Date` if possible. |
| 555 |
#[allow(clippy::wrong_self_convention)] |
| 556 |
#[deprecated(since = "0.4.23", note = "use `from_local_datetime()` instead")] |
| 557 |
#[allow(deprecated)] |
| 558 |
fn from_local_date(&self, local: &NaiveDate) -> MappedLocalTime<Date<Self>> { |
| 559 |
self.offset_from_local_date(local).map(|offset| { |
| 560 |
// since FixedOffset is within +/- 1 day, the date is never affected |
| 561 |
Date::from_utc(*local, offset) |
| 562 |
}) |
| 563 |
} |
| 564 |
|
| 565 |
/// Converts the local `NaiveDateTime` to the timezone-aware `DateTime` if possible. |
| 566 |
#[allow(clippy::wrong_self_convention)] |
| 567 |
fn from_local_datetime(&self, local: &NaiveDateTime) -> MappedLocalTime<DateTime<Self>> { |
| 568 |
self.offset_from_local_datetime(local).and_then(|off| { |
| 569 |
local |
| 570 |
.checked_sub_offset(off.fix()) |
| 571 |
.map(|dt| DateTime::from_naive_utc_and_offset(dt, off)) |
| 572 |
}) |
| 573 |
} |
| 574 |
|
| 575 |
/// Creates the offset for given UTC `NaiveDate`. This cannot fail. |
| 576 |
fn offset_from_utc_date(&self, utc: &NaiveDate) -> Self::Offset; |
| 577 |
|
| 578 |
/// Creates the offset for given UTC `NaiveDateTime`. This cannot fail. |
| 579 |
fn offset_from_utc_datetime(&self, utc: &NaiveDateTime) -> Self::Offset; |
| 580 |
|
| 581 |
/// Converts the UTC `NaiveDate` to the local time. |
| 582 |
/// The UTC is continuous and thus this cannot fail (but can give the duplicate local time). |
| 583 |
#[allow(clippy::wrong_self_convention)] |
| 584 |
#[deprecated(since = "0.4.23", note = "use `from_utc_datetime()` instead")] |
| 585 |
#[allow(deprecated)] |
| 586 |
fn from_utc_date(&self, utc: &NaiveDate) -> Date<Self> { |
| 587 |
Date::from_utc(*utc, self.offset_from_utc_date(utc)) |
| 588 |
} |
| 589 |
|
| 590 |
/// Converts the UTC `NaiveDateTime` to the local time. |
| 591 |
/// The UTC is continuous and thus this cannot fail (but can give the duplicate local time). |
| 592 |
#[allow(clippy::wrong_self_convention)] |
| 593 |
fn from_utc_datetime(&self, utc: &NaiveDateTime) -> DateTime<Self> { |
| 594 |
DateTime::from_naive_utc_and_offset(*utc, self.offset_from_utc_datetime(utc)) |
| 595 |
} |
| 596 |
} |
| 597 |
|
| 598 |
#[cfg(test)] |
| 599 |
mod tests { |
| 600 |
use super::*; |
| 601 |
|
| 602 |
#[test] |
| 603 |
fn test_fixed_offset_min_max_dates() { |
| 604 |
for offset_hour in -23..=23 { |
| 605 |
dbg!(offset_hour); |
| 606 |
let offset = FixedOffset::east_opt(offset_hour * 60 * 60).unwrap(); |
| 607 |
|
| 608 |
let local_max = offset.from_utc_datetime(&NaiveDateTime::MAX); |
| 609 |
assert_eq!(local_max.naive_utc(), NaiveDateTime::MAX); |
| 610 |
let local_min = offset.from_utc_datetime(&NaiveDateTime::MIN); |
| 611 |
assert_eq!(local_min.naive_utc(), NaiveDateTime::MIN); |
| 612 |
|
| 613 |
let local_max = offset.from_local_datetime(&NaiveDateTime::MAX); |
| 614 |
if offset_hour >= 0 { |
| 615 |
assert_eq!(local_max.unwrap().naive_local(), NaiveDateTime::MAX); |
| 616 |
} else { |
| 617 |
assert_eq!(local_max, MappedLocalTime::None); |
| 618 |
} |
| 619 |
let local_min = offset.from_local_datetime(&NaiveDateTime::MIN); |
| 620 |
if offset_hour <= 0 { |
| 621 |
assert_eq!(local_min.unwrap().naive_local(), NaiveDateTime::MIN); |
| 622 |
} else { |
| 623 |
assert_eq!(local_min, MappedLocalTime::None); |
| 624 |
} |
| 625 |
} |
| 626 |
} |
| 627 |
|
| 628 |
#[test] |
| 629 |
fn test_negative_millis() { |
| 630 |
let dt = Utc.timestamp_millis_opt(-1000).unwrap(); |
| 631 |
assert_eq!(dt.to_string(), "1969-12-31 23:59:59 UTC"); |
| 632 |
let dt = Utc.timestamp_millis_opt(-7000).unwrap(); |
| 633 |
assert_eq!(dt.to_string(), "1969-12-31 23:59:53 UTC"); |
| 634 |
let dt = Utc.timestamp_millis_opt(-7001).unwrap(); |
| 635 |
assert_eq!(dt.to_string(), "1969-12-31 23:59:52.999 UTC"); |
| 636 |
let dt = Utc.timestamp_millis_opt(-7003).unwrap(); |
| 637 |
assert_eq!(dt.to_string(), "1969-12-31 23:59:52.997 UTC"); |
| 638 |
let dt = Utc.timestamp_millis_opt(-999).unwrap(); |
| 639 |
assert_eq!(dt.to_string(), "1969-12-31 23:59:59.001 UTC"); |
| 640 |
let dt = Utc.timestamp_millis_opt(-1).unwrap(); |
| 641 |
assert_eq!(dt.to_string(), "1969-12-31 23:59:59.999 UTC"); |
| 642 |
let dt = Utc.timestamp_millis_opt(-60000).unwrap(); |
| 643 |
assert_eq!(dt.to_string(), "1969-12-31 23:59:00 UTC"); |
| 644 |
let dt = Utc.timestamp_millis_opt(-3600000).unwrap(); |
| 645 |
assert_eq!(dt.to_string(), "1969-12-31 23:00:00 UTC"); |
| 646 |
|
| 647 |
for (millis, expected) in &[ |
| 648 |
(-7000, "1969-12-31 23:59:53 UTC"), |
| 649 |
(-7001, "1969-12-31 23:59:52.999 UTC"), |
| 650 |
(-7003, "1969-12-31 23:59:52.997 UTC"), |
| 651 |
] { |
| 652 |
match Utc.timestamp_millis_opt(*millis) { |
| 653 |
MappedLocalTime::Single(dt) => { |
| 654 |
assert_eq!(dt.to_string(), *expected); |
| 655 |
} |
| 656 |
e => panic!("Got {:?} instead of an okay answer", e), |
| 657 |
} |
| 658 |
} |
| 659 |
} |
| 660 |
|
| 661 |
#[test] |
| 662 |
fn test_negative_nanos() { |
| 663 |
let dt = Utc.timestamp_nanos(-1_000_000_000); |
| 664 |
assert_eq!(dt.to_string(), "1969-12-31 23:59:59 UTC"); |
| 665 |
let dt = Utc.timestamp_nanos(-999_999_999); |
| 666 |
assert_eq!(dt.to_string(), "1969-12-31 23:59:59.000000001 UTC"); |
| 667 |
let dt = Utc.timestamp_nanos(-1); |
| 668 |
assert_eq!(dt.to_string(), "1969-12-31 23:59:59.999999999 UTC"); |
| 669 |
let dt = Utc.timestamp_nanos(-60_000_000_000); |
| 670 |
assert_eq!(dt.to_string(), "1969-12-31 23:59:00 UTC"); |
| 671 |
let dt = Utc.timestamp_nanos(-3_600_000_000_000); |
| 672 |
assert_eq!(dt.to_string(), "1969-12-31 23:00:00 UTC"); |
| 673 |
} |
| 674 |
|
| 675 |
#[test] |
| 676 |
fn test_nanos_never_panics() { |
| 677 |
Utc.timestamp_nanos(i64::max_value()); |
| 678 |
Utc.timestamp_nanos(i64::default()); |
| 679 |
Utc.timestamp_nanos(i64::min_value()); |
| 680 |
} |
| 681 |
|
| 682 |
#[test] |
| 683 |
fn test_negative_micros() { |
| 684 |
let dt = Utc.timestamp_micros(-1_000_000).unwrap(); |
| 685 |
assert_eq!(dt.to_string(), "1969-12-31 23:59:59 UTC"); |
| 686 |
let dt = Utc.timestamp_micros(-999_999).unwrap(); |
| 687 |
assert_eq!(dt.to_string(), "1969-12-31 23:59:59.000001 UTC"); |
| 688 |
let dt = Utc.timestamp_micros(-1).unwrap(); |
| 689 |
assert_eq!(dt.to_string(), "1969-12-31 23:59:59.999999 UTC"); |
| 690 |
let dt = Utc.timestamp_micros(-60_000_000).unwrap(); |
| 691 |
assert_eq!(dt.to_string(), "1969-12-31 23:59:00 UTC"); |
| 692 |
let dt = Utc.timestamp_micros(-3_600_000_000).unwrap(); |
| 693 |
assert_eq!(dt.to_string(), "1969-12-31 23:00:00 UTC"); |
| 694 |
} |
| 695 |
} |