1// This is a part of Chrono.
2// See README.md and LICENSE.txt for details.
3
4//! ISO 8601 week.
5
6use core::fmt;
7
8use super::internals::{DateImpl, Of, YearFlags};
9
10#[cfg(feature = "rkyv")]
11use 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))]
21pub 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`.
34pub(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
53impl 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/// ```
135impl 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)]
149mod 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