| 1 |
use crate::{IsoWeek, Weekday}; |
| 2 |
|
| 3 |
/// The common set of methods for date component. |
| 4 |
/// |
| 5 |
/// Methods such as [`year`], [`month`], [`day`] and [`weekday`] can be used to get basic |
| 6 |
/// information about the date. |
| 7 |
/// |
| 8 |
/// The `with_*` methods can change the date. |
| 9 |
/// |
| 10 |
/// # Warning |
| 11 |
/// |
| 12 |
/// The `with_*` methods can be convenient to change a single component of a date, but they must be |
| 13 |
/// used with some care. Examples to watch out for: |
| 14 |
/// |
| 15 |
/// - [`with_year`] changes the year component of a year-month-day value. Don't use this method if |
| 16 |
/// you want the ordinal to stay the same after changing the year, of if you want the week and |
| 17 |
/// weekday values to stay the same. |
| 18 |
/// - Don't combine two `with_*` methods to change two components of the date. For example to |
| 19 |
/// change both the year and month components of a date. This could fail because an intermediate |
| 20 |
/// value does not exist, while the final date would be valid. |
| 21 |
/// |
| 22 |
/// For more complex changes to a date, it is best to use the methods on [`NaiveDate`] to create a |
| 23 |
/// new value instead of altering an existing date. |
| 24 |
/// |
| 25 |
/// [`year`]: Datelike::year |
| 26 |
/// [`month`]: Datelike::month |
| 27 |
/// [`day`]: Datelike::day |
| 28 |
/// [`weekday`]: Datelike::weekday |
| 29 |
/// [`with_year`]: Datelike::with_year |
| 30 |
/// [`NaiveDate`]: crate::NaiveDate |
| 31 |
pub trait Datelike: Sized { |
| 32 |
/// Returns the year number in the [calendar date](./naive/struct.NaiveDate.html#calendar-date). |
| 33 |
fn year(&self) -> i32; |
| 34 |
|
| 35 |
/// Returns the absolute year number starting from 1 with a boolean flag, |
| 36 |
/// which is false when the year predates the epoch (BCE/BC) and true otherwise (CE/AD). |
| 37 |
#[inline] |
| 38 |
fn year_ce(&self) -> (bool, u32) { |
| 39 |
let year = self.year(); |
| 40 |
if year < 1 { |
| 41 |
(false, (1 - year) as u32) |
| 42 |
} else { |
| 43 |
(true, year as u32) |
| 44 |
} |
| 45 |
} |
| 46 |
|
| 47 |
/// Returns the month number starting from 1. |
| 48 |
/// |
| 49 |
/// The return value ranges from 1 to 12. |
| 50 |
fn month(&self) -> u32; |
| 51 |
|
| 52 |
/// Returns the month number starting from 0. |
| 53 |
/// |
| 54 |
/// The return value ranges from 0 to 11. |
| 55 |
fn month0(&self) -> u32; |
| 56 |
|
| 57 |
/// Returns the day of month starting from 1. |
| 58 |
/// |
| 59 |
/// The return value ranges from 1 to 31. (The last day of month differs by months.) |
| 60 |
fn day(&self) -> u32; |
| 61 |
|
| 62 |
/// Returns the day of month starting from 0. |
| 63 |
/// |
| 64 |
/// The return value ranges from 0 to 30. (The last day of month differs by months.) |
| 65 |
fn day0(&self) -> u32; |
| 66 |
|
| 67 |
/// Returns the day of year starting from 1. |
| 68 |
/// |
| 69 |
/// The return value ranges from 1 to 366. (The last day of year differs by years.) |
| 70 |
fn ordinal(&self) -> u32; |
| 71 |
|
| 72 |
/// Returns the day of year starting from 0. |
| 73 |
/// |
| 74 |
/// The return value ranges from 0 to 365. (The last day of year differs by years.) |
| 75 |
fn ordinal0(&self) -> u32; |
| 76 |
|
| 77 |
/// Returns the day of week. |
| 78 |
fn weekday(&self) -> Weekday; |
| 79 |
|
| 80 |
/// Returns the ISO week. |
| 81 |
fn iso_week(&self) -> IsoWeek; |
| 82 |
|
| 83 |
/// Makes a new value with the year number changed, while keeping the same month and day. |
| 84 |
/// |
| 85 |
/// This method assumes you want to work on the date as a year-month-day value. Don't use it if |
| 86 |
/// you want the ordinal to stay the same after changing the year, of if you want the week and |
| 87 |
/// weekday values to stay the same. |
| 88 |
/// |
| 89 |
/// # Errors |
| 90 |
/// |
| 91 |
/// Returns `None` when: |
| 92 |
/// |
| 93 |
/// - The resulting date does not exist (February 29 in a non-leap year). |
| 94 |
/// - The year is out of range for [`NaiveDate`]. |
| 95 |
/// - In case of [`DateTime<Tz>`] if the resulting date and time fall within a timezone |
| 96 |
/// transition such as from DST to standard time. |
| 97 |
/// |
| 98 |
/// [`NaiveDate`]: crate::NaiveDate |
| 99 |
/// [`DateTime<Tz>`]: crate::DateTime |
| 100 |
/// |
| 101 |
/// # Examples |
| 102 |
/// |
| 103 |
/// ``` |
| 104 |
/// use chrono::{Datelike, NaiveDate}; |
| 105 |
/// |
| 106 |
/// assert_eq!( |
| 107 |
/// NaiveDate::from_ymd_opt(2020, 5, 13).unwrap().with_year(2023).unwrap(), |
| 108 |
/// NaiveDate::from_ymd_opt(2023, 5, 13).unwrap() |
| 109 |
/// ); |
| 110 |
/// // Resulting date 2023-02-29 does not exist: |
| 111 |
/// assert!(NaiveDate::from_ymd_opt(2020, 2, 29).unwrap().with_year(2023).is_none()); |
| 112 |
/// |
| 113 |
/// // Don't use `with_year` if you want the ordinal date to stay the same: |
| 114 |
/// assert_ne!( |
| 115 |
/// NaiveDate::from_yo_opt(2020, 100).unwrap().with_year(2023).unwrap(), |
| 116 |
/// NaiveDate::from_yo_opt(2023, 100).unwrap() // result is 2023-101 |
| 117 |
/// ); |
| 118 |
/// ``` |
| 119 |
fn with_year(&self, year: i32) -> Option<Self>; |
| 120 |
|
| 121 |
/// Makes a new value with the month number (starting from 1) changed. |
| 122 |
/// |
| 123 |
/// # Errors |
| 124 |
/// |
| 125 |
/// Returns `None` when: |
| 126 |
/// |
| 127 |
/// - The resulting date does not exist (for example `month(4)` when day of the month is 31). |
| 128 |
/// - In case of [`DateTime<Tz>`] if the resulting date and time fall within a timezone |
| 129 |
/// transition such as from DST to standard time. |
| 130 |
/// - The value for `month` is out of range. |
| 131 |
/// |
| 132 |
/// [`DateTime<Tz>`]: crate::DateTime |
| 133 |
/// |
| 134 |
/// # Examples |
| 135 |
/// |
| 136 |
/// ``` |
| 137 |
/// use chrono::{Datelike, NaiveDate}; |
| 138 |
/// |
| 139 |
/// assert_eq!( |
| 140 |
/// NaiveDate::from_ymd_opt(2023, 5, 12).unwrap().with_month(9).unwrap(), |
| 141 |
/// NaiveDate::from_ymd_opt(2023, 9, 12).unwrap() |
| 142 |
/// ); |
| 143 |
/// // Resulting date 2023-09-31 does not exist: |
| 144 |
/// assert!(NaiveDate::from_ymd_opt(2023, 5, 31).unwrap().with_month(9).is_none()); |
| 145 |
/// ``` |
| 146 |
/// |
| 147 |
/// Don't combine multiple `Datelike::with_*` methods. The intermediate value may not exist. |
| 148 |
/// ``` |
| 149 |
/// use chrono::{Datelike, NaiveDate}; |
| 150 |
/// |
| 151 |
/// fn with_year_month(date: NaiveDate, year: i32, month: u32) -> Option<NaiveDate> { |
| 152 |
/// date.with_year(year)?.with_month(month) |
| 153 |
/// } |
| 154 |
/// let d = NaiveDate::from_ymd_opt(2020, 2, 29).unwrap(); |
| 155 |
/// assert!(with_year_month(d, 2019, 1).is_none()); // fails because of invalid intermediate value |
| 156 |
/// |
| 157 |
/// // Correct version: |
| 158 |
/// fn with_year_month_fixed(date: NaiveDate, year: i32, month: u32) -> Option<NaiveDate> { |
| 159 |
/// NaiveDate::from_ymd_opt(year, month, date.day()) |
| 160 |
/// } |
| 161 |
/// let d = NaiveDate::from_ymd_opt(2020, 2, 29).unwrap(); |
| 162 |
/// assert_eq!(with_year_month_fixed(d, 2019, 1), NaiveDate::from_ymd_opt(2019, 1, 29)); |
| 163 |
/// ``` |
| 164 |
fn with_month(&self, month: u32) -> Option<Self>; |
| 165 |
|
| 166 |
/// Makes a new value with the month number (starting from 0) changed. |
| 167 |
/// |
| 168 |
/// # Errors |
| 169 |
/// |
| 170 |
/// Returns `None` when: |
| 171 |
/// |
| 172 |
/// - The resulting date does not exist (for example `month0(3)` when day of the month is 31). |
| 173 |
/// - In case of [`DateTime<Tz>`] if the resulting date and time fall within a timezone |
| 174 |
/// transition such as from DST to standard time. |
| 175 |
/// - The value for `month0` is out of range. |
| 176 |
/// |
| 177 |
/// [`DateTime<Tz>`]: crate::DateTime |
| 178 |
fn with_month0(&self, month0: u32) -> Option<Self>; |
| 179 |
|
| 180 |
/// Makes a new value with the day of month (starting from 1) changed. |
| 181 |
/// |
| 182 |
/// # Errors |
| 183 |
/// |
| 184 |
/// Returns `None` when: |
| 185 |
/// |
| 186 |
/// - The resulting date does not exist (for example `day(31)` in April). |
| 187 |
/// - In case of [`DateTime<Tz>`] if the resulting date and time fall within a timezone |
| 188 |
/// transition such as from DST to standard time. |
| 189 |
/// - The value for `day` is out of range. |
| 190 |
/// |
| 191 |
/// [`DateTime<Tz>`]: crate::DateTime |
| 192 |
fn with_day(&self, day: u32) -> Option<Self>; |
| 193 |
|
| 194 |
/// Makes a new value with the day of month (starting from 0) changed. |
| 195 |
/// |
| 196 |
/// # Errors |
| 197 |
/// |
| 198 |
/// Returns `None` when: |
| 199 |
/// |
| 200 |
/// - The resulting date does not exist (for example `day0(30)` in April). |
| 201 |
/// - In case of [`DateTime<Tz>`] if the resulting date and time fall within a timezone |
| 202 |
/// transition such as from DST to standard time. |
| 203 |
/// - The value for `day0` is out of range. |
| 204 |
/// |
| 205 |
/// [`DateTime<Tz>`]: crate::DateTime |
| 206 |
fn with_day0(&self, day0: u32) -> Option<Self>; |
| 207 |
|
| 208 |
/// Makes a new value with the day of year (starting from 1) changed. |
| 209 |
/// |
| 210 |
/// # Errors |
| 211 |
/// |
| 212 |
/// Returns `None` when: |
| 213 |
/// |
| 214 |
/// - The resulting date does not exist (`with_ordinal(366)` in a non-leap year). |
| 215 |
/// - In case of [`DateTime<Tz>`] if the resulting date and time fall within a timezone |
| 216 |
/// transition such as from DST to standard time. |
| 217 |
/// - The value for `ordinal` is out of range. |
| 218 |
/// |
| 219 |
/// [`DateTime<Tz>`]: crate::DateTime |
| 220 |
fn with_ordinal(&self, ordinal: u32) -> Option<Self>; |
| 221 |
|
| 222 |
/// Makes a new value with the day of year (starting from 0) changed. |
| 223 |
/// |
| 224 |
/// # Errors |
| 225 |
/// |
| 226 |
/// Returns `None` when: |
| 227 |
/// |
| 228 |
/// - The resulting date does not exist (`with_ordinal0(365)` in a non-leap year). |
| 229 |
/// - In case of [`DateTime<Tz>`] if the resulting date and time fall within a timezone |
| 230 |
/// transition such as from DST to standard time. |
| 231 |
/// - The value for `ordinal0` is out of range. |
| 232 |
/// |
| 233 |
/// [`DateTime<Tz>`]: crate::DateTime |
| 234 |
fn with_ordinal0(&self, ordinal0: u32) -> Option<Self>; |
| 235 |
|
| 236 |
/// Counts the days in the proleptic Gregorian calendar, with January 1, Year 1 (CE) as day 1. |
| 237 |
/// |
| 238 |
/// # Examples |
| 239 |
/// |
| 240 |
/// ``` |
| 241 |
/// use chrono::{Datelike, NaiveDate}; |
| 242 |
/// |
| 243 |
/// assert_eq!(NaiveDate::from_ymd_opt(1970, 1, 1).unwrap().num_days_from_ce(), 719_163); |
| 244 |
/// assert_eq!(NaiveDate::from_ymd_opt(2, 1, 1).unwrap().num_days_from_ce(), 366); |
| 245 |
/// assert_eq!(NaiveDate::from_ymd_opt(1, 1, 1).unwrap().num_days_from_ce(), 1); |
| 246 |
/// assert_eq!(NaiveDate::from_ymd_opt(0, 1, 1).unwrap().num_days_from_ce(), -365); |
| 247 |
/// ``` |
| 248 |
fn num_days_from_ce(&self) -> i32 { |
| 249 |
// See test_num_days_from_ce_against_alternative_impl below for a more straightforward |
| 250 |
// implementation. |
| 251 |
|
| 252 |
// we know this wouldn't overflow since year is limited to 1/2^13 of i32's full range. |
| 253 |
let mut year = self.year() - 1; |
| 254 |
let mut ndays = 0; |
| 255 |
if year < 0 { |
| 256 |
let excess = 1 + (-year) / 400; |
| 257 |
year += excess * 400; |
| 258 |
ndays -= excess * 146_097; |
| 259 |
} |
| 260 |
let div_100 = year / 100; |
| 261 |
ndays += ((year * 1461) >> 2) - div_100 + (div_100 >> 2); |
| 262 |
ndays + self.ordinal() as i32 |
| 263 |
} |
| 264 |
} |
| 265 |
|
| 266 |
/// The common set of methods for time component. |
| 267 |
pub trait Timelike: Sized { |
| 268 |
/// Returns the hour number from 0 to 23. |
| 269 |
fn hour(&self) -> u32; |
| 270 |
|
| 271 |
/// Returns the hour number from 1 to 12 with a boolean flag, |
| 272 |
/// which is false for AM and true for PM. |
| 273 |
#[inline] |
| 274 |
fn hour12(&self) -> (bool, u32) { |
| 275 |
let hour = self.hour(); |
| 276 |
let mut hour12 = hour % 12; |
| 277 |
if hour12 == 0 { |
| 278 |
hour12 = 12; |
| 279 |
} |
| 280 |
(hour >= 12, hour12) |
| 281 |
} |
| 282 |
|
| 283 |
/// Returns the minute number from 0 to 59. |
| 284 |
fn minute(&self) -> u32; |
| 285 |
|
| 286 |
/// Returns the second number from 0 to 59. |
| 287 |
fn second(&self) -> u32; |
| 288 |
|
| 289 |
/// Returns the number of nanoseconds since the whole non-leap second. |
| 290 |
/// The range from 1,000,000,000 to 1,999,999,999 represents |
| 291 |
/// the [leap second](./naive/struct.NaiveTime.html#leap-second-handling). |
| 292 |
fn nanosecond(&self) -> u32; |
| 293 |
|
| 294 |
/// Makes a new value with the hour number changed. |
| 295 |
/// |
| 296 |
/// Returns `None` when the resulting value would be invalid. |
| 297 |
fn with_hour(&self, hour: u32) -> Option<Self>; |
| 298 |
|
| 299 |
/// Makes a new value with the minute number changed. |
| 300 |
/// |
| 301 |
/// Returns `None` when the resulting value would be invalid. |
| 302 |
fn with_minute(&self, min: u32) -> Option<Self>; |
| 303 |
|
| 304 |
/// Makes a new value with the second number changed. |
| 305 |
/// |
| 306 |
/// Returns `None` when the resulting value would be invalid. |
| 307 |
/// As with the [`second`](#tymethod.second) method, |
| 308 |
/// the input range is restricted to 0 through 59. |
| 309 |
fn with_second(&self, sec: u32) -> Option<Self>; |
| 310 |
|
| 311 |
/// Makes a new value with nanoseconds since the whole non-leap second changed. |
| 312 |
/// |
| 313 |
/// Returns `None` when the resulting value would be invalid. |
| 314 |
/// As with the [`nanosecond`](#tymethod.nanosecond) method, |
| 315 |
/// the input range can exceed 1,000,000,000 for leap seconds. |
| 316 |
fn with_nanosecond(&self, nano: u32) -> Option<Self>; |
| 317 |
|
| 318 |
/// Returns the number of non-leap seconds past the last midnight. |
| 319 |
/// |
| 320 |
/// Every value in 00:00:00-23:59:59 maps to an integer in 0-86399. |
| 321 |
/// |
| 322 |
/// This method is not intended to provide the real number of seconds since midnight on a given |
| 323 |
/// day. It does not take things like DST transitions into account. |
| 324 |
#[inline] |
| 325 |
fn num_seconds_from_midnight(&self) -> u32 { |
| 326 |
self.hour() * 3600 + self.minute() * 60 + self.second() |
| 327 |
} |
| 328 |
} |
| 329 |
|
| 330 |
#[cfg(test)] |
| 331 |
mod tests { |
| 332 |
use super::Datelike; |
| 333 |
use crate::{Days, NaiveDate}; |
| 334 |
|
| 335 |
/// Tests `Datelike::num_days_from_ce` against an alternative implementation. |
| 336 |
/// |
| 337 |
/// The alternative implementation is not as short as the current one but it is simpler to |
| 338 |
/// understand, with less unexplained magic constants. |
| 339 |
#[test] |
| 340 |
fn test_num_days_from_ce_against_alternative_impl() { |
| 341 |
/// Returns the number of multiples of `div` in the range `start..end`. |
| 342 |
/// |
| 343 |
/// If the range `start..end` is back-to-front, i.e. `start` is greater than `end`, the |
| 344 |
/// behaviour is defined by the following equation: |
| 345 |
/// `in_between(start, end, div) == - in_between(end, start, div)`. |
| 346 |
/// |
| 347 |
/// When `div` is 1, this is equivalent to `end - start`, i.e. the length of `start..end`. |
| 348 |
/// |
| 349 |
/// # Panics |
| 350 |
/// |
| 351 |
/// Panics if `div` is not positive. |
| 352 |
fn in_between(start: i32, end: i32, div: i32) -> i32 { |
| 353 |
assert!(div > 0, "in_between: nonpositive div = {}", div); |
| 354 |
let start = (start.div_euclid(div), start.rem_euclid(div)); |
| 355 |
let end = (end.div_euclid(div), end.rem_euclid(div)); |
| 356 |
// The lowest multiple of `div` greater than or equal to `start`, divided. |
| 357 |
let start = start.0 + (start.1 != 0) as i32; |
| 358 |
// The lowest multiple of `div` greater than or equal to `end`, divided. |
| 359 |
let end = end.0 + (end.1 != 0) as i32; |
| 360 |
end - start |
| 361 |
} |
| 362 |
|
| 363 |
/// Alternative implementation to `Datelike::num_days_from_ce` |
| 364 |
fn num_days_from_ce<Date: Datelike>(date: &Date) -> i32 { |
| 365 |
let year = date.year(); |
| 366 |
let diff = move |div| in_between(1, year, div); |
| 367 |
// 365 days a year, one more in leap years. In the gregorian calendar, leap years are all |
| 368 |
// the multiples of 4 except multiples of 100 but including multiples of 400. |
| 369 |
date.ordinal() as i32 + 365 * diff(1) + diff(4) - diff(100) + diff(400) |
| 370 |
} |
| 371 |
|
| 372 |
for year in NaiveDate::MIN.year()..=NaiveDate::MAX.year() { |
| 373 |
let jan1_year = NaiveDate::from_ymd_opt(year, 1, 1).unwrap(); |
| 374 |
assert_eq!( |
| 375 |
jan1_year.num_days_from_ce(), |
| 376 |
num_days_from_ce(&jan1_year), |
| 377 |
"on {:?}", |
| 378 |
jan1_year |
| 379 |
); |
| 380 |
let mid_year = jan1_year + Days::new(133); |
| 381 |
assert_eq!( |
| 382 |
mid_year.num_days_from_ce(), |
| 383 |
num_days_from_ce(&mid_year), |
| 384 |
"on {:?}", |
| 385 |
mid_year |
| 386 |
); |
| 387 |
} |
| 388 |
} |
| 389 |
} |