chrono/naive/
isoweek.rs

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::YearFlags;
9
10#[cfg(any(feature = "rkyv", feature = "rkyv-16", feature = "rkyv-32", feature = "rkyv-64"))]
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(
21    any(feature = "rkyv", feature = "rkyv-16", feature = "rkyv-32", feature = "rkyv-64"),
22    derive(Archive, Deserialize, Serialize),
23    archive(compare(PartialEq, PartialOrd)),
24    archive_attr(derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug, Hash))
25)]
26#[cfg_attr(feature = "rkyv-validation", archive(check_bytes))]
27pub struct IsoWeek {
28    // Note that this allows for larger year range than `NaiveDate`.
29    // This is crucial because we have an edge case for the first and last week supported,
30    // which year number might not match the calendar year number.
31    ywf: i32, // (year << 10) | (week << 4) | flag
32}
33
34impl IsoWeek {
35    /// Returns the corresponding `IsoWeek` from the year and the `Of` internal value.
36    //
37    // Internal use only. We don't expose the public constructor for `IsoWeek` for now
38    // because the year range for the week date and the calendar date do not match, and
39    // it is confusing to have a date that is out of range in one and not in another.
40    // Currently we sidestep this issue by making `IsoWeek` fully dependent of `Datelike`.
41    pub(super) fn from_yof(year: i32, ordinal: u32, year_flags: YearFlags) -> Self {
42        let rawweek = (ordinal + year_flags.isoweek_delta()) / 7;
43        let (year, week) = if rawweek < 1 {
44            // previous year
45            let prevlastweek = YearFlags::from_year(year - 1).nisoweeks();
46            (year - 1, prevlastweek)
47        } else {
48            let lastweek = year_flags.nisoweeks();
49            if rawweek > lastweek {
50                // next year
51                (year + 1, 1)
52            } else {
53                (year, rawweek)
54            }
55        };
56        let flags = YearFlags::from_year(year);
57        IsoWeek { ywf: (year << 10) | (week << 4) as i32 | i32::from(flags.0) }
58    }
59
60    /// Returns the year number for this ISO week.
61    ///
62    /// # Example
63    ///
64    /// ```
65    /// use chrono::{Datelike, NaiveDate, Weekday};
66    ///
67    /// let d = NaiveDate::from_isoywd_opt(2015, 1, Weekday::Mon).unwrap();
68    /// assert_eq!(d.iso_week().year(), 2015);
69    /// ```
70    ///
71    /// This year number might not match the calendar year number.
72    /// Continuing the example...
73    ///
74    /// ```
75    /// # use chrono::{NaiveDate, Datelike, Weekday};
76    /// # let d = NaiveDate::from_isoywd_opt(2015, 1, Weekday::Mon).unwrap();
77    /// assert_eq!(d.year(), 2014);
78    /// assert_eq!(d, NaiveDate::from_ymd_opt(2014, 12, 29).unwrap());
79    /// ```
80    #[inline]
81    pub const fn year(&self) -> i32 {
82        self.ywf >> 10
83    }
84
85    /// Returns the ISO week number starting from 1.
86    ///
87    /// The return value ranges from 1 to 53. (The last week of year differs by years.)
88    ///
89    /// # Example
90    ///
91    /// ```
92    /// use chrono::{Datelike, NaiveDate, Weekday};
93    ///
94    /// let d = NaiveDate::from_isoywd_opt(2015, 15, Weekday::Mon).unwrap();
95    /// assert_eq!(d.iso_week().week(), 15);
96    /// ```
97    #[inline]
98    pub const fn week(&self) -> u32 {
99        ((self.ywf >> 4) & 0x3f) as u32
100    }
101
102    /// Returns the ISO week number starting from 0.
103    ///
104    /// The return value ranges from 0 to 52. (The last week of year differs by years.)
105    ///
106    /// # Example
107    ///
108    /// ```
109    /// use chrono::{Datelike, NaiveDate, Weekday};
110    ///
111    /// let d = NaiveDate::from_isoywd_opt(2015, 15, Weekday::Mon).unwrap();
112    /// assert_eq!(d.iso_week().week0(), 14);
113    /// ```
114    #[inline]
115    pub const fn week0(&self) -> u32 {
116        ((self.ywf >> 4) & 0x3f) as u32 - 1
117    }
118}
119
120/// The `Debug` output of the ISO week `w` is the same as
121/// [`d.format("%G-W%V")`](../format/strftime/index.html)
122/// where `d` is any `NaiveDate` value in that week.
123///
124/// # Example
125///
126/// ```
127/// use chrono::{Datelike, NaiveDate};
128///
129/// assert_eq!(
130///     format!("{:?}", NaiveDate::from_ymd_opt(2015, 9, 5).unwrap().iso_week()),
131///     "2015-W36"
132/// );
133/// assert_eq!(format!("{:?}", NaiveDate::from_ymd_opt(0, 1, 3).unwrap().iso_week()), "0000-W01");
134/// assert_eq!(
135///     format!("{:?}", NaiveDate::from_ymd_opt(9999, 12, 31).unwrap().iso_week()),
136///     "9999-W52"
137/// );
138/// ```
139///
140/// ISO 8601 requires an explicit sign for years before 1 BCE or after 9999 CE.
141///
142/// ```
143/// # use chrono::{NaiveDate, Datelike};
144/// assert_eq!(format!("{:?}", NaiveDate::from_ymd_opt(0, 1, 2).unwrap().iso_week()), "-0001-W52");
145/// assert_eq!(
146///     format!("{:?}", NaiveDate::from_ymd_opt(10000, 12, 31).unwrap().iso_week()),
147///     "+10000-W52"
148/// );
149/// ```
150impl fmt::Debug for IsoWeek {
151    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
152        let year = self.year();
153        let week = self.week();
154        if (0..=9999).contains(&year) {
155            write!(f, "{year:04}-W{week:02}")
156        } else {
157            // ISO 8601 requires the explicit sign for out-of-range years
158            write!(f, "{year:+05}-W{week:02}")
159        }
160    }
161}
162
163#[cfg(feature = "defmt")]
164impl defmt::Format for IsoWeek {
165    fn format(&self, fmt: defmt::Formatter) {
166        let year = self.year();
167        let week = self.week();
168        if (0..=9999).contains(&year) {
169            defmt::write!(fmt, "{:04}-W{:02}", year, week)
170        } else {
171            // ISO 8601 requires the explicit sign for out-of-range years
172            let sign = ['+', '-'][(year < 0) as usize];
173            defmt::write!(fmt, "{}{:05}-W{:02}", sign, year.abs(), week)
174        }
175    }
176}
177
178#[cfg(test)]
179mod tests {
180    #[cfg(feature = "rkyv-validation")]
181    use super::IsoWeek;
182    use crate::Datelike;
183    use crate::naive::date::{self, NaiveDate};
184
185    #[test]
186    fn test_iso_week_extremes() {
187        let minweek = NaiveDate::MIN.iso_week();
188        let maxweek = NaiveDate::MAX.iso_week();
189
190        assert_eq!(minweek.year(), date::MIN_YEAR);
191        assert_eq!(minweek.week(), 1);
192        assert_eq!(minweek.week0(), 0);
193        #[cfg(feature = "alloc")]
194        assert_eq!(format!("{minweek:?}"), NaiveDate::MIN.format("%G-W%V").to_string());
195
196        assert_eq!(maxweek.year(), date::MAX_YEAR + 1);
197        assert_eq!(maxweek.week(), 1);
198        assert_eq!(maxweek.week0(), 0);
199        #[cfg(feature = "alloc")]
200        assert_eq!(format!("{maxweek:?}"), NaiveDate::MAX.format("%G-W%V").to_string());
201    }
202
203    #[test]
204    fn test_iso_week_equivalence_for_first_week() {
205        let monday = NaiveDate::from_ymd_opt(2024, 12, 30).unwrap();
206        let friday = NaiveDate::from_ymd_opt(2025, 1, 3).unwrap();
207
208        assert_eq!(monday.iso_week(), friday.iso_week());
209    }
210
211    #[test]
212    fn test_iso_week_equivalence_for_last_week() {
213        let monday = NaiveDate::from_ymd_opt(2026, 12, 28).unwrap();
214        let friday = NaiveDate::from_ymd_opt(2027, 1, 1).unwrap();
215
216        assert_eq!(monday.iso_week(), friday.iso_week());
217    }
218
219    #[test]
220    fn test_iso_week_ordering_for_first_week() {
221        let monday = NaiveDate::from_ymd_opt(2024, 12, 30).unwrap();
222        let friday = NaiveDate::from_ymd_opt(2025, 1, 3).unwrap();
223
224        assert!(monday.iso_week() >= friday.iso_week());
225        assert!(monday.iso_week() <= friday.iso_week());
226    }
227
228    #[test]
229    fn test_iso_week_ordering_for_last_week() {
230        let monday = NaiveDate::from_ymd_opt(2026, 12, 28).unwrap();
231        let friday = NaiveDate::from_ymd_opt(2027, 1, 1).unwrap();
232
233        assert!(monday.iso_week() >= friday.iso_week());
234        assert!(monday.iso_week() <= friday.iso_week());
235    }
236
237    #[test]
238    #[cfg(feature = "rkyv-validation")]
239    fn test_rkyv_validation() {
240        let minweek = NaiveDate::MIN.iso_week();
241        let bytes = rkyv::to_bytes::<_, 4>(&minweek).unwrap();
242        assert_eq!(rkyv::from_bytes::<IsoWeek>(&bytes).unwrap(), minweek);
243
244        let maxweek = NaiveDate::MAX.iso_week();
245        let bytes = rkyv::to_bytes::<_, 4>(&maxweek).unwrap();
246        assert_eq!(rkyv::from_bytes::<IsoWeek>(&bytes).unwrap(), maxweek);
247    }
248}
chrono/naive/isoweek.rs

chrono/naive/
isoweek.rs
