alkale 2.0.0

//! Sub-module of [`common`](crate::common) specifically for number parsing.
//!
//! In Alkale and, indeed, with most lexers, it is idiomatic to handle negative numbers
//! during *parsing*, not during lexing. As such, methods defined here completely ignore
//! minus signs\*.
//!
//! \*Methods will parse out negative signs for numbers such as `23e-5`, however these
//! are very clearly part of a number token and not a potential minus operation. See
//! [`consume_standard_number`][SourceCodeScanner::consume_standard_number] for more
//! information.

pub mod base;
mod error;

use core::{num::ParseFloatError, str};

use base::{NumericalBase, StandardBase};
use num_traits::{CheckedAdd, CheckedMul, Unsigned, Zero};

use crate::{
    span::{Span, Spannable, Spanned},
    SourceCodeScanner,
};

pub use error::IntegerParseError;
pub use error::ParseNumberResult;

/// Internal method for determining if a character is considered "numerical."
const fn is_numerical(ch: char) -> bool {
    ch.is_ascii_alphanumeric() || ch == '_' || ch == '.'
}

/// List of of number prefixes and their corresponding
/// bases.
const BASE_MAPPINGS: [(&str, StandardBase); 3] = [
    ("0b", StandardBase::Binary),
    ("0o", StandardBase::Octal),
    ("0x", StandardBase::Hexadecimal),
];

/// Internal method to check if a string begins with `0x`, `0b`, etc.
/// If it does, return the relevant base and modify the input string slice
/// to disclude those characters. If not, the string is unchanged and
/// [None] is returned.
fn chop_standard_base(s: &mut &str) -> Option<StandardBase> {
    for (prefix, base) in BASE_MAPPINGS {
        if s.starts_with(prefix) {
            // SAFETY: s ends with f, a 1-byte ascii char.
            unsafe {
                *s = s.get_unchecked(prefix.len()..);
            }

            return Some(base);
        }
    }

    None
}

/// Internal method to check if a string ends in an `f` character.
/// If it does, it will be removed and `true` returned, otherwise `false`
/// is returned.
fn check_float_suffix(s: &mut &str) -> bool {
    let result = s.ends_with('f');

    if result {
        // SAFETY: s ends with f, a 1-byte ascii char.
        unsafe { *s = s.get_unchecked(..s.len().unchecked_sub(1)) }
    }

    result
}

/// Internal method to parse an integer from a string using the specified base.
fn parse_integer_from_base<
    R: Copy + Zero + CheckedAdd<Output = R> + CheckedMul<Output = R> + From<u8> + Unsigned,
    B: NumericalBase,
>(
    s: &str,
    span: Span,
    base: &B,
) -> Spanned<Result<R, IntegerParseError>> {
    let mut out = R::zero();
    let position = R::from(base.position_value());

    for next in s.chars() {
        if base.includes(next) {
            // SAFETY: digit * sign should never overflow
            let value = Into::<R>::into(unsafe { base.value_of_unchecked(next) });

            // out = Some(out * position + value); out = IntegerOutOfRangeError if anything goes wrong
            let Some(new_value) = out
                .checked_mul(&position)
                .and_then(|y| y.checked_add(&value))
            else {
                return Err(IntegerParseError::OutOfRange).spanned(span);
            };

            out = new_value;
        } else if next != '_' {
            return Err(IntegerParseError::InvalidCharacter(next)).spanned(span);
        }
    }

    Ok(out).spanned(span)
}

impl<'src> SourceCodeScanner<'src> {
    /// This method will greedily match the following regex pattern in the source code:
    /// `[0-9.]([a-df-zA-DF-Z0-9._] | [Ee][+-]?)*`. This method will return a spanned
    /// [`prim@str`] of the captured region.
    ///
    /// If the pattern does not match the source code, [`None`] returned.
    ///
    /// In human-readable terms, this will match as many letters, digits, periods,
    /// underscores, pluses, and minuses as possible. Plus and minus will only be
    /// matched if they are immediately following an `e` or `E`.
    ///
    /// # Intention
    /// This method should be used to capture a "number-like" part of
    /// source code, and then manual parsing into a number datatype can be done
    /// afterwards. This is more efficient than grabbing digits one-by-one.
    ///
    /// # Examples
    /// ```rust
    /// # use alkale::SourceCodeScanner;
    /// # use alkale::span::Span;
    /// let scanner = SourceCodeScanner::new(r#"
    ///     123
    ///     1.5
    ///     1e-5
    ///     5fuas_____f2098ufhbj
    ///     invalid
    ///     .
    /// "#);
    ///
    /// # unsafe {
    /// scanner.skip_whitespace();
    /// assert_eq!(
    ///     scanner.consume_standard_number(),
    ///     Some(Span::new(5, 3).wrap("123"))
    /// );
    ///
    /// scanner.skip_whitespace();
    /// assert_eq!(
    ///     scanner.consume_standard_number(),
    ///     Some(Span::new(13, 3).wrap("1.5"))
    /// );
    ///
    /// scanner.skip_whitespace();
    /// assert_eq!(
    ///     scanner.consume_standard_number(),
    ///     Some(Span::new(21, 4).wrap("1e-5"))
    /// );
    ///
    /// scanner.skip_whitespace();
    /// assert_eq!(
    ///     scanner.consume_standard_number(),
    ///     Some(Span::new(30, 20).wrap("5fuas_____f2098ufhbj"))
    /// );
    ///
    /// scanner.skip_whitespace();
    /// assert_eq!(
    ///     scanner.consume_standard_number(),
    ///     None
    /// );
    ///
    /// scanner.skip_line();
    /// scanner.skip_whitespace();
    /// assert_eq!(
    ///     scanner.consume_standard_number(),
    ///     Some(Span::new(67, 1).wrap("."))
    /// );
    ///
    /// scanner.skip_whitespace();
    /// assert_eq!(
    ///     scanner.consume_standard_number(),
    ///     None
    /// );
    /// # }
    /// ```
    #[inline]
    pub fn consume_standard_number(&self) -> Option<Spanned<&'src str>> {
        // Peek the next character, exit if it doesn't exist.
        let first_char = self.peek()?;

        if !first_char.is_ascii_digit() && first_char != '.' {
            return None;
        }

        let num = self.capture_str(|| {
            self.skip();

            // Determines if a sign is allowed at the current pos or not.
            let mut sign_allowed = false;

            while let Some(char) = self.peek() {
                if is_numerical(char) || (sign_allowed && (char == '+' || char == '-')) {
                    sign_allowed = char == 'e' || char == 'E';
                    self.skip();
                } else {
                    break;
                }
            }
        });

        Some(num)
    }

    /// Consumes a number and parses it into the specified integer type with the given base.
    ///
    /// If no number is found in the source code (sequence of `[a-zA-Z0-9_]` chars),
    /// [`None`] is returned and no characters consumed.
    ///
    /// This method takes in an unsigned number data-type as a generic and
    /// uses that as the resulting number type, if the textual number in the source code overflows this
    /// type's maximum value, then [`IntegerParseError::OutOfRange`] is returned.
    ///
    /// During parsing, underscores are completely ignored.
    ///
    /// # Purpose
    /// This method should be used for languages that only support integers of a certain base.
    ///
    /// # Examples
    /// ```rust
    /// # use alkale::SourceCodeScanner;
    /// # use alkale::span::Span;
    /// # use alkale::common::numeric::base::StandardBase;
    /// # use alkale::common::numeric::IntegerParseError;
    /// let scanner = SourceCodeScanner::new(r#"1100100 FF20 1e3 %invalid"#);
    ///
    /// # unsafe {
    /// assert_eq!(
    ///     scanner.try_parse_integer_from_base::<u32, _>(&StandardBase::Binary),
    ///     Some(Span::new(0, 7).wrap(Ok(0b1100100)))
    /// );
    ///
    /// scanner.skip_whitespace();
    /// assert_eq!(
    ///     scanner.try_parse_integer_from_base::<u32, _>(&StandardBase::Hexadecimal),
    ///     Some(Span::new(8, 4).wrap(Ok(0xFF20)))
    /// );
    ///
    /// scanner.skip_whitespace();
    /// assert_eq!(
    ///     scanner.try_parse_integer_from_base::<u32, _>(&StandardBase::Decimal),
    ///     Some(Span::new(13, 3).wrap(Err(IntegerParseError::InvalidCharacter('e'))))
    /// );
    ///
    /// scanner.skip_whitespace();
    /// assert_eq!(
    ///     scanner.try_parse_integer_from_base::<u32, _>(&StandardBase::Decimal),
    ///     None
    /// );
    /// # }
    /// ```
    ///
    /// # See Also
    /// If base-10 is needed, use [`try_parse_integer`][Self::try_parse_integer] instead.
    /// If only floats are needed, use [`try_parse_float`][Self::try_parse_float].
    /// If both floats and integers are needed, use [`try_parse_number`][Self::try_parse_number].
    #[inline]
    pub fn try_parse_integer_from_base<
        R: Copy + Zero + CheckedAdd<Output = R> + CheckedMul<Output = R> + From<u8> + Unsigned,
        B: NumericalBase,
    >(
        &self,
        base: &B,
    ) -> Option<Spanned<Result<R, IntegerParseError>>> {
        let Spanned { span, data } = self.try_consume_identifier(
            |x| x.is_ascii_alphanumeric() || x == '_',
            |x| x.is_ascii_alphanumeric() || x == '_',
        )?;

        Some(parse_integer_from_base(data, span, base))
    }

    /// Consumes a number and parses it into the specified integer type.
    ///
    /// If no number is found in the source code (by [`consume_standard_number`][Self::consume_standard_number]),
    /// [`None`] is returned and no characters consumed.
    ///
    /// This method takes in an unsigned number data-type as a generic and
    /// uses that as the resulting number type, if the textual number in the source code overflows this
    /// type's maximum value, then [`IntegerParseError::OutOfRange`] is returned.
    ///
    /// During parsing, underscores are completely ignored.
    ///
    /// # Purpose
    /// This method should be used for languages that only support base-10 integers.
    ///
    /// # Examples
    /// ```rust
    /// # use alkale::SourceCodeScanner;
    /// # use alkale::span::Span;
    /// # use alkale::common::numeric::base::StandardBase;
    /// # use alkale::common::numeric::IntegerParseError;
    /// let scanner = SourceCodeScanner::new(r#"123 1500 3e-2 invalid"#);
    ///
    /// # unsafe {
    /// assert_eq!(
    ///     scanner.try_parse_integer::<u32>(),
    ///     Some(Span::new(0, 3).wrap(Ok(123)))
    /// );
    ///
    /// scanner.skip_whitespace();
    /// assert_eq!(
    ///     scanner.try_parse_integer::<u32>(),
    ///     Some(Span::new(4, 4).wrap(Ok(1500)))
    /// );
    ///
    /// scanner.skip_whitespace();
    /// assert_eq!(
    ///     scanner.try_parse_integer::<u32>(),
    ///     Some(Span::new(9, 4).wrap(Err(IntegerParseError::InvalidCharacter('e'))))
    /// );
    ///
    /// scanner.skip_whitespace();
    /// assert_eq!(
    ///     scanner.try_parse_integer::<u32>(),
    ///     None
    /// );
    /// # }
    /// ```
    ///
    /// # See Also
    /// If another base is needed, use [`try_parse_integer_from_base`][Self::try_parse_integer_from_base].
    /// If only floats are needed, use [`try_parse_float`][Self::try_parse_float].
    /// If both floats and integers are needed, use [`try_parse_number`][Self::try_parse_number].
    #[inline]
    pub fn try_parse_integer<
        R: Copy + Zero + CheckedAdd<Output = R> + CheckedMul<Output = R> + From<u8> + Unsigned,
    >(
        &self,
    ) -> Option<Spanned<Result<R, IntegerParseError>>> {
        let Spanned { span, data } = self.consume_standard_number()?;

        Some(parse_integer_from_base(data, span, &StandardBase::Decimal))
    }

    /// Consumes a number and parses it into an [`f64`].
    ///
    /// If no number is found in the source code (by [`consume_standard_number`][Self::consume_standard_number]),
    /// [`None`] is returned and no characters consumed.
    ///
    /// During parsing, underscores are completely ignored.
    ///
    /// # Purpose
    /// This method should be used for languages that only support floating point number literals.
    ///
    /// # Examples
    /// ```rust
    /// # use alkale::SourceCodeScanner;
    /// # use alkale::span::Span;
    /// # use alkale::common::numeric::base::StandardBase;
    /// # use alkale::common::numeric::IntegerParseError;
    /// let scanner = SourceCodeScanner::new(r#"123 150.2 3e-2 invalid"#);
    ///
    /// # unsafe {
    /// assert_eq!(
    ///     scanner.try_parse_float(),
    ///     Some(Span::new(0, 3).wrap(Ok(123.0)))
    /// );
    ///
    /// scanner.skip_whitespace();
    /// assert_eq!(
    ///     scanner.try_parse_float(),
    ///     Some(Span::new(4, 5).wrap(Ok(150.2)))
    /// );
    ///
    /// scanner.skip_whitespace();
    /// assert_eq!(
    ///     scanner.try_parse_float(),
    ///     Some(Span::new(10, 4).wrap(Ok(3e-2)))
    /// );
    ///
    /// scanner.skip_whitespace();
    /// assert_eq!(
    ///     scanner.try_parse_float(),
    ///     None
    /// );
    /// # }
    /// ```
    ///
    /// # See Also
    /// If only integers are needed, use [`try_parse_integer`][Self::try_parse_integer].
    /// If both floats and integers are needed, use [`try_parse_number`][Self::try_parse_number].
    #[inline]
    pub fn try_parse_float(&self) -> Option<Spanned<Result<f64, ParseFloatError>>> {
        let res = self.consume_standard_number()?;

        match str::parse::<f64>(&res.data.replace('_', "")) {
            Ok(value) => Some(Ok(value).spanned(res.span)),
            Err(err) => Some(Err(err).spanned(res.span)),
        }
    }

    /// Consumes a number and parses it into either an [`f64`] or an integer. The integer type
    /// is defined by the `R` generic.
    ///
    /// If no number is found in the source code (by [`consume_standard_number`][Self::consume_standard_number]),
    /// [`None`] is returned and no characters consumed.
    ///
    /// Numbers will be parsed in the following way:
    /// 1. If the number begins with `0x`, parse it as a base-16 integer.
    /// 2. If the number begins with `0o`, parse it as a base-8 integer.
    /// 3. If the number begins with `0b`, parse it as a base-2 integer.
    /// 4. If the number ends with `f`, parse it as a float.
    /// 5. If the number contains a `.`, `-`, or `+`, parse it as a float.
    /// 6. If none of the above passed, parse it as a base-10 integer.
    ///
    /// In all of these cases, `_` characters are completely ignored.
    ///
    /// # Purpose
    /// This method should be used for languages that need to support both float
    /// and integer literals. This method will not always be applicable (for example,
    /// some languages use `0` to represent octal instead of `0o`), but it should be
    /// acceptable for rust-like languages and for testing.
    ///
    /// # Examples
    /// ```rust
    /// # use alkale::SourceCodeScanner;
    /// # use alkale::span::Span;
    /// # use alkale::common::numeric::ParseNumberResult;
    /// let scanner = SourceCodeScanner::new(r#"123 150.2 3e-2 0xFF22"#);
    ///
    /// # unsafe {
    /// assert_eq!(
    ///     scanner.try_parse_number::<u32>(),
    ///     Some(Span::new(0, 3).wrap(ParseNumberResult::Integer(Ok(123u32))))
    /// );
    ///
    /// scanner.skip_whitespace();
    /// assert_eq!(
    ///     scanner.try_parse_number::<u32>(),
    ///     Some(Span::new(4, 5).wrap(ParseNumberResult::Float(Ok(150.2))))
    /// );
    ///
    /// scanner.skip_whitespace();
    /// assert_eq!(
    ///     scanner.try_parse_number::<u32>(),
    ///     Some(Span::new(10, 4).wrap(ParseNumberResult::Float(Ok(3e-2))))
    /// );
    ///
    /// scanner.skip_whitespace();
    /// assert_eq!(
    ///     scanner.try_parse_number::<u32>(),
    ///     Some(Span::new(15, 6).wrap(ParseNumberResult::Integer(Ok(0xFF22))))
    /// );
    ///
    /// scanner.skip_whitespace();
    /// assert_eq!(
    ///     scanner.try_parse_number::<u32>(),
    ///     None
    /// );
    /// # }
    /// ```
    ///
    /// # See Also
    /// If only integers are needed, use [`try_parse_integer`][Self::try_parse_integer].
    /// If only floats are needed, use [`try_parse_float`][Self::try_parse_float].
    #[inline]
    pub fn try_parse_number<
        R: Copy + Zero + CheckedAdd<Output = R> + CheckedMul<Output = R> + From<u8> + Unsigned,
    >(
        &self,
    ) -> Option<Spanned<ParseNumberResult<R>>> {
        let parsed_number = self.consume_standard_number()?;

        let span = parsed_number.span;
        let mut data = parsed_number.data;

        // Numbers with explicit base.
        if let Some(base) = chop_standard_base(&mut data) {
            let result = parse_integer_from_base(data, span, &base);

            return Some(ParseNumberResult::Integer(result.data).spanned(result.span));
        }

        // Floats.
        if check_float_suffix(&mut data) || data.contains(['.', '-', '+']) {
            return match str::parse::<f64>(&data.replace('_', "")) {
                Ok(value) => Some(ParseNumberResult::Float(Ok(value)).spanned(span)),
                Err(err) => Some(ParseNumberResult::Float(Err(err)).spanned(span)),
            };
        }

        // Base-10 integers.
        let result = parse_integer_from_base(data, span, &StandardBase::Decimal);

        Some(ParseNumberResult::Integer(result.data).spanned(result.span))
    }
}

#[cfg(test)]
mod tests {
    use crate::{
        common::numeric::{base::StandardBase, IntegerParseError, ParseNumberResult},
        span::{Span, Spannable, Spanned},
        SourceCodeScanner,
    };

    fn ctx(code: &str) -> SourceCodeScanner {
        SourceCodeScanner::new(code)
    }

    #[test]
    fn consume_standard_number() {
        let code = ctx("256 12 h 999");

        // SAFETY: Spans are all valid.
        unsafe {
            assert_eq!(
                code.consume_standard_number(),
                Some("256".spanned(Span::new(0, 3)))
            );

            code.skip();

            assert_eq!(
                code.consume_standard_number(),
                Some("12".spanned(Span::new(4, 2)))
            );

            code.skip();

            assert_eq!(code.consume_standard_number(), None);

            code.skip();
            code.skip();

            assert_eq!(
                code.consume_standard_number(),
                Some("999".spanned(Span::new(9, 3)))
            );

            assert!(!code.has_next());
        }
    }

    #[test]
    fn try_parse_integer_from_base() {
        let code = ctx("123 10102 % 0x6 300");

        // SAFETY: Spans are all valid.
        unsafe {
            assert_eq!(
                code.try_parse_integer_from_base(&StandardBase::Decimal),
                Some(Ok(123u32).spanned(Span::new(0, 3)))
            );

            code.skip();

            assert_eq!(
                code.try_parse_integer_from_base::<u8, _>(&StandardBase::Binary),
                Some(Err(IntegerParseError::InvalidCharacter('2')).spanned(Span::new(4, 5)))
            );

            code.skip();

            assert_eq!(
                code.try_parse_integer_from_base::<u32, _>(&StandardBase::Hexadecimal),
                None
            );

            code.skip();
            code.skip();

            assert_eq!(
                code.try_parse_integer_from_base::<u8, _>(&StandardBase::Binary),
                Some(Err(IntegerParseError::InvalidCharacter('x')).spanned(Span::new(12, 3)))
            );

            code.skip();

            assert_eq!(
                code.try_parse_integer_from_base::<u8, _>(&StandardBase::Decimal),
                Some(Err(IntegerParseError::OutOfRange).spanned(Span::new(16, 3)))
            );

            assert_eq!(
                code.try_parse_integer_from_base::<u8, _>(&StandardBase::Octal),
                None
            );

            assert!(!code.has_next());
        }
    }

    #[test]
    fn try_parse_integer() {
        let code = ctx("123 10102 h 0x6 300");

        // SAFETY: Spans are all valid.
        unsafe {
            assert_eq!(
                code.try_parse_integer(),
                Some(Ok(123u32).spanned(Span::new(0, 3)))
            );

            code.skip();

            assert_eq!(
                code.try_parse_integer(),
                Some(Ok(10102u32).spanned(Span::new(4, 5)))
            );

            code.skip();

            assert_eq!(code.try_parse_integer::<u32>(), None);

            code.skip();
            code.skip();

            assert_eq!(
                code.try_parse_integer::<u8>(),
                Some(Err(IntegerParseError::InvalidCharacter('x')).spanned(Span::new(12, 3)))
            );

            code.skip();

            assert_eq!(
                code.try_parse_integer::<u8>(),
                Some(Err(IntegerParseError::OutOfRange).spanned(Span::new(16, 3)))
            );

            assert_eq!(code.try_parse_integer::<u8>(), None);

            assert!(!code.has_next());
        }
    }

    #[test]
    fn try_parse_float() {
        let code = ctx("123 10.2 h 0x12C .34");

        // SAFETY: Spans are all valid.
        unsafe {
            assert_eq!(
                code.try_parse_float(),
                Some(Ok(123.0).spanned(Span::new(0, 3)))
            );

            code.skip();

            assert_eq!(
                code.try_parse_float(),
                Some(Ok(10.2).spanned(Span::new(4, 4)))
            );

            code.skip();

            assert_eq!(code.try_parse_float(), None);

            code.skip();
            code.skip();

            let Some(Spanned {
                span: _,
                data: Err(_),
            }) = code.try_parse_float()
            else {
                panic!("Expected parsed float to exist and return error.");
            };

            code.skip();

            assert_eq!(
                code.try_parse_float(),
                Some(Ok(0.34).spanned(Span::new(17, 3)))
            );

            assert_eq!(code.try_parse_float(), None);

            assert!(!code.has_next());
        }
    }

    #[test]
    fn try_parse_number() {
        let code = ctx("12 0x2F 1.25 9f 7E+2");

        // SAFETY: Spans are all valid.
        unsafe {
            assert_eq!(
                code.try_parse_number::<u32>(),
                Some(ParseNumberResult::Integer(Ok(12)).spanned(Span::new(0, 2)))
            );

            code.skip();

            assert_eq!(
                code.try_parse_number::<u32>(),
                Some(ParseNumberResult::Integer(Ok(0x2F)).spanned(Span::new(3, 4)))
            );

            code.skip();

            assert_eq!(
                code.try_parse_number::<u32>(),
                Some(ParseNumberResult::Float(Ok(1.25)).spanned(Span::new(8, 4)))
            );

            code.skip();

            assert_eq!(
                code.try_parse_number::<u32>(),
                Some(ParseNumberResult::Float(Ok(9.0)).spanned(Span::new(13, 2)))
            );

            code.skip();

            assert_eq!(
                code.try_parse_number::<u32>(),
                Some(ParseNumberResult::Float(Ok(7E+2)).spanned(Span::new(16, 4)))
            );

            assert_eq!(code.try_parse_number::<u32>(), None);

            assert!(!code.has_next());
        }
    }
}