Debian Codegraph @

.cargo/vendor/chrono/src/month.rs

raw
1 use core::fmt;
2
3 #[cfg(any(feature = "rkyv", feature = "rkyv-16", feature = "rkyv-32", feature = "rkyv-64"))]
4 use rkyv::{Archive, Deserialize, Serialize};
5
6 use crate::OutOfRange;
7
8 /// The month of the year.
9 ///
10 /// This enum is just a convenience implementation.
11 /// The month in dates created by DateLike objects does not return this enum.
12 ///
13 /// It is possible to convert from a date to a month independently
14 /// ```
15 /// use chrono::prelude::*;
16 /// let date = Utc.with_ymd_and_hms(2019, 10, 28, 9, 10, 11).unwrap();
17 /// // `2019-10-28T09:10:11Z`
18 /// let month = Month::try_from(u8::try_from(date.month()).unwrap()).ok();
19 /// assert_eq!(month, Some(Month::October))
20 /// ```
21 /// Or from a Month to an integer usable by dates
22 /// ```
23 /// # use chrono::prelude::*;
24 /// let month = Month::January;
25 /// let dt = Utc.with_ymd_and_hms(2019, month.number_from_month(), 28, 9, 10, 11).unwrap();
26 /// assert_eq!((dt.year(), dt.month(), dt.day()), (2019, 1, 28));
27 /// ```
28 /// Allows mapping from and to month, from 1-January to 12-December.
29 /// Can be Serialized/Deserialized with serde
30 // Actual implementation is zero-indexed, API intended as 1-indexed for more intuitive behavior.
31 #[derive(PartialEq, Eq, Copy, Clone, Debug, Hash, PartialOrd, Ord)]
32 #[cfg_attr(
33 any(feature = "rkyv", feature = "rkyv-16", feature = "rkyv-32", feature = "rkyv-64"),
34 derive(Archive, Deserialize, Serialize),
35 archive(compare(PartialEq, PartialOrd)),
36 archive_attr(derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug, Hash))
37 )]
38 #[cfg_attr(feature = "rkyv-validation", archive(check_bytes))]
39 #[cfg_attr(all(feature = "arbitrary", feature = "std"), derive(arbitrary::Arbitrary))]
40 pub enum Month {
41 /// January
42 January = 0,
43 /// February
44 February = 1,
45 /// March
46 March = 2,
47 /// April
48 April = 3,
49 /// May
50 May = 4,
51 /// June
52 June = 5,
53 /// July
54 July = 6,
55 /// August
56 August = 7,
57 /// September
58 September = 8,
59 /// October
60 October = 9,
61 /// November
62 November = 10,
63 /// December
64 December = 11,
65 }
66
67 impl Month {
68 /// The next month.
69 ///
70 /// `m`: | `January` | `February` | `...` | `December`
71 /// ----------- | --------- | ---------- | --- | ---------
72 /// `m.succ()`: | `February` | `March` | `...` | `January`
73 #[inline]
74 #[must_use]
75 pub const fn succ(&self) -> Month {
76 match *self {
77 Month::January => Month::February,
78 Month::February => Month::March,
79 Month::March => Month::April,
80 Month::April => Month::May,
81 Month::May => Month::June,
82 Month::June => Month::July,
83 Month::July => Month::August,
84 Month::August => Month::September,
85 Month::September => Month::October,
86 Month::October => Month::November,
87 Month::November => Month::December,
88 Month::December => Month::January,
89 }
90 }
91
92 /// The previous month.
93 ///
94 /// `m`: | `January` | `February` | `...` | `December`
95 /// ----------- | --------- | ---------- | --- | ---------
96 /// `m.pred()`: | `December` | `January` | `...` | `November`
97 #[inline]
98 #[must_use]
99 pub const fn pred(&self) -> Month {
100 match *self {
101 Month::January => Month::December,
102 Month::February => Month::January,
103 Month::March => Month::February,
104 Month::April => Month::March,
105 Month::May => Month::April,
106 Month::June => Month::May,
107 Month::July => Month::June,
108 Month::August => Month::July,
109 Month::September => Month::August,
110 Month::October => Month::September,
111 Month::November => Month::October,
112 Month::December => Month::November,
113 }
114 }
115
116 /// Returns a month-of-year number starting from January = 1.
117 ///
118 /// `m`: | `January` | `February` | `...` | `December`
119 /// -------------------------| --------- | ---------- | --- | -----
120 /// `m.number_from_month()`: | 1 | 2 | `...` | 12
121 #[inline]
122 #[must_use]
123 pub const fn number_from_month(&self) -> u32 {
124 match *self {
125 Month::January => 1,
126 Month::February => 2,
127 Month::March => 3,
128 Month::April => 4,
129 Month::May => 5,
130 Month::June => 6,
131 Month::July => 7,
132 Month::August => 8,
133 Month::September => 9,
134 Month::October => 10,
135 Month::November => 11,
136 Month::December => 12,
137 }
138 }
139
140 /// Get the name of the month
141 ///
142 /// ```
143 /// use chrono::Month;
144 ///
145 /// assert_eq!(Month::January.name(), "January")
146 /// ```
147 #[must_use]
148 pub const fn name(&self) -> &'static str {
149 match *self {
150 Month::January => "January",
151 Month::February => "February",
152 Month::March => "March",
153 Month::April => "April",
154 Month::May => "May",
155 Month::June => "June",
156 Month::July => "July",
157 Month::August => "August",
158 Month::September => "September",
159 Month::October => "October",
160 Month::November => "November",
161 Month::December => "December",
162 }
163 }
164 }
165
166 impl TryFrom<u8> for Month {
167 type Error = OutOfRange;
168
169 fn try_from(value: u8) -> Result<Self, Self::Error> {
170 match value {
171 1 => Ok(Month::January),
172 2 => Ok(Month::February),
173 3 => Ok(Month::March),
174 4 => Ok(Month::April),
175 5 => Ok(Month::May),
176 6 => Ok(Month::June),
177 7 => Ok(Month::July),
178 8 => Ok(Month::August),
179 9 => Ok(Month::September),
180 10 => Ok(Month::October),
181 11 => Ok(Month::November),
182 12 => Ok(Month::December),
183 _ => Err(OutOfRange::new()),
184 }
185 }
186 }
187
188 impl num_traits::FromPrimitive for Month {
189 /// Returns an `Option<Month>` from a i64, assuming a 1-index, January = 1.
190 ///
191 /// `Month::from_i64(n: i64)`: | `1` | `2` | ... | `12`
192 /// ---------------------------| -------------------- | --------------------- | ... | -----
193 /// ``: | Some(Month::January) | Some(Month::February) | ... | Some(Month::December)
194
195 #[inline]
196 fn from_u64(n: u64) -> Option<Month> {
197 Self::from_u32(n as u32)
198 }
199
200 #[inline]
201 fn from_i64(n: i64) -> Option<Month> {
202 Self::from_u32(n as u32)
203 }
204
205 #[inline]
206 fn from_u32(n: u32) -> Option<Month> {
207 match n {
208 1 => Some(Month::January),
209 2 => Some(Month::February),
210 3 => Some(Month::March),
211 4 => Some(Month::April),
212 5 => Some(Month::May),
213 6 => Some(Month::June),
214 7 => Some(Month::July),
215 8 => Some(Month::August),
216 9 => Some(Month::September),
217 10 => Some(Month::October),
218 11 => Some(Month::November),
219 12 => Some(Month::December),
220 _ => None,
221 }
222 }
223 }
224
225 /// A duration in calendar months
226 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, PartialOrd, Ord)]
227 #[cfg_attr(all(feature = "arbitrary", feature = "std"), derive(arbitrary::Arbitrary))]
228 pub struct Months(pub(crate) u32);
229
230 impl Months {
231 /// Construct a new `Months` from a number of months
232 pub const fn new(num: u32) -> Self {
233 Self(num)
234 }
235
236 /// Returns the total number of months in the `Months` instance.
237 #[inline]
238 pub const fn as_u32(&self) -> u32 {
239 self.0
240 }
241 }
242
243 /// An error resulting from reading `<Month>` value with `FromStr`.
244 #[derive(Clone, PartialEq, Eq)]
245 pub struct ParseMonthError {
246 pub(crate) _dummy: (),
247 }
248
249 #[cfg(feature = "std")]
250 impl std::error::Error for ParseMonthError {}
251
252 impl fmt::Display for ParseMonthError {
253 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
254 write!(f, "ParseMonthError {{ .. }}")
255 }
256 }
257
258 impl fmt::Debug for ParseMonthError {
259 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
260 write!(f, "ParseMonthError {{ .. }}")
261 }
262 }
263
264 #[cfg(feature = "serde")]
265 mod month_serde {
266 use super::Month;
267 use serde::{de, ser};
268
269 use core::fmt;
270
271 impl ser::Serialize for Month {
272 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
273 where
274 S: ser::Serializer,
275 {
276 serializer.collect_str(self.name())
277 }
278 }
279
280 struct MonthVisitor;
281
282 impl<'de> de::Visitor<'de> for MonthVisitor {
283 type Value = Month;
284
285 fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
286 f.write_str("Month")
287 }
288
289 fn visit_str<E>(self, value: &str) -> Result<Self::Value, E>
290 where
291 E: de::Error,
292 {
293 value.parse().map_err(|_| E::custom("short (3-letter) or full month names expected"))
294 }
295 }
296
297 impl<'de> de::Deserialize<'de> for Month {
298 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
299 where
300 D: de::Deserializer<'de>,
301 {
302 deserializer.deserialize_str(MonthVisitor)
303 }
304 }
305 }
306
307 #[cfg(test)]
308 mod tests {
309 use super::Month;
310 use crate::{Datelike, Months, OutOfRange, TimeZone, Utc};
311
312 #[test]
313 fn test_month_enum_try_from() {
314 assert_eq!(Month::try_from(1), Ok(Month::January));
315 assert_eq!(Month::try_from(2), Ok(Month::February));
316 assert_eq!(Month::try_from(12), Ok(Month::December));
317 assert_eq!(Month::try_from(13), Err(OutOfRange::new()));
318
319 let date = Utc.with_ymd_and_hms(2019, 10, 28, 9, 10, 11).unwrap();
320 assert_eq!(Month::try_from(date.month() as u8), Ok(Month::October));
321
322 let month = Month::January;
323 let dt = Utc.with_ymd_and_hms(2019, month.number_from_month(), 28, 9, 10, 11).unwrap();
324 assert_eq!((dt.year(), dt.month(), dt.day()), (2019, 1, 28));
325 }
326
327 #[test]
328 fn test_month_enum_primitive_parse() {
329 use num_traits::FromPrimitive;
330
331 let jan_opt = Month::from_u32(1);
332 let feb_opt = Month::from_u64(2);
333 let dec_opt = Month::from_i64(12);
334 let no_month = Month::from_u32(13);
335 assert_eq!(jan_opt, Some(Month::January));
336 assert_eq!(feb_opt, Some(Month::February));
337 assert_eq!(dec_opt, Some(Month::December));
338 assert_eq!(no_month, None);
339
340 let date = Utc.with_ymd_and_hms(2019, 10, 28, 9, 10, 11).unwrap();
341 assert_eq!(Month::from_u32(date.month()), Some(Month::October));
342
343 let month = Month::January;
344 let dt = Utc.with_ymd_and_hms(2019, month.number_from_month(), 28, 9, 10, 11).unwrap();
345 assert_eq!((dt.year(), dt.month(), dt.day()), (2019, 1, 28));
346 }
347
348 #[test]
349 fn test_month_enum_succ_pred() {
350 assert_eq!(Month::January.succ(), Month::February);
351 assert_eq!(Month::December.succ(), Month::January);
352 assert_eq!(Month::January.pred(), Month::December);
353 assert_eq!(Month::February.pred(), Month::January);
354 }
355
356 #[test]
357 fn test_month_partial_ord() {
358 assert!(Month::January <= Month::January);
359 assert!(Month::January < Month::February);
360 assert!(Month::January < Month::December);
361 assert!(Month::July >= Month::May);
362 assert!(Month::September > Month::March);
363 }
364
365 #[test]
366 fn test_months_as_u32() {
367 assert_eq!(Months::new(0).as_u32(), 0);
368 assert_eq!(Months::new(1).as_u32(), 1);
369 assert_eq!(Months::new(u32::MAX).as_u32(), u32::MAX);
370 }
371
372 #[test]
373 #[cfg(feature = "serde")]
374 fn test_serde_serialize() {
375 use serde_json::to_string;
376 use Month::*;
377
378 let cases: Vec<(Month, &str)> = vec![
379 (January, "\"January\""),
380 (February, "\"February\""),
381 (March, "\"March\""),
382 (April, "\"April\""),
383 (May, "\"May\""),
384 (June, "\"June\""),
385 (July, "\"July\""),
386 (August, "\"August\""),
387 (September, "\"September\""),
388 (October, "\"October\""),
389 (November, "\"November\""),
390 (December, "\"December\""),
391 ];
392
393 for (month, expected_str) in cases {
394 let string = to_string(&month).unwrap();
395 assert_eq!(string, expected_str);
396 }
397 }
398
399 #[test]
400 #[cfg(feature = "serde")]
401 fn test_serde_deserialize() {
402 use serde_json::from_str;
403 use Month::*;
404
405 let cases: Vec<(&str, Month)> = vec![
406 ("\"january\"", January),
407 ("\"jan\"", January),
408 ("\"FeB\"", February),
409 ("\"MAR\"", March),
410 ("\"mar\"", March),
411 ("\"april\"", April),
412 ("\"may\"", May),
413 ("\"june\"", June),
414 ("\"JULY\"", July),
415 ("\"august\"", August),
416 ("\"september\"", September),
417 ("\"October\"", October),
418 ("\"November\"", November),
419 ("\"DECEmbEr\"", December),
420 ];
421
422 for (string, expected_month) in cases {
423 let month = from_str::<Month>(string).unwrap();
424 assert_eq!(month, expected_month);
425 }
426
427 let errors: Vec<&str> =
428 vec!["\"not a month\"", "\"ja\"", "\"Dece\"", "Dec", "\"Augustin\""];
429
430 for string in errors {
431 from_str::<Month>(string).unwrap_err();
432 }
433 }
434
435 #[test]
436 #[cfg(feature = "rkyv-validation")]
437 fn test_rkyv_validation() {
438 let month = Month::January;
439 let bytes = rkyv::to_bytes::<_, 1>(&month).unwrap();
440 assert_eq!(rkyv::from_bytes::<Month>(&bytes).unwrap(), month);
441 }
442 }