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 /// ## Important
43 ///
44 /// - Assumes this [`Dt`] is counting seconds from the library's
45 /// `2000-01-01 12:00:00` epoch.
46 ///
47 /// ## Errors
48 ///
49 /// - Jiff only supports years in the range `-9999..=9999`. Years outside
50 /// this range will return a [`DtErr`].
51 /// - If Jiff cannot find the timezone name or if applying the timezone would cause
52 /// the [`jiff::Zoned`] to be outside the `-9999..=9999` year range then a
53 /// [`DtErr`] with [`DtErrKind::InvalidTimezoneOffset`] is returned.
54 #[inline(always)]
55 pub fn add_yr_tz(&self, n: i64, tz: &str) -> Result<Self, DtErr> {
56 Ok(self.to_ymd().add_yr_tz(n, tz)?.to_dt())
57 }
58
59 /// Adds the given number of months in the specified IANA timezone,
60 /// respecting timezone rules and calendar month-end clamping.
61 ///
62 /// ## Important
63 ///
64 /// - Assumes this [`Dt`] is counting seconds from the library's
65 /// `2000-01-01 12:00:00` epoch.
66 /// - Will error if the year is outside of `-9999..=9999`.
67 ///
68 /// ## Errors
69 ///
70 /// - Jiff only supports years in the range `-9999..=9999`. Years outside
71 /// this range will return a [`DtErr`].
72 /// - If Jiff cannot find the timezone name or if applying the timezone would cause
73 /// the [`jiff::Zoned`] to be outside the `-9999..=9999` year range then a
74 /// [`DtErr`] with [`DtErrKind::InvalidTimezoneOffset`] is returned.
75 #[inline(always)]
76 pub fn add_mo_tz(&self, n: i64, tz: &str) -> Result<Self, DtErr> {
77 Ok(self.to_ymd().add_mo_tz(n, tz)?.to_dt())
78 }
79
80 /// Adds the given number of weeks in the specified IANA timezone,
81 /// respecting timezone rules (including DST).
82 ///
83 /// ## Important
84 ///
85 /// - Assumes this [`Dt`] is counting seconds from the library's
86 /// `2000-01-01 12:00:00` epoch.
87 /// - Will error if the year is outside of `-9999..=9999`.
88 ///
89 /// ## Errors
90 ///
91 /// - Jiff only supports years in the range `-9999..=9999`. Years outside
92 /// this range will return a [`DtErr`].
93 /// - If Jiff cannot find the timezone name or if applying the timezone would cause
94 /// the [`jiff::Zoned`] to be outside the `-9999..=9999` year range then a
95 /// [`DtErr`] with [`DtErrKind::InvalidTimezoneOffset`] is returned.
96 #[inline(always)]
97 pub fn add_wk_tz(&self, n: i64, tz: &str) -> Result<Self, DtErr> {
98 Ok(self.to_ymd().add_wk_tz(n, tz)?.to_dt())
99 }
100
101 /// Adds the given number of calendar days in the specified IANA timezone,
102 /// respecting timezone rules (including DST).
103 ///
104 /// ## Important
105 ///
106 /// - Assumes this [`Dt`] is counting seconds from the library's
107 /// `2000-01-01 12:00:00` epoch.
108 /// - Will error if the year is outside of `-9999..=9999`.
109 ///
110 /// ## Errors
111 ///
112 /// - Jiff only supports years in the range `-9999..=9999`. Years outside
113 /// this range will return a [`DtErr`].
114 /// - If Jiff cannot find the timezone name or if applying the timezone would cause
115 /// the [`jiff::Zoned`] to be outside the `-9999..=9999` year range then a
116 /// [`DtErr`] with [`DtErrKind::InvalidTimezoneOffset`] is returned.
117 #[inline(always)]
118 pub fn add_days_tz(&self, n: i64, tz: &str) -> Result<Self, DtErr> {
119 Ok(self.to_ymd().add_days_tz(n, tz)?.to_dt())
120 }
121
122 /// Adds the given number of hours in the specified IANA timezone,
123 /// respecting timezone rules (including DST).
124 ///
125 /// ## Important
126 ///
127 /// - Assumes this [`Dt`] is counting seconds from the library's
128 /// `2000-01-01 12:00:00` epoch.
129 /// - Will error if the year is outside of `-9999..=9999`.
130 ///
131 /// ## Errors
132 ///
133 /// - Jiff only supports years in the range `-9999..=9999`. Years outside
134 /// this range will return a [`DtErr`].
135 /// - If Jiff cannot find the timezone name or if applying the timezone would cause
136 /// the [`jiff::Zoned`] to be outside the `-9999..=9999` year range then a
137 /// [`DtErr`] with [`DtErrKind::InvalidTimezoneOffset`] is returned.
138 #[inline(always)]
139 pub fn add_hr_tz(&self, n: i64, tz: &str) -> Result<Self, DtErr> {
140 Ok(self.to_ymd().add_hr_tz(n, tz)?.to_dt())
141 }
142
143 /// Adds the given number of minutes in the specified IANA timezone,
144 /// respecting timezone rules (including DST).
145 ///
146 /// ## Important
147 ///
148 /// - Assumes this [`Dt`] is counting seconds from the library's
149 /// `2000-01-01 12:00:00` epoch.
150 /// - Will error if the year is outside of `-9999..=9999`.
151 ///
152 /// ## Errors
153 ///
154 /// - Jiff only supports years in the range `-9999..=9999`. Years outside
155 /// this range will return a [`DtErr`].
156 /// - If Jiff cannot find the timezone name or if applying the timezone would cause
157 /// the [`jiff::Zoned`] to be outside the `-9999..=9999` year range then a
158 /// [`DtErr`] with [`DtErrKind::InvalidTimezoneOffset`] is returned.
159 #[inline(always)]
160 pub fn add_min_tz(&self, n: i64, tz: &str) -> Result<Self, DtErr> {
161 Ok(self.to_ymd().add_min_tz(n, tz)?.to_dt())
162 }
163
164 /// Adds the given number of seconds in the specified IANA timezone,
165 /// respecting timezone rules (including DST).
166 ///
167 /// ## Important
168 ///
169 /// - Assumes this [`Dt`] is counting seconds from the library's
170 /// `2000-01-01 12:00:00` epoch.
171 /// - Will error if the year is outside of `-9999..=9999`.
172 ///
173 /// ## Errors
174 ///
175 /// - Jiff only supports years in the range `-9999..=9999`. Years outside
176 /// this range will return a [`DtErr`].
177 /// - If Jiff cannot find the timezone name or if applying the timezone would cause
178 /// the [`jiff::Zoned`] to be outside the `-9999..=9999` year range then a
179 /// [`DtErr`] with [`DtErrKind::InvalidTimezoneOffset`] is returned.
180 #[inline(always)]
181 pub fn add_sec_tz(&self, n: i64, tz: &str) -> Result<Self, DtErr> {
182 Ok(self.to_ymd().add_sec_tz(n, tz)?.to_dt())
183 }
184}