1 | // This is a part of Chrono. |
2 | // See README.md and LICENSE.txt for details. |
3 | |
4 | //! ISO 8601 week. |
5 | |
6 | use core::fmt; |
7 | |
8 | use super::internals::{DateImpl, Of, YearFlags}; |
9 | |
10 | #[cfg (feature = "rkyv" )] |
11 | use rkyv::{Archive, Deserialize, Serialize}; |
12 | |
13 | /// ISO 8601 week. |
14 | /// |
15 | /// This type, combined with [`Weekday`](../enum.Weekday.html), |
16 | /// constitutes the ISO 8601 [week date](./struct.NaiveDate.html#week-date). |
17 | /// One can retrieve this type from the existing [`Datelike`](../trait.Datelike.html) types |
18 | /// via the [`Datelike::iso_week`](../trait.Datelike.html#tymethod.iso_week) method. |
19 | #[derive (PartialEq, Eq, PartialOrd, Ord, Copy, Clone, Hash)] |
20 | #[cfg_attr (feature = "rkyv" , derive(Archive, Deserialize, Serialize))] |
21 | pub struct IsoWeek { |
22 | // note that this allows for larger year range than `NaiveDate`. |
23 | // this is crucial because we have an edge case for the first and last week supported, |
24 | // which year number might not match the calendar year number. |
25 | ywf: DateImpl, // (year << 10) | (week << 4) | flag |
26 | } |
27 | |
28 | /// Returns the corresponding `IsoWeek` from the year and the `Of` internal value. |
29 | // |
30 | // internal use only. we don't expose the public constructor for `IsoWeek` for now, |
31 | // because the year range for the week date and the calendar date do not match and |
32 | // it is confusing to have a date that is out of range in one and not in another. |
33 | // currently we sidestep this issue by making `IsoWeek` fully dependent of `Datelike`. |
34 | pub(super) fn iso_week_from_yof(year: i32, of: Of) -> IsoWeek { |
35 | let (rawweek: u32, _) = of.isoweekdate_raw(); |
36 | let (year: i32, week: u32) = if rawweek < 1 { |
37 | // previous year |
38 | let prevlastweek: u32 = YearFlags::from_year(year - 1).nisoweeks(); |
39 | (year - 1, prevlastweek) |
40 | } else { |
41 | let lastweek: u32 = of.flags().nisoweeks(); |
42 | if rawweek > lastweek { |
43 | // next year |
44 | (year + 1, 1) |
45 | } else { |
46 | (year, rawweek) |
47 | } |
48 | }; |
49 | let flags: YearFlags = YearFlags::from_year(year); |
50 | IsoWeek { ywf: (year << 10) | (week << 4) as DateImpl | DateImpl::from(flags.0) } |
51 | } |
52 | |
53 | impl IsoWeek { |
54 | /// Returns the year number for this ISO week. |
55 | /// |
56 | /// # Example |
57 | /// |
58 | /// ``` |
59 | /// use chrono::{NaiveDate, Datelike, Weekday}; |
60 | /// |
61 | /// let d = NaiveDate::from_isoywd_opt(2015, 1, Weekday::Mon).unwrap(); |
62 | /// assert_eq!(d.iso_week().year(), 2015); |
63 | /// ``` |
64 | /// |
65 | /// This year number might not match the calendar year number. |
66 | /// Continuing the example... |
67 | /// |
68 | /// ``` |
69 | /// # use chrono::{NaiveDate, Datelike, Weekday}; |
70 | /// # let d = NaiveDate::from_isoywd_opt(2015, 1, Weekday::Mon).unwrap(); |
71 | /// assert_eq!(d.year(), 2014); |
72 | /// assert_eq!(d, NaiveDate::from_ymd_opt(2014, 12, 29).unwrap()); |
73 | /// ``` |
74 | #[inline ] |
75 | pub const fn year(&self) -> i32 { |
76 | self.ywf >> 10 |
77 | } |
78 | |
79 | /// Returns the ISO week number starting from 1. |
80 | /// |
81 | /// The return value ranges from 1 to 53. (The last week of year differs by years.) |
82 | /// |
83 | /// # Example |
84 | /// |
85 | /// ``` |
86 | /// use chrono::{NaiveDate, Datelike, Weekday}; |
87 | /// |
88 | /// let d = NaiveDate::from_isoywd_opt(2015, 15, Weekday::Mon).unwrap(); |
89 | /// assert_eq!(d.iso_week().week(), 15); |
90 | /// ``` |
91 | #[inline ] |
92 | pub const fn week(&self) -> u32 { |
93 | ((self.ywf >> 4) & 0x3f) as u32 |
94 | } |
95 | |
96 | /// Returns the ISO week number starting from 0. |
97 | /// |
98 | /// The return value ranges from 0 to 52. (The last week of year differs by years.) |
99 | /// |
100 | /// # Example |
101 | /// |
102 | /// ``` |
103 | /// use chrono::{NaiveDate, Datelike, Weekday}; |
104 | /// |
105 | /// let d = NaiveDate::from_isoywd_opt(2015, 15, Weekday::Mon).unwrap(); |
106 | /// assert_eq!(d.iso_week().week0(), 14); |
107 | /// ``` |
108 | #[inline ] |
109 | pub const fn week0(&self) -> u32 { |
110 | ((self.ywf >> 4) & 0x3f) as u32 - 1 |
111 | } |
112 | } |
113 | |
114 | /// The `Debug` output of the ISO week `w` is the same as |
115 | /// [`d.format("%G-W%V")`](../format/strftime/index.html) |
116 | /// where `d` is any `NaiveDate` value in that week. |
117 | /// |
118 | /// # Example |
119 | /// |
120 | /// ``` |
121 | /// use chrono::{NaiveDate, Datelike}; |
122 | /// |
123 | /// assert_eq!(format!("{:?}" , NaiveDate::from_ymd_opt(2015, 9, 5).unwrap().iso_week()), "2015-W36" ); |
124 | /// assert_eq!(format!("{:?}" , NaiveDate::from_ymd_opt( 0, 1, 3).unwrap().iso_week()), "0000-W01" ); |
125 | /// assert_eq!(format!("{:?}" , NaiveDate::from_ymd_opt(9999, 12, 31).unwrap().iso_week()), "9999-W52" ); |
126 | /// ``` |
127 | /// |
128 | /// ISO 8601 requires an explicit sign for years before 1 BCE or after 9999 CE. |
129 | /// |
130 | /// ``` |
131 | /// # use chrono::{NaiveDate, Datelike}; |
132 | /// assert_eq!(format!("{:?}" , NaiveDate::from_ymd_opt( 0, 1, 2).unwrap().iso_week()), "-0001-W52" ); |
133 | /// assert_eq!(format!("{:?}" , NaiveDate::from_ymd_opt(10000, 12, 31).unwrap().iso_week()), "+10000-W52" ); |
134 | /// ``` |
135 | impl fmt::Debug for IsoWeek { |
136 | fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { |
137 | let year: i32 = self.year(); |
138 | let week: u32 = self.week(); |
139 | if (0..=9999).contains(&year) { |
140 | write!(f, " {:04}-W {:02}" , year, week) |
141 | } else { |
142 | // ISO 8601 requires the explicit sign for out-of-range years |
143 | write!(f, " {:+05}-W {:02}" , year, week) |
144 | } |
145 | } |
146 | } |
147 | |
148 | #[cfg (test)] |
149 | mod tests { |
150 | use crate::naive::{internals, NaiveDate}; |
151 | use crate::Datelike; |
152 | |
153 | #[test ] |
154 | fn test_iso_week_extremes() { |
155 | let minweek = NaiveDate::MIN.iso_week(); |
156 | let maxweek = NaiveDate::MAX.iso_week(); |
157 | |
158 | assert_eq!(minweek.year(), internals::MIN_YEAR); |
159 | assert_eq!(minweek.week(), 1); |
160 | assert_eq!(minweek.week0(), 0); |
161 | assert_eq!(format!(" {:?}" , minweek), NaiveDate::MIN.format("%G-W%V" ).to_string()); |
162 | |
163 | assert_eq!(maxweek.year(), internals::MAX_YEAR + 1); |
164 | assert_eq!(maxweek.week(), 1); |
165 | assert_eq!(maxweek.week0(), 0); |
166 | assert_eq!(format!(" {:?}" , maxweek), NaiveDate::MAX.format("%G-W%V" ).to_string()); |
167 | } |
168 | |
169 | #[test ] |
170 | fn test_iso_week_equivalence_for_first_week() { |
171 | let monday = NaiveDate::from_ymd_opt(2024, 12, 30).unwrap(); |
172 | let friday = NaiveDate::from_ymd_opt(2025, 1, 3).unwrap(); |
173 | |
174 | assert_eq!(monday.iso_week(), friday.iso_week()); |
175 | } |
176 | |
177 | #[test ] |
178 | fn test_iso_week_equivalence_for_last_week() { |
179 | let monday = NaiveDate::from_ymd_opt(2026, 12, 28).unwrap(); |
180 | let friday = NaiveDate::from_ymd_opt(2027, 1, 1).unwrap(); |
181 | |
182 | assert_eq!(monday.iso_week(), friday.iso_week()); |
183 | } |
184 | |
185 | #[test ] |
186 | fn test_iso_week_ordering_for_first_week() { |
187 | let monday = NaiveDate::from_ymd_opt(2024, 12, 30).unwrap(); |
188 | let friday = NaiveDate::from_ymd_opt(2025, 1, 3).unwrap(); |
189 | |
190 | assert!(monday.iso_week() >= friday.iso_week()); |
191 | assert!(monday.iso_week() <= friday.iso_week()); |
192 | } |
193 | |
194 | #[test ] |
195 | fn test_iso_week_ordering_for_last_week() { |
196 | let monday = NaiveDate::from_ymd_opt(2026, 12, 28).unwrap(); |
197 | let friday = NaiveDate::from_ymd_opt(2027, 1, 1).unwrap(); |
198 | |
199 | assert!(monday.iso_week() >= friday.iso_week()); |
200 | assert!(monday.iso_week() <= friday.iso_week()); |
201 | } |
202 | } |
203 | |