tz/parse/
tz_string.rs

1//! Functions used for parsing a TZ string.
2
3use crate::error::parse::{ParseDataError, TzStringError};
4use crate::error::TzError;
5use crate::parse::utils::{read_exact, read_optional_tag, read_tag, read_until, read_while, Cursor};
6use crate::timezone::{AlternateTime, Julian0WithLeap, Julian1WithoutLeap, LocalTimeType, MonthWeekDay, RuleDay, TransitionRule};
7
8use core::num::ParseIntError;
9use core::str::{self, FromStr};
10
11/// Convert the `Err` variant of a `Result`
12fn map_err<T>(result: Result<T, ParseDataError>) -> Result<T, TzStringError> {
13    Ok(result?)
14}
15
16/// Parse integer from a slice of bytes
17fn parse_int<T: FromStr<Err = ParseIntError>>(bytes: &[u8]) -> Result<T, TzStringError> {
18    Ok(str::from_utf8(bytes)?.parse()?)
19}
20
21/// Parse time zone designation
22fn parse_time_zone_designation<'a>(cursor: &mut Cursor<'a>) -> Result<&'a [u8], ParseDataError> {
23    let unquoted = if cursor.first() == Some(&b'<') {
24        read_exact(cursor, 1)?;
25        let unquoted = read_until(cursor, |&x| x == b'>')?;
26        read_exact(cursor, 1)?;
27        unquoted
28    } else {
29        read_while(cursor, u8::is_ascii_alphabetic)?
30    };
31
32    Ok(unquoted)
33}
34
35/// Parse hours, minutes and seconds
36fn parse_hhmmss(cursor: &mut Cursor<'_>) -> Result<(i32, i32, i32), TzStringError> {
37    let hour = parse_int(read_while(cursor, u8::is_ascii_digit)?)?;
38
39    let mut minute = 0;
40    let mut second = 0;
41
42    if read_optional_tag(cursor, b":")? {
43        minute = parse_int(read_while(cursor, u8::is_ascii_digit)?)?;
44
45        if read_optional_tag(cursor, b":")? {
46            second = parse_int(read_while(cursor, u8::is_ascii_digit)?)?;
47        }
48    }
49
50    Ok((hour, minute, second))
51}
52
53/// Parse signed hours, minutes and seconds
54fn parse_signed_hhmmss(cursor: &mut Cursor<'_>) -> Result<(i32, i32, i32, i32), TzStringError> {
55    let mut sign = 1;
56    if let Some(&c @ b'+') | Some(&c @ b'-') = cursor.first() {
57        read_exact(cursor, 1)?;
58        if c == b'-' {
59            sign = -1;
60        }
61    }
62
63    let (hour, minute, second) = parse_hhmmss(cursor)?;
64    Ok((sign, hour, minute, second))
65}
66
67/// Parse time zone offset
68fn parse_offset(cursor: &mut Cursor<'_>) -> Result<i32, TzStringError> {
69    let (sign, hour, minute, second) = parse_signed_hhmmss(cursor)?;
70
71    if !(0..=24).contains(&hour) {
72        return Err(TzStringError::InvalidOffsetHour);
73    }
74    if !(0..=59).contains(&minute) {
75        return Err(TzStringError::InvalidOffsetMinute);
76    }
77    if !(0..=59).contains(&second) {
78        return Err(TzStringError::InvalidOffsetSecond);
79    }
80
81    Ok(sign * (hour * 3600 + minute * 60 + second))
82}
83
84/// Parse transition rule day
85fn parse_rule_day(cursor: &mut Cursor<'_>) -> Result<RuleDay, TzError> {
86    match cursor.first() {
87        Some(b'J') => {
88            map_err(read_exact(cursor, 1))?;
89            let data = map_err(read_while(cursor, u8::is_ascii_digit))?;
90            Ok(RuleDay::Julian1WithoutLeap(Julian1WithoutLeap::new(parse_int(data)?)?))
91        }
92        Some(b'M') => {
93            map_err(read_exact(cursor, 1))?;
94
95            let month = parse_int(map_err(read_while(cursor, u8::is_ascii_digit))?)?;
96            map_err(read_tag(cursor, b"."))?;
97            let week = parse_int(map_err(read_while(cursor, u8::is_ascii_digit))?)?;
98            map_err(read_tag(cursor, b"."))?;
99            let week_day = parse_int(map_err(read_while(cursor, u8::is_ascii_digit))?)?;
100
101            Ok(RuleDay::MonthWeekDay(MonthWeekDay::new(month, week, week_day)?))
102        }
103        _ => {
104            let data = map_err(read_while(cursor, u8::is_ascii_digit))?;
105            Ok(RuleDay::Julian0WithLeap(Julian0WithLeap::new(parse_int(data)?)?))
106        }
107    }
108}
109
110/// Parse transition rule time
111fn parse_rule_time(cursor: &mut Cursor<'_>) -> Result<i32, TzStringError> {
112    let (hour, minute, second) = parse_hhmmss(cursor)?;
113
114    if !(0..=24).contains(&hour) {
115        return Err(TzStringError::InvalidDayTimeHour);
116    }
117    if !(0..=59).contains(&minute) {
118        return Err(TzStringError::InvalidDayTimeMinute);
119    }
120    if !(0..=59).contains(&second) {
121        return Err(TzStringError::InvalidDayTimeSecond);
122    }
123
124    Ok(hour * 3600 + minute * 60 + second)
125}
126
127/// Parse transition rule time with TZ string extensions
128fn parse_rule_time_extended(cursor: &mut Cursor<'_>) -> Result<i32, TzStringError> {
129    let (sign, hour, minute, second) = parse_signed_hhmmss(cursor)?;
130
131    if !(-167..=167).contains(&hour) {
132        return Err(TzStringError::InvalidDayTimeHour);
133    }
134    if !(0..=59).contains(&minute) {
135        return Err(TzStringError::InvalidDayTimeMinute);
136    }
137    if !(0..=59).contains(&second) {
138        return Err(TzStringError::InvalidDayTimeSecond);
139    }
140
141    Ok(sign * (hour * 3600 + minute * 60 + second))
142}
143
144/// Parse transition rule
145fn parse_rule_block(cursor: &mut Cursor<'_>, use_string_extensions: bool) -> Result<(RuleDay, i32), TzError> {
146    let date = parse_rule_day(cursor)?;
147
148    let time = if map_err(read_optional_tag(cursor, b"/"))? {
149        if use_string_extensions {
150            parse_rule_time_extended(cursor)?
151        } else {
152            parse_rule_time(cursor)?
153        }
154    } else {
155        2 * 3600
156    };
157
158    Ok((date, time))
159}
160
161/// Parse a POSIX TZ string containing a time zone description, as described in [the POSIX documentation of the `TZ` environment variable](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html).
162///
163/// TZ string extensions from [RFC 8536](https://datatracker.ietf.org/doc/html/rfc8536#section-3.3.1) may be used.
164///
165pub(crate) fn parse_posix_tz(tz_string: &[u8], use_string_extensions: bool) -> Result<TransitionRule, TzError> {
166    let mut cursor = tz_string;
167
168    let std_time_zone = Some(map_err(parse_time_zone_designation(&mut cursor))?);
169    let std_offset = parse_offset(&mut cursor)?;
170
171    if cursor.is_empty() {
172        return Ok(TransitionRule::Fixed(LocalTimeType::new(-std_offset, false, std_time_zone)?));
173    }
174
175    let dst_time_zone = Some(map_err(parse_time_zone_designation(&mut cursor))?);
176
177    let dst_offset = match cursor.first() {
178        Some(&b',') => std_offset - 3600,
179        Some(_) => parse_offset(&mut cursor)?,
180        None => return Err(TzError::TzString(TzStringError::MissingDstStartEndRules)),
181    };
182
183    if cursor.is_empty() {
184        return Err(TzError::TzString(TzStringError::MissingDstStartEndRules));
185    }
186
187    map_err(read_tag(&mut cursor, b","))?;
188    let (dst_start, dst_start_time) = parse_rule_block(&mut cursor, use_string_extensions)?;
189
190    map_err(read_tag(&mut cursor, b","))?;
191    let (dst_end, dst_end_time) = parse_rule_block(&mut cursor, use_string_extensions)?;
192
193    if !cursor.is_empty() {
194        return Err(TzError::TzString(TzStringError::RemainingData));
195    }
196
197    Ok(TransitionRule::Alternate(AlternateTime::new(
198        LocalTimeType::new(-std_offset, false, std_time_zone)?,
199        LocalTimeType::new(-dst_offset, true, dst_time_zone)?,
200        dst_start,
201        dst_start_time,
202        dst_end,
203        dst_end_time,
204    )?))
205}
206
207#[cfg(test)]
208mod tests {
209    use super::*;
210
211    #[test]
212    fn test_no_dst() -> Result<(), TzError> {
213        let tz_string = b"HST10";
214
215        let transition_rule = parse_posix_tz(tz_string, false)?;
216        let transition_rule_result = TransitionRule::Fixed(LocalTimeType::new(-36000, false, Some(b"HST"))?);
217
218        assert_eq!(transition_rule, transition_rule_result);
219
220        Ok(())
221    }
222
223    #[test]
224    fn test_quoted() -> Result<(), TzError> {
225        let tz_string = b"<-03>+3<+03>-3,J1,J365";
226
227        let transition_rule = parse_posix_tz(tz_string, false)?;
228
229        let transition_rule_result = TransitionRule::Alternate(AlternateTime::new(
230            LocalTimeType::new(-10800, false, Some(b"-03"))?,
231            LocalTimeType::new(10800, true, Some(b"+03"))?,
232            RuleDay::Julian1WithoutLeap(Julian1WithoutLeap::new(1)?),
233            7200,
234            RuleDay::Julian1WithoutLeap(Julian1WithoutLeap::new(365)?),
235            7200,
236        )?);
237
238        assert_eq!(transition_rule, transition_rule_result);
239
240        Ok(())
241    }
242
243    #[test]
244    fn test_full() -> Result<(), TzError> {
245        let tz_string = b"NZST-12:00:00NZDT-13:00:00,M10.1.0/02:00:00,M3.3.0/02:00:00";
246
247        let transition_rule = parse_posix_tz(tz_string, false)?;
248
249        let transition_rule_result = TransitionRule::Alternate(AlternateTime::new(
250            LocalTimeType::new(43200, false, Some(b"NZST"))?,
251            LocalTimeType::new(46800, true, Some(b"NZDT"))?,
252            RuleDay::MonthWeekDay(MonthWeekDay::new(10, 1, 0)?),
253            7200,
254            RuleDay::MonthWeekDay(MonthWeekDay::new(3, 3, 0)?),
255            7200,
256        )?);
257
258        assert_eq!(transition_rule, transition_rule_result);
259
260        Ok(())
261    }
262
263    #[test]
264    fn test_negative_dst() -> Result<(), TzError> {
265        let tz_string = b"IST-1GMT0,M10.5.0,M3.5.0/1";
266
267        let transition_rule = parse_posix_tz(tz_string, false)?;
268
269        let transition_rule_result = TransitionRule::Alternate(AlternateTime::new(
270            LocalTimeType::new(3600, false, Some(b"IST"))?,
271            LocalTimeType::new(0, true, Some(b"GMT"))?,
272            RuleDay::MonthWeekDay(MonthWeekDay::new(10, 5, 0)?),
273            7200,
274            RuleDay::MonthWeekDay(MonthWeekDay::new(3, 5, 0)?),
275            3600,
276        )?);
277
278        assert_eq!(transition_rule, transition_rule_result);
279
280        Ok(())
281    }
282
283    #[test]
284    fn test_negative_hour() -> Result<(), TzError> {
285        let tz_string = b"<-03>3<-02>,M3.5.0/-2,M10.5.0/-1";
286
287        assert!(parse_posix_tz(tz_string, false).is_err());
288
289        let transition_rule = parse_posix_tz(tz_string, true)?;
290
291        let transition_rule_result = TransitionRule::Alternate(AlternateTime::new(
292            LocalTimeType::new(-10800, false, Some(b"-03"))?,
293            LocalTimeType::new(-7200, true, Some(b"-02"))?,
294            RuleDay::MonthWeekDay(MonthWeekDay::new(3, 5, 0)?),
295            -7200,
296            RuleDay::MonthWeekDay(MonthWeekDay::new(10, 5, 0)?),
297            -3600,
298        )?);
299
300        assert_eq!(transition_rule, transition_rule_result);
301
302        Ok(())
303    }
304
305    #[test]
306    fn test_all_year_dst() -> Result<(), TzError> {
307        let tz_string = b"EST5EDT,0/0,J365/25";
308
309        assert!(parse_posix_tz(tz_string, false).is_err());
310
311        let transition_rule = parse_posix_tz(tz_string, true)?;
312
313        let transition_rule_result = TransitionRule::Alternate(AlternateTime::new(
314            LocalTimeType::new(-18000, false, Some(b"EST"))?,
315            LocalTimeType::new(-14400, true, Some(b"EDT"))?,
316            RuleDay::Julian0WithLeap(Julian0WithLeap::new(0)?),
317            0,
318            RuleDay::Julian1WithoutLeap(Julian1WithoutLeap::new(365)?),
319            90000,
320        )?);
321
322        assert_eq!(transition_rule, transition_rule_result);
323
324        Ok(())
325    }
326
327    #[test]
328    fn test_min_dst_offset() -> Result<(), TzError> {
329        let tz_string = b"STD24:59:59DST,J1,J365";
330
331        let transition_rule = parse_posix_tz(tz_string, false)?;
332
333        let transition_rule_result = TransitionRule::Alternate(AlternateTime::new(
334            LocalTimeType::new(-89999, false, Some(b"STD"))?,
335            LocalTimeType::new(-86399, true, Some(b"DST"))?,
336            RuleDay::Julian1WithoutLeap(Julian1WithoutLeap::new(1)?),
337            7200,
338            RuleDay::Julian1WithoutLeap(Julian1WithoutLeap::new(365)?),
339            7200,
340        )?);
341
342        assert_eq!(transition_rule, transition_rule_result);
343
344        Ok(())
345    }
346
347    #[test]
348    fn test_max_dst_offset() -> Result<(), TzError> {
349        let tz_string = b"STD-24:59:59DST,J1,J365";
350
351        let transition_rule = parse_posix_tz(tz_string, false)?;
352
353        let transition_rule_result = TransitionRule::Alternate(AlternateTime::new(
354            LocalTimeType::new(89999, false, Some(b"STD"))?,
355            LocalTimeType::new(93599, true, Some(b"DST"))?,
356            RuleDay::Julian1WithoutLeap(Julian1WithoutLeap::new(1)?),
357            7200,
358            RuleDay::Julian1WithoutLeap(Julian1WithoutLeap::new(365)?),
359            7200,
360        )?);
361
362        assert_eq!(transition_rule, transition_rule_result);
363
364        Ok(())
365    }
366
367    #[test]
368    fn test_error() -> Result<(), TzError> {
369        assert!(matches!(parse_posix_tz(b"IST-1GMT0", false), Err(TzError::TzString(TzStringError::MissingDstStartEndRules))));
370        assert!(matches!(parse_posix_tz(b"EET-2EEST", false), Err(TzError::TzString(TzStringError::MissingDstStartEndRules))));
371
372        Ok(())
373    }
374}
tz/parse/tz_string.rs

tz/parse/
tz_string.rs
