deep_time/dt/arithmetic_calendar.rs
1use crate::Dt;
2
3#[cfg(feature = "jiff-tz")]
4use crate::DtErr;
5
6impl Dt {
7 /// Adds (or subtracts) calendar years, preserving month and day-of-month.
8 /// - Uses standard last-day-of-month clamping.
9 /// - Negative values subtract.
10 #[inline(always)]
11 pub const fn add_yr(&self, n: i64) -> Self {
12 self.to_ymd().add_yr(n).to_dt()
13 }
14
15 /// Adds (or subtracts) calendar months.
16 /// Negative values subtract.
17 #[inline(always)]
18 pub const fn add_mo(&self, n: i64) -> Self {
19 self.to_ymd().add_mo(n).to_dt()
20 }
21
22 /// Adds (or subtracts) calendar weeks.
23 /// Negative values subtract.
24 #[inline(always)]
25 pub const fn add_wk(&self, n: i64) -> Self {
26 self.to_ymd().add_wk(n).to_dt()
27 }
28
29 /// Adds (or subtracts) calendar days.
30 /// Negative values subtract.
31 #[inline(always)]
32 pub const fn add_days(&self, n: i64) -> Self {
33 self.to_ymd().add_days(n).to_dt()
34 }
35}
36
37#[cfg(feature = "jiff-tz")]
38impl Dt {
39 /// Adds the given number of years in the specified IANA timezone,
40 /// respecting timezone rules (including DST) and calendar arithmetic.
41 ///
42 /// ## Notes
43 ///
44 /// - Requires the `jiff-tz` feature.
45 /// - Assumes this [`Dt`] is counting seconds from the library's
46 /// `2000-01-01 12:00:00` epoch.
47 ///
48 /// ## Errors
49 ///
50 /// - Jiff only supports years in the range `-9999..=9999`. Years outside
51 /// this range will return a [`DtErr`].
52 /// - If Jiff cannot find the timezone name or if applying the timezone would cause
53 /// the [`jiff::Zoned`] to be outside the `-9999..=9999` year range then a
54 /// [`DtErr`] with [`DtErrKind::InvalidTimezoneOffset`] is returned.
55 #[inline(always)]
56 pub fn add_yr_tz(&self, n: i64, tz: &str) -> Result<Self, DtErr> {
57 Ok(self.to_ymd().add_yr_tz(n, tz)?.to_dt())
58 }
59
60 /// Adds the given number of months in the specified IANA timezone,
61 /// respecting timezone rules and calendar month-end clamping.
62 ///
63 /// ## Notes
64 ///
65 /// - Requires the `jiff-tz` feature.
66 /// - Assumes this [`Dt`] is counting seconds from the library's
67 /// `2000-01-01 12:00:00` epoch.
68 /// - Will error if the year is outside of `-9999..=9999`.
69 ///
70 /// ## Errors
71 ///
72 /// - Jiff only supports years in the range `-9999..=9999`. Years outside
73 /// this range will return a [`DtErr`].
74 /// - If Jiff cannot find the timezone name or if applying the timezone would cause
75 /// the [`jiff::Zoned`] to be outside the `-9999..=9999` year range then a
76 /// [`DtErr`] with [`DtErrKind::InvalidTimezoneOffset`] is returned.
77 #[inline(always)]
78 pub fn add_mo_tz(&self, n: i64, tz: &str) -> Result<Self, DtErr> {
79 Ok(self.to_ymd().add_mo_tz(n, tz)?.to_dt())
80 }
81
82 /// Adds the given number of weeks in the specified IANA timezone,
83 /// respecting timezone rules (including DST).
84 ///
85 /// ## Notes
86 ///
87 /// - Requires the `jiff-tz` feature.
88 /// - Assumes this [`Dt`] is counting seconds from the library's
89 /// `2000-01-01 12:00:00` epoch.
90 /// - Will error if the year is outside of `-9999..=9999`.
91 ///
92 /// ## Errors
93 ///
94 /// - Jiff only supports years in the range `-9999..=9999`. Years outside
95 /// this range will return a [`DtErr`].
96 /// - If Jiff cannot find the timezone name or if applying the timezone would cause
97 /// the [`jiff::Zoned`] to be outside the `-9999..=9999` year range then a
98 /// [`DtErr`] with [`DtErrKind::InvalidTimezoneOffset`] is returned.
99 #[inline(always)]
100 pub fn add_wk_tz(&self, n: i64, tz: &str) -> Result<Self, DtErr> {
101 Ok(self.to_ymd().add_wk_tz(n, tz)?.to_dt())
102 }
103
104 /// Adds the given number of calendar days in the specified IANA timezone,
105 /// respecting timezone rules (including DST).
106 ///
107 /// ## Notes
108 ///
109 /// - Requires the `jiff-tz` feature.
110 /// - Assumes this [`Dt`] is counting seconds from the library's
111 /// `2000-01-01 12:00:00` epoch.
112 /// - Will error if the year is outside of `-9999..=9999`.
113 ///
114 /// ## Errors
115 ///
116 /// - Jiff only supports years in the range `-9999..=9999`. Years outside
117 /// this range will return a [`DtErr`].
118 /// - If Jiff cannot find the timezone name or if applying the timezone would cause
119 /// the [`jiff::Zoned`] to be outside the `-9999..=9999` year range then a
120 /// [`DtErr`] with [`DtErrKind::InvalidTimezoneOffset`] is returned.
121 #[inline(always)]
122 pub fn add_days_tz(&self, n: i64, tz: &str) -> Result<Self, DtErr> {
123 Ok(self.to_ymd().add_days_tz(n, tz)?.to_dt())
124 }
125
126 /// Adds the given number of hours in the specified IANA timezone,
127 /// respecting timezone rules (including DST).
128 ///
129 /// ## Notes
130 ///
131 /// - Requires the `jiff-tz` feature.
132 /// - Assumes this [`Dt`] is counting seconds from the library's
133 /// `2000-01-01 12:00:00` epoch.
134 /// - Will error if the year is outside of `-9999..=9999`.
135 ///
136 /// ## Errors
137 ///
138 /// - Jiff only supports years in the range `-9999..=9999`. Years outside
139 /// this range will return a [`DtErr`].
140 /// - If Jiff cannot find the timezone name or if applying the timezone would cause
141 /// the [`jiff::Zoned`] to be outside the `-9999..=9999` year range then a
142 /// [`DtErr`] with [`DtErrKind::InvalidTimezoneOffset`] is returned.
143 #[inline(always)]
144 pub fn add_hr_tz(&self, n: i64, tz: &str) -> Result<Self, DtErr> {
145 Ok(self.to_ymd().add_hr_tz(n, tz)?.to_dt())
146 }
147
148 /// Adds the given number of minutes in the specified IANA timezone,
149 /// respecting timezone rules (including DST).
150 ///
151 /// ## Notes
152 ///
153 /// - Requires the `jiff-tz` feature.
154 /// - Assumes this [`Dt`] is counting seconds from the library's
155 /// `2000-01-01 12:00:00` epoch.
156 /// - Will error if the year is outside of `-9999..=9999`.
157 ///
158 /// ## Errors
159 ///
160 /// - Jiff only supports years in the range `-9999..=9999`. Years outside
161 /// this range will return a [`DtErr`].
162 /// - If Jiff cannot find the timezone name or if applying the timezone would cause
163 /// the [`jiff::Zoned`] to be outside the `-9999..=9999` year range then a
164 /// [`DtErr`] with [`DtErrKind::InvalidTimezoneOffset`] is returned.
165 #[inline(always)]
166 pub fn add_min_tz(&self, n: i64, tz: &str) -> Result<Self, DtErr> {
167 Ok(self.to_ymd().add_min_tz(n, tz)?.to_dt())
168 }
169
170 /// Adds the given number of seconds in the specified IANA timezone,
171 /// respecting timezone rules (including DST).
172 ///
173 /// ## Notes
174 ///
175 /// - Requires the `jiff-tz` feature.
176 /// - Assumes this [`Dt`] is counting seconds from the library's
177 /// `2000-01-01 12:00:00` epoch.
178 /// - Will error if the year is outside of `-9999..=9999`.
179 ///
180 /// ## Errors
181 ///
182 /// - Jiff only supports years in the range `-9999..=9999`. Years outside
183 /// this range will return a [`DtErr`].
184 /// - If Jiff cannot find the timezone name or if applying the timezone would cause
185 /// the [`jiff::Zoned`] to be outside the `-9999..=9999` year range then a
186 /// [`DtErr`] with [`DtErrKind::InvalidTimezoneOffset`] is returned.
187 #[inline(always)]
188 pub fn add_sec_tz(&self, n: i64, tz: &str) -> Result<Self, DtErr> {
189 Ok(self.to_ymd().add_sec_tz(n, tz)?.to_dt())
190 }
191}