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 | } |
390 | |