Skip to main content

arrow_cast/
parse.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: See the NOTICE file distributed with this work for additional information regarding copyright ownership
3// SPDX-FileContributor: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements
4
5//! [`Parser`] implementations for converting strings to Arrow types
6//!
7//! Used by the CSV and JSON readers to convert strings to Arrow types
8use crate::local_time::resolve_local_datetime;
9use arrow_array::ArrowNativeTypeOp;
10use arrow_array::timezone::Tz;
11use arrow_array::types::*;
12use arrow_buffer::ArrowNativeType;
13use arrow_schema::ArrowError;
14use chrono::prelude::*;
15use half::f16;
16use std::str::FromStr;
17
18/// Parse nanoseconds from the first `N` values in digits, subtracting the offset `O`
19#[inline]
20fn parse_nanos<const N: usize, const O: u8>(digits: &[u8]) -> u32 {
21    digits[..N]
22        .iter()
23        .fold(0_u32, |acc, v| acc * 10 + v.wrapping_sub(O) as u32)
24        * 10_u32.pow((9 - N) as _)
25}
26
27/// Helper for parsing RFC3339 timestamps
28struct TimestampParser {
29    /// The timestamp bytes to parse minus `b'0'`
30    ///
31    /// This makes interpretation as an integer inexpensive
32    digits: [u8; 32],
33    /// A mask containing a `1` bit where the corresponding byte is a valid ASCII digit
34    mask: u32,
35}
36
37impl TimestampParser {
38    fn new(bytes: &[u8]) -> Self {
39        let mut digits = [0; 32];
40        let mut mask = 0;
41
42        // Treating all bytes the same way, helps LLVM vectorise this correctly
43        for (idx, (o, i)) in digits.iter_mut().zip(bytes).enumerate() {
44            *o = i.wrapping_sub(b'0');
45            mask |= ((*o < 10) as u32) << idx
46        }
47
48        Self { digits, mask }
49    }
50
51    /// Returns true if the byte at `idx` in the original string equals `b`
52    fn test(&self, idx: usize, b: u8) -> bool {
53        self.digits[idx] == b.wrapping_sub(b'0')
54    }
55
56    /// Parses a date of the form `1997-01-31`
57    fn date(&self) -> Option<NaiveDate> {
58        if self.mask & 0b1111111111 != 0b1101101111 || !self.test(4, b'-') || !self.test(7, b'-') {
59            return None;
60        }
61
62        let year = self.digits[0] as u16 * 1000
63            + self.digits[1] as u16 * 100
64            + self.digits[2] as u16 * 10
65            + self.digits[3] as u16;
66
67        let month = self.digits[5] * 10 + self.digits[6];
68        let day = self.digits[8] * 10 + self.digits[9];
69
70        NaiveDate::from_ymd_opt(year as _, month as _, day as _)
71    }
72
73    /// Parses a time of any of forms
74    /// - `09:26`
75    /// - `09:26:56`
76    /// - `09:26:56.123`
77    /// - `09:26:56.123456`
78    /// - `09:26:56.123456789`
79    /// - `092656`
80    ///
81    /// Returning the end byte offset
82    fn time(&self) -> Option<(NaiveTime, usize)> {
83        // Make a NaiveTime handling leap seconds
84        let time = |hour, min, sec, nano| match sec {
85            60 => {
86                let nano = 1_000_000_000 + nano;
87                NaiveTime::from_hms_nano_opt(hour as _, min as _, 59, nano)
88            }
89            _ => NaiveTime::from_hms_nano_opt(hour as _, min as _, sec as _, nano),
90        };
91
92        match (self.mask >> 11) & 0b11111111 {
93            // 09:26:56
94            0b11011011 if self.test(13, b':') && self.test(16, b':') => {
95                let hour = self.digits[11] * 10 + self.digits[12];
96                let minute = self.digits[14] * 10 + self.digits[15];
97                let second = self.digits[17] * 10 + self.digits[18];
98
99                match self.test(19, b'.') {
100                    true => {
101                        let digits = (self.mask >> 20).trailing_ones();
102                        let nanos = match digits {
103                            0 => return None,
104                            1 => parse_nanos::<1, 0>(&self.digits[20..21]),
105                            2 => parse_nanos::<2, 0>(&self.digits[20..22]),
106                            3 => parse_nanos::<3, 0>(&self.digits[20..23]),
107                            4 => parse_nanos::<4, 0>(&self.digits[20..24]),
108                            5 => parse_nanos::<5, 0>(&self.digits[20..25]),
109                            6 => parse_nanos::<6, 0>(&self.digits[20..26]),
110                            7 => parse_nanos::<7, 0>(&self.digits[20..27]),
111                            8 => parse_nanos::<8, 0>(&self.digits[20..28]),
112                            _ => parse_nanos::<9, 0>(&self.digits[20..29]),
113                        };
114                        Some((time(hour, minute, second, nanos)?, 20 + digits as usize))
115                    }
116                    false => Some((time(hour, minute, second, 0)?, 19)),
117                }
118            }
119            // 092656
120            0b111111 => {
121                let hour = self.digits[11] * 10 + self.digits[12];
122                let minute = self.digits[13] * 10 + self.digits[14];
123                let second = self.digits[15] * 10 + self.digits[16];
124                let time = time(hour, minute, second, 0)?;
125                Some((time, 17))
126            }
127            // 09:26
128            m if m & 0b111111 == 0b011011
129                && self.test(13, b':')
130                && !self.test(16, b':')
131                && !self.test(16, b'.') =>
132            {
133                let hour = self.digits[11] * 10 + self.digits[12];
134                let minute = self.digits[14] * 10 + self.digits[15];
135                Some((time(hour, minute, 0, 0)?, 16))
136            }
137            _ => None,
138        }
139    }
140}
141
142/// Accepts a string and parses it relative to the provided `timezone`
143///
144/// In addition to RFC3339 / ISO8601 standard timestamps, it also
145/// accepts strings that use a space ` ` to separate the date and time
146/// as well as strings that have no explicit timezone offset.
147///
148/// Examples of accepted inputs:
149/// * `1997-01-31T09:26:56.123Z`        # RCF3339
150/// * `1997-01-31T09:26:56.123-05:00`   # RCF3339
151/// * `1997-01-31T09:26Z`               # ISO8601 without seconds
152/// * `1997-01-31 09:26:56.123-05:00`   # close to RCF3339 but with a space rather than T
153/// * `2023-01-01 04:05:06.789 -08`     # close to RCF3339, no fractional seconds or time separator
154/// * `1997-01-31T09:26:56.123`         # close to RCF3339 but no timezone offset specified
155/// * `1997-01-31 09:26:56.123`         # close to RCF3339 but uses a space and no timezone offset
156/// * `1997-01-31 09:26:56`             # close to RCF3339, no fractional seconds
157/// * `1997-01-31 092656`               # close to RCF3339, no fractional seconds
158/// * `1997-01-31 092656+04:00`         # close to RCF3339, no fractional seconds or time separator
159/// * `1997-01-31`                      # close to RCF3339, only date no time
160///
161/// [IANA timezones] are only supported if the `arrow-array/chrono-tz` feature is enabled
162///
163/// * `2023-01-01 040506 America/Los_Angeles`
164///
165/// A timestamp with no explicit offset is read as a wall clock time in the
166/// relevant timezone, which for an IANA timezone does not always identify a
167/// unique instant. Daylight savings transitions are resolved the same way
168/// PostgreSQL and DuckDB resolve them: an *ambiguous* reading (the repeated
169/// hour when the clocks go back) takes the later instant, and a *nonexistent*
170/// reading (the skipped hour when the clocks go forward) is shifted forward by
171/// the length of the gap.
172///
173/// ```
174/// # use arrow_cast::parse::string_to_datetime;
175/// # use chrono::Utc;
176/// // 02:30 does not exist in America/New_York on 2024-03-10; it is read as 03:30 EDT
177/// let gap = string_to_datetime(&Utc, "2024-03-10 02:30:00 America/New_York").unwrap();
178/// assert_eq!(gap.to_rfc3339(), "2024-03-10T07:30:00+00:00");
179/// // 01:30 happens twice on 2024-11-03; the later (EST) instant is used
180/// let ambiguous = string_to_datetime(&Utc, "2024-11-03 01:30:00 America/New_York").unwrap();
181/// assert_eq!(ambiguous.to_rfc3339(), "2024-11-03T06:30:00+00:00");
182/// ```
183///
184/// Some formats supported by PostgresSql <https://www.postgresql.org/docs/current/datatype-datetime.html#DATATYPE-DATETIME-TIME-TABLE>
185/// are not supported, like
186///
187/// * "2023-01-01 04:05:06.789 +07:30:00",
188/// * "2023-01-01 040506 +07:30:00",
189/// * "2023-01-01 04:05:06.789 PST",
190///
191/// [IANA timezones]: https://www.iana.org/time-zones
192pub fn string_to_datetime<T: TimeZone>(timezone: &T, s: &str) -> Result<DateTime<T>, ArrowError> {
193    let err =
194        |ctx: &str| ArrowError::ParseError(format!("Error parsing timestamp from '{s}': {ctx}"));
195
196    let bytes = s.as_bytes();
197    if bytes.len() < 10 {
198        return Err(err("timestamp must contain at least 10 characters"));
199    }
200
201    let parser = TimestampParser::new(bytes);
202    let date = parser.date().ok_or_else(|| err("error parsing date"))?;
203    if bytes.len() == 10 {
204        let datetime = date.and_time(NaiveTime::MIN);
205        return resolve_local_datetime(timezone, &datetime)
206            .ok_or_else(|| err("error computing timezone offset"));
207    }
208
209    if !parser.test(10, b'T') && !parser.test(10, b't') && !parser.test(10, b' ') {
210        return Err(err("invalid timestamp separator"));
211    }
212
213    let (time, mut tz_offset) = parser.time().ok_or_else(|| err("error parsing time"))?;
214    let datetime = date.and_time(time);
215
216    if tz_offset == 32 {
217        // Decimal overrun
218        while tz_offset < bytes.len() && bytes[tz_offset].is_ascii_digit() {
219            tz_offset += 1;
220        }
221    }
222
223    if bytes.len() <= tz_offset {
224        return resolve_local_datetime(timezone, &datetime)
225            .ok_or_else(|| err("error computing timezone offset"));
226    }
227
228    if (bytes[tz_offset] == b'z' || bytes[tz_offset] == b'Z') && tz_offset == bytes.len() - 1 {
229        return Ok(timezone.from_utc_datetime(&datetime));
230    }
231
232    // Parse remainder of string as timezone
233    let parsed_tz: Tz = s[tz_offset..].trim_start().parse()?;
234    let parsed = resolve_local_datetime(&parsed_tz, &datetime)
235        .ok_or_else(|| err("error computing timezone offset"))?;
236
237    Ok(parsed.with_timezone(timezone))
238}
239
240/// Accepts a string in RFC3339 / ISO8601 standard format and some
241/// variants and converts it to a nanosecond precision timestamp.
242///
243/// See [`string_to_datetime`] for the full set of supported formats
244///
245/// Implements the `to_timestamp` function to convert a string to a
246/// timestamp, following the model of spark SQL’s to_`timestamp`.
247///
248/// Internally, this function uses the `chrono` library for the
249/// datetime parsing
250///
251/// We hope to extend this function in the future with a second
252/// parameter to specifying the format string.
253///
254/// ## Timestamp Precision
255///
256/// Function uses the maximum precision timestamps supported by
257/// Arrow (nanoseconds stored as a 64-bit integer) timestamps. This
258/// means the range of dates that timestamps can represent is ~1677 AD
259/// to 2262 AM
260///
261/// ## Timezone / Offset Handling
262///
263/// Numerical values of timestamps are stored compared to offset UTC.
264///
265/// This function interprets string without an explicit time zone as timestamps
266/// relative to UTC, see [`string_to_datetime`] for alternative semantics
267///
268/// In particular:
269///
270/// ```
271/// # use arrow_cast::parse::string_to_timestamp_nanos;
272/// // Note all three of these timestamps are parsed as the same value
273/// let a = string_to_timestamp_nanos("1997-01-31 09:26:56.123Z").unwrap();
274/// let b = string_to_timestamp_nanos("1997-01-31T09:26:56.123").unwrap();
275/// let c = string_to_timestamp_nanos("1997-01-31T14:26:56.123+05:00").unwrap();
276///
277/// assert_eq!(a, b);
278/// assert_eq!(b, c);
279/// ```
280///
281#[inline]
282pub fn string_to_timestamp_nanos(s: &str) -> Result<i64, ArrowError> {
283    to_timestamp_nanos(string_to_datetime(&Utc, s)?.naive_utc())
284}
285
286/// Fallible conversion of [`NaiveDateTime`] to `i64` nanoseconds
287#[inline]
288fn to_timestamp_nanos(dt: NaiveDateTime) -> Result<i64, ArrowError> {
289    dt.and_utc()
290        .timestamp_nanos_opt()
291        .ok_or_else(|| ArrowError::ParseError(ERR_NANOSECONDS_NOT_SUPPORTED.to_string()))
292}
293
294/// Accepts a string in ISO8601 standard format and some
295/// variants and converts it to nanoseconds since midnight.
296///
297/// Examples of accepted inputs:
298///
299/// * `09:26:56.123 AM`
300/// * `23:59:59`
301/// * `6:00 pm`
302///
303/// Internally, this function uses the `chrono` library for the time parsing
304///
305/// ## Timezone / Offset Handling
306///
307/// This function does not support parsing strings with a timezone
308/// or offset specified, as it considers only time since midnight.
309pub fn string_to_time_nanoseconds(s: &str) -> Result<i64, ArrowError> {
310    let nt = string_to_time(s)
311        .ok_or_else(|| ArrowError::ParseError(format!("Failed to parse \'{s}\' as time")))?;
312    Ok(nt.num_seconds_from_midnight() as i64 * 1_000_000_000 + nt.nanosecond() as i64)
313}
314
315fn string_to_time(s: &str) -> Option<NaiveTime> {
316    let bytes = s.as_bytes();
317    if bytes.len() < 4 {
318        return None;
319    }
320
321    let (am, bytes) = match bytes.get(bytes.len() - 3..) {
322        Some(b" AM" | b" am" | b" Am" | b" aM") => (Some(true), &bytes[..bytes.len() - 3]),
323        Some(b" PM" | b" pm" | b" pM" | b" Pm") => (Some(false), &bytes[..bytes.len() - 3]),
324        _ => (None, bytes),
325    };
326
327    if bytes.len() < 4 {
328        return None;
329    }
330
331    let mut digits = [b'0'; 6];
332
333    // Extract hour
334    let bytes = match (bytes[1], bytes[2]) {
335        (b':', _) => {
336            digits[1] = bytes[0];
337            &bytes[2..]
338        }
339        (_, b':') => {
340            digits[0] = bytes[0];
341            digits[1] = bytes[1];
342            &bytes[3..]
343        }
344        _ => return None,
345    };
346
347    if bytes.len() < 2 {
348        return None; // Minutes required
349    }
350
351    // Extract minutes
352    digits[2] = bytes[0];
353    digits[3] = bytes[1];
354
355    let nanoseconds = match bytes.get(2) {
356        Some(b':') => {
357            if bytes.len() < 5 {
358                return None;
359            }
360
361            // Extract seconds
362            digits[4] = bytes[3];
363            digits[5] = bytes[4];
364
365            // Extract sub-seconds if any
366            match bytes.get(5) {
367                Some(b'.') => {
368                    let decimal = &bytes[6..];
369                    if decimal.iter().any(|x| !x.is_ascii_digit()) {
370                        return None;
371                    }
372                    match decimal.len() {
373                        0 => return None,
374                        1 => parse_nanos::<1, b'0'>(decimal),
375                        2 => parse_nanos::<2, b'0'>(decimal),
376                        3 => parse_nanos::<3, b'0'>(decimal),
377                        4 => parse_nanos::<4, b'0'>(decimal),
378                        5 => parse_nanos::<5, b'0'>(decimal),
379                        6 => parse_nanos::<6, b'0'>(decimal),
380                        7 => parse_nanos::<7, b'0'>(decimal),
381                        8 => parse_nanos::<8, b'0'>(decimal),
382                        _ => parse_nanos::<9, b'0'>(decimal),
383                    }
384                }
385                Some(_) => return None,
386                None => 0,
387            }
388        }
389        Some(_) => return None,
390        None => 0,
391    };
392
393    digits.iter_mut().for_each(|x| *x = x.wrapping_sub(b'0'));
394    if digits.iter().any(|x| *x > 9) {
395        return None;
396    }
397
398    let hour = match (digits[0] * 10 + digits[1], am) {
399        (12, Some(true)) => 0,               // 12:00 AM -> 00:00
400        (h @ 1..=11, Some(true)) => h,       // 1:00 AM -> 01:00
401        (12, Some(false)) => 12,             // 12:00 PM -> 12:00
402        (h @ 1..=11, Some(false)) => h + 12, // 1:00 PM -> 13:00
403        (_, Some(_)) => return None,
404        (h, None) => h,
405    };
406
407    // Handle leap second
408    let (second, nanoseconds) = match digits[4] * 10 + digits[5] {
409        60 => (59, nanoseconds + 1_000_000_000),
410        s => (s, nanoseconds),
411    };
412
413    NaiveTime::from_hms_nano_opt(
414        hour as _,
415        (digits[2] * 10 + digits[3]) as _,
416        second as _,
417        nanoseconds,
418    )
419}
420
421/// Specialized parsing implementations to convert strings to Arrow types.
422///
423/// This is used by csv and json reader and can be used directly as well.
424///
425/// # Example
426///
427/// To parse a string to a [`Date32Type`]:
428///
429/// ```
430/// use arrow_cast::parse::Parser;
431/// use arrow_array::types::Date32Type;
432/// let date = Date32Type::parse("2021-01-01").unwrap();
433/// assert_eq!(date, 18628);
434/// ```
435///
436/// To parse a string to a [`TimestampNanosecondType`]:
437///
438/// ```
439/// use arrow_cast::parse::Parser;
440/// use arrow_array::types::TimestampNanosecondType;
441/// let ts = TimestampNanosecondType::parse("2021-01-01T00:00:00.123456789Z").unwrap();
442/// assert_eq!(ts, 1609459200123456789);
443/// ```
444pub trait Parser: ArrowPrimitiveType {
445    /// Parse a string to the native type
446    fn parse(string: &str) -> Option<Self::Native>;
447
448    /// Parse a string to the native type with a format string
449    ///
450    /// When not implemented, the format string is unused, and this method is equivalent to [parse](#tymethod.parse)
451    fn parse_formatted(string: &str, _format: &str) -> Option<Self::Native> {
452        Self::parse(string)
453    }
454}
455
456impl Parser for Float16Type {
457    fn parse(string: &str) -> Option<f16> {
458        if let Ok(raw_float) = lexical_core::parse(string.as_bytes()) {
459            return Some(f16::from_f32(raw_float));
460        }
461        let string = trim_pre_and_post_whitespace(string);
462        lexical_core::parse(string.as_bytes())
463            .ok()
464            .map(f16::from_f32)
465    }
466}
467
468impl Parser for Float32Type {
469    fn parse(string: &str) -> Option<f32> {
470        if let Ok(raw_float) = lexical_core::parse(string.as_bytes()) {
471            return Some(raw_float);
472        }
473        let string = trim_pre_and_post_whitespace(string);
474        lexical_core::parse(string.as_bytes()).ok()
475    }
476}
477
478impl Parser for Float64Type {
479    fn parse(string: &str) -> Option<f64> {
480        if let Ok(raw_float) = lexical_core::parse(string.as_bytes()) {
481            return Some(raw_float);
482        }
483        let string = trim_pre_and_post_whitespace(string);
484        lexical_core::parse(string.as_bytes()).ok()
485    }
486}
487
488/// this is a no-op if the string starts and ends with a digit, otherwise it will trim whitespace from the start and end of the string.
489#[inline]
490fn trim_pre_and_post_whitespace(string: &str) -> &str {
491    let bytes = string.as_bytes();
492    let prefix = bytes.first().is_some_and(|b| !b.is_ascii_digit());
493    let suffix = bytes.last().is_some_and(|b| !b.is_ascii_digit());
494    match (prefix, suffix) {
495        (false, false) => string,
496        (true, false) => string.trim_ascii_start(),
497        (false, true) => string.trim_ascii_end(),
498        (true, true) => string.trim_ascii(),
499    }
500}
501
502macro_rules! parser_primitive {
503    ($t:ty) => {
504        impl Parser for $t {
505            fn parse(string: &str) -> Option<Self::Native> {
506                let mut raw_bytes = string.as_bytes();
507                if !raw_bytes.last().is_some_and(|x| x.is_ascii_digit()) {
508                    raw_bytes = raw_bytes.trim_ascii_end();
509                    if !raw_bytes.last().is_some_and(|x| x.is_ascii_digit()) {
510                        return None;
511                    }
512                }
513                match atoi::FromRadix10SignedChecked::from_radix_10_signed_checked(raw_bytes) {
514                    (Some(n), x) if x == raw_bytes.len() => Some(n),
515                    _ => {
516                        let trimmed = raw_bytes.trim_ascii_start();
517                        match atoi::FromRadix10SignedChecked::from_radix_10_signed_checked(trimmed)
518                        {
519                            (Some(n), x) if x == trimmed.len() => Some(n),
520                            _ => None,
521                        }
522                    }
523                }
524            }
525        }
526    };
527}
528parser_primitive!(UInt64Type);
529parser_primitive!(UInt32Type);
530parser_primitive!(UInt16Type);
531parser_primitive!(UInt8Type);
532parser_primitive!(Int64Type);
533parser_primitive!(Int32Type);
534parser_primitive!(Int16Type);
535parser_primitive!(Int8Type);
536parser_primitive!(DurationNanosecondType);
537parser_primitive!(DurationMicrosecondType);
538parser_primitive!(DurationMillisecondType);
539parser_primitive!(DurationSecondType);
540
541impl Parser for TimestampNanosecondType {
542    fn parse(string: &str) -> Option<i64> {
543        if let Ok(nanos) = string_to_timestamp_nanos(string) {
544            return Some(nanos);
545        }
546
547        let trimmed = trim_pre_and_post_whitespace(string);
548        string_to_timestamp_nanos(trimmed).ok()
549    }
550}
551
552impl Parser for TimestampMicrosecondType {
553    fn parse(string: &str) -> Option<i64> {
554        if let Ok(nanos) = string_to_timestamp_nanos(string) {
555            return Some(nanos / 1_000);
556        }
557
558        let trimmed = trim_pre_and_post_whitespace(string);
559        string_to_timestamp_nanos(trimmed).ok().map(|x| x / 1_000)
560    }
561}
562
563impl Parser for TimestampMillisecondType {
564    fn parse(string: &str) -> Option<i64> {
565        if let Ok(nanos) = string_to_timestamp_nanos(string) {
566            return Some(nanos / 1_000_000);
567        }
568
569        let trimmed = trim_pre_and_post_whitespace(string);
570        string_to_timestamp_nanos(trimmed)
571            .ok()
572            .map(|x| x / 1_000_000)
573    }
574}
575
576impl Parser for TimestampSecondType {
577    fn parse(string: &str) -> Option<i64> {
578        if let Ok(nanos) = string_to_timestamp_nanos(string) {
579            return Some(nanos / 1_000_000_000);
580        }
581
582        let trimmed = trim_pre_and_post_whitespace(string);
583        string_to_timestamp_nanos(trimmed)
584            .ok()
585            .map(|x| x / 1_000_000_000)
586    }
587}
588
589impl Parser for Time64NanosecondType {
590    // Will truncate any fractions of a nanosecond
591    fn parse(string: &str) -> Option<Self::Native> {
592        let value = string_to_time_nanoseconds(string)
593            .ok()
594            .or_else(|| string.parse::<Self::Native>().ok());
595
596        if value.is_some() {
597            return value;
598        }
599
600        let trimmed = trim_pre_and_post_whitespace(string);
601        string_to_time_nanoseconds(trimmed)
602            .ok()
603            .or_else(|| string.parse::<Self::Native>().ok())
604    }
605
606    fn parse_formatted(string: &str, format: &str) -> Option<Self::Native> {
607        let nt = NaiveTime::parse_from_str(string, format).ok()?;
608        Some(nt.num_seconds_from_midnight() as i64 * 1_000_000_000 + nt.nanosecond() as i64)
609    }
610}
611
612impl Parser for Time64MicrosecondType {
613    // Will truncate any fractions of a microsecond
614    fn parse(string: &str) -> Option<Self::Native> {
615        let value = string_to_time_nanoseconds(string)
616            .ok()
617            .map(|nanos| nanos / 1_000)
618            .or_else(|| string.parse::<Self::Native>().ok());
619
620        if value.is_some() {
621            return value;
622        }
623
624        let trimmed = trim_pre_and_post_whitespace(string);
625        string_to_time_nanoseconds(trimmed)
626            .ok()
627            .map(|x| x / 1_000)
628            .or_else(|| string.parse::<Self::Native>().ok())
629    }
630
631    fn parse_formatted(string: &str, format: &str) -> Option<Self::Native> {
632        let nt = NaiveTime::parse_from_str(string, format).ok()?;
633        Some(nt.num_seconds_from_midnight() as i64 * 1_000_000 + nt.nanosecond() as i64 / 1_000)
634    }
635}
636
637impl Parser for Time32MillisecondType {
638    // Will truncate any fractions of a millisecond
639    fn parse(string: &str) -> Option<Self::Native> {
640        let value = string_to_time_nanoseconds(string)
641            .ok()
642            .map(|nanos| (nanos / 1_000_000) as i32)
643            .or_else(|| string.parse::<Self::Native>().ok());
644
645        if value.is_some() {
646            return value;
647        }
648
649        let trimmed = trim_pre_and_post_whitespace(string);
650        string_to_time_nanoseconds(trimmed)
651            .ok()
652            .map(|x| (x / 1_000_000) as i32)
653            .or_else(|| string.parse::<Self::Native>().ok())
654    }
655
656    fn parse_formatted(string: &str, format: &str) -> Option<Self::Native> {
657        let nt = NaiveTime::parse_from_str(string, format).ok()?;
658        Some(nt.num_seconds_from_midnight() as i32 * 1_000 + nt.nanosecond() as i32 / 1_000_000)
659    }
660}
661
662impl Parser for Time32SecondType {
663    // Will truncate any fractions of a second
664    fn parse(string: &str) -> Option<Self::Native> {
665        let value = string_to_time_nanoseconds(string)
666            .ok()
667            .map(|nanos| (nanos / 1_000_000_000) as i32)
668            .or_else(|| string.parse::<Self::Native>().ok());
669
670        if value.is_some() {
671            return value;
672        }
673
674        let trimmed = trim_pre_and_post_whitespace(string);
675        string_to_time_nanoseconds(trimmed)
676            .ok()
677            .map(|x| (x / 1_000_000_000) as i32)
678            .or_else(|| string.parse::<Self::Native>().ok())
679    }
680
681    fn parse_formatted(string: &str, format: &str) -> Option<Self::Native> {
682        let nt = NaiveTime::parse_from_str(string, format).ok()?;
683        Some(nt.num_seconds_from_midnight() as i32 + nt.nanosecond() as i32 / 1_000_000_000)
684    }
685}
686
687/// Number of days between 0001-01-01 and 1970-01-01
688const EPOCH_DAYS_FROM_CE: i32 = 719_163;
689
690/// Error message if nanosecond conversion request beyond supported interval
691const ERR_NANOSECONDS_NOT_SUPPORTED: &str = "The dates that can be represented as nanoseconds have to be between 1677-09-21T00:12:44.0 and 2262-04-11T23:47:16.854775804";
692
693/// Parse the ISO 8601 signed extended-year form (`±YYYY[Y...]-MM-DD`) into
694/// raw `(year, month, day)` components, without validating the calendar date.
695///
696/// The caller must have already verified that `string` begins with `+` or `-`;
697/// the year must have at least 4 digits. Returns `None` if the shape is
698/// malformed or any component fails to parse numerically.
699fn parse_extended_ymd(string: &str) -> Option<(i32, u32, u32)> {
700    debug_assert!(string.starts_with('+') || string.starts_with('-'));
701    // Skip the sign and look for the hyphen that terminates the year digits.
702    // Per ISO 8601 the unsigned year part must be at least 4 digits.
703    let rest = &string[1..];
704    let hyphen = rest.find('-')?;
705    if hyphen < 4 {
706        return None;
707    }
708    // The year substring is the sign and the digits (but not the separator),
709    // e.g. for "+10999-12-31", hyphen is 5 and s[..6] is "+10999".
710    let year: i32 = string[..hyphen + 1].parse().ok()?;
711    // The remainder should begin with a '-' which we strip off, leaving the month-day part.
712    let remainder = string[hyphen + 1..].strip_prefix('-')?;
713    let mut parts = remainder.splitn(2, '-');
714    let month: u32 = parts.next()?.parse().ok()?;
715    let day: u32 = parts.next()?.parse().ok()?;
716    Some((year, month, day))
717}
718
719fn parse_date(string: &str) -> Option<NaiveDate> {
720    // If the date has an extended (signed) year such as "+10999-12-31" or "-0012-05-06"
721    //
722    // According to [ISO 8601], years have:
723    //  Four digits or more for the year. Years in the range 0000 to 9999 will be pre-padded by
724    //  zero to ensure four digits. Years outside that range will have a prefixed positive or negative symbol.
725    //
726    // [ISO 8601]: https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/format/DateTimeFormatter.html#ISO_LOCAL_DATE
727    if string.starts_with('+') || string.starts_with('-') {
728        let (year, month, day) = parse_extended_ymd(string)?;
729        return NaiveDate::from_ymd_opt(year, month, day);
730    }
731
732    if string.len() > 10 {
733        // Try to parse as datetime and return just the date part
734        return string_to_datetime(&Utc, string)
735            .map(|dt| dt.date_naive())
736            .ok();
737    }
738    let mut digits = [0; 10];
739    let mut mask = 0;
740
741    // Treating all bytes the same way, helps LLVM vectorise this correctly
742    for (idx, (o, i)) in digits.iter_mut().zip(string.bytes()).enumerate() {
743        *o = i.wrapping_sub(b'0');
744        mask |= ((*o < 10) as u16) << idx
745    }
746
747    const HYPHEN: u8 = b'-'.wrapping_sub(b'0');
748
749    //  refer to https://www.rfc-editor.org/rfc/rfc3339#section-3
750    if digits[4] != HYPHEN {
751        let (year, month, day) = match (mask, string.len()) {
752            (0b11111111, 8) => (
753                digits[0] as u16 * 1000
754                    + digits[1] as u16 * 100
755                    + digits[2] as u16 * 10
756                    + digits[3] as u16,
757                digits[4] * 10 + digits[5],
758                digits[6] * 10 + digits[7],
759            ),
760            _ => return None,
761        };
762        return NaiveDate::from_ymd_opt(year as _, month as _, day as _);
763    }
764
765    let (month, day) = match mask {
766        0b1101101111 => {
767            if digits[7] != HYPHEN {
768                return None;
769            }
770            (digits[5] * 10 + digits[6], digits[8] * 10 + digits[9])
771        }
772        0b101101111 => {
773            if digits[7] != HYPHEN {
774                return None;
775            }
776            (digits[5] * 10 + digits[6], digits[8])
777        }
778        0b110101111 => {
779            if digits[6] != HYPHEN {
780                return None;
781            }
782            (digits[5], digits[7] * 10 + digits[8])
783        }
784        0b10101111 => {
785            if digits[6] != HYPHEN {
786                return None;
787            }
788            (digits[5], digits[7])
789        }
790        _ => return None,
791    };
792
793    let year =
794        digits[0] as u16 * 1000 + digits[1] as u16 * 100 + digits[2] as u16 * 10 + digits[3] as u16;
795
796    NaiveDate::from_ymd_opt(year as _, month as _, day as _)
797}
798
799/// Parse a date string into days since 1970-01-01, covering the full
800/// `Date32` range (years ≈ ±5,881,580) for the signed extended-year form.
801///
802/// The Gregorian calendar repeats exactly every 400 years (146,097 days), so
803/// we fold the year into `[0, 400)`, validate the folded date, and add
804/// `era * 146_097` to recover the absolute day count.
805///
806/// For all other inputs, behavior matches [`parse_date`].
807fn parse_date_to_days(string: &str) -> Option<i32> {
808    if string.starts_with('+') || string.starts_with('-') {
809        let (year, month, day) = parse_extended_ymd(string)?;
810        let y = year as i64;
811        let era = y.div_euclid(400);
812        let yoe = y.rem_euclid(400) as i32;
813        let naive_date = NaiveDate::from_ymd_opt(yoe, month, day)?;
814        let in_era = (naive_date.num_days_from_ce() - EPOCH_DAYS_FROM_CE) as i64;
815        return i32::try_from(era * 146_097 + in_era).ok();
816    }
817    parse_date(string).map(|naive_date| naive_date.num_days_from_ce() - EPOCH_DAYS_FROM_CE)
818}
819
820impl Parser for Date32Type {
821    fn parse(string: &str) -> Option<i32> {
822        if let Some(days) = parse_date_to_days(string) {
823            return Some(days);
824        }
825
826        let trimmed = trim_pre_and_post_whitespace(string);
827        parse_date_to_days(trimmed)
828    }
829
830    fn parse_formatted(string: &str, format: &str) -> Option<i32> {
831        let date = NaiveDate::parse_from_str(string, format).ok()?;
832        Some(date.num_days_from_ce() - EPOCH_DAYS_FROM_CE)
833    }
834}
835
836impl Parser for Date64Type {
837    fn parse(string: &str) -> Option<i64> {
838        if string.len() <= 10 {
839            let datetime = NaiveDateTime::new(parse_date(string)?, NaiveTime::default());
840            Some(datetime.and_utc().timestamp_millis())
841        } else {
842            let date_time = string_to_datetime(&Utc, string).ok()?;
843            Some(date_time.timestamp_millis())
844        }
845    }
846
847    fn parse_formatted(string: &str, format: &str) -> Option<i64> {
848        use chrono::format::Fixed;
849        use chrono::format::StrftimeItems;
850        let fmt = StrftimeItems::new(format);
851        let has_zone = fmt.into_iter().any(|item| match item {
852            chrono::format::Item::Fixed(fixed_item) => matches!(
853                fixed_item,
854                Fixed::RFC2822
855                    | Fixed::RFC3339
856                    | Fixed::TimezoneName
857                    | Fixed::TimezoneOffsetColon
858                    | Fixed::TimezoneOffsetColonZ
859                    | Fixed::TimezoneOffset
860                    | Fixed::TimezoneOffsetZ
861            ),
862            _ => false,
863        });
864        if has_zone {
865            let date_time = chrono::DateTime::parse_from_str(string, format).ok()?;
866            Some(date_time.timestamp_millis())
867        } else {
868            let date_time = NaiveDateTime::parse_from_str(string, format).ok()?;
869            Some(date_time.and_utc().timestamp_millis())
870        }
871    }
872}
873
874/// Parses the string representation of a decimal number into the unscaled
875/// native value of a decimal type with the given `precision` and `scale`.
876///
877/// The accepted syntax is:
878///
879/// ```text
880/// [whitespace] [+|-] digits [. [digits]] [(e|E) [+|-] digits] [whitespace]
881/// ```
882///
883/// or the same with the integer digits omitted (e.g. `.5`), as long as at
884/// least one digit is present in the mantissa. ASCII whitespace is trimmed
885/// from both ends. The exponent is applied before scaling, so `1.5e2` and
886/// `150` parse identically.
887///
888/// Fractional digits beyond `scale` are not stored but round the result half
889/// away from zero (e.g. `1.005` at scale 2 is `101`, `-1.005` is `-101`).
890/// Negative scales are supported and round the integer part in the same way
891/// (e.g. `150` at scale -2 is `2`).
892///
893/// Returns an error if the input is not a valid decimal string, or if the
894/// result does not fit the given precision.
895///
896/// # Example
897///
898/// ```
899/// # use arrow_array::types::Decimal128Type;
900/// # use arrow_cast::parse::parse_decimal;
901/// assert_eq!(parse_decimal::<Decimal128Type>("123.45", 10, 2).unwrap(), 12345);
902/// assert_eq!(parse_decimal::<Decimal128Type>("1.005", 10, 2).unwrap(), 101);
903/// assert_eq!(parse_decimal::<Decimal128Type>("1.5e2", 10, 0).unwrap(), 150);
904/// assert!(parse_decimal::<Decimal128Type>("1234.5", 5, 2).is_err()); // does not fit
905/// ```
906pub fn parse_decimal<T: DecimalType>(
907    s: &str,
908    precision: u8,
909    scale: i8,
910) -> Result<T::Native, ArrowError> {
911    parse_decimal_checked::<T>(s, precision, scale).map_err(|e| match e {
912        DecimalParseError::Overflow => ArrowError::ParseError(format!(
913            "{s:?} does not fit in {}({precision}, {scale})",
914            T::PREFIX
915        )),
916        DecimalParseError::InvalidFormat => {
917            ArrowError::ParseError(format!("Invalid decimal format: {s:?}"))
918        }
919    })
920}
921
922/// The reason a decimal string could not be parsed.
923#[derive(Debug, Clone, Copy, PartialEq, Eq)]
924pub(crate) enum DecimalParseError {
925    /// The input is not a valid decimal string
926    InvalidFormat,
927    /// The value does not fit in the precision or the native type of the decimal
928    Overflow,
929}
930
931/// Like [`parse_decimal`], but reports failures as a [`DecimalParseError`]
932/// instead of formatting an error message, for callers that discard or
933/// re-wrap the error.
934pub(crate) fn parse_decimal_checked<T: DecimalType>(
935    s: &str,
936    precision: u8,
937    scale: i8,
938) -> Result<T::Native, DecimalParseError> {
939    let (value, digits) = parse_decimal_native::<T>(s, scale)?;
940    // A value of at most `precision` digits is within the precision without
941    // inspecting it. A precision beyond the type's maximum is invalid.
942    let fits = precision <= T::MAX_PRECISION
943        && (digits <= precision as usize || T::is_valid_decimal_precision(value, precision));
944    if fits {
945        Ok(value)
946    } else {
947        Err(DecimalParseError::Overflow)
948    }
949}
950
951/// Parses `s` as a decimal with the given `scale` into the native type of `T`,
952/// checking only that the result fits the native type (not the precision),
953/// and returns it with an upper bound on its number of decimal digits.
954///
955/// See [`parse_decimal`] for the accepted syntax and rounding behaviour.
956#[inline]
957fn parse_decimal_native<T: DecimalType>(
958    s: &str,
959    scale: i8,
960) -> Result<(T::Native, usize), DecimalParseError> {
961    let bytes = s.as_bytes().trim_ascii();
962    let (negative, mut mantissa) = split_sign(bytes);
963
964    let mut scale = scale as i64;
965    loop {
966        let exponent_at = match parse_decimal_mantissa::<T>(mantissa, negative, scale) {
967            Ok(result) => return Ok(result),
968            Err(MantissaError::InvalidFormat) => return Err(DecimalParseError::InvalidFormat),
969            Err(MantissaError::Exponent(index)) => index,
970            // The digits before an exponent marker need not fit on their own
971            // (e.g. "4825037936439135476E-14"), so the overflow only stands
972            // if no marker follows
973            Err(MantissaError::Overflow) => mantissa
974                .iter()
975                .position(|b| matches!(b, b'e' | b'E'))
976                .ok_or(DecimalParseError::Overflow)?,
977        };
978
979        // If we saw an exponent, update the effective scale and rescan.
980        // Exponents are rare, so the risk of repeated work is preferable to
981        // the cost of scanning ahead for an exponent marker for every input.
982        let exponent = parse_decimal_exponent(&mantissa[exponent_at + 1..])?;
983        scale = scale.saturating_add(exponent);
984
985        // Trim the exponent so the next iteration succeeds without rescanning
986        mantissa = &mantissa[..exponent_at];
987    }
988}
989
990/// Why scanning the digits of a decimal string stopped.
991enum MantissaError {
992    /// The input is not a valid decimal string
993    InvalidFormat,
994    /// The value does not fit in the native type
995    Overflow,
996    /// An exponent marker (`e` or `E`) was found at the given byte offset
997    Exponent(usize),
998}
999
1000impl From<DecimalParseError> for MantissaError {
1001    fn from(e: DecimalParseError) -> Self {
1002        match e {
1003            DecimalParseError::InvalidFormat => Self::InvalidFormat,
1004            DecimalParseError::Overflow => Self::Overflow,
1005        }
1006    }
1007}
1008
1009/// The maximum number of decimal digits accumulated in a `u64` before the
1010/// chunk is folded into the native value: every 18-digit number fits in a
1011/// `u64`, and splits into two halves that each fit in a `u32` (see
1012/// [`decimal_chunk_to_native`]).
1013const MAX_CHUNK_DIGITS: usize = 18;
1014
1015/// Scans `mantissa` (digits with at most one decimal point; the sign has
1016/// already been removed) and folds the digits that are significant at
1017/// `scale` into a native value, rounding half away from zero on the first
1018/// digit that is not. Also returns an upper bound on the number of decimal
1019/// digits of the value: the digits kept, the zeros appended to reach the
1020/// scale, and the digit that rounding up can add.
1021#[inline]
1022fn parse_decimal_mantissa<T: DecimalType>(
1023    mantissa: &[u8],
1024    negative: bool,
1025    scale: i64,
1026) -> Result<(T::Native, usize), MantissaError> {
1027    // The number of integer and fractional digits that contribute to the
1028    // result. For a non-negative scale that is every integer digit and the
1029    // first `scale` fractional digits. For a negative scale the last `-scale`
1030    // integer digits (and every fractional digit) only matter for rounding.
1031    let (int_keep, frac_keep, mut round) = if scale >= 0 {
1032        (
1033            usize::MAX,
1034            usize::try_from(scale).unwrap_or(usize::MAX),
1035            true,
1036        )
1037    } else {
1038        let int_digits = mantissa.iter().take_while(|b| b.is_ascii_digit()).count();
1039        match usize::try_from(int_digits as i64 + scale) {
1040            Ok(keep) => (keep, 0, true),
1041            // Even the first digit is more than one position below the
1042            // least significant digit of the result: the value rounds to
1043            // zero regardless of what the digits are
1044            Err(_) => (0, 0, false),
1045        }
1046    };
1047
1048    let mut acc = DecimalAccumulator::<T> {
1049        value: T::Native::ZERO,
1050        chunk: 0,
1051        chunk_len: 0,
1052        negative,
1053    };
1054    let mut int_kept = 0_usize;
1055    let mut frac_kept = 0_usize;
1056    let mut first_discarded_digit = None;
1057
1058    // Digits before the decimal point
1059    let mut index = 0;
1060    while let Some(&b) = mantissa.get(index) {
1061        if !b.is_ascii_digit() {
1062            break;
1063        }
1064        if int_kept < int_keep {
1065            int_kept += 1;
1066            acc.push(b - b'0')?;
1067        } else {
1068            first_discarded_digit.get_or_insert(b - b'0');
1069        }
1070        index += 1;
1071    }
1072
1073    // Digits after the decimal point
1074    if mantissa.get(index) == Some(&b'.') {
1075        index += 1;
1076        while let Some(&b) = mantissa.get(index) {
1077            if !b.is_ascii_digit() {
1078                break;
1079            }
1080            if frac_kept < frac_keep {
1081                frac_kept += 1;
1082                acc.push(b - b'0')?;
1083            } else {
1084                first_discarded_digit.get_or_insert(b - b'0');
1085            }
1086            index += 1;
1087        }
1088    }
1089
1090    match mantissa.get(index) {
1091        None => {}
1092        Some(b'e' | b'E') => return Err(MantissaError::Exponent(index)),
1093        Some(_) => return Err(MantissaError::InvalidFormat),
1094    }
1095
1096    if int_kept == 0 && frac_kept == 0 && first_discarded_digit.is_none() {
1097        return Err(MantissaError::InvalidFormat);
1098    }
1099
1100    let mut value = acc.finish()?;
1101
1102    // Scale the value up to the target scale. Skipped for zero, where computing
1103    // 10^missing could overflow the native type even though the result (zero)
1104    // is always representable.
1105    let missing = scale - frac_kept as i64;
1106    if missing > 0 && !value.is_zero() {
1107        value = value
1108            .mul_checked(decimal_pow::<T>(missing)?)
1109            .map_err(|_| MantissaError::Overflow)?;
1110    }
1111
1112    round &= first_discarded_digit.is_some_and(|digit| digit >= 5);
1113    if round {
1114        value = if negative {
1115            value.sub_checked(T::Native::ONE)
1116        } else {
1117            value.add_checked(T::Native::ONE)
1118        }
1119        .map_err(|_| MantissaError::Overflow)?;
1120    }
1121
1122    let digits = usize::try_from(missing.max(0))
1123        .unwrap_or(usize::MAX)
1124        .saturating_add(int_kept + frac_kept + round as usize);
1125    Ok((value, digits))
1126}
1127
1128/// Parses the digits of an exponent (`[+|-] digits`), saturating at the bounds
1129/// of `i64`; any exponent that large scales every non-zero mantissa out of
1130/// range of every decimal type.
1131fn parse_decimal_exponent(exponent: &[u8]) -> Result<i64, DecimalParseError> {
1132    let (negative, digits) = split_sign(exponent);
1133    if digits.is_empty() {
1134        return Err(DecimalParseError::InvalidFormat);
1135    }
1136    let mut value = 0_i64;
1137    for &b in digits {
1138        if !b.is_ascii_digit() {
1139            return Err(DecimalParseError::InvalidFormat);
1140        }
1141        value = value.saturating_mul(10).saturating_add((b - b'0') as i64);
1142    }
1143    Ok(if negative { -value } else { value })
1144}
1145
1146/// Splits an optional leading sign from `bytes`, returning whether it is `-`
1147/// and the bytes that follow it.
1148#[inline]
1149fn split_sign(bytes: &[u8]) -> (bool, &[u8]) {
1150    match bytes.first() {
1151        Some(b'-') => (true, &bytes[1..]),
1152        Some(b'+') => (false, &bytes[1..]),
1153        _ => (false, bytes),
1154    }
1155}
1156
1157/// Accumulates decimal digits into `chunk`, folding it into `value` whenever
1158/// it reaches [`MAX_CHUNK_DIGITS`] digits
1159struct DecimalAccumulator<T: DecimalType> {
1160    value: T::Native,
1161    chunk: u64,
1162    chunk_len: usize,
1163    negative: bool,
1164}
1165
1166impl<T: DecimalType> DecimalAccumulator<T> {
1167    #[inline(always)]
1168    fn push(&mut self, digit: u8) -> Result<(), DecimalParseError> {
1169        // Cannot overflow: the chunk is folded into `value` before it exceeds
1170        // MAX_CHUNK_DIGITS digits, all of which fit in a u64
1171        self.chunk = self.chunk * 10 + digit as u64;
1172        self.chunk_len += 1;
1173        if self.chunk_len == MAX_CHUNK_DIGITS {
1174            self.value =
1175                fold_decimal_chunk::<T>(self.value, self.chunk, self.chunk_len, self.negative)?;
1176            self.chunk = 0;
1177            self.chunk_len = 0;
1178        }
1179        Ok(())
1180    }
1181
1182    /// Folds the digits still in `chunk` into the value
1183    #[inline]
1184    fn finish(self) -> Result<T::Native, DecimalParseError> {
1185        if self.chunk_len == 0 {
1186            return Ok(self.value);
1187        }
1188        fold_decimal_chunk::<T>(self.value, self.chunk, self.chunk_len, self.negative)
1189    }
1190}
1191
1192/// Folds a chunk of up to [`MAX_CHUNK_DIGITS`] digits into `value`, producing
1193/// `value * 10^chunk_len + chunk` (`chunk` is negated first when parsing a
1194/// negative number).
1195#[inline(always)]
1196fn fold_decimal_chunk<T: DecimalType>(
1197    value: T::Native,
1198    chunk: u64,
1199    chunk_len: usize,
1200    negative: bool,
1201) -> Result<T::Native, DecimalParseError> {
1202    let chunk = decimal_chunk_to_native::<T>(chunk, negative)?;
1203
1204    // When `value` is zero the multiply would be a no-op; skipping it avoids
1205    // computing 10^chunk_len, which can overflow a narrow native type even
1206    // though the result (the chunk itself) is representable.
1207    if value.is_zero() {
1208        return Ok(chunk);
1209    }
1210
1211    value
1212        .mul_checked(decimal_pow::<T>(chunk_len as i64)?)
1213        .map_err(|_| DecimalParseError::Overflow)?
1214        .add_checked(chunk)
1215        .map_err(|_| DecimalParseError::Overflow)
1216}
1217
1218/// Converts a chunk of at most [`MAX_CHUNK_DIGITS`] digits to the native type,
1219/// negated if `negative`.
1220#[inline]
1221fn decimal_chunk_to_native<T: DecimalType>(
1222    chunk: u64,
1223    negative: bool,
1224) -> Result<T::Native, DecimalParseError> {
1225    // Every native type can represent +/- 10^9, so a chunk below that converts
1226    // losslessly through usize on every target. So does any chunk when the
1227    // native type holds MAX_CHUNK_DIGITS digits and usize holds a u64.
1228    const HALF: u64 = 1_000_000_000;
1229    if chunk < HALF || (T::MAX_PRECISION as usize >= MAX_CHUNK_DIGITS && usize::BITS >= 64) {
1230        let chunk = T::Native::usize_as(chunk as usize);
1231        // `ZERO.sub_wrapping` rather than `neg_wrapping`: the latter compiles
1232        // to measurably slower code for i256 (~10% on casting strings to
1233        // Decimal256)
1234        return Ok(if negative {
1235            T::Native::ZERO.sub_wrapping(chunk)
1236        } else {
1237            chunk
1238        });
1239    }
1240    // Otherwise narrow the chunk in two halves that are each below 10^9
1241    let low = T::Native::usize_as((chunk % HALF) as usize);
1242    let high = T::Native::usize_as((chunk / HALF) as usize)
1243        .mul_checked(T::Native::usize_as(HALF as usize))
1244        .map_err(|_| DecimalParseError::Overflow)?;
1245    // Negate before combining so that a chunk with the magnitude of the
1246    // native type's minimum value (e.g. "2147483648" for Decimal32) remains
1247    // representable
1248    if negative {
1249        T::Native::ZERO
1250            .sub_checked(high)
1251            .map_err(|_| DecimalParseError::Overflow)?
1252            .sub_checked(low)
1253            .map_err(|_| DecimalParseError::Overflow)
1254    } else {
1255        high.add_checked(low)
1256            .map_err(|_| DecimalParseError::Overflow)
1257    }
1258}
1259
1260/// Returns `10^exp` as a `T::Native`, or an overflow error if the result does
1261/// not fit in the native type.
1262#[inline]
1263fn decimal_pow<T: DecimalType>(exp: i64) -> Result<T::Native, DecimalParseError> {
1264    // T::MAX_FOR_EACH_PRECISION[k] holds 10^k - 1, so adding one yields 10^k
1265    // without computing a power at runtime. Exponents beyond the table always
1266    // overflow: the native type cannot hold 10^(MAX_PRECISION + 1).
1267    usize::try_from(exp)
1268        .ok()
1269        .and_then(|exp| T::MAX_FOR_EACH_PRECISION.get(exp))
1270        .map(|max| max.add_wrapping(T::Native::ONE))
1271        .ok_or(DecimalParseError::Overflow)
1272}
1273
1274/// Parse human-readable interval string to Arrow [IntervalYearMonthType]
1275pub fn parse_interval_year_month(
1276    value: &str,
1277) -> Result<<IntervalYearMonthType as ArrowPrimitiveType>::Native, ArrowError> {
1278    let config = IntervalParseConfig::new(IntervalUnit::Year);
1279    let interval = Interval::parse(value, &config)?;
1280
1281    let months = interval.to_year_months().map_err(|_| {
1282        ArrowError::CastError(format!(
1283            "Cannot cast {value} to IntervalYearMonth. Only year and month fields are allowed."
1284        ))
1285    })?;
1286
1287    Ok(IntervalYearMonthType::make_value(0, months))
1288}
1289
1290/// Parse human-readable interval string to Arrow [IntervalDayTimeType]
1291pub fn parse_interval_day_time(
1292    value: &str,
1293) -> Result<<IntervalDayTimeType as ArrowPrimitiveType>::Native, ArrowError> {
1294    let config = IntervalParseConfig::new(IntervalUnit::Day);
1295    let interval = Interval::parse(value, &config)?;
1296
1297    let (days, millis) = interval.to_day_time().map_err(|_| ArrowError::CastError(format!(
1298        "Cannot cast {value} to IntervalDayTime because the nanos part isn't multiple of milliseconds"
1299    )))?;
1300
1301    Ok(IntervalDayTimeType::make_value(days, millis))
1302}
1303
1304/// Parse human-readable interval string to Arrow [IntervalMonthDayNanoType]
1305pub fn parse_interval_month_day_nano_config(
1306    value: &str,
1307    config: IntervalParseConfig,
1308) -> Result<<IntervalMonthDayNanoType as ArrowPrimitiveType>::Native, ArrowError> {
1309    let interval = Interval::parse(value, &config)?;
1310
1311    let (months, days, nanos) = interval.to_month_day_nanos();
1312
1313    Ok(IntervalMonthDayNanoType::make_value(months, days, nanos))
1314}
1315
1316/// Parse human-readable interval string to Arrow [IntervalMonthDayNanoType]
1317pub fn parse_interval_month_day_nano(
1318    value: &str,
1319) -> Result<<IntervalMonthDayNanoType as ArrowPrimitiveType>::Native, ArrowError> {
1320    parse_interval_month_day_nano_config(value, IntervalParseConfig::new(IntervalUnit::Month))
1321}
1322
1323const NANOS_PER_MILLIS: i64 = 1_000_000;
1324const NANOS_PER_SECOND: i64 = 1_000 * NANOS_PER_MILLIS;
1325const NANOS_PER_MINUTE: i64 = 60 * NANOS_PER_SECOND;
1326const NANOS_PER_HOUR: i64 = 60 * NANOS_PER_MINUTE;
1327pub(crate) const NANOS_PER_DAY: i64 = 24 * NANOS_PER_HOUR;
1328
1329/// Config to parse interval strings
1330///
1331/// Stores the `default_unit` to use if the string doesn't have one specified,
1332/// and whether fractional calendar units may be spilled into smaller units.
1333#[derive(Debug, Clone)]
1334pub struct IntervalParseConfig {
1335    /// The default unit to use if none is specified
1336    /// e.g. `INTERVAL 1` represents `INTERVAL 1 SECOND` when default_unit = [IntervalUnit::Second]
1337    default_unit: IntervalUnit,
1338    /// Whether fractional calendar units (centuries, decades, years, months)
1339    /// may be spilled into smaller units. `0.5 months` is parsed as 15 days
1340    /// when this is `true`.
1341    allow_fractional_calendar_units: bool,
1342}
1343
1344impl IntervalParseConfig {
1345    /// Create a new [IntervalParseConfig] with the given default unit
1346    pub fn new(default_unit: IntervalUnit) -> Self {
1347        Self {
1348            default_unit,
1349            allow_fractional_calendar_units: true,
1350        }
1351    }
1352
1353    /// Reject fractional calendar units instead of spilling them into smaller units
1354    pub(crate) fn reject_fractional_calendar_units(mut self) -> Self {
1355        self.allow_fractional_calendar_units = false;
1356        self
1357    }
1358}
1359
1360#[rustfmt::skip]
1361#[derive(Debug, Clone, Copy)]
1362#[repr(u16)]
1363/// Represents the units of an interval, with each variant
1364/// corresponding to a bit in the interval's bitfield representation
1365pub enum IntervalUnit {
1366    /// A Century
1367    Century     = 0b_0000_0000_0001,
1368    /// A Decade
1369    Decade      = 0b_0000_0000_0010,
1370    /// A Year
1371    Year        = 0b_0000_0000_0100,
1372    /// A Month
1373    Month       = 0b_0000_0000_1000,
1374    /// A Week
1375    Week        = 0b_0000_0001_0000,
1376    /// A Day
1377    Day         = 0b_0000_0010_0000,
1378    /// An Hour
1379    Hour        = 0b_0000_0100_0000,
1380    /// A Minute
1381    Minute      = 0b_0000_1000_0000,
1382    /// A Second
1383    Second      = 0b_0001_0000_0000,
1384    /// A Millisecond
1385    Millisecond = 0b_0010_0000_0000,
1386    /// A Microsecond
1387    Microsecond = 0b_0100_0000_0000,
1388    /// A Nanosecond
1389    Nanosecond  = 0b_1000_0000_0000,
1390}
1391
1392/// Logic for parsing interval unit strings
1393///
1394/// See <https://github.com/postgres/postgres/blob/2caa85f4aae689e6f6721d7363b4c66a2a6417d6/src/backend/utils/adt/datetime.c#L189>
1395/// for a list of unit names supported by PostgreSQL which we try to match here.
1396impl FromStr for IntervalUnit {
1397    type Err = ArrowError;
1398
1399    fn from_str(s: &str) -> Result<Self, ArrowError> {
1400        match s.to_lowercase().as_str() {
1401            "c" | "cent" | "cents" | "century" | "centuries" => Ok(Self::Century),
1402            "dec" | "decs" | "decade" | "decades" => Ok(Self::Decade),
1403            "y" | "yr" | "yrs" | "year" | "years" => Ok(Self::Year),
1404            "mon" | "mons" | "month" | "months" => Ok(Self::Month),
1405            "w" | "week" | "weeks" => Ok(Self::Week),
1406            "d" | "day" | "days" => Ok(Self::Day),
1407            "h" | "hr" | "hrs" | "hour" | "hours" => Ok(Self::Hour),
1408            "m" | "min" | "mins" | "minute" | "minutes" => Ok(Self::Minute),
1409            "s" | "sec" | "secs" | "second" | "seconds" => Ok(Self::Second),
1410            "ms" | "msec" | "msecs" | "msecond" | "mseconds" | "millisecond" | "milliseconds" => {
1411                Ok(Self::Millisecond)
1412            }
1413            "us" | "usec" | "usecs" | "usecond" | "useconds" | "microsecond" | "microseconds" => {
1414                Ok(Self::Microsecond)
1415            }
1416            "nanosecond" | "nanoseconds" => Ok(Self::Nanosecond),
1417            _ => Err(ArrowError::InvalidArgumentError(format!(
1418                "Unknown interval type: {s}"
1419            ))),
1420        }
1421    }
1422}
1423
1424impl IntervalUnit {
1425    fn from_str_or_config(
1426        s: Option<&str>,
1427        config: &IntervalParseConfig,
1428    ) -> Result<Self, ArrowError> {
1429        match s {
1430            Some(s) => s.parse(),
1431            None => Ok(config.default_unit),
1432        }
1433    }
1434
1435    fn is_calendar_unit(self) -> bool {
1436        matches!(
1437            self,
1438            Self::Century | Self::Decade | Self::Year | Self::Month
1439        )
1440    }
1441}
1442
1443/// A tuple representing (months, days, nanoseconds) in an interval
1444pub type MonthDayNano = (i32, i32, i64);
1445
1446/// Chosen based on the number of decimal digits in 1 week in nanoseconds
1447const INTERVAL_PRECISION: u32 = 15;
1448
1449#[derive(Clone, Copy, Debug, PartialEq)]
1450struct IntervalAmount {
1451    /// The integer component of the interval amount
1452    integer: i64,
1453    /// The fractional component multiplied by 10^INTERVAL_PRECISION
1454    frac: i64,
1455}
1456
1457#[cfg(test)]
1458impl IntervalAmount {
1459    fn new(integer: i64, frac: i64) -> Self {
1460        Self { integer, frac }
1461    }
1462}
1463
1464impl FromStr for IntervalAmount {
1465    type Err = ArrowError;
1466
1467    fn from_str(s: &str) -> Result<Self, Self::Err> {
1468        match s.split_once('.') {
1469            Some((integer, frac))
1470                if frac.len() <= INTERVAL_PRECISION as usize
1471                    && !frac.is_empty()
1472                    && !frac.starts_with('-') =>
1473            {
1474                // integer will be "" for values like ".5"
1475                // and "-" for values like "-.5"
1476                let explicit_neg = integer.starts_with('-');
1477                let integer = if integer.is_empty() || integer == "-" {
1478                    Ok(0)
1479                } else {
1480                    integer.parse::<i64>().map_err(|_| {
1481                        ArrowError::ParseError(format!("Failed to parse {s} as interval amount"))
1482                    })
1483                }?;
1484
1485                let frac_unscaled = frac.parse::<i64>().map_err(|_| {
1486                    ArrowError::ParseError(format!("Failed to parse {s} as interval amount"))
1487                })?;
1488
1489                // scale fractional part by interval precision
1490                let frac = frac_unscaled * 10_i64.pow(INTERVAL_PRECISION - frac.len() as u32);
1491
1492                // propagate the sign of the integer part to the fractional part
1493                let frac = if integer < 0 || explicit_neg {
1494                    -frac
1495                } else {
1496                    frac
1497                };
1498
1499                let result = Self { integer, frac };
1500
1501                Ok(result)
1502            }
1503            Some((_, frac)) if frac.starts_with('-') => Err(ArrowError::ParseError(format!(
1504                "Failed to parse {s} as interval amount"
1505            ))),
1506            Some((_, frac)) if frac.len() > INTERVAL_PRECISION as usize => {
1507                Err(ArrowError::ParseError(format!(
1508                    "{s} exceeds the precision available for interval amount"
1509                )))
1510            }
1511            Some(_) | None => {
1512                let integer = s.parse::<i64>().map_err(|_| {
1513                    ArrowError::ParseError(format!("Failed to parse {s} as interval amount"))
1514                })?;
1515
1516                let result = Self { integer, frac: 0 };
1517                Ok(result)
1518            }
1519        }
1520    }
1521}
1522
1523#[derive(Debug, Default, PartialEq)]
1524struct Interval {
1525    months: i32,
1526    days: i32,
1527    nanos: i64,
1528}
1529
1530impl Interval {
1531    fn new(months: i32, days: i32, nanos: i64) -> Self {
1532        Self {
1533            months,
1534            days,
1535            nanos,
1536        }
1537    }
1538
1539    fn to_year_months(&self) -> Result<i32, ArrowError> {
1540        match (self.months, self.days, self.nanos) {
1541            (months, days, nanos) if days == 0 && nanos == 0 => Ok(months),
1542            _ => Err(ArrowError::InvalidArgumentError(format!(
1543                "Unable to represent interval with days and nanos as year-months: {self:?}"
1544            ))),
1545        }
1546    }
1547
1548    fn to_day_time(&self) -> Result<(i32, i32), ArrowError> {
1549        let days = self.months.mul_checked(30)?.add_checked(self.days)?;
1550
1551        match self.nanos {
1552            nanos if nanos % NANOS_PER_MILLIS == 0 => {
1553                let millis = (self.nanos / 1_000_000).try_into().map_err(|_| {
1554                    ArrowError::InvalidArgumentError(format!(
1555                        "Unable to represent {} nanos as milliseconds in a signed 32-bit integer",
1556                        self.nanos
1557                    ))
1558                })?;
1559
1560                Ok((days, millis))
1561            }
1562            nanos => Err(ArrowError::InvalidArgumentError(format!(
1563                "Unable to represent {nanos} as milliseconds"
1564            ))),
1565        }
1566    }
1567
1568    fn to_month_day_nanos(&self) -> (i32, i32, i64) {
1569        (self.months, self.days, self.nanos)
1570    }
1571
1572    /// Parse string value in traditional Postgres format such as
1573    /// `1 year 2 months 3 days 4 hours 5 minutes 6 seconds`
1574    fn parse(value: &str, config: &IntervalParseConfig) -> Result<Self, ArrowError> {
1575        let components = parse_interval_components(value, config)?;
1576
1577        components
1578            .into_iter()
1579            .try_fold(Self::default(), |result, (amount, unit)| {
1580                result.add(amount, unit)
1581            })
1582    }
1583
1584    /// Interval addition following Postgres behavior. Fractional units will be spilled into smaller units.
1585    /// When the interval unit is larger than months, the result is rounded to total months and not spilled to days/nanos.
1586    /// Fractional parts of weeks and days are represented using days and nanoseconds.
1587    /// e.g. INTERVAL '0.5 MONTH' = 15 days, INTERVAL '1.5 MONTH' = 1 month 15 days
1588    /// e.g. INTERVAL '0.5 DAY' = 12 hours, INTERVAL '1.5 DAY' = 1 day 12 hours
1589    /// [Postgres reference](https://www.postgresql.org/docs/15/datatype-datetime.html#DATATYPE-INTERVAL-INPUT:~:text=Field%20values%20can,fractional%20on%20output.)
1590    fn add(&self, amount: IntervalAmount, unit: IntervalUnit) -> Result<Self, ArrowError> {
1591        let result = match unit {
1592            IntervalUnit::Century => {
1593                let months_int = amount.integer.mul_checked(100)?.mul_checked(12)?;
1594                let month_frac = amount.frac * 12 / 10_i64.pow(INTERVAL_PRECISION - 2);
1595                let months = months_int
1596                    .add_checked(month_frac)?
1597                    .try_into()
1598                    .map_err(|_| {
1599                        ArrowError::ParseError(format!(
1600                            "Unable to represent {} centuries as months in a signed 32-bit integer",
1601                            amount.integer
1602                        ))
1603                    })?;
1604
1605                Self::new(self.months.add_checked(months)?, self.days, self.nanos)
1606            }
1607            IntervalUnit::Decade => {
1608                let months_int = amount.integer.mul_checked(10)?.mul_checked(12)?;
1609
1610                let month_frac = amount.frac * 12 / 10_i64.pow(INTERVAL_PRECISION - 1);
1611                let months = months_int
1612                    .add_checked(month_frac)?
1613                    .try_into()
1614                    .map_err(|_| {
1615                        ArrowError::ParseError(format!(
1616                            "Unable to represent {} decades as months in a signed 32-bit integer",
1617                            amount.integer
1618                        ))
1619                    })?;
1620
1621                Self::new(self.months.add_checked(months)?, self.days, self.nanos)
1622            }
1623            IntervalUnit::Year => {
1624                let months_int = amount.integer.mul_checked(12)?;
1625                let month_frac = amount.frac * 12 / 10_i64.pow(INTERVAL_PRECISION);
1626                let months = months_int
1627                    .add_checked(month_frac)?
1628                    .try_into()
1629                    .map_err(|_| {
1630                        ArrowError::ParseError(format!(
1631                            "Unable to represent {} years as months in a signed 32-bit integer",
1632                            amount.integer
1633                        ))
1634                    })?;
1635
1636                Self::new(self.months.add_checked(months)?, self.days, self.nanos)
1637            }
1638            IntervalUnit::Month => {
1639                let months = amount.integer.try_into().map_err(|_| {
1640                    ArrowError::ParseError(format!(
1641                        "Unable to represent {} months in a signed 32-bit integer",
1642                        amount.integer
1643                    ))
1644                })?;
1645
1646                let days = amount.frac * 3 / 10_i64.pow(INTERVAL_PRECISION - 1);
1647                let days = days.try_into().map_err(|_| {
1648                    ArrowError::ParseError(format!(
1649                        "Unable to represent {} months as days in a signed 32-bit integer",
1650                        amount.frac / 10_i64.pow(INTERVAL_PRECISION)
1651                    ))
1652                })?;
1653
1654                Self::new(
1655                    self.months.add_checked(months)?,
1656                    self.days.add_checked(days)?,
1657                    self.nanos,
1658                )
1659            }
1660            IntervalUnit::Week => {
1661                let days = amount.integer.mul_checked(7)?.try_into().map_err(|_| {
1662                    ArrowError::ParseError(format!(
1663                        "Unable to represent {} weeks as days in a signed 32-bit integer",
1664                        amount.integer
1665                    ))
1666                })?;
1667
1668                let nanos = amount.frac * 7 * 24 * 6 * 6 / 10_i64.pow(INTERVAL_PRECISION - 11);
1669
1670                Self::new(
1671                    self.months,
1672                    self.days.add_checked(days)?,
1673                    self.nanos.add_checked(nanos)?,
1674                )
1675            }
1676            IntervalUnit::Day => {
1677                let days = amount.integer.try_into().map_err(|_| {
1678                    ArrowError::InvalidArgumentError(format!(
1679                        "Unable to represent {} days in a signed 32-bit integer",
1680                        amount.integer
1681                    ))
1682                })?;
1683
1684                let nanos = amount.frac * 24 * 6 * 6 / 10_i64.pow(INTERVAL_PRECISION - 11);
1685
1686                Self::new(
1687                    self.months,
1688                    self.days.add_checked(days)?,
1689                    self.nanos.add_checked(nanos)?,
1690                )
1691            }
1692            IntervalUnit::Hour => {
1693                let nanos_int = amount.integer.mul_checked(NANOS_PER_HOUR)?;
1694                let nanos_frac = amount.frac * 6 * 6 / 10_i64.pow(INTERVAL_PRECISION - 11);
1695                let nanos = nanos_int.add_checked(nanos_frac)?;
1696
1697                Interval::new(self.months, self.days, self.nanos.add_checked(nanos)?)
1698            }
1699            IntervalUnit::Minute => {
1700                let nanos_int = amount.integer.mul_checked(NANOS_PER_MINUTE)?;
1701                let nanos_frac = amount.frac * 6 / 10_i64.pow(INTERVAL_PRECISION - 10);
1702
1703                let nanos = nanos_int.add_checked(nanos_frac)?;
1704
1705                Interval::new(self.months, self.days, self.nanos.add_checked(nanos)?)
1706            }
1707            IntervalUnit::Second => {
1708                let nanos_int = amount.integer.mul_checked(NANOS_PER_SECOND)?;
1709                let nanos_frac = amount.frac / 10_i64.pow(INTERVAL_PRECISION - 9);
1710                let nanos = nanos_int.add_checked(nanos_frac)?;
1711
1712                Interval::new(self.months, self.days, self.nanos.add_checked(nanos)?)
1713            }
1714            IntervalUnit::Millisecond => {
1715                let nanos_int = amount.integer.mul_checked(NANOS_PER_MILLIS)?;
1716                let nanos_frac = amount.frac / 10_i64.pow(INTERVAL_PRECISION - 6);
1717                let nanos = nanos_int.add_checked(nanos_frac)?;
1718
1719                Interval::new(self.months, self.days, self.nanos.add_checked(nanos)?)
1720            }
1721            IntervalUnit::Microsecond => {
1722                let nanos_int = amount.integer.mul_checked(1_000)?;
1723                let nanos_frac = amount.frac / 10_i64.pow(INTERVAL_PRECISION - 3);
1724                let nanos = nanos_int.add_checked(nanos_frac)?;
1725
1726                Interval::new(self.months, self.days, self.nanos.add_checked(nanos)?)
1727            }
1728            IntervalUnit::Nanosecond => {
1729                let nanos_int = amount.integer;
1730                let nanos_frac = amount.frac / 10_i64.pow(INTERVAL_PRECISION);
1731                let nanos = nanos_int.add_checked(nanos_frac)?;
1732
1733                Interval::new(self.months, self.days, self.nanos.add_checked(nanos)?)
1734            }
1735        };
1736
1737        Ok(result)
1738    }
1739}
1740
1741/// parse the string into a vector of interval components i.e. (amount, unit) tuples
1742fn parse_interval_components(
1743    value: &str,
1744    config: &IntervalParseConfig,
1745) -> Result<Vec<(IntervalAmount, IntervalUnit)>, ArrowError> {
1746    let raw_pairs = split_interval_components(value);
1747
1748    // parse amounts and units
1749    let Ok(pairs): Result<Vec<(IntervalAmount, IntervalUnit)>, ArrowError> = raw_pairs
1750        .iter()
1751        .map(|(a, u)| Ok((a.parse()?, IntervalUnit::from_str_or_config(*u, config)?)))
1752        .collect()
1753    else {
1754        return Err(ArrowError::ParseError(format!(
1755            "Invalid input syntax for type interval: {value:?}"
1756        )));
1757    };
1758
1759    if !config.allow_fractional_calendar_units {
1760        for (amount, unit) in &pairs {
1761            if amount.frac != 0 && unit.is_calendar_unit() {
1762                return Err(ArrowError::ParseError(format!(
1763                    "Fractional calendar units are not supported: {value:?}"
1764                )));
1765            }
1766        }
1767    }
1768
1769    // collect parsed results
1770    let (amounts, units): (Vec<_>, Vec<_>) = pairs.into_iter().unzip();
1771
1772    // duplicate units?
1773    let mut observed_interval_types = 0;
1774    for (unit, (_, raw_unit)) in units.iter().zip(raw_pairs) {
1775        if observed_interval_types & (*unit as u16) != 0 {
1776            return Err(ArrowError::ParseError(format!(
1777                "Invalid input syntax for type interval: {:?}. Repeated type '{}'",
1778                value,
1779                raw_unit.unwrap_or_default(),
1780            )));
1781        }
1782
1783        observed_interval_types |= *unit as u16;
1784    }
1785
1786    let result = amounts.iter().copied().zip(units.iter().copied());
1787
1788    Ok(result.collect::<Vec<_>>())
1789}
1790
1791/// Split an interval into a vec of amounts and units.
1792///
1793/// Pairs are separated by spaces, but within a pair the amount and unit may or may not be separated by a space.
1794///
1795/// This should match the behavior of PostgreSQL's interval parser.
1796fn split_interval_components(value: &str) -> Vec<(&str, Option<&str>)> {
1797    let mut result = vec![];
1798    let mut words = value.split(char::is_whitespace);
1799    while let Some(word) = words.next() {
1800        if let Some(split_word_at) = word.find(not_interval_amount) {
1801            let (amount, unit) = word.split_at(split_word_at);
1802            result.push((amount, Some(unit)));
1803        } else if let Some(unit) = words.next() {
1804            result.push((word, Some(unit)));
1805        } else {
1806            result.push((word, None));
1807            break;
1808        }
1809    }
1810    result
1811}
1812
1813/// test if a character is NOT part of an interval numeric amount
1814fn not_interval_amount(c: char) -> bool {
1815    !c.is_ascii_digit() && c != '.' && c != '-'
1816}
1817
1818#[cfg(test)]
1819mod tests {
1820    use super::*;
1821    use arrow_array::temporal_conversions::date32_to_datetime;
1822    use arrow_buffer::i256;
1823
1824    /// Parses `s` without a precision check, for probing the native range
1825    fn parse_native<T: DecimalType>(s: &str, scale: i8) -> Result<T::Native, DecimalParseError> {
1826        parse_decimal_native::<T>(s, scale).map(|(value, _)| value)
1827    }
1828
1829    #[test]
1830    fn test_parse_nanos() {
1831        assert_eq!(parse_nanos::<3, 0>(&[1, 2, 3]), 123_000_000);
1832        assert_eq!(parse_nanos::<5, 0>(&[1, 2, 3, 4, 5]), 123_450_000);
1833        assert_eq!(parse_nanos::<6, b'0'>(b"123456"), 123_456_000);
1834    }
1835
1836    #[test]
1837    fn string_to_timestamp_timezone() {
1838        // Explicit timezone
1839        assert_eq!(
1840            1599572549190855000,
1841            parse_timestamp("2020-09-08T13:42:29.190855+00:00").unwrap()
1842        );
1843        assert_eq!(
1844            1599572549190855000,
1845            parse_timestamp("2020-09-08T13:42:29.190855Z").unwrap()
1846        );
1847        assert_eq!(
1848            1599572549000000000,
1849            parse_timestamp("2020-09-08T13:42:29Z").unwrap()
1850        ); // no fractional part
1851        assert_eq!(
1852            1599590549190855000,
1853            parse_timestamp("2020-09-08T13:42:29.190855-05:00").unwrap()
1854        );
1855    }
1856
1857    #[test]
1858    fn string_to_timestamp_timezone_space() {
1859        // Ensure space rather than T between time and date is accepted
1860        assert_eq!(
1861            1599572549190855000,
1862            parse_timestamp("2020-09-08 13:42:29.190855+00:00").unwrap()
1863        );
1864        assert_eq!(
1865            1599572549190855000,
1866            parse_timestamp("2020-09-08 13:42:29.190855Z").unwrap()
1867        );
1868        assert_eq!(
1869            1599572549000000000,
1870            parse_timestamp("2020-09-08 13:42:29Z").unwrap()
1871        ); // no fractional part
1872        assert_eq!(
1873            1599590549190855000,
1874            parse_timestamp("2020-09-08 13:42:29.190855-05:00").unwrap()
1875        );
1876    }
1877
1878    #[test]
1879    fn string_to_timestamp_no_timezone() {
1880        // This test is designed to succeed in regardless of the local
1881        // timezone the test machine is running. Thus it is still
1882        // somewhat susceptible to bugs in the use of chrono
1883        let naive_datetime = NaiveDateTime::new(
1884            NaiveDate::from_ymd_opt(2020, 9, 8).unwrap(),
1885            NaiveTime::from_hms_nano_opt(13, 42, 29, 190855000).unwrap(),
1886        );
1887
1888        // Ensure both T and ' ' variants work
1889        assert_eq!(
1890            naive_datetime.and_utc().timestamp_nanos_opt().unwrap(),
1891            parse_timestamp("2020-09-08T13:42:29.190855").unwrap()
1892        );
1893
1894        assert_eq!(
1895            naive_datetime.and_utc().timestamp_nanos_opt().unwrap(),
1896            parse_timestamp("2020-09-08 13:42:29.190855").unwrap()
1897        );
1898
1899        // Also ensure that parsing timestamps with no fractional
1900        // second part works as well
1901        let datetime_whole_secs = NaiveDateTime::new(
1902            NaiveDate::from_ymd_opt(2020, 9, 8).unwrap(),
1903            NaiveTime::from_hms_opt(13, 42, 29).unwrap(),
1904        )
1905        .and_utc();
1906
1907        // Ensure both T and ' ' variants work
1908        assert_eq!(
1909            datetime_whole_secs.timestamp_nanos_opt().unwrap(),
1910            parse_timestamp("2020-09-08T13:42:29").unwrap()
1911        );
1912
1913        assert_eq!(
1914            datetime_whole_secs.timestamp_nanos_opt().unwrap(),
1915            parse_timestamp("2020-09-08 13:42:29").unwrap()
1916        );
1917
1918        // ensure without time work
1919        // no time, should be the nano second at
1920        // 2020-09-08 0:0:0
1921        let datetime_no_time = NaiveDateTime::new(
1922            NaiveDate::from_ymd_opt(2020, 9, 8).unwrap(),
1923            NaiveTime::from_hms_opt(0, 0, 0).unwrap(),
1924        )
1925        .and_utc();
1926
1927        assert_eq!(
1928            datetime_no_time.timestamp_nanos_opt().unwrap(),
1929            parse_timestamp("2020-09-08").unwrap()
1930        )
1931    }
1932
1933    #[test]
1934    fn string_to_timestamp_chrono() {
1935        let cases = [
1936            "2020-09-08T13:42:29Z",
1937            "1969-01-01T00:00:00.1Z",
1938            "2020-09-08T12:00:12.12345678+00:00",
1939            "2020-09-08T12:00:12+00:00",
1940            "2020-09-08T12:00:12.1+00:00",
1941            "2020-09-08T12:00:12.12+00:00",
1942            "2020-09-08T12:00:12.123+00:00",
1943            "2020-09-08T12:00:12.1234+00:00",
1944            "2020-09-08T12:00:12.12345+00:00",
1945            "2020-09-08T12:00:12.123456+00:00",
1946            "2020-09-08T12:00:12.1234567+00:00",
1947            "2020-09-08T12:00:12.12345678+00:00",
1948            "2020-09-08T12:00:12.123456789+00:00",
1949            "2020-09-08T12:00:12.12345678912z",
1950            "2020-09-08T12:00:12.123456789123Z",
1951            "2020-09-08T12:00:12.123456789123+02:00",
1952            "2020-09-08T12:00:12.12345678912345Z",
1953            "2020-09-08T12:00:12.1234567891234567+02:00",
1954            "2020-09-08T12:00:60Z",
1955            "2020-09-08T12:00:60.123Z",
1956            "2020-09-08T12:00:60.123456+02:00",
1957            "2020-09-08T12:00:60.1234567891234567+02:00",
1958            "2020-09-08T12:00:60.999999999+02:00",
1959            "2020-09-08t12:00:12.12345678+00:00",
1960            "2020-09-08t12:00:12+00:00",
1961            "2020-09-08t12:00:12Z",
1962        ];
1963
1964        for case in cases {
1965            let chrono = DateTime::parse_from_rfc3339(case).unwrap();
1966            let chrono_utc = chrono.with_timezone(&Utc);
1967
1968            let custom = string_to_datetime(&Utc, case).unwrap();
1969            assert_eq!(chrono_utc, custom)
1970        }
1971    }
1972
1973    #[test]
1974    fn string_to_timestamp_naive() {
1975        let cases = [
1976            "2018-11-13T17:11:10.011375885995",
1977            "2030-12-04T17:11:10.123",
1978            "2030-12-04T17:11:10.1234",
1979            "2030-12-04T17:11:10.123456",
1980        ];
1981        for case in cases {
1982            let chrono = NaiveDateTime::parse_from_str(case, "%Y-%m-%dT%H:%M:%S%.f").unwrap();
1983            let custom = string_to_datetime(&Utc, case).unwrap();
1984            assert_eq!(chrono, custom.naive_utc())
1985        }
1986    }
1987
1988    #[test]
1989    fn string_to_timestamp_without_seconds() {
1990        let cases = [
1991            ("2025-08-14T00:00Z", (2025, 8, 14, 0, 0)),
1992            ("2025-08-14T09:26", (2025, 8, 14, 9, 26)),
1993            ("2025-08-14 09:26+05:30", (2025, 8, 14, 3, 56)),
1994            ("2025-08-14t23:59-08:00", (2025, 8, 15, 7, 59)),
1995        ];
1996        for (case, (y, m, d, h, min)) in cases {
1997            let expected = Utc.with_ymd_and_hms(y, m, d, h, min, 0).unwrap();
1998            assert_eq!(string_to_datetime(&Utc, case).unwrap(), expected)
1999        }
2000    }
2001
2002    #[test]
2003    fn string_to_timestamp_invalid() {
2004        // Test parsing invalid formats
2005        let cases = [
2006            ("", "timestamp must contain at least 10 characters"),
2007            ("SS", "timestamp must contain at least 10 characters"),
2008            ("Wed, 18 Feb 2015 23:16:09 GMT", "error parsing date"),
2009            ("1997-01-31H09:26:56.123Z", "invalid timestamp separator"),
2010            ("1997-01-31  09:26:56.123Z", "error parsing time"),
2011            ("1997:01:31T09:26:56.123Z", "error parsing date"),
2012            ("1997:1:31T09:26:56.123Z", "error parsing date"),
2013            ("1997-01-32T09:26:56.123Z", "error parsing date"),
2014            ("1997-13-32T09:26:56.123Z", "error parsing date"),
2015            ("1997-02-29T09:26:56.123Z", "error parsing date"),
2016            ("2015-02-30T17:35:20-08:00", "error parsing date"),
2017            ("1997-01-10T9:26:56.123Z", "error parsing time"),
2018            ("2015-01-20T25:35:20-08:00", "error parsing time"),
2019            ("1997-01-10T09:61:56.123Z", "error parsing time"),
2020            ("1997-01-10T09:61:90.123Z", "error parsing time"),
2021            ("1997-01-10T12:00:6.123Z", "error parsing time"),
2022            ("1997-01-31T092656.123Z", "error parsing time"),
2023            ("1997-01-10T12:00:06.", "error parsing time"),
2024            ("1997-01-10T12:00:06. ", "error parsing time"),
2025            ("1997-01-10T09:2Z", "error parsing time"),
2026            ("1997-01-10T09:26:Z", "error parsing time"),
2027            ("1997-01-10T09:26.5Z", "error parsing time"),
2028            ("1997-01-10T09:61Z", "error parsing time"),
2029        ];
2030
2031        for (s, ctx) in cases {
2032            let expected = format!("Parser error: Error parsing timestamp from '{s}': {ctx}");
2033            let actual = string_to_datetime(&Utc, s).unwrap_err().to_string();
2034            assert_eq!(actual, expected)
2035        }
2036    }
2037
2038    // Parse a timestamp to timestamp int with a useful human readable error message
2039    fn parse_timestamp(s: &str) -> Result<i64, ArrowError> {
2040        let result = string_to_timestamp_nanos(s);
2041        if let Err(e) = &result {
2042            eprintln!("Error parsing timestamp '{s}': {e:?}");
2043        }
2044        result
2045    }
2046
2047    #[test]
2048    fn string_without_timezone_to_timestamp() {
2049        // string without timezone should always output the same regardless the local or session timezone
2050
2051        let naive_datetime = NaiveDateTime::new(
2052            NaiveDate::from_ymd_opt(2020, 9, 8).unwrap(),
2053            NaiveTime::from_hms_nano_opt(13, 42, 29, 190855000).unwrap(),
2054        );
2055
2056        // Ensure both T and ' ' variants work
2057        assert_eq!(
2058            naive_datetime.and_utc().timestamp_nanos_opt().unwrap(),
2059            parse_timestamp("2020-09-08T13:42:29.190855").unwrap()
2060        );
2061
2062        assert_eq!(
2063            naive_datetime.and_utc().timestamp_nanos_opt().unwrap(),
2064            parse_timestamp("2020-09-08 13:42:29.190855").unwrap()
2065        );
2066
2067        let naive_datetime = NaiveDateTime::new(
2068            NaiveDate::from_ymd_opt(2020, 9, 8).unwrap(),
2069            NaiveTime::from_hms_nano_opt(13, 42, 29, 0).unwrap(),
2070        );
2071
2072        // Ensure both T and ' ' variants work
2073        assert_eq!(
2074            naive_datetime.and_utc().timestamp_nanos_opt().unwrap(),
2075            parse_timestamp("2020-09-08T13:42:29").unwrap()
2076        );
2077
2078        assert_eq!(
2079            naive_datetime.and_utc().timestamp_nanos_opt().unwrap(),
2080            parse_timestamp("2020-09-08 13:42:29").unwrap()
2081        );
2082
2083        let tz: Tz = "+02:00".parse().unwrap();
2084        let date = string_to_datetime(&tz, "2020-09-08 13:42:29").unwrap();
2085        let utc = date.naive_utc().to_string();
2086        assert_eq!(utc, "2020-09-08 11:42:29");
2087        let local = date.naive_local().to_string();
2088        assert_eq!(local, "2020-09-08 13:42:29");
2089
2090        let date = string_to_datetime(&tz, "2020-09-08 13:42:29Z").unwrap();
2091        let utc = date.naive_utc().to_string();
2092        assert_eq!(utc, "2020-09-08 13:42:29");
2093        let local = date.naive_local().to_string();
2094        assert_eq!(local, "2020-09-08 15:42:29");
2095
2096        let dt =
2097            NaiveDateTime::parse_from_str("2020-09-08T13:42:29Z", "%Y-%m-%dT%H:%M:%SZ").unwrap();
2098        let local: Tz = "+08:00".parse().unwrap();
2099
2100        // Parsed as offset from UTC
2101        let date = string_to_datetime(&local, "2020-09-08T13:42:29Z").unwrap();
2102        assert_eq!(dt, date.naive_utc());
2103        assert_ne!(dt, date.naive_local());
2104
2105        // Parsed as offset from local
2106        let date = string_to_datetime(&local, "2020-09-08 13:42:29").unwrap();
2107        assert_eq!(dt, date.naive_local());
2108        assert_ne!(dt, date.naive_utc());
2109    }
2110
2111    #[test]
2112    fn parse_date32() {
2113        let cases = [
2114            "2020-09-08",
2115            "2020-9-8",
2116            "2020-09-8",
2117            "2020-9-08",
2118            "2020-12-1",
2119            "1690-2-5",
2120            "2020-09-08 01:02:03",
2121            "2020-09-08 01:02",
2122        ];
2123        for case in cases {
2124            let v = date32_to_datetime(Date32Type::parse(case).unwrap()).unwrap();
2125            let expected = NaiveDate::parse_from_str(case, "%Y-%m-%d")
2126                .or_else(|_| NaiveDate::parse_from_str(case, "%Y-%m-%d %H:%M:%S"))
2127                .or_else(|_| NaiveDate::parse_from_str(case, "%Y-%m-%d %H:%M"))
2128                .unwrap();
2129            assert_eq!(v.date(), expected);
2130        }
2131
2132        let err_cases = [
2133            "",
2134            "80-01-01",
2135            "342",
2136            "Foo",
2137            "2020-09-08-03",
2138            "2020--04-03",
2139            "2020--",
2140            "2020-09-08 01",
2141            "2020-09-08 01-02-03",
2142            "2020-9-8 01:02:03",
2143            "2020-09-08 1:2:3",
2144        ];
2145        for case in err_cases {
2146            assert_eq!(Date32Type::parse(case), None);
2147        }
2148    }
2149
2150    #[test]
2151    fn parse_date32_extended_year() {
2152        // `Date32` covers any i32 days-from-epoch, verify we can parse it
2153        let cases: &[(&str, i32)] = &[
2154            ("+1970-01-01", 0),
2155            ("+2024-01-01", 19_723),
2156            ("-0001-01-01", -719_893),
2157            ("+29349-01-26", 10_000_000),
2158            ("+2739877-01-03", 1_000_000_000),
2159            // Extremes of the Date32 representable range.
2160            ("+5881580-07-11", i32::MAX),
2161            ("-5877641-06-23", i32::MIN),
2162        ];
2163        for (input, expected) in cases {
2164            assert_eq!(Date32Type::parse(input), Some(*expected), "input: {input}");
2165        }
2166
2167        // One past Date32::MAX / MIN overflows i32 days-from-epoch.
2168        assert_eq!(Date32Type::parse("+5881580-07-12"), None);
2169        assert_eq!(Date32Type::parse("-5877641-06-22"), None);
2170        // Invalid calendar dates still rejected regardless of year magnitude.
2171        assert_eq!(Date32Type::parse("+2739877-02-30"), None);
2172        assert_eq!(Date32Type::parse("+2739877-13-01"), None);
2173        assert_eq!(Date32Type::parse("-2739877-02-30"), None);
2174    }
2175
2176    #[test]
2177    fn parse_time64_nanos() {
2178        assert_eq!(
2179            Time64NanosecondType::parse("02:10:01.1234567899999999"),
2180            Some(7_801_123_456_789)
2181        );
2182        assert_eq!(
2183            Time64NanosecondType::parse("02:10:01.1234567"),
2184            Some(7_801_123_456_700)
2185        );
2186        assert_eq!(
2187            Time64NanosecondType::parse("2:10:01.1234567"),
2188            Some(7_801_123_456_700)
2189        );
2190        assert_eq!(
2191            Time64NanosecondType::parse("12:10:01.123456789 AM"),
2192            Some(601_123_456_789)
2193        );
2194        assert_eq!(
2195            Time64NanosecondType::parse("12:10:01.123456789 am"),
2196            Some(601_123_456_789)
2197        );
2198        assert_eq!(
2199            Time64NanosecondType::parse("2:10:01.12345678 PM"),
2200            Some(51_001_123_456_780)
2201        );
2202        assert_eq!(
2203            Time64NanosecondType::parse("2:10:01.12345678 pm"),
2204            Some(51_001_123_456_780)
2205        );
2206        assert_eq!(
2207            Time64NanosecondType::parse("02:10:01"),
2208            Some(7_801_000_000_000)
2209        );
2210        assert_eq!(
2211            Time64NanosecondType::parse("2:10:01"),
2212            Some(7_801_000_000_000)
2213        );
2214        assert_eq!(
2215            Time64NanosecondType::parse("12:10:01 AM"),
2216            Some(601_000_000_000)
2217        );
2218        assert_eq!(
2219            Time64NanosecondType::parse("12:10:01 am"),
2220            Some(601_000_000_000)
2221        );
2222        assert_eq!(
2223            Time64NanosecondType::parse("2:10:01 PM"),
2224            Some(51_001_000_000_000)
2225        );
2226        assert_eq!(
2227            Time64NanosecondType::parse("2:10:01 pm"),
2228            Some(51_001_000_000_000)
2229        );
2230        assert_eq!(
2231            Time64NanosecondType::parse("02:10"),
2232            Some(7_800_000_000_000)
2233        );
2234        assert_eq!(Time64NanosecondType::parse("2:10"), Some(7_800_000_000_000));
2235        assert_eq!(
2236            Time64NanosecondType::parse("12:10 AM"),
2237            Some(600_000_000_000)
2238        );
2239        assert_eq!(
2240            Time64NanosecondType::parse("12:10 am"),
2241            Some(600_000_000_000)
2242        );
2243        assert_eq!(
2244            Time64NanosecondType::parse("2:10 PM"),
2245            Some(51_000_000_000_000)
2246        );
2247        assert_eq!(
2248            Time64NanosecondType::parse("2:10 pm"),
2249            Some(51_000_000_000_000)
2250        );
2251
2252        // parse directly as nanoseconds
2253        assert_eq!(Time64NanosecondType::parse("1"), Some(1));
2254
2255        // leap second
2256        assert_eq!(
2257            Time64NanosecondType::parse("23:59:60"),
2258            Some(86_400_000_000_000)
2259        );
2260
2261        // custom format
2262        assert_eq!(
2263            Time64NanosecondType::parse_formatted("02 - 10 - 01 - .1234567", "%H - %M - %S - %.f"),
2264            Some(7_801_123_456_700)
2265        );
2266    }
2267
2268    #[test]
2269    fn parse_time64_micros() {
2270        // expected formats
2271        assert_eq!(
2272            Time64MicrosecondType::parse("02:10:01.1234"),
2273            Some(7_801_123_400)
2274        );
2275        assert_eq!(
2276            Time64MicrosecondType::parse("2:10:01.1234"),
2277            Some(7_801_123_400)
2278        );
2279        assert_eq!(
2280            Time64MicrosecondType::parse("12:10:01.123456 AM"),
2281            Some(601_123_456)
2282        );
2283        assert_eq!(
2284            Time64MicrosecondType::parse("12:10:01.123456 am"),
2285            Some(601_123_456)
2286        );
2287        assert_eq!(
2288            Time64MicrosecondType::parse("2:10:01.12345 PM"),
2289            Some(51_001_123_450)
2290        );
2291        assert_eq!(
2292            Time64MicrosecondType::parse("2:10:01.12345 pm"),
2293            Some(51_001_123_450)
2294        );
2295        assert_eq!(
2296            Time64MicrosecondType::parse("02:10:01"),
2297            Some(7_801_000_000)
2298        );
2299        assert_eq!(Time64MicrosecondType::parse("2:10:01"), Some(7_801_000_000));
2300        assert_eq!(
2301            Time64MicrosecondType::parse("12:10:01 AM"),
2302            Some(601_000_000)
2303        );
2304        assert_eq!(
2305            Time64MicrosecondType::parse("12:10:01 am"),
2306            Some(601_000_000)
2307        );
2308        assert_eq!(
2309            Time64MicrosecondType::parse("2:10:01 PM"),
2310            Some(51_001_000_000)
2311        );
2312        assert_eq!(
2313            Time64MicrosecondType::parse("2:10:01 pm"),
2314            Some(51_001_000_000)
2315        );
2316        assert_eq!(Time64MicrosecondType::parse("02:10"), Some(7_800_000_000));
2317        assert_eq!(Time64MicrosecondType::parse("2:10"), Some(7_800_000_000));
2318        assert_eq!(Time64MicrosecondType::parse("12:10 AM"), Some(600_000_000));
2319        assert_eq!(Time64MicrosecondType::parse("12:10 am"), Some(600_000_000));
2320        assert_eq!(
2321            Time64MicrosecondType::parse("2:10 PM"),
2322            Some(51_000_000_000)
2323        );
2324        assert_eq!(
2325            Time64MicrosecondType::parse("2:10 pm"),
2326            Some(51_000_000_000)
2327        );
2328
2329        // parse directly as microseconds
2330        assert_eq!(Time64MicrosecondType::parse("1"), Some(1));
2331
2332        // leap second
2333        assert_eq!(
2334            Time64MicrosecondType::parse("23:59:60"),
2335            Some(86_400_000_000)
2336        );
2337
2338        // custom format
2339        assert_eq!(
2340            Time64MicrosecondType::parse_formatted("02 - 10 - 01 - .1234", "%H - %M - %S - %.f"),
2341            Some(7_801_123_400)
2342        );
2343    }
2344
2345    #[test]
2346    fn parse_time32_millis() {
2347        // expected formats
2348        assert_eq!(Time32MillisecondType::parse("02:10:01.1"), Some(7_801_100));
2349        assert_eq!(Time32MillisecondType::parse("2:10:01.1"), Some(7_801_100));
2350        assert_eq!(
2351            Time32MillisecondType::parse("12:10:01.123 AM"),
2352            Some(601_123)
2353        );
2354        assert_eq!(
2355            Time32MillisecondType::parse("12:10:01.123 am"),
2356            Some(601_123)
2357        );
2358        assert_eq!(
2359            Time32MillisecondType::parse("2:10:01.12 PM"),
2360            Some(51_001_120)
2361        );
2362        assert_eq!(
2363            Time32MillisecondType::parse("2:10:01.12 pm"),
2364            Some(51_001_120)
2365        );
2366        assert_eq!(Time32MillisecondType::parse("02:10:01"), Some(7_801_000));
2367        assert_eq!(Time32MillisecondType::parse("2:10:01"), Some(7_801_000));
2368        assert_eq!(Time32MillisecondType::parse("12:10:01 AM"), Some(601_000));
2369        assert_eq!(Time32MillisecondType::parse("12:10:01 am"), Some(601_000));
2370        assert_eq!(Time32MillisecondType::parse("2:10:01 PM"), Some(51_001_000));
2371        assert_eq!(Time32MillisecondType::parse("2:10:01 pm"), Some(51_001_000));
2372        assert_eq!(Time32MillisecondType::parse("02:10"), Some(7_800_000));
2373        assert_eq!(Time32MillisecondType::parse("2:10"), Some(7_800_000));
2374        assert_eq!(Time32MillisecondType::parse("12:10 AM"), Some(600_000));
2375        assert_eq!(Time32MillisecondType::parse("12:10 am"), Some(600_000));
2376        assert_eq!(Time32MillisecondType::parse("2:10 PM"), Some(51_000_000));
2377        assert_eq!(Time32MillisecondType::parse("2:10 pm"), Some(51_000_000));
2378
2379        // parse directly as milliseconds
2380        assert_eq!(Time32MillisecondType::parse("1"), Some(1));
2381
2382        // leap second
2383        assert_eq!(Time32MillisecondType::parse("23:59:60"), Some(86_400_000));
2384
2385        // custom format
2386        assert_eq!(
2387            Time32MillisecondType::parse_formatted("02 - 10 - 01 - .1", "%H - %M - %S - %.f"),
2388            Some(7_801_100)
2389        );
2390    }
2391
2392    #[test]
2393    fn parse_time32_secs() {
2394        // expected formats
2395        assert_eq!(Time32SecondType::parse("02:10:01.1"), Some(7_801));
2396        assert_eq!(Time32SecondType::parse("02:10:01"), Some(7_801));
2397        assert_eq!(Time32SecondType::parse("2:10:01"), Some(7_801));
2398        assert_eq!(Time32SecondType::parse("12:10:01 AM"), Some(601));
2399        assert_eq!(Time32SecondType::parse("12:10:01 am"), Some(601));
2400        assert_eq!(Time32SecondType::parse("2:10:01 PM"), Some(51_001));
2401        assert_eq!(Time32SecondType::parse("2:10:01 pm"), Some(51_001));
2402        assert_eq!(Time32SecondType::parse("02:10"), Some(7_800));
2403        assert_eq!(Time32SecondType::parse("2:10"), Some(7_800));
2404        assert_eq!(Time32SecondType::parse("12:10 AM"), Some(600));
2405        assert_eq!(Time32SecondType::parse("12:10 am"), Some(600));
2406        assert_eq!(Time32SecondType::parse("2:10 PM"), Some(51_000));
2407        assert_eq!(Time32SecondType::parse("2:10 pm"), Some(51_000));
2408
2409        // parse directly as seconds
2410        assert_eq!(Time32SecondType::parse("1"), Some(1));
2411
2412        // leap second
2413        assert_eq!(Time32SecondType::parse("23:59:60"), Some(86400));
2414
2415        // custom format
2416        assert_eq!(
2417            Time32SecondType::parse_formatted("02 - 10 - 01", "%H - %M - %S"),
2418            Some(7_801)
2419        );
2420    }
2421
2422    #[test]
2423    fn test_string_to_time_invalid() {
2424        let cases = [
2425            "25:00",
2426            "9:00:",
2427            "009:00",
2428            "09:0:00",
2429            "25:00:00",
2430            "13:00 AM",
2431            "13:00 PM",
2432            "12:00. AM",
2433            "09:0:00",
2434            "09:01:0",
2435            "09:01:1",
2436            "9:1:0",
2437            "09:01:0",
2438            "1:00.123",
2439            "1:00:00.123f",
2440            " 9:00:00",
2441            ":09:00",
2442            "T9:00:00",
2443            "AM",
2444        ];
2445        for case in cases {
2446            assert!(string_to_time(case).is_none(), "{case}");
2447        }
2448    }
2449
2450    #[test]
2451    fn test_string_to_time_chrono() {
2452        let cases = [
2453            ("1:00", "%H:%M"),
2454            ("12:00", "%H:%M"),
2455            ("13:00", "%H:%M"),
2456            ("24:00", "%H:%M"),
2457            ("1:00:00", "%H:%M:%S"),
2458            ("12:00:30", "%H:%M:%S"),
2459            ("13:00:59", "%H:%M:%S"),
2460            ("24:00:60", "%H:%M:%S"),
2461            ("09:00:00", "%H:%M:%S%.f"),
2462            ("0:00:30.123456", "%H:%M:%S%.f"),
2463            ("0:00 AM", "%I:%M %P"),
2464            ("1:00 AM", "%I:%M %P"),
2465            ("12:00 AM", "%I:%M %P"),
2466            ("13:00 AM", "%I:%M %P"),
2467            ("0:00 PM", "%I:%M %P"),
2468            ("1:00 PM", "%I:%M %P"),
2469            ("12:00 PM", "%I:%M %P"),
2470            ("13:00 PM", "%I:%M %P"),
2471            ("1:00 pM", "%I:%M %P"),
2472            ("1:00 Pm", "%I:%M %P"),
2473            ("1:00 aM", "%I:%M %P"),
2474            ("1:00 Am", "%I:%M %P"),
2475            ("1:00:30.123456 PM", "%I:%M:%S%.f %P"),
2476            ("1:00:30.123456789 PM", "%I:%M:%S%.f %P"),
2477            ("1:00:30.123456789123 PM", "%I:%M:%S%.f %P"),
2478            ("1:00:30.1234 PM", "%I:%M:%S%.f %P"),
2479            ("1:00:30.123456 PM", "%I:%M:%S%.f %P"),
2480            ("1:00:30.123456789123456789 PM", "%I:%M:%S%.f %P"),
2481            ("1:00:30.12F456 PM", "%I:%M:%S%.f %P"),
2482        ];
2483        for (s, format) in cases {
2484            let chrono = NaiveTime::parse_from_str(s, format).ok();
2485            let custom = string_to_time(s);
2486            assert_eq!(chrono, custom, "{s}");
2487        }
2488    }
2489
2490    #[test]
2491    fn test_parse_interval() {
2492        let config = IntervalParseConfig::new(IntervalUnit::Month);
2493
2494        assert_eq!(
2495            Interval::new(1i32, 0i32, 0i64),
2496            Interval::parse("1 month", &config).unwrap(),
2497        );
2498
2499        assert_eq!(
2500            Interval::new(2i32, 0i32, 0i64),
2501            Interval::parse("2 month", &config).unwrap(),
2502        );
2503
2504        assert_eq!(
2505            Interval::new(-1i32, -18i32, -(NANOS_PER_DAY / 5)),
2506            Interval::parse("-1.5 months -3.2 days", &config).unwrap(),
2507        );
2508
2509        assert_eq!(
2510            Interval::new(0i32, 15i32, 0),
2511            Interval::parse("0.5 months", &config).unwrap(),
2512        );
2513
2514        assert_eq!(
2515            Interval::new(0i32, 15i32, 0),
2516            Interval::parse(".5 months", &config).unwrap(),
2517        );
2518
2519        assert_eq!(
2520            Interval::new(0i32, -15i32, 0),
2521            Interval::parse("-0.5 months", &config).unwrap(),
2522        );
2523
2524        assert_eq!(
2525            Interval::new(0i32, -15i32, 0),
2526            Interval::parse("-.5 months", &config).unwrap(),
2527        );
2528
2529        assert_eq!(
2530            Interval::new(2i32, 10i32, 9 * NANOS_PER_HOUR),
2531            Interval::parse("2.1 months 7.25 days 3 hours", &config).unwrap(),
2532        );
2533
2534        assert_eq!(
2535            Interval::parse("1 centurys 1 month", &config)
2536                .unwrap_err()
2537                .to_string(),
2538            r#"Parser error: Invalid input syntax for type interval: "1 centurys 1 month""#
2539        );
2540
2541        assert_eq!(
2542            Interval::new(37i32, 0i32, 0i64),
2543            Interval::parse("3 year 1 month", &config).unwrap(),
2544        );
2545
2546        assert_eq!(
2547            Interval::new(35i32, 0i32, 0i64),
2548            Interval::parse("3 year -1 month", &config).unwrap(),
2549        );
2550
2551        assert_eq!(
2552            Interval::new(-37i32, 0i32, 0i64),
2553            Interval::parse("-3 year -1 month", &config).unwrap(),
2554        );
2555
2556        assert_eq!(
2557            Interval::new(-35i32, 0i32, 0i64),
2558            Interval::parse("-3 year 1 month", &config).unwrap(),
2559        );
2560
2561        assert_eq!(
2562            Interval::new(0i32, 5i32, 0i64),
2563            Interval::parse("5 days", &config).unwrap(),
2564        );
2565
2566        assert_eq!(
2567            Interval::new(0i32, 7i32, 3 * NANOS_PER_HOUR),
2568            Interval::parse("7 days 3 hours", &config).unwrap(),
2569        );
2570
2571        assert_eq!(
2572            Interval::new(0i32, 7i32, 5 * NANOS_PER_MINUTE),
2573            Interval::parse("7 days 5 minutes", &config).unwrap(),
2574        );
2575
2576        assert_eq!(
2577            Interval::new(0i32, 7i32, -5 * NANOS_PER_MINUTE),
2578            Interval::parse("7 days -5 minutes", &config).unwrap(),
2579        );
2580
2581        assert_eq!(
2582            Interval::new(0i32, -7i32, 5 * NANOS_PER_HOUR),
2583            Interval::parse("-7 days 5 hours", &config).unwrap(),
2584        );
2585
2586        assert_eq!(
2587            Interval::new(
2588                0i32,
2589                -7i32,
2590                -5 * NANOS_PER_HOUR - 5 * NANOS_PER_MINUTE - 5 * NANOS_PER_SECOND
2591            ),
2592            Interval::parse("-7 days -5 hours -5 minutes -5 seconds", &config).unwrap(),
2593        );
2594
2595        assert_eq!(
2596            Interval::new(12i32, 0i32, 25 * NANOS_PER_MILLIS),
2597            Interval::parse("1 year 25 millisecond", &config).unwrap(),
2598        );
2599
2600        assert_eq!(
2601            Interval::new(
2602                12i32,
2603                1i32,
2604                (NANOS_PER_SECOND as f64 * 0.000000001_f64) as i64
2605            ),
2606            Interval::parse("1 year 1 day 0.000000001 seconds", &config).unwrap(),
2607        );
2608
2609        assert_eq!(
2610            Interval::new(12i32, 1i32, NANOS_PER_MILLIS / 10),
2611            Interval::parse("1 year 1 day 0.1 milliseconds", &config).unwrap(),
2612        );
2613
2614        assert_eq!(
2615            Interval::new(12i32, 1i32, 1000i64),
2616            Interval::parse("1 year 1 day 1 microsecond", &config).unwrap(),
2617        );
2618
2619        assert_eq!(
2620            Interval::new(12i32, 1i32, 1i64),
2621            Interval::parse("1 year 1 day 1 nanoseconds", &config).unwrap(),
2622        );
2623
2624        assert_eq!(
2625            Interval::new(1i32, 0i32, -NANOS_PER_SECOND),
2626            Interval::parse("1 month -1 second", &config).unwrap(),
2627        );
2628
2629        assert_eq!(
2630            Interval::new(
2631                -13i32,
2632                -8i32,
2633                -NANOS_PER_HOUR
2634                    - NANOS_PER_MINUTE
2635                    - NANOS_PER_SECOND
2636                    - (1.11_f64 * NANOS_PER_MILLIS as f64) as i64
2637            ),
2638            Interval::parse(
2639                "-1 year -1 month -1 week -1 day -1 hour -1 minute -1 second -1.11 millisecond",
2640                &config
2641            )
2642            .unwrap(),
2643        );
2644
2645        // no units
2646        assert_eq!(
2647            Interval::new(1, 0, 0),
2648            Interval::parse("1", &config).unwrap()
2649        );
2650        assert_eq!(
2651            Interval::new(42, 0, 0),
2652            Interval::parse("42", &config).unwrap()
2653        );
2654        assert_eq!(
2655            Interval::new(0, 0, 42_000_000_000),
2656            Interval::parse("42", &IntervalParseConfig::new(IntervalUnit::Second)).unwrap()
2657        );
2658
2659        // shorter units
2660        assert_eq!(
2661            Interval::new(1, 0, 0),
2662            Interval::parse("1 mon", &config).unwrap()
2663        );
2664        assert_eq!(
2665            Interval::new(1, 0, 0),
2666            Interval::parse("1 mons", &config).unwrap()
2667        );
2668        assert_eq!(
2669            Interval::new(0, 0, 1_000_000),
2670            Interval::parse("1 ms", &config).unwrap()
2671        );
2672        assert_eq!(
2673            Interval::new(0, 0, 1_000),
2674            Interval::parse("1 us", &config).unwrap()
2675        );
2676
2677        // no space
2678        assert_eq!(
2679            Interval::new(0, 0, 1_000),
2680            Interval::parse("1us", &config).unwrap()
2681        );
2682        assert_eq!(
2683            Interval::new(0, 0, NANOS_PER_SECOND),
2684            Interval::parse("1s", &config).unwrap()
2685        );
2686        assert_eq!(
2687            Interval::new(1, 2, 10_864_000_000_000),
2688            Interval::parse("1mon 2days 3hr 1min 4sec", &config).unwrap()
2689        );
2690
2691        assert_eq!(
2692            Interval::new(
2693                -13i32,
2694                -8i32,
2695                -NANOS_PER_HOUR
2696                    - NANOS_PER_MINUTE
2697                    - NANOS_PER_SECOND
2698                    - (1.11_f64 * NANOS_PER_MILLIS as f64) as i64
2699            ),
2700            Interval::parse(
2701                "-1year -1month -1week -1day -1 hour -1 minute -1 second -1.11millisecond",
2702                &config
2703            )
2704            .unwrap(),
2705        );
2706
2707        assert_eq!(
2708            Interval::parse("1h s", &config).unwrap_err().to_string(),
2709            r#"Parser error: Invalid input syntax for type interval: "1h s""#
2710        );
2711
2712        assert_eq!(
2713            Interval::parse("1XX", &config).unwrap_err().to_string(),
2714            r#"Parser error: Invalid input syntax for type interval: "1XX""#
2715        );
2716    }
2717
2718    #[test]
2719    fn test_duplicate_interval_type() {
2720        let config = IntervalParseConfig::new(IntervalUnit::Month);
2721
2722        let err = Interval::parse("1 month 1 second 1 second", &config)
2723            .expect_err("parsing interval should have failed");
2724        assert_eq!(
2725            r#"ParseError("Invalid input syntax for type interval: \"1 month 1 second 1 second\". Repeated type 'second'")"#,
2726            format!("{err:?}")
2727        );
2728
2729        // test with singular and plural forms
2730        let err = Interval::parse("1 century 2 centuries", &config)
2731            .expect_err("parsing interval should have failed");
2732        assert_eq!(
2733            r#"ParseError("Invalid input syntax for type interval: \"1 century 2 centuries\". Repeated type 'centuries'")"#,
2734            format!("{err:?}")
2735        );
2736    }
2737
2738    #[test]
2739    fn test_interval_amount_parsing() {
2740        // integer
2741        let result = IntervalAmount::from_str("123").unwrap();
2742        let expected = IntervalAmount::new(123, 0);
2743
2744        assert_eq!(result, expected);
2745
2746        // positive w/ fractional
2747        let result = IntervalAmount::from_str("0.3").unwrap();
2748        let expected = IntervalAmount::new(0, 3 * 10_i64.pow(INTERVAL_PRECISION - 1));
2749
2750        assert_eq!(result, expected);
2751
2752        // negative w/ fractional
2753        let result = IntervalAmount::from_str("-3.5").unwrap();
2754        let expected = IntervalAmount::new(-3, -5 * 10_i64.pow(INTERVAL_PRECISION - 1));
2755
2756        assert_eq!(result, expected);
2757
2758        // invalid: missing fractional
2759        let result = IntervalAmount::from_str("3.");
2760        assert!(result.is_err());
2761
2762        // invalid: sign in fractional
2763        let result = IntervalAmount::from_str("3.-5");
2764        assert!(result.is_err());
2765    }
2766
2767    #[test]
2768    fn test_interval_precision() {
2769        let config = IntervalParseConfig::new(IntervalUnit::Month);
2770
2771        let result = Interval::parse("100000.1 days", &config).unwrap();
2772        let expected = Interval::new(0_i32, 100_000_i32, NANOS_PER_DAY / 10);
2773
2774        assert_eq!(result, expected);
2775    }
2776
2777    #[test]
2778    fn test_interval_addition() {
2779        // add 4.1 centuries
2780        let start = Interval::new(1, 2, 3);
2781        let expected = Interval::new(4921, 2, 3);
2782
2783        let result = start
2784            .add(
2785                IntervalAmount::new(4, 10_i64.pow(INTERVAL_PRECISION - 1)),
2786                IntervalUnit::Century,
2787            )
2788            .unwrap();
2789
2790        assert_eq!(result, expected);
2791
2792        // add 10.25 decades
2793        let start = Interval::new(1, 2, 3);
2794        let expected = Interval::new(1231, 2, 3);
2795
2796        let result = start
2797            .add(
2798                IntervalAmount::new(10, 25 * 10_i64.pow(INTERVAL_PRECISION - 2)),
2799                IntervalUnit::Decade,
2800            )
2801            .unwrap();
2802
2803        assert_eq!(result, expected);
2804
2805        // add 30.3 years (reminder: Postgres logic does not spill to days/nanos when interval is larger than a month)
2806        let start = Interval::new(1, 2, 3);
2807        let expected = Interval::new(364, 2, 3);
2808
2809        let result = start
2810            .add(
2811                IntervalAmount::new(30, 3 * 10_i64.pow(INTERVAL_PRECISION - 1)),
2812                IntervalUnit::Year,
2813            )
2814            .unwrap();
2815
2816        assert_eq!(result, expected);
2817
2818        // add 1.5 months
2819        let start = Interval::new(1, 2, 3);
2820        let expected = Interval::new(2, 17, 3);
2821
2822        let result = start
2823            .add(
2824                IntervalAmount::new(1, 5 * 10_i64.pow(INTERVAL_PRECISION - 1)),
2825                IntervalUnit::Month,
2826            )
2827            .unwrap();
2828
2829        assert_eq!(result, expected);
2830
2831        // add -2 weeks
2832        let start = Interval::new(1, 25, 3);
2833        let expected = Interval::new(1, 11, 3);
2834
2835        let result = start
2836            .add(IntervalAmount::new(-2, 0), IntervalUnit::Week)
2837            .unwrap();
2838
2839        assert_eq!(result, expected);
2840
2841        // add 2.2 days
2842        let start = Interval::new(12, 15, 3);
2843        let expected = Interval::new(12, 17, 3 + 17_280 * NANOS_PER_SECOND);
2844
2845        let result = start
2846            .add(
2847                IntervalAmount::new(2, 2 * 10_i64.pow(INTERVAL_PRECISION - 1)),
2848                IntervalUnit::Day,
2849            )
2850            .unwrap();
2851
2852        assert_eq!(result, expected);
2853
2854        // add 12.5 hours
2855        let start = Interval::new(1, 2, 3);
2856        let expected = Interval::new(1, 2, 3 + 45_000 * NANOS_PER_SECOND);
2857
2858        let result = start
2859            .add(
2860                IntervalAmount::new(12, 5 * 10_i64.pow(INTERVAL_PRECISION - 1)),
2861                IntervalUnit::Hour,
2862            )
2863            .unwrap();
2864
2865        assert_eq!(result, expected);
2866
2867        // add -1.5 minutes
2868        let start = Interval::new(0, 0, -3);
2869        let expected = Interval::new(0, 0, -90_000_000_000 - 3);
2870
2871        let result = start
2872            .add(
2873                IntervalAmount::new(-1, -5 * 10_i64.pow(INTERVAL_PRECISION - 1)),
2874                IntervalUnit::Minute,
2875            )
2876            .unwrap();
2877
2878        assert_eq!(result, expected);
2879    }
2880
2881    #[test]
2882    fn string_to_timestamp_old() {
2883        parse_timestamp("1677-06-14T07:29:01.256")
2884            .map_err(|e| assert!(e.to_string().ends_with(ERR_NANOSECONDS_NOT_SUPPORTED)))
2885            .unwrap_err();
2886    }
2887
2888    #[test]
2889    fn test_parse_decimal_with_parameter() {
2890        let tests = [
2891            ("0", 0i128),
2892            ("123.123", 123123i128),
2893            ("123.1234", 123123i128),
2894            ("123.1", 123100i128),
2895            ("123", 123000i128),
2896            ("-123.123", -123123i128),
2897            ("-123.1234", -123123i128),
2898            ("-123.1", -123100i128),
2899            ("-123", -123000i128),
2900            ("0.0000123", 0i128),
2901            ("12.", 12000i128),
2902            ("-12.", -12000i128),
2903            ("00.1", 100i128),
2904            ("-00.1", -100i128),
2905            ("12345678912345678.1234", 12345678912345678123i128),
2906            ("-12345678912345678.1234", -12345678912345678123i128),
2907            ("99999999999999999.999", 99999999999999999999i128),
2908            ("-99999999999999999.999", -99999999999999999999i128),
2909            (".123", 123i128),
2910            ("-.123", -123i128),
2911            ("123.", 123000i128),
2912            ("-123.", -123000i128),
2913        ];
2914        for (s, i) in tests {
2915            let result_128 = parse_decimal::<Decimal128Type>(s, 20, 3);
2916            assert_eq!(i, result_128.unwrap());
2917            let result_256 = parse_decimal::<Decimal256Type>(s, 20, 3);
2918            assert_eq!(i256::from_i128(i), result_256.unwrap());
2919        }
2920
2921        let e_notation_tests = [
2922            ("1.23e3", "1230.0", 2),
2923            ("5.6714e+2", "567.14", 4),
2924            ("5.6714e-2", "0.056714", 4),
2925            ("5.6714e-2", "0.056714", 3),
2926            ("5.6741214125e2", "567.41214125", 4),
2927            ("8.91E4", "89100.0", 2),
2928            ("3.14E+5", "314000.0", 2),
2929            ("2.718e0", "2.718", 2),
2930            ("9.999999e-1", "0.9999999", 4),
2931            ("1.23e+3", "1230", 2),
2932            ("1.234559e+3", "1234.559", 2),
2933            ("1.00E-10", "0.0000000001", 11),
2934            ("1.23e-4", "0.000123", 2),
2935            ("9.876e7", "98760000.0", 2),
2936            ("5.432E+8", "543200000.0", 10),
2937            ("1.234567e9", "1234567000.0", 2),
2938            ("1.234567e2", "123.45670000", 2),
2939            ("4749.3e-5", "0.047493", 10),
2940            ("4749.3e+5", "474930000", 10),
2941            ("4749.3e-5", "0.047493", 1),
2942            ("4749.3e+5", "474930000", 1),
2943            ("0E-8", "0", 10),
2944            ("0E+6", "0", 10),
2945            ("0e0", "0", 10),
2946            ("-0e0", "0", 10),
2947            ("00e48", "0", 10),
2948            ("1E-8", "0.00000001", 10),
2949            ("12E+6", "12000000", 10),
2950            ("12E-6", "0.000012", 10),
2951            ("0.1e-6", "0.0000001", 10),
2952            ("0.1e+6", "100000", 10),
2953            ("0.12e-6", "0.00000012", 10),
2954            ("0.12e+6", "120000", 10),
2955            ("000000000001e0", "000000000001", 3),
2956            ("000001.1034567002e0", "000001.1034567002", 3),
2957            ("1.234e16", "12340000000000000", 0),
2958            ("123.4e16", "1234000000000000000", 0),
2959            ("15e-1", "1.5", 0),
2960            ("1.25e1", "12.5", 0),
2961            ("1.5e-1", "0.15", 1),
2962        ];
2963        for (e, d, scale) in e_notation_tests {
2964            let result_128_e = parse_decimal::<Decimal128Type>(e, 20, scale);
2965            let result_128_d = parse_decimal::<Decimal128Type>(d, 20, scale);
2966            assert_eq!(result_128_e.unwrap(), result_128_d.unwrap(), "{e} vs {d}");
2967            let result_256_e = parse_decimal::<Decimal256Type>(e, 20, scale);
2968            let result_256_d = parse_decimal::<Decimal256Type>(d, 20, scale);
2969            assert_eq!(result_256_e.unwrap(), result_256_d.unwrap(), "{e} vs {d}");
2970        }
2971        let can_not_parse_tests = [
2972            "123,123",
2973            ".",
2974            "123.123.123",
2975            "",
2976            "+",
2977            "-",
2978            "e",
2979            "e5",
2980            "-.",
2981            "+e-11",
2982            "-.E+3",
2983            ".e5",
2984            "1.3e+e3",
2985            "5.6714ee-2",
2986            "4.11ee-+4",
2987            "4.11e++4",
2988            "1.1e.12",
2989            "1.23e+3.",
2990            "1.23e+3.1",
2991            "1e",
2992            "1e+",
2993            "1e-",
2994            "1e5e5",
2995            "1 000",
2996            "1_000",
2997            "- 1",
2998            "1.5 x",
2999            "0x10",
3000            "NaN",
3001            "inf",
3002            "\u{661}\u{662}",
3003            "\u{ff11}",
3004        ];
3005        for s in can_not_parse_tests {
3006            let result_128 = parse_decimal::<Decimal128Type>(s, 20, 3);
3007            assert_eq!(
3008                format!("Parser error: Invalid decimal format: {s:?}"),
3009                result_128.unwrap_err().to_string()
3010            );
3011            let result_256 = parse_decimal::<Decimal256Type>(s, 20, 3);
3012            assert_eq!(
3013                format!("Parser error: Invalid decimal format: {s:?}"),
3014                result_256.unwrap_err().to_string()
3015            );
3016        }
3017        let overflow_parse_tests = [
3018            ("12345678", 3),
3019            ("1.2345678e7", 3),
3020            ("12345678.9", 3),
3021            ("1.23456789e+7", 3),
3022            ("99999999.99", 3),
3023            ("9.999999999e7", 3),
3024            ("12345678908765.123456", 3),
3025            ("123456789087651234.56e-4", 3),
3026            ("1234560000000", 0),
3027            ("12345678900.0", 0),
3028            ("1.23456e12", 0),
3029            ("9999999.9995", 3),
3030            ("1e99999", 0),
3031            ("1e40", 0),
3032        ];
3033        for (s, scale) in overflow_parse_tests {
3034            let result_128 = parse_decimal::<Decimal128Type>(s, 10, scale);
3035            let expected_128 =
3036                format!("Parser error: {s:?} does not fit in Decimal128(10, {scale})");
3037            assert_eq!(result_128.unwrap_err().to_string(), expected_128);
3038
3039            let result_256 = parse_decimal::<Decimal256Type>(s, 10, scale);
3040            let expected_256 =
3041                format!("Parser error: {s:?} does not fit in Decimal256(10, {scale})");
3042            assert_eq!(result_256.unwrap_err().to_string(), expected_256);
3043        }
3044
3045        let edge_tests_128 = [
3046            (
3047                "99999999999999999999999999999999999999",
3048                99999999999999999999999999999999999999i128,
3049                0,
3050            ),
3051            (
3052                "999999999999999999999999999999999999.99",
3053                99999999999999999999999999999999999999i128,
3054                2,
3055            ),
3056            (
3057                "9999999999999999999999999.9999999999999",
3058                99999999999999999999999999999999999999i128,
3059                13,
3060            ),
3061            (
3062                "9999999999999999999999999",
3063                99999999999999999999999990000000000000i128,
3064                13,
3065            ),
3066            (
3067                "0.99999999999999999999999999999999999999",
3068                99999999999999999999999999999999999999i128,
3069                38,
3070            ),
3071            (
3072                "0.00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001016744",
3073                0i128,
3074                15,
3075            ),
3076            ("1.016744e-320", 0i128, 15),
3077            ("-1e3", -1000000000i128, 6),
3078            ("+1e3", 1000000000i128, 6),
3079            ("-1e31", -10000000000000000000000000000000000000i128, 6),
3080            // More digits than an i128 can hold, but a small value
3081            ("10000000000000000000000000000000000000000e-39", 10i128, 0),
3082            // Digits beyond the scale round; here the result still fits
3083            (
3084                "99999999999999999999999999999999999994e-1",
3085                9999999999999999999999999999999999999i128,
3086                0,
3087            ),
3088        ];
3089        for (s, i, scale) in edge_tests_128 {
3090            let result_128 = parse_decimal::<Decimal128Type>(s, 38, scale);
3091            assert_eq!(i, result_128.unwrap(), "{s}");
3092        }
3093        // Rounding carries into a 39th digit, which does not fit
3094        assert!(
3095            parse_decimal::<Decimal128Type>("999999999999999999999999999999999999999e-1", 38, 0)
3096                .is_err()
3097        );
3098
3099        let edge_tests_256 = [
3100            (
3101                "9999999999999999999999999999999999999999999999999999999999999999999999999999",
3102                i256::from_string(
3103                    "9999999999999999999999999999999999999999999999999999999999999999999999999999",
3104                )
3105                .unwrap(),
3106                0,
3107            ),
3108            (
3109                "999999999999999999999999999999999999999999999999999999999999999999999999.9999",
3110                i256::from_string(
3111                    "9999999999999999999999999999999999999999999999999999999999999999999999999999",
3112                )
3113                .unwrap(),
3114                4,
3115            ),
3116            (
3117                "99999999999999999999999999999999999999999999999999.99999999999999999999999999",
3118                i256::from_string(
3119                    "9999999999999999999999999999999999999999999999999999999999999999999999999999",
3120                )
3121                .unwrap(),
3122                26,
3123            ),
3124            (
3125                "9.999999999999999999999999999999999999999999999999999999999999999999999999999e49",
3126                i256::from_string(
3127                    "9999999999999999999999999999999999999999999999999999999999999999999999999999",
3128                )
3129                .unwrap(),
3130                26,
3131            ),
3132            (
3133                "99999999999999999999999999999999999999999999999999",
3134                i256::from_string(
3135                    "9999999999999999999999999999999999999999999999999900000000000000000000000000",
3136                )
3137                .unwrap(),
3138                26,
3139            ),
3140            (
3141                "9.9999999999999999999999999999999999999999999999999e+49",
3142                i256::from_string(
3143                    "9999999999999999999999999999999999999999999999999900000000000000000000000000",
3144                )
3145                .unwrap(),
3146                26,
3147            ),
3148        ];
3149        for (s, i, scale) in edge_tests_256 {
3150            let result = parse_decimal::<Decimal256Type>(s, 76, scale);
3151            assert_eq!(i, result.unwrap());
3152        }
3153
3154        let zero_scale_tests = [
3155            (".123", 0, 3),
3156            ("0.123", 0, 3),
3157            ("1.0", 1, 3),
3158            ("1.2", 1, 3),
3159            ("1.00", 1, 3),
3160            ("1.23", 1, 3),
3161            ("1.000", 1, 3),
3162            ("1.123", 1, 3),
3163            ("1.5", 2, 3),
3164            ("1.9", 2, 3),
3165            ("123.0", 123, 3),
3166            ("123.4", 123, 3),
3167            ("123.00", 123, 3),
3168            ("123.45", 123, 3),
3169            ("123.5", 124, 3),
3170            ("123.000000000000000000004", 123, 3),
3171            ("0.123e2", 12, 3),
3172            ("0.123e4", 1230, 10),
3173            ("1.23e4", 12300, 10),
3174            ("12.3e4", 123000, 10),
3175            ("123e4", 1230000, 10),
3176            (
3177                "20000000000000000000000000000000000002.0",
3178                20000000000000000000000000000000000002,
3179                38,
3180            ),
3181        ];
3182        for (s, i, precision) in zero_scale_tests {
3183            let result_128 = parse_decimal::<Decimal128Type>(s, precision, 0).unwrap();
3184            assert_eq!(i, result_128, "{s}");
3185        }
3186
3187        let can_not_parse_zero_scale = [".", "blag", "", "+", "-", "e"];
3188        for s in can_not_parse_zero_scale {
3189            let result_128 = parse_decimal::<Decimal128Type>(s, 5, 0);
3190            assert_eq!(
3191                format!("Parser error: Invalid decimal format: {s:?}"),
3192                result_128.unwrap_err().to_string(),
3193            );
3194        }
3195    }
3196
3197    #[test]
3198    fn test_parse_decimal_rounds_half_away_from_zero() {
3199        let tests = [
3200            ("1.234", 2, 123),
3201            ("1.235", 2, 124),
3202            ("1.2350000", 2, 124),
3203            ("1.2349999", 2, 123),
3204            ("-1.234", 2, -123),
3205            ("-1.235", 2, -124),
3206            ("-0.004", 2, 0),
3207            ("-0.005", 2, -1),
3208            (".5", 0, 1),
3209            ("-.5", 0, -1),
3210            ("0.5", 0, 1),
3211            ("1.5", 0, 2),
3212            ("2.5", 0, 3),
3213            ("-2.5", 0, -3),
3214            ("1.99", 1, 20),
3215            ("0.995", 2, 100),
3216            ("9.99", 1, 100),
3217            ("123.4567891", 5, 12345679),
3218            ("123.45", 0, 123),
3219            ("0.0000123", 3, 0),
3220            ("12.", 2, 1200),
3221            (".12", 2, 12),
3222            ("+.12", 2, 12),
3223            ("-.12", 2, -12),
3224        ];
3225        for (s, scale, expected) in tests {
3226            assert_eq!(
3227                parse_decimal::<Decimal128Type>(s, 38, scale).unwrap(),
3228                expected,
3229                "{s} at scale {scale}"
3230            );
3231            assert_eq!(
3232                parse_decimal::<Decimal256Type>(s, 76, scale).unwrap(),
3233                i256::from_i128(expected),
3234                "{s} at scale {scale}"
3235            );
3236        }
3237    }
3238
3239    #[test]
3240    fn test_parse_decimal_rounding_overflow() {
3241        // Rounding up can push the value past the precision ...
3242        assert!(parse_decimal::<Decimal128Type>("99999.5", 5, 0).is_err());
3243        assert!(parse_decimal::<Decimal128Type>("9.995", 3, 2).is_err());
3244        assert_eq!(parse_decimal::<Decimal128Type>("9.994", 3, 2).unwrap(), 999);
3245        assert_eq!(parse_decimal::<Decimal128Type>("0.995", 3, 2).unwrap(), 100);
3246
3247        // ... or past the native type itself
3248        assert_eq!(
3249            parse_native::<Decimal32Type>("2147483647.5", 0),
3250            Err(DecimalParseError::Overflow)
3251        );
3252        assert_eq!(
3253            parse_native::<Decimal32Type>("-2147483648.5", 0),
3254            Err(DecimalParseError::Overflow)
3255        );
3256        assert_eq!(
3257            parse_native::<Decimal128Type>(&format!("{}.5", i128::MAX), 0),
3258            Err(DecimalParseError::Overflow)
3259        );
3260        assert_eq!(
3261            parse_native::<Decimal128Type>(&format!("{}.5", i128::MIN), 0),
3262            Err(DecimalParseError::Overflow)
3263        );
3264        assert_eq!(
3265            parse_native::<Decimal256Type>(&format!("{}.5", i256::MAX), 0),
3266            Err(DecimalParseError::Overflow)
3267        );
3268        assert_eq!(
3269            parse_native::<Decimal256Type>(&format!("{}.5", i256::MIN), 0),
3270            Err(DecimalParseError::Overflow)
3271        );
3272    }
3273
3274    #[test]
3275    fn test_parse_decimal_precision_by_digit_count() {
3276        // Rounding up can add a digit
3277        assert_eq!(
3278            parse_decimal::<Decimal128Type>("99999.4", 5, 0).unwrap(),
3279            99999
3280        );
3281        assert!(parse_decimal::<Decimal128Type>("99999.5", 5, 0).is_err());
3282        assert!(parse_decimal::<Decimal128Type>("-99999.5", 5, 0).is_err());
3283        assert_eq!(
3284            parse_decimal::<Decimal128Type>("99999.5", 6, 0).unwrap(),
3285            100000
3286        );
3287        // Leading zeros count as digits only for the shortcut; the value is
3288        // then checked by its range
3289        assert_eq!(
3290            parse_decimal::<Decimal128Type>("000000000000000000000001", 1, 0).unwrap(),
3291            1
3292        );
3293        assert_eq!(
3294            parse_decimal::<Decimal128Type>("0.000000000000000000001", 1, 21).unwrap(),
3295            1
3296        );
3297        assert!(parse_decimal::<Decimal128Type>("0.0000000000000000000012", 1, 22).is_err());
3298        // The zeros appended to reach the scale count as digits
3299        assert_eq!(parse_decimal::<Decimal128Type>("1", 3, 2).unwrap(), 100);
3300        assert!(parse_decimal::<Decimal128Type>("1", 2, 2).is_err());
3301        assert!(parse_decimal::<Decimal128Type>("1e2", 2, 0).is_err());
3302        assert_eq!(parse_decimal::<Decimal32Type>("1e2", 3, 0).unwrap(), 100);
3303        // Scaling down leaves fewer digits
3304        assert_eq!(
3305            parse_decimal::<Decimal128Type>("123456", 2, -4).unwrap(),
3306            12
3307        );
3308        assert!(parse_decimal::<Decimal128Type>("123456", 1, -4).is_err());
3309        // A precision beyond the type's maximum is invalid
3310        assert!(parse_decimal::<Decimal32Type>("1", 10, 0).is_err());
3311        assert!(parse_decimal::<Decimal32Type>("00000000001", 10, 0).is_err());
3312        assert!(parse_decimal::<Decimal128Type>("1", 39, 0).is_err());
3313        assert!(parse_decimal::<Decimal256Type>("1", 77, 0).is_err());
3314    }
3315
3316    #[test]
3317    fn test_parse_decimal_native_full_range() {
3318        // The native range exceeds the largest precision; the precision check
3319        // is the caller's responsibility
3320        assert_eq!(
3321            parse_native::<Decimal32Type>("-2147483648", 0),
3322            Ok(i32::MIN)
3323        );
3324        assert_eq!(
3325            parse_native::<Decimal32Type>("2147483648", 0),
3326            Err(DecimalParseError::Overflow)
3327        );
3328        assert_eq!(
3329            parse_native::<Decimal64Type>("-9223372036854775808", 0),
3330            Ok(i64::MIN)
3331        );
3332        assert_eq!(
3333            parse_native::<Decimal64Type>("9223372036854775808", 0),
3334            Err(DecimalParseError::Overflow)
3335        );
3336        assert_eq!(
3337            parse_native::<Decimal128Type>(&i128::MAX.to_string(), 0),
3338            Ok(i128::MAX)
3339        );
3340        assert_eq!(
3341            parse_native::<Decimal128Type>(&i128::MIN.to_string(), 0),
3342            Ok(i128::MIN)
3343        );
3344        assert_eq!(
3345            parse_native::<Decimal256Type>(&i256::MAX.to_string(), 0),
3346            Ok(i256::MAX)
3347        );
3348        assert_eq!(
3349            parse_native::<Decimal256Type>(&i256::MIN.to_string(), 0),
3350            Ok(i256::MIN)
3351        );
3352        // The unscaled value (integer digits scaled by 10^21) far exceeds the
3353        // i256 range, so this must report overflow rather than wrapping to an
3354        // arbitrary (possibly in-range) value
3355        let input = format!("{}.12345678901234567890123", "7".repeat(71));
3356        assert_eq!(
3357            parse_native::<Decimal256Type>(&input, 21),
3358            Err(DecimalParseError::Overflow)
3359        );
3360
3361        assert!(parse_decimal::<Decimal128Type>(&i128::MAX.to_string(), 38, 0).is_err());
3362        assert!(parse_decimal::<Decimal32Type>("-2147483648", 9, 0).is_err());
3363    }
3364
3365    #[test]
3366    fn test_parse_decimal_integer_widths() {
3367        assert_eq!(
3368            parse_decimal::<Decimal32Type>("123.45", 9, 2).unwrap(),
3369            12_345_i32
3370        );
3371        assert_eq!(
3372            parse_decimal::<Decimal32Type>("-9999999.994", 9, 2).unwrap(),
3373            -999_999_999_i32
3374        );
3375        assert!(parse_decimal::<Decimal32Type>("9999999.995", 9, 2).is_err());
3376        assert!(parse_decimal::<Decimal32Type>("-9999999.995", 9, 2).is_err());
3377        assert_eq!(
3378            parse_decimal::<Decimal64Type>("123.45", 18, 2).unwrap(),
3379            12_345_i64
3380        );
3381        assert_eq!(
3382            parse_decimal::<Decimal64Type>("9999999999999999.99", 18, 2).unwrap(),
3383            999_999_999_999_999_999_i64
3384        );
3385        assert!(parse_decimal::<Decimal64Type>("10000000000000000.00", 18, 2).is_err());
3386        // Fractional parts longer than any native integer type parse fine;
3387        // digits beyond the scale only matter for rounding
3388        assert_eq!(
3389            parse_decimal::<Decimal64Type>(&format!(".{}", "5".repeat(100)), 18, 4).unwrap(),
3390            5_556_i64
3391        );
3392        assert_eq!(
3393            parse_decimal::<Decimal128Type>(&format!(".{}", "1".repeat(100)), 38, 4).unwrap(),
3394            1_111_i128
3395        );
3396    }
3397
3398    #[test]
3399    fn test_parse_decimal_exponent() {
3400        let tests = [
3401            ("1e2", 0, 100),
3402            ("1E2", 0, 100),
3403            ("1e+2", 0, 100),
3404            ("1e+02", 0, 100),
3405            ("1.5e2", 0, 150),
3406            ("1.5e2", 2, 15000),
3407            ("1.5e-1", 1, 2),
3408            ("15e-1", 0, 2),
3409            ("1e-2", 1, 0),
3410            ("1e-3", 2, 0),
3411            ("0e0", 2, 0),
3412            ("-0e0", 2, 0),
3413            ("0E5", 2, 0),
3414            ("0e99999", 2, 0),
3415            ("00e48", 8, 0),
3416            ("+00.0E+41", 12, 0),
3417            ("1.25e1", 0, 13),
3418            ("1e-99999", 2, 0),
3419            ("1.5e-400", 2, 0),
3420            ("123456789e-9", 9, 123456789),
3421            ("0.000000001e9", 0, 1),
3422            ("5e-1", 0, 1),
3423            ("4e-1", 0, 0),
3424            ("-5e-1", 0, -1),
3425        ];
3426        for (s, scale, expected) in tests {
3427            assert_eq!(
3428                parse_decimal::<Decimal128Type>(s, 38, scale).unwrap(),
3429                expected,
3430                "{s} at scale {scale}"
3431            );
3432            assert_eq!(
3433                parse_decimal::<Decimal32Type>(s, 9, scale).unwrap(),
3434                expected as i32,
3435                "{s} at scale {scale}"
3436            );
3437        }
3438
3439        // Exponents shift digits across the decimal point without losing any
3440        assert_eq!(
3441            parse_decimal::<Decimal32Type>("4825037936439135476.2609835314269495255615E-14", 9, 4)
3442                .unwrap(),
3443            482503794
3444        );
3445        assert_eq!(
3446            parse_decimal::<Decimal32Type>(
3447                "+18232335063972188138031550982650807591758238.0724251287782783777442440E-58",
3448                1,
3449                0
3450            )
3451            .unwrap(),
3452            0
3453        );
3454        assert_eq!(
3455            parse_decimal::<Decimal128Type>("4825037936439135476.2609835314269495255615E-14", 9, 1)
3456                .unwrap(),
3457            482504
3458        );
3459        assert!(
3460            parse_decimal::<Decimal128Type>("4825037936439135476.2609835314269495255615E-14", 5, 1)
3461                .is_err()
3462        );
3463        // Absurdly long exponents saturate rather than wrap
3464        assert!(parse_decimal::<Decimal128Type>(&format!("1e{}", "9".repeat(30)), 38, 0).is_err());
3465        assert_eq!(
3466            parse_decimal::<Decimal128Type>(&format!("1e-{}", "9".repeat(30)), 38, 0).unwrap(),
3467            0
3468        );
3469    }
3470
3471    #[test]
3472    fn test_parse_decimal_negative_scale() {
3473        let tests = [
3474            ("1234.5", -2, 12),
3475            ("150", -2, 2),
3476            ("149", -2, 1),
3477            ("-150", -2, -2),
3478            ("-149", -2, -1),
3479            ("50", -2, 1),
3480            ("49", -2, 0),
3481            ("5", -1, 1),
3482            ("4", -1, 0),
3483            ("0.5", -1, 0),
3484            ("5.9", -1, 1),
3485            ("1e5", -2, 1000),
3486            ("1.5e5", -2, 1500),
3487            ("0.9e2", -1, 9),
3488            (".5e3", -2, 5),
3489            ("12345", -5, 0),
3490            ("12345", -4, 1),
3491            ("000123456", -3, 123),
3492            ("0", -5, 0),
3493            ("-0.0", -5, 0),
3494        ];
3495        for (s, scale, expected) in tests {
3496            assert_eq!(
3497                parse_decimal::<Decimal128Type>(s, 38, scale).unwrap(),
3498                expected,
3499                "{s} at scale {scale}"
3500            );
3501            assert_eq!(
3502                parse_decimal::<Decimal32Type>(s, 9, scale).unwrap(),
3503                expected as i32,
3504                "{s} at scale {scale}"
3505            );
3506            assert_eq!(
3507                parse_decimal::<Decimal256Type>(s, 76, scale).unwrap(),
3508                i256::from_i128(expected),
3509                "{s} at scale {scale}"
3510            );
3511        }
3512        // The integer part can be wider than the native type as long as the
3513        // scaled value fits
3514        assert_eq!(
3515            parse_decimal::<Decimal128Type>(&format!("1{}", "0".repeat(50)), 38, -40).unwrap(),
3516            10_000_000_000
3517        );
3518        assert_eq!(
3519            parse_decimal::<Decimal32Type>("123456789012", 9, -5).unwrap(),
3520            1234568
3521        );
3522        assert!(parse_decimal::<Decimal32Type>("123456789012", 9, -2).is_err());
3523    }
3524
3525    #[test]
3526    fn test_parse_decimal_whitespace_and_long_input() {
3527        for s in [" 1.5", "1.5 ", " 1.5 ", "\t1.5\n", "\r\n1.5\x0c"] {
3528            assert_eq!(
3529                parse_decimal::<Decimal128Type>(s, 38, 1).unwrap(),
3530                15,
3531                "{s:?}"
3532            );
3533        }
3534        // Only ASCII whitespace is trimmed, as for the other CSV parsers
3535        assert!(parse_decimal::<Decimal128Type>("\u{a0}1.5", 38, 1).is_err());
3536        assert!(parse_decimal::<Decimal128Type>("1.5\u{2003}", 38, 1).is_err());
3537        assert!(parse_decimal::<Decimal128Type>(" ", 38, 1).is_err());
3538
3539        // Long inputs report overflow rather than wrapping or panicking
3540        for s in [
3541            "1".repeat(255),
3542            "1".repeat(256),
3543            "1".repeat(300),
3544            format!("{}.5", "1".repeat(300)),
3545            format!("1e{}", "9".repeat(300)),
3546        ] {
3547            let err = parse_decimal::<Decimal128Type>(&s, 38, 0).unwrap_err();
3548            assert!(err.to_string().contains("does not fit"), "{err}");
3549        }
3550        // Long fractions only matter for rounding
3551        assert_eq!(
3552            parse_decimal::<Decimal128Type>(&format!("0.{}", "0".repeat(200)), 38, 10).unwrap(),
3553            0
3554        );
3555        assert_eq!(
3556            parse_decimal::<Decimal128Type>(&format!("0.{}1", "0".repeat(200)), 38, 10).unwrap(),
3557            0
3558        );
3559        assert_eq!(
3560            parse_decimal::<Decimal128Type>(&format!("1.{}", "9".repeat(300)), 38, 2).unwrap(),
3561            200
3562        );
3563        // 10^scale overflows the native type, but zero is still representable
3564        assert_eq!(parse_decimal::<Decimal32Type>("0", 9, 10).unwrap(), 0);
3565        assert_eq!(parse_decimal::<Decimal32Type>("-0.0", 9, 10).unwrap(), 0);
3566        assert_eq!(parse_decimal::<Decimal64Type>("0", 18, 20).unwrap(), 0);
3567        assert_eq!(parse_decimal::<Decimal128Type>("0", 38, 40).unwrap(), 0);
3568        assert!(parse_decimal::<Decimal32Type>("1", 9, 10).is_err());
3569    }
3570
3571    #[test]
3572    #[cfg_attr(miri, ignore)] // Takes too long under Miri (adds ~1 hour to CI)
3573    fn test_parse_decimal_matches_bigint_reference() {
3574        use num_bigint::BigInt;
3575        use rand::rngs::StdRng;
3576        use rand::{RngExt, SeedableRng};
3577
3578        /// Generates random decimal strings with a known exact value and checks
3579        /// that `parse_decimal` rounds them correctly or reports overflow
3580        fn check<T: DecimalType>(rng: &mut StdRng, iterations: usize)
3581        where
3582            T::Native: std::fmt::Display,
3583        {
3584            let random_digits = |rng: &mut StdRng, len: usize| -> String {
3585                (0..len)
3586                    .map(|_| char::from(b'0' + rng.random_range(0..10u8)))
3587                    .collect()
3588            };
3589            for _ in 0..iterations {
3590                let sign = ["", "+", "-"][rng.random_range(0..3)];
3591                let int_len = rng.random_range(0..=40);
3592                let frac_len = if rng.random_bool(0.3) {
3593                    0
3594                } else {
3595                    rng.random_range(0..=40)
3596                };
3597                if int_len == 0 && frac_len == 0 {
3598                    continue;
3599                }
3600                let int = random_digits(rng, int_len);
3601                let frac = random_digits(rng, frac_len);
3602                let mut s = format!("{sign}{int}");
3603                if frac_len > 0 || rng.random_bool(0.2) {
3604                    s.push('.');
3605                    s.push_str(&frac);
3606                }
3607                let exponent: i64 = if rng.random_bool(0.3) {
3608                    rng.random_range(-60..=60)
3609                } else {
3610                    0
3611                };
3612                if exponent != 0 || rng.random_bool(0.1) {
3613                    s.push(if rng.random_bool(0.5) { 'e' } else { 'E' });
3614                    if exponent >= 0 && rng.random_bool(0.5) {
3615                        s.push('+');
3616                    }
3617                    s.push_str(&exponent.to_string());
3618                }
3619                let precision = rng.random_range(1..=T::MAX_PRECISION);
3620                let scale = rng.random_range(-10..=T::MAX_SCALE.min(precision as i8));
3621
3622                // value = mantissa * 10^(exponent - frac_len), scaled by 10^scale
3623                // and rounded half away from zero
3624                let mantissa: BigInt = format!("{int}{frac}").parse().unwrap();
3625                let shift = exponent - frac_len as i64 + scale as i64;
3626                let mut expected = if shift >= 0 {
3627                    mantissa * BigInt::from(10).pow(shift as u32)
3628                } else {
3629                    let divisor = BigInt::from(10).pow((-shift) as u32);
3630                    let quotient = &mantissa / &divisor;
3631                    if (&mantissa % &divisor) * 2 >= divisor {
3632                        quotient + 1
3633                    } else {
3634                        quotient
3635                    }
3636                };
3637                if sign == "-" {
3638                    expected = -expected;
3639                }
3640                let limit = BigInt::from(10).pow(precision as u32);
3641                let fits = expected < limit && expected > -limit;
3642
3643                match (fits, parse_decimal::<T>(&s, precision, scale)) {
3644                    (true, Ok(actual)) => {
3645                        let actual: BigInt = actual.to_string().parse().unwrap();
3646                        assert_eq!(
3647                            actual,
3648                            expected,
3649                            "{s:?} as {}({precision}, {scale})",
3650                            T::PREFIX
3651                        );
3652                    }
3653                    (false, Err(_)) => {}
3654                    (true, Err(e)) => {
3655                        panic!(
3656                            "{s:?} as {}({precision}, {scale}): expected {expected}, got {e}",
3657                            T::PREFIX
3658                        )
3659                    }
3660                    (false, Ok(actual)) => panic!(
3661                        "{s:?} as {}({precision}, {scale}): expected overflow, got {actual}",
3662                        T::PREFIX
3663                    ),
3664                }
3665            }
3666        }
3667
3668        let mut rng = StdRng::seed_from_u64(0xDEC1_3A15);
3669        check::<Decimal32Type>(&mut rng, 5_000);
3670        check::<Decimal64Type>(&mut rng, 5_000);
3671        check::<Decimal128Type>(&mut rng, 5_000);
3672        check::<Decimal256Type>(&mut rng, 5_000);
3673    }
3674
3675    #[test]
3676    fn test_parse_empty() {
3677        assert_eq!(Int32Type::parse(""), None);
3678        assert_eq!(Int64Type::parse(""), None);
3679        assert_eq!(UInt32Type::parse(""), None);
3680        assert_eq!(UInt64Type::parse(""), None);
3681        assert_eq!(Float32Type::parse(""), None);
3682        assert_eq!(Float64Type::parse(""), None);
3683        assert_eq!(Int32Type::parse("+"), None);
3684        assert_eq!(Int64Type::parse("+"), None);
3685        assert_eq!(UInt32Type::parse("+"), None);
3686        assert_eq!(UInt64Type::parse("+"), None);
3687        assert_eq!(Float32Type::parse("+"), None);
3688        assert_eq!(Float64Type::parse("+"), None);
3689        assert_eq!(TimestampNanosecondType::parse(""), None);
3690        assert_eq!(Date32Type::parse(""), None);
3691    }
3692
3693    #[test]
3694    fn test_parse_integer_bounds() {
3695        // The all-nines cases have as many digits as a bound but lie past it. atoi 3.1.0
3696        // parsed -99999 as i16 without an overflow check (#11591).
3697        macro_rules! check {
3698            ($t:ty) => {{
3699                type Native = <$t as ArrowPrimitiveType>::Native;
3700                let (min, max) = (i128::from(Native::MIN), i128::from(Native::MAX));
3701                let nines = 10_i128.pow(max.ilog10() + 1) - 1;
3702                for v in [
3703                    min,
3704                    max,
3705                    min - 1,
3706                    max + 1,
3707                    -nines,
3708                    nines,
3709                    -nines - 1,
3710                    nines + 1,
3711                ] {
3712                    let expected = Native::try_from(v).ok();
3713                    // The leading space takes the path that trims before parsing
3714                    for s in [v.to_string(), format!(" {v}")] {
3715                        assert_eq!(
3716                            <$t>::parse(&s),
3717                            expected,
3718                            "{s:?} as {}",
3719                            <$t as ArrowPrimitiveType>::DATA_TYPE
3720                        );
3721                    }
3722                }
3723            }};
3724        }
3725        check!(Int8Type);
3726        check!(Int16Type);
3727        check!(Int32Type);
3728        check!(Int64Type);
3729        check!(UInt8Type);
3730        check!(UInt16Type);
3731        check!(UInt32Type);
3732        check!(UInt64Type);
3733    }
3734
3735    #[test]
3736    fn test_parse_interval_month_day_nano_config() {
3737        let interval = parse_interval_month_day_nano_config(
3738            "1",
3739            IntervalParseConfig::new(IntervalUnit::Second),
3740        )
3741        .unwrap();
3742        assert_eq!(interval.months, 0);
3743        assert_eq!(interval.days, 0);
3744        assert_eq!(interval.nanoseconds, NANOS_PER_SECOND);
3745    }
3746    #[test]
3747    fn test_parse_prefix_white_space() {
3748        assert_eq!(Float64Type::parse(" 1.5"), Some(1.5));
3749        assert_eq!(Float64Type::parse("\t\n 20.54"), Some(20.54));
3750        assert_eq!(Float64Type::parse("\n2.5"), Some(2.5));
3751        assert_eq!(Float64Type::parse("\n-942.5423"), Some(-942.5423));
3752        assert_eq!(Float64Type::parse("\n\t\n\t\n40.5123"), Some(40.5123));
3753        assert_eq!(Float64Type::parse(" 1.5"), Some(1.5));
3754        assert_eq!(Float64Type::parse("\n\t\n\t\n-40.5123"), Some(-40.5123));
3755        assert_eq!(Float64Type::parse(" -1.5"), Some(-1.5));
3756        assert_eq!(Int32Type::parse(" 3"), Some(3));
3757        assert_eq!(Int32Type::parse("          30"), Some(30));
3758        assert_eq!(Int32Type::parse("\n \n 100"), Some(100));
3759        assert_eq!(Int32Type::parse(" \n25"), Some(25));
3760        assert_eq!(Int32Type::parse("\t800"), Some(800));
3761        assert_eq!(Int32Type::parse("\t  \n \t 851"), Some(851));
3762        assert_eq!(Int32Type::parse("\t\n\t\n\n\n\t1"), Some(1));
3763        assert_eq!(Int32Type::parse(" \n-25"), Some(-25));
3764        assert_eq!(Int32Type::parse("\t-800"), Some(-800));
3765
3766        // suffix whitespace
3767        assert_eq!(Float64Type::parse("1.5 "), Some(1.5));
3768        assert_eq!(Float64Type::parse("40.5123\n"), Some(40.5123));
3769        assert_eq!(Float64Type::parse("40.5123\n\t\n\t\n"), Some(40.5123));
3770        assert_eq!(Float64Type::parse("-942.5423\t"), Some(-942.5423));
3771        assert_eq!(Int32Type::parse("3 "), Some(3));
3772        assert_eq!(Int32Type::parse("30          "), Some(30));
3773        assert_eq!(Int32Type::parse("-25 \n"), Some(-25));
3774        assert_eq!(Int32Type::parse("800\t"), Some(800));
3775        // whitespace on both sides
3776        assert_eq!(Float64Type::parse(" 1.5 "), Some(1.5));
3777        assert_eq!(Float64Type::parse("\t\n 20.54 \t"), Some(20.54));
3778        assert_eq!(Float64Type::parse("\n-942.5423\n"), Some(-942.5423));
3779        assert_eq!(Int32Type::parse(" 3 "), Some(3));
3780        assert_eq!(Int32Type::parse("\n \n 100 \n"), Some(100));
3781        assert_eq!(Int32Type::parse("\t-800\t\n"), Some(-800));
3782
3783        // trailing non-whitespace chars should not parse
3784        assert_eq!(Float64Type::parse("1.5abc"), None);
3785        assert_eq!(Float64Type::parse("40.5123x"), None);
3786        assert_eq!(Int32Type::parse("30x"), None);
3787        assert_eq!(Int32Type::parse("100px"), None);
3788        assert_eq!(Int32Type::parse("-25!"), None);
3789        assert_eq!(Int32Type::parse("3j"), None);
3790        assert_eq!(Int32Type::parse("3"), Some(3));
3791    }
3792
3793    #[test]
3794    fn test_parse_temporal_with_surrounding_whitespace() {
3795        let date = Date32Type::parse("2024-01-05");
3796        assert_eq!(Date32Type::parse(" 2024-01-05 "), date);
3797        assert_eq!(Date32Type::parse("\t2024-01-05\n"), date);
3798
3799        let timestamp = "2024-01-05T10:00:00";
3800        let padded_timestamp = " 2024-01-05T10:00:00 ";
3801
3802        assert_eq!(
3803            TimestampNanosecondType::parse(padded_timestamp),
3804            TimestampNanosecondType::parse(timestamp)
3805        );
3806        assert_eq!(
3807            TimestampMicrosecondType::parse(padded_timestamp),
3808            TimestampMicrosecondType::parse(timestamp)
3809        );
3810        assert_eq!(
3811            TimestampMillisecondType::parse(padded_timestamp),
3812            TimestampMillisecondType::parse(timestamp)
3813        );
3814        assert_eq!(
3815            TimestampSecondType::parse(padded_timestamp),
3816            TimestampSecondType::parse(timestamp)
3817        );
3818        assert_eq!(
3819            TimestampNanosecondType::parse("\t2024-01-05T10:00:00\n"),
3820            TimestampNanosecondType::parse(timestamp)
3821        );
3822
3823        // leet :)
3824        let time = "13:37:00";
3825        let padded_time = " 13:37:00 ";
3826
3827        assert_eq!(
3828            Time64NanosecondType::parse(padded_time),
3829            Time64NanosecondType::parse(time)
3830        );
3831        assert_eq!(
3832            Time64MicrosecondType::parse(padded_time),
3833            Time64MicrosecondType::parse(time)
3834        );
3835        assert_eq!(
3836            Time64MicrosecondType::parse("\t13:37:00\n"),
3837            Time64MicrosecondType::parse(time)
3838        );
3839    }
3840
3841    #[test]
3842    fn test_parse_time_with_surrounding_ascii_whitespace() {
3843        let time = "10:00:00";
3844        let padded = " 10:00:00 ";
3845        let ascii_whitespace = "\t10:00:00\n";
3846
3847        assert_eq!(
3848            Time64NanosecondType::parse(padded),
3849            Time64NanosecondType::parse(time)
3850        );
3851        assert_eq!(
3852            Time64MicrosecondType::parse(padded),
3853            Time64MicrosecondType::parse(time)
3854        );
3855        assert_eq!(
3856            Time32MillisecondType::parse(padded),
3857            Time32MillisecondType::parse(time)
3858        );
3859        assert_eq!(
3860            Time32SecondType::parse(padded),
3861            Time32SecondType::parse(time)
3862        );
3863
3864        assert_eq!(
3865            Time64NanosecondType::parse(ascii_whitespace),
3866            Time64NanosecondType::parse(time)
3867        );
3868        assert_eq!(
3869            Time64MicrosecondType::parse(ascii_whitespace),
3870            Time64MicrosecondType::parse(time)
3871        );
3872        assert_eq!(
3873            Time32MillisecondType::parse(ascii_whitespace),
3874            Time32MillisecondType::parse(time)
3875        );
3876        assert_eq!(
3877            Time32SecondType::parse(ascii_whitespace),
3878            Time32SecondType::parse(time)
3879        );
3880    }
3881
3882    /// Parses `s` as a wall clock reading in `zone` and returns the resulting
3883    /// instant, as (seconds since the epoch, RFC3339 rendering in UTC).
3884    ///
3885    /// `zone` plays the role of the target `Timestamp(_, Some(tz))` timezone.
3886    fn parse_in_zone(zone: &str, s: &str) -> (i64, String) {
3887        let tz: Tz = zone.parse().unwrap();
3888        let dt = string_to_datetime(&tz, s).unwrap();
3889        (dt.timestamp(), dt.to_utc().to_rfc3339())
3890    }
3891
3892    /// Parses `s`, which names its own timezone, against a UTC target.
3893    fn parse_with_named_zone(s: &str) -> (i64, String) {
3894        let dt = string_to_datetime(&Utc, s).unwrap();
3895        (dt.timestamp(), dt.to_utc().to_rfc3339())
3896    }
3897
3898    // A naive datetime read as a wall clock time in the target timezone. This is
3899    // the `'2024-03-10 02:30:00'::timestamptz` spelling, where the timezone comes
3900    // from the target type rather than from the string.
3901    //
3902    // Every expectation here was taken from PostgreSQL 17.11 via
3903    // `SET TimeZone = <zone>; SELECT '<input>'::timestamptz;`.
3904    #[test]
3905    fn test_string_to_datetime_dst_target_timezone() {
3906        // (zone, input, epoch seconds, UTC rendering)
3907        let cases = [
3908            // America/New_York: a one hour DST step.
3909            // Control: nothing special about this reading.
3910            (
3911                "America/New_York",
3912                "2024-11-01 00:00:00",
3913                1_730_433_600,
3914                "2024-11-01T04:00:00+00:00",
3915            ),
3916            // Ambiguous: the clocks go back at 2024-11-03T02:00 EDT, so 01:30
3917            // happens twice. The later (EST, -05:00) instant wins.
3918            (
3919                "America/New_York",
3920                "2024-11-03 01:30:00",
3921                1_730_615_400,
3922                "2024-11-03T06:30:00+00:00",
3923            ),
3924            // Nonexistent: the clocks go forward at 2024-03-10T02:00 EST, so
3925            // 02:30 never happens. It shifts forward to 03:30 EDT.
3926            (
3927                "America/New_York",
3928                "2024-03-10 02:30:00",
3929                1_710_055_800,
3930                "2024-03-10T07:30:00+00:00",
3931            ),
3932            // Australia/Sydney: southern hemisphere, so the gap is in October and
3933            // the repeated hour is in April.
3934            (
3935                "Australia/Sydney",
3936                "2024-04-07 02:30:00",
3937                1_712_421_000,
3938                "2024-04-06T16:30:00+00:00",
3939            ),
3940            (
3941                "Australia/Sydney",
3942                "2024-10-06 02:30:00",
3943                1_728_145_800,
3944                "2024-10-05T16:30:00+00:00",
3945            ),
3946            // Australia/Lord_Howe: a *thirty minute* DST step, so the gap is half
3947            // an hour wide and 02:15 shifts to 02:45 rather than to 03:15.
3948            (
3949                "Australia/Lord_Howe",
3950                "2024-04-07 01:45:00",
3951                1_712_416_500,
3952                "2024-04-06T15:15:00+00:00",
3953            ),
3954            (
3955                "Australia/Lord_Howe",
3956                "2024-10-06 02:15:00",
3957                1_728_143_100,
3958                "2024-10-05T15:45:00+00:00",
3959            ),
3960            // Pacific/Chatham: +12:45 / +13:45, i.e. an offset that is not a whole
3961            // number of hours on either side of the transition.
3962            (
3963                "Pacific/Chatham",
3964                "2024-04-07 03:00:00",
3965                1_712_412_900,
3966                "2024-04-06T14:15:00+00:00",
3967            ),
3968            (
3969                "Pacific/Chatham",
3970                "2024-09-29 03:00:00",
3971                1_727_532_900,
3972                "2024-09-28T14:15:00+00:00",
3973            ),
3974            // A fixed offset has no transitions and is unaffected.
3975            (
3976                "+05:30",
3977                "2024-03-10 02:30:00",
3978                1_710_018_000,
3979                "2024-03-09T21:00:00+00:00",
3980            ),
3981        ];
3982
3983        for (zone, input, epoch, utc) in cases {
3984            assert_eq!(
3985                parse_in_zone(zone, input),
3986                (epoch, utc.to_string()),
3987                "{input} in {zone}"
3988            );
3989        }
3990    }
3991
3992    // The date-only branch of `string_to_datetime`, which reads local midnight.
3993    // Midnight is where a transition falls in a number of zones, and it is easy
3994    // to miss when only datetime inputs are considered.
3995    #[test]
3996    fn test_string_to_datetime_dst_date_only() {
3997        let cases = [
3998            // Brazil started DST at midnight, so 2018-11-04T00:00 does not exist
3999            // in America/Sao_Paulo. It shifts forward to 01:00 -02:00.
4000            (
4001                "America/Sao_Paulo",
4002                "2018-11-04",
4003                1_541_300_400,
4004                "2018-11-04T03:00:00+00:00",
4005            ),
4006            // Cuba ends DST at midnight, so 2024-11-03T00:00 happens twice in
4007            // America/Havana. The later (-05:00) instant wins.
4008            (
4009                "America/Havana",
4010                "2024-11-03",
4011                1_730_610_000,
4012                "2024-11-03T05:00:00+00:00",
4013            ),
4014            // Control: New York's transition that day is at 02:00, not midnight.
4015            (
4016                "America/New_York",
4017                "2024-03-10",
4018                1_710_046_800,
4019                "2024-03-10T05:00:00+00:00",
4020            ),
4021        ];
4022
4023        for (zone, input, epoch, utc) in cases {
4024            assert_eq!(
4025                parse_in_zone(zone, input),
4026                (epoch, utc.to_string()),
4027                "{input} in {zone}"
4028            );
4029        }
4030    }
4031
4032    // A timezone named by the string itself, e.g.
4033    // `TIMESTAMPTZ '2024-03-10 02:30:00 America/New_York'`. PostgreSQL resolves
4034    // these exactly as it resolves a reading taken against the session timezone,
4035    // and so do we: the zone is named more explicitly, but the wall clock reading
4036    // is no less ambiguous for it.
4037    #[test]
4038    fn test_string_to_datetime_dst_named_zone_in_string() {
4039        let cases = [
4040            (
4041                "2024-11-03 01:30:00 America/New_York",
4042                1_730_615_400,
4043                "2024-11-03T06:30:00+00:00",
4044            ),
4045            (
4046                "2024-03-10 02:30:00 America/New_York",
4047                1_710_055_800,
4048                "2024-03-10T07:30:00+00:00",
4049            ),
4050            (
4051                "2024-04-07 02:30:00 Australia/Sydney",
4052                1_712_421_000,
4053                "2024-04-06T16:30:00+00:00",
4054            ),
4055            (
4056                "2024-10-06 02:30:00 Australia/Sydney",
4057                1_728_145_800,
4058                "2024-10-05T16:30:00+00:00",
4059            ),
4060            (
4061                "2024-04-07 01:45:00 Australia/Lord_Howe",
4062                1_712_416_500,
4063                "2024-04-06T15:15:00+00:00",
4064            ),
4065            (
4066                "2024-10-06 02:15:00 Australia/Lord_Howe",
4067                1_728_143_100,
4068                "2024-10-05T15:45:00+00:00",
4069            ),
4070            (
4071                "2024-04-07 03:00:00 Pacific/Chatham",
4072                1_712_412_900,
4073                "2024-04-06T14:15:00+00:00",
4074            ),
4075            (
4076                "2024-09-29 03:00:00 Pacific/Chatham",
4077                1_727_532_900,
4078                "2024-09-28T14:15:00+00:00",
4079            ),
4080            // A fixed offset spelled out in the string stays unaffected.
4081            (
4082                "2024-03-10 02:30:00 +05:30",
4083                1_710_018_000,
4084                "2024-03-09T21:00:00+00:00",
4085            ),
4086        ];
4087
4088        for (input, epoch, utc) in cases {
4089            assert_eq!(
4090                parse_with_named_zone(input),
4091                (epoch, utc.to_string()),
4092                "{input}"
4093            );
4094        }
4095    }
4096
4097    // Sub-second precision survives the shift applied to a nonexistent reading.
4098    #[test]
4099    fn test_string_to_datetime_dst_subsecond() {
4100        let tz: Tz = "America/New_York".parse().unwrap();
4101        let dt = string_to_datetime(&tz, "2024-03-10 02:30:00.123456789").unwrap();
4102        assert_eq!(dt.timestamp(), 1_710_055_800);
4103        assert_eq!(dt.timestamp_subsec_nanos(), 123_456_789);
4104
4105        let dt =
4106            string_to_datetime(&Utc, "2024-11-03 01:30:00.123456789 America/New_York").unwrap();
4107        assert_eq!(dt.timestamp(), 1_730_615_400);
4108        assert_eq!(dt.timestamp_subsec_nanos(), 123_456_789);
4109    }
4110
4111    // `string_to_timestamp_nanos` reads against UTC, which has no transitions, so
4112    // none of this changes what it does.
4113    #[test]
4114    fn test_string_to_timestamp_nanos_unaffected_by_dst() {
4115        assert_eq!(
4116            string_to_timestamp_nanos("2024-03-10 02:30:00").unwrap(),
4117            1_710_037_800 * 1_000_000_000
4118        );
4119    }
4120}