scolapasta_int_parse/
error.rs

1use core::fmt::{self, Write as _};
2
3use scolapasta_string_escape::format_debug_escape_into;
4
5use crate::subject::IntegerString;
6
7/// Sum type for all possible errors from this crate.
8///
9/// See [`ArgumentError`] and [`InvalidRadixError`] for more details.
10#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord)]
11pub enum Error<'a> {
12    /// An [`ArgumentError`].
13    Argument(ArgumentError<'a>),
14    /// An [`InvalidRadixError`].
15    Radix(InvalidRadixError),
16}
17
18impl<'a> From<ArgumentError<'a>> for Error<'a> {
19    fn from(err: ArgumentError<'a>) -> Self {
20        Self::Argument(err)
21    }
22}
23
24impl<'a> From<IntegerString<'a>> for Error<'a> {
25    fn from(subject: IntegerString<'a>) -> Self {
26        Self::Argument(subject.into())
27    }
28}
29
30impl<'a> From<&'a [u8]> for Error<'a> {
31    fn from(subject: &'a [u8]) -> Self {
32        Self::Argument(subject.into())
33    }
34}
35
36impl From<InvalidRadixError> for Error<'_> {
37    fn from(err: InvalidRadixError) -> Self {
38        Self::Radix(err)
39    }
40}
41
42impl From<InvalidRadixErrorKind> for Error<'_> {
43    fn from(err: InvalidRadixErrorKind) -> Self {
44        Self::Radix(err.into())
45    }
46}
47
48impl fmt::Display for Error<'_> {
49    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
50        match self {
51            Self::Argument(err) => write!(f, "{err}"),
52            Self::Radix(err) => write!(f, "{err}"),
53        }
54    }
55}
56
57#[cfg(feature = "std")]
58impl std::error::Error for Error<'_> {}
59
60/// Error that indicates the byte string input to [`parse`] was invalid.
61///
62/// This error can be returned in the following circumstances:
63///
64/// - The input has non-ASCII bytes.
65/// - The input contains a NUL byte.
66/// - The input is the empty byte slice.
67/// - The input only contains +/- signs.
68/// - The given radix does not match a `0x`-style prefix.
69/// - Invalid or duplicate +/- signs are in the input.
70/// - Consecutive underscores are present in the input.
71/// - Leading or trailing underscores are present in the input.
72/// - The input contains ASCII alphanumeric bytes that are invalid for the
73///   computed radix.
74///
75/// # Examples
76///
77/// ```
78/// # use scolapasta_int_parse::Radix;
79/// let result = scolapasta_int_parse::parse("0xBAD", Some(10));
80/// let err = result.unwrap_err();
81/// assert_eq!(err.to_string(), r#"invalid value for Integer(): "0xBAD""#);
82/// ```
83///
84/// [`parse`]: crate::parse
85/// [Ruby `ArgumentError` Exception class]: https://ruby-doc.org/core-3.1.2/ArgumentError.html
86#[derive(Default, Debug, Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord)]
87pub struct ArgumentError<'a> {
88    subject: &'a [u8],
89}
90
91impl<'a> ArgumentError<'a> {
92    /// Return the subject of parsing that returned this argument error.
93    ///
94    /// # Examples
95    ///
96    /// ```
97    /// # use scolapasta_int_parse::Error;
98    /// let result = scolapasta_int_parse::parse("0xBAD", Some(10));
99    /// let err = result.unwrap_err();
100    /// assert!(matches!(err, Error::Argument(err) if err.subject() == "0xBAD".as_bytes()));
101    /// ```
102    #[must_use]
103    pub const fn subject(self) -> &'a [u8] {
104        self.subject
105    }
106}
107
108impl<'a> From<IntegerString<'a>> for ArgumentError<'a> {
109    fn from(subject: IntegerString<'a>) -> Self {
110        let subject = subject.as_bytes();
111        Self { subject }
112    }
113}
114
115impl<'a> From<&'a [u8]> for ArgumentError<'a> {
116    fn from(subject: &'a [u8]) -> Self {
117        Self { subject }
118    }
119}
120
121impl fmt::Display for ArgumentError<'_> {
122    fn fmt(&self, mut f: &mut fmt::Formatter<'_>) -> fmt::Result {
123        f.write_str(r#"invalid value for Integer(): ""#)?;
124        // FIXME: this should actually be `String#inspect`, which is encoding
125        // aware.
126        format_debug_escape_into(&mut f, self.subject)?;
127        f.write_char('"')?;
128        Ok(())
129    }
130}
131
132#[cfg(feature = "std")]
133impl std::error::Error for ArgumentError<'_> {}
134
135#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord)]
136pub enum InvalidRadixErrorKind {
137    TooSmall(i64),
138    TooBig(i64),
139    Invalid(i64),
140}
141
142/// An enum describing which type of Ruby `Exception` an [`InvalidRadixError`]
143/// should be mapped to.
144///
145/// If the given radix falls outside the range of an [`i32`], the error should
146/// be mapped to a [`RangeError`].
147///
148/// If the given radix falls within the range of an [`i32`], but outside the
149/// range of `2..=36` (or `-36..=-2` in some cases), the error should be mapped
150/// to an [`ArgumentError`].
151///
152/// The error message for these Ruby exceptions should be derived from the
153/// [`fmt::Display`] implementation of [`InvalidRadixError`].
154///
155/// [`RangeError`]: https://ruby-doc.org/core-3.1.2/RangeError.html
156/// [`ArgumentError`]: https://ruby-doc.org/core-3.1.2/ArgumentError.html
157#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord)]
158pub enum InvalidRadixExceptionKind {
159    /// If the given radix falls within the range of an [`i32`], but outside the
160    /// range of `2..=36` (or -36..=-2 in some cases), the error should be
161    /// mapped to an [`ArgumentError`]:
162    ///
163    /// ```console
164    /// [3.1.2] > begin; Integer "123", 49; rescue => e; p e; end
165    /// #<ArgumentError: invalid radix 49>
166    /// [3.1.2] > begin; Integer "123", -49; rescue => e; p e; end
167    /// #<ArgumentError: invalid radix 49>
168    /// ```
169    ///
170    /// [`ArgumentError`]: https://ruby-doc.org/core-3.1.2/ArgumentError.html
171    ArgumentError,
172    /// If the given radix falls outside the range of an [`i32`], the error should
173    /// be mapped to a [`RangeError`]:
174    ///
175    /// ```console
176    /// [3.1.2] > begin; Integer "123", (2 ** 31 + 1); rescue => e; p e; end
177    /// #<RangeError: integer 2147483649 too big to convert to `int'>
178    /// [3.1.2] > begin; Integer "123", -(2 ** 31 + 1); rescue => e; p e; end
179    /// #<RangeError: integer -2147483649 too small to convert to `int'>
180    /// ```
181    ///
182    /// [`RangeError`]: https://ruby-doc.org/core-3.1.2/RangeError.html
183    RangeError,
184}
185
186/// Error that indicates the radix input to [`parse`] was invalid.
187///
188/// This error can be returned in the following circumstances:
189///
190/// - The input is out of range of [`i32`].
191/// - The input radix is negative (if the input byte string does not have an
192///   `0x`-style prefix) and out of range `-36..=-2`.
193/// - The input is out of range of `2..=36`.
194///
195/// This error may map to several Ruby `Exception` types. See
196/// [`InvalidRadixExceptionKind`] for more details.
197///
198/// # Examples
199///
200/// ```
201/// # use scolapasta_int_parse::Radix;
202/// let result = scolapasta_int_parse::parse("123", Some(500));
203/// let err = result.unwrap_err();
204/// assert_eq!(err.to_string(), "invalid radix 500");
205/// ```
206///
207/// [`parse`]: crate::parse
208#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord)]
209pub struct InvalidRadixError {
210    kind: InvalidRadixErrorKind,
211}
212
213impl From<InvalidRadixErrorKind> for InvalidRadixError {
214    fn from(kind: InvalidRadixErrorKind) -> Self {
215        Self { kind }
216    }
217}
218
219impl InvalidRadixError {
220    /// Map an invalid radix error to the kind of Ruby `Exception` it should be
221    /// raised as.
222    ///
223    /// See [`InvalidRadixExceptionKind`] for more details.
224    #[must_use]
225    pub fn exception_kind(&self) -> InvalidRadixExceptionKind {
226        match self.kind {
227            InvalidRadixErrorKind::Invalid(_) => InvalidRadixExceptionKind::ArgumentError,
228            InvalidRadixErrorKind::TooSmall(_) | InvalidRadixErrorKind::TooBig(_) => {
229                InvalidRadixExceptionKind::RangeError
230            }
231        }
232    }
233}
234
235impl fmt::Display for InvalidRadixError {
236    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
237        match self.kind {
238            // ```
239            // [3.1.2] > Integer "123", -((2 ** 31 + 1))
240            // (irb):14:in `Integer': integer -2147483649 too small to convert to `int' (RangeError)
241            //         from (irb):14:in `<main>'
242            //         from /usr/local/var/rbenv/versions/3.1.2/lib/ruby/gems/3.1.0/gems/irb-1.4.1/exe/irb:11:in `<top (required)>'
243            //         from /usr/local/var/rbenv/versions/3.1.2/bin/irb:25:in `load'
244            //         from /usr/local/var/rbenv/versions/3.1.2/bin/irb:25:in `<main>'
245            // ```
246            InvalidRadixErrorKind::TooSmall(num) => write!(f, "integer {num} too small to convert to `int'"),
247            // ```
248            // [3.1.2] > Integer "123", (2 ** 31 + 1)
249            // (irb):15:in `Integer': integer 2147483649 too big to convert to `int' (RangeError)
250            //         from (irb):15:in `<main>'
251            //         from /usr/local/var/rbenv/versions/3.1.2/lib/ruby/gems/3.1.0/gems/irb-1.4.1/exe/irb:11:in `<top (required)>'
252            //         from /usr/local/var/rbenv/versions/3.1.2/bin/irb:25:in `load'
253            //         from /usr/local/var/rbenv/versions/3.1.2/bin/irb:25:in `<main>'
254            // ```
255            InvalidRadixErrorKind::TooBig(num) => write!(f, "integer {num} too big to convert to `int'"),
256            // ```
257            // [3.1.2] > Integer "123", 1
258            // (irb):17:in `Integer': invalid radix 1 (ArgumentError)
259            //         from (irb):17:in `<main>'
260            //         from /usr/local/var/rbenv/versions/3.1.2/lib/ruby/gems/3.1.0/gems/irb-1.4.1/exe/irb:11:in `<top (required)>'
261            //         from /usr/local/var/rbenv/versions/3.1.2/bin/irb:25:in `load'
262            //         from /usr/local/var/rbenv/versions/3.1.2/bin/irb:25:in `<main>'
263            // [3.1.2] > Integer "123", 39
264            // (irb):18:in `Integer': invalid radix 39 (ArgumentError)
265            //         from (irb):18:in `<main>'
266            //         from /usr/local/var/rbenv/versions/3.1.2/lib/ruby/gems/3.1.0/gems/irb-1.4.1/exe/irb:11:in `<top (required)>'
267            //         from /usr/local/var/rbenv/versions/3.1.2/bin/irb:25:in `load'
268            //         from /usr/local/var/rbenv/versions/3.1.2/bin/irb:25:in `<main>'
269            // ```
270            InvalidRadixErrorKind::Invalid(num) => write!(f, "invalid radix {num}"),
271        }
272    }
273}
274
275#[cfg(feature = "std")]
276impl std::error::Error for InvalidRadixError {}
277
278#[cfg(test)]
279mod tests {
280    use alloc::string::String;
281    use core::fmt::Write as _;
282
283    use super::ArgumentError;
284    use crate::subject::IntegerString;
285
286    #[test]
287    fn argument_error_display_from_integer_string() {
288        let test_cases = [
289            ["0x", r#"invalid value for Integer(): "0x""#],
290            ["0b", r#"invalid value for Integer(): "0b""#],
291            ["0o", r#"invalid value for Integer(): "0o""#],
292            ["o", r#"invalid value for Integer(): "o""#],
293            ["0d", r#"invalid value for Integer(): "0d""#],
294            ["0X", r#"invalid value for Integer(): "0X""#],
295            ["0B", r#"invalid value for Integer(): "0B""#],
296            ["0O", r#"invalid value for Integer(): "0O""#],
297            ["O", r#"invalid value for Integer(): "O""#],
298            ["0D", r#"invalid value for Integer(): "0D""#],
299            ["-0x", r#"invalid value for Integer(): "-0x""#],
300            ["-0b", r#"invalid value for Integer(): "-0b""#],
301            ["-0o", r#"invalid value for Integer(): "-0o""#],
302            ["-o", r#"invalid value for Integer(): "-o""#],
303            ["-0d", r#"invalid value for Integer(): "-0d""#],
304            ["-0X", r#"invalid value for Integer(): "-0X""#],
305            ["-0B", r#"invalid value for Integer(): "-0B""#],
306            ["-0O", r#"invalid value for Integer(): "-0O""#],
307            ["-O", r#"invalid value for Integer(): "-O""#],
308            ["-0D", r#"invalid value for Integer(): "-0D""#],
309            ["0z", r#"invalid value for Integer(): "0z""#],
310            ["-0z", r#"invalid value for Integer(): "-0z""#],
311            ["B1", r#"invalid value for Integer(): "B1""#],
312            ["b1", r#"invalid value for Integer(): "b1""#],
313            ["O7", r#"invalid value for Integer(): "O7""#],
314            ["o7", r#"invalid value for Integer(): "o7""#],
315            ["D9", r#"invalid value for Integer(): "D9""#],
316            ["d9", r#"invalid value for Integer(): "d9""#],
317            ["XF", r#"invalid value for Integer(): "XF""#],
318            ["Xf", r#"invalid value for Integer(): "Xf""#],
319            ["xF", r#"invalid value for Integer(): "xF""#],
320            ["xf", r#"invalid value for Integer(): "xf""#],
321            ["0x_0000001234567", r#"invalid value for Integer(): "0x_0000001234567""#],
322            ["0_x0000001234567", r#"invalid value for Integer(): "0_x0000001234567""#],
323            [
324                "___0x0000001234567",
325                r#"invalid value for Integer(): "___0x0000001234567""#,
326            ],
327            ["0x111__11", r#"invalid value for Integer(): "0x111__11""#],
328            ["0x111_11_", r#"invalid value for Integer(): "0x111_11_""#],
329            ["0x00000_", r#"invalid value for Integer(): "0x00000_""#],
330            ["    ", r#"invalid value for Integer(): "    ""#],
331            ["", r#"invalid value for Integer(): """#],
332            ["++12", r#"invalid value for Integer(): "++12""#],
333            ["+-12", r#"invalid value for Integer(): "+-12""#],
334            ["-+12", r#"invalid value for Integer(): "-+12""#],
335            ["--12", r#"invalid value for Integer(): "--12""#],
336        ];
337        for [input, message] in test_cases {
338            let subject = IntegerString::try_from(input).unwrap();
339            let err = ArgumentError::from(subject);
340            let mut buf = String::new();
341            write!(&mut buf, "{err}").unwrap();
342            assert_eq!(&*buf, message, "unexpected value for test case '{input}'");
343        }
344    }
345
346    #[test]
347    fn argument_error_display_from_invalid_subject() {
348        let test_cases: &[(&[u8], &str)] = &[
349            (b"\xFF", r#"invalid value for Integer(): "\xFF""#),
350            ("🦀".as_bytes(), r#"invalid value for Integer(): "🦀""#),
351            // XXX: for UTF-8 strings, `"\x00".inspect` is `"\u0000"`.
352            (b"\x00", r#"invalid value for Integer(): "\x00""#),
353        ];
354        for (input, message) in test_cases.iter().copied() {
355            let err = ArgumentError::from(input);
356            let mut buf = String::new();
357            write!(&mut buf, "{err}").unwrap();
358            assert_eq!(&*buf, message, "unexpected value for test case '{input:?}'");
359        }
360    }
361}
scolapasta_int_parse/error.rs

scolapasta_int_parse/
error.rs
