endf_parser 0.2.0

//! Provide utilities for parsing ENDF-6 format reals.
//!
//! ENDF reals format is described in section `0.6.2` of ENDF-6 Formats Manual.
//!
//! ENDF-6 format available at [ENDF-6 Formats Manual](https://www.nndc.bnl.gov/csewg/docs/endf-manual.pdf).

use std::fmt;
use std::fmt::Formatter;

/// ENDF reals length, FORTRAN77 `E11.0` specification.
pub const ENDF_REAL_LENGTH: usize = 11;
/// ENDF real radix.
pub const ENDF_REAL_RADIX: u32 = 10;
/// ENDF real digits.
pub const ENDF_REAL_MAX_DIGITS: u32 = 11;
/// ENDF real regex.
pub const ENDF_REAL_REGEX: &str = r"^[ ]*[+\-]?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE]?[+\-]\d+)?[ ]*$";

/// Error returned when parsing ENDF real fails.
#[derive(Debug, Eq, PartialEq)]
pub enum ParseEndfRealError {
    /// Empty string.
    Empty,
    /// Empty exponent part.
    EmptyExponentPart,
    /// Empty fractional part.
    EmptyFractionalPart,
    /// Empty integer part.
    EmptyIntegerPart,
    /// Invalid.
    Invalid,
    /// Invalid decimal separator.
    InvalidDecimalSeparator { invalid: char },
    /// Invalid exponent separator.
    InvalidExponentSeparator { invalid: char },
    /// Invalid exponent sign.
    InvalidExponentSign { invalid: char },
    /// Invalid sign
    InvalidSign { invalid: char },
    /// Non ASCII string.
    NonASCII,
    /// Too long string.
    TooLong,
}

impl fmt::Display for ParseEndfRealError {
    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
        match self {
            ParseEndfRealError::Empty => write!(f, "empty string"),
            ParseEndfRealError::EmptyExponentPart => write!(f, "empty exponent part"),
            ParseEndfRealError::EmptyFractionalPart => write!(f, "empty fractional part"),
            ParseEndfRealError::EmptyIntegerPart => write!(f, "empty integer part"),
            ParseEndfRealError::Invalid => write!(f, "invalid"),
            ParseEndfRealError::InvalidDecimalSeparator { invalid: sep } => {
                write!(f, "invalid decimal separator: '{}'", sep)
            }
            ParseEndfRealError::InvalidExponentSeparator { invalid: sep } => {
                write!(f, "invalid exponent separator: '{}'", sep)
            }
            ParseEndfRealError::InvalidExponentSign { invalid: sign } => {
                write!(f, "invalid exponent sign: '{}'", sign)
            }
            ParseEndfRealError::InvalidSign { invalid: sign } => {
                write!(f, "invalid sign: '{}'", sign)
            }
            ParseEndfRealError::NonASCII => write!(f, "non ASCII string"),
            ParseEndfRealError::TooLong => write!(f, "too long string"),
        }
    }
}

/// Parse ENDF real.
///
/// # Format
/// ENDF reals can be read with FORTRAN77 `E11.0` format specification.
///
/// ENDF reals have following format:
///
/// | Format        | Value          | Max exponent  | Digits        | Comment                              |
/// |---------------|----------------|:-------------:|:-------------:|--------------------------------------|
/// | `±nnnnnnnnnn` | `±nnnnnnnnnn`  | N/A           | 10            | integer                              |
/// | `±n.nnnnnnnn` | `±n.nnnnnnnn`  | N/A           | 9             | decimal                              |
/// | `±n.nnnnnE±d` | `±n.nnnnnE±d`  | 9             | 6             | scientific, 1-digit exponent         |
/// | `±n.nnnnnn±d` | `±n.nnnnnnE±d` | 9             | 7             | scientific, E-less, 1-digit exponent |
/// | `±n.nnnnE±dd` | `±n.nnnnE±dd`  | 38            | 5             | scientific, 2-digits exponent        |
/// | `±n.nnnnn±dd` | `±n.nnnnnE±dd` | 38            | 6             | scientific, E-less, 2-digits exponent|
///
/// with:
/// - zero or more leading blanks followed by
/// - a leading sign `'-'` or `'+'` for negative or positive respectively (positive sign is optional)
/// - `n` a digit of the mantissa between `0` and `9`
/// - `.` the decimal separator
/// - `e|E` the optional exponent separator (E-less format)
/// - `d` a digit of the exponent between `0` and `9`
/// - full real length is less than or equal to `11`
///
/// # Preconditions
/// Following preconditions must hold or a `ParseEndfRealError` is returned:
/// - `real` is ASCII
/// - `real` is not empty
/// - `real` is not blank (combination of chars: `' ', '\t', '\n' and '\r'`)
/// - `real` length is less than or equal to `11`
/// - `real` respect the ENDF real format (see [Format](#format))
///
/// # Examples
/// ```
/// let x = endf_parser::primitive::real::parse(" 1234567890");
/// assert_eq!(1_234_567_890_f64, x.unwrap());
/// ```
/// ```
/// let x = endf_parser::primitive::real::parse("-1.23456789");
/// let expected = -1.234_567_89;
/// let diff = (expected - x.unwrap()).abs();
/// assert!(diff <= 1e-10);
/// ```
/// ```
/// let x = endf_parser::primitive::real::parse(" 1.23456e-1");
/// let expected = 1.23456e-1;
/// let diff = (expected - x.unwrap()).abs();
/// assert!(diff <= 1e-10);
/// ```
/// ```
/// let x = endf_parser::primitive::real::parse("+1.234567-1");
/// let expected = 1.234_567e-1;
/// let diff = (expected - x.unwrap()).abs();
/// assert!(diff <= 1e-10);
/// ```
/// ```
/// let x = endf_parser::primitive::real::parse("-1.2345e+12");
/// let expected = -1.2345e+12;
/// let diff = (expected - x.unwrap()).abs();
/// assert!(diff <= 1.);
/// ```
/// ```
/// let x = endf_parser::primitive::real::parse("+1.23456+12");
/// let expected = 1.23456e+12;
/// let diff = (expected - x.unwrap()).abs();
/// assert!(diff <= 1.);
/// ```
///
/// # Regex
/// The input real can be tested with the [ENDF_REAL_REGEX](constant.ENDF_REAL_REGEX.html) regex.
///
/// # Reference
/// ENDF real format is described in section `0.6.2` of [ENDF-6 Formats Manual](https://www.nndc.bnl.gov/csewg/docs/endf-manual.pdf)
pub fn parse(real: &str) -> Result<f64, ParseEndfRealError> {
    if !real.is_ascii() {
        return Err(ParseEndfRealError::NonASCII);
    }
    if real.len() > ENDF_REAL_LENGTH {
        return Err(ParseEndfRealError::TooLong);
    }
    // At this point, real is full ASCII and has a correct length.
    // ASCII => (iteration over chars <=> iteration over bytes)
    // (length <= 11) => mantissa won't overflow i64/u64
    let bytes = real.trim().as_bytes();
    // Extract sign
    let (neg, tail) = match bytes.first() {
        Some(&b'-') => (true, &bytes[1..]),
        Some(&b'+') => (false, &bytes[1..]),
        Some(x) if &b'0' <= x && x <= &b'9' => (false, bytes),
        Some(x) => {
            return Err(ParseEndfRealError::InvalidSign {
                invalid: *x as char,
            })
        }
        None => return Err(ParseEndfRealError::Empty),
    };
    // Extract integer part
    let (int_part, tail) = retrieve_digits(tail);
    if int_part.is_empty() {
        return Err(ParseEndfRealError::EmptyIntegerPart);
    }
    // Expect decimal separator
    let tail = match tail.first() {
        Some(&b'.') => &tail[1..],
        Some(x) => {
            return Err(ParseEndfRealError::InvalidDecimalSeparator {
                invalid: *x as char,
            })
        }
        None => return Ok(parse_integer(neg, int_part)),
    };
    // Extract fractional part
    let (frac_part, tail) = retrieve_digits(tail);
    if frac_part.is_empty() {
        return Err(ParseEndfRealError::EmptyFractionalPart);
    }
    // Expect exponent separator
    let tail = match tail.first() {
        Some(&b'e') | Some(&b'E') => &tail[1..],
        Some(&b'-') | Some(&b'+') => tail,
        Some(x) => {
            return Err(ParseEndfRealError::InvalidExponentSeparator {
                invalid: *x as char,
            })
        }
        None => return Ok(parse_decimal(neg, int_part, frac_part)),
    };
    // Extract exponent sign
    let (neg_exp, tail) = match tail.first() {
        Some(&b'-') => (true, &tail[1..]),
        Some(&b'+') => (false, &tail[1..]),
        Some(x) => {
            return Err(ParseEndfRealError::InvalidExponentSign {
                invalid: *x as char,
            })
        }
        None => return Err(ParseEndfRealError::EmptyExponentPart),
    };
    // Extract exponent part
    let (exp_part, tail) = retrieve_digits(tail);
    if exp_part.is_empty() {
        return Err(ParseEndfRealError::EmptyExponentPart);
    }
    // Expect empty tail
    if !tail.is_empty() {
        return Err(ParseEndfRealError::Invalid);
    }
    // Real is parsed successfully
    Ok(parse_scientific(
        neg, int_part, frac_part, neg_exp, exp_part,
    ))
}

fn retrieve_digits(bytes: &[u8]) -> (&[u8], &[u8]) {
    let mut i = 0;
    while i < bytes.len() && b'0' <= bytes[i] && bytes[i] <= b'9' {
        i += 1
    }
    (&bytes[..i], &bytes[i..])
}

fn parse_integer(neg: bool, int_part: &[u8]) -> f64 {
    let number = parse_integer_unchecked(int_part) as f64;
    apply_sign(neg, number)
}

fn parse_decimal(neg: bool, int_part: &[u8], frac_part: &[u8]) -> f64 {
    let mantissa = parse_integer_unchecked(int_part.iter().chain(frac_part.iter())) as f64;
    let exp = -(frac_part.len() as i32);
    let number = mantissa * 10_f64.powi(exp);
    apply_sign(neg, number)
}

fn parse_scientific(
    neg: bool,
    int_part: &[u8],
    frac_part: &[u8],
    neg_exp: bool,
    exp_part: &[u8],
) -> f64 {
    let mantissa = parse_integer_unchecked(int_part.iter().chain(frac_part.iter())) as f64;
    let mut exponent = parse_integer_unchecked(exp_part) as i32;
    exponent = apply_sign(neg_exp, exponent);
    exponent -= frac_part.len() as i32;
    let number = mantissa * 10_f64.powi(exponent);
    apply_sign(neg, number)
}

fn parse_integer_unchecked<'a, T>(bytes: T) -> u64
where
    T: IntoIterator<Item = &'a u8>,
{
    let mut result = 0;
    for &digit in bytes {
        result = result * 10 + (digit - b'0') as u64
    }
    result
}

fn apply_sign<T>(negative: bool, number: T) -> T
where
    T: std::ops::Neg<Output = T>,
{
    if negative {
        -number
    } else {
        number
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use regex::Regex;

    fn assert_endf_real_eq(expected: f64, actual: f64) {
        let mut exp = if expected.abs() <= 1. {
            0
        } else {
            expected.abs().log10().floor() as i32
        };
        exp -= ENDF_REAL_MAX_DIGITS as i32;
        let delta = 10_f64.powi(exp);
        let diff = (expected - actual).abs();
        if diff > delta {
            panic!(
                "assertion failed: (expected == actual)\n\
            expected = `{:?}\n\
            actual   = `{:?}\n\
            diff     = `{:?}`\n\
            delta    = `{:?}\n",
                expected, actual, diff, delta
            )
        }
    }

    #[test]
    fn parse_empty() {
        let real = "";
        let expected = ParseEndfRealError::Empty;
        let actual = parse(real).unwrap_err();
        assert_eq!(expected, actual);
    }

    #[test]
    fn parse_whitespace() {
        // Rust allows following whitespace:
        // - ' ' (space)
        // - '\n' (new line)
        // - '\t' (tab)
        // - '\r' (line feed)
        let expected = ParseEndfRealError::Empty;
        assert_eq!(expected, parse(" ").unwrap_err());
        assert_eq!(expected, parse("\n").unwrap_err());
        assert_eq!(expected, parse("\t").unwrap_err());
        assert_eq!(expected, parse("\r").unwrap_err());
        assert_eq!(expected, parse(" \n\t\r").unwrap_err());
    }

    #[test]
    fn parse_empty_exponent() {
        let expected = ParseEndfRealError::EmptyExponentPart;
        assert_eq!(expected, parse("1.2345e+").unwrap_err());
        assert_eq!(expected, parse("1.2345e-").unwrap_err());
        assert_eq!(expected, parse("1.2345+").unwrap_err());
        assert_eq!(expected, parse("1.2345-").unwrap_err());
    }

    #[test]
    fn parse_empty_fraction() {
        let expected = ParseEndfRealError::EmptyFractionalPart;
        assert_eq!(expected, parse(" 1.").unwrap_err());
        assert_eq!(expected, parse("+1.").unwrap_err());
        assert_eq!(expected, parse("-1.").unwrap_err());
    }

    #[test]
    fn parse_empty_integer() {
        let expected = ParseEndfRealError::EmptyIntegerPart;
        assert_eq!(expected, parse("-.1").unwrap_err());
        assert_eq!(expected, parse("+.1").unwrap_err());
    }

    #[test]
    fn parse_sign_only() {
        let real = "-";
        let expected = ParseEndfRealError::EmptyIntegerPart;
        assert_eq!(expected, parse(real).unwrap_err());
        let real = "+";
        let expected = ParseEndfRealError::EmptyIntegerPart;
        assert_eq!(expected, parse(real).unwrap_err());
    }

    #[test]
    fn parse_invalid() {
        let real = "1.2345e+6a";
        let expected = ParseEndfRealError::Invalid;
        assert_eq!(expected, parse(real).unwrap_err());
    }

    #[test]
    fn parse_invalid_decimal_separator() {
        let real = "-1,23456789";
        let expected = ParseEndfRealError::InvalidDecimalSeparator { invalid: ',' };
        assert_eq!(expected, parse(real).unwrap_err());
        let real = "-1|23456789";
        let expected = ParseEndfRealError::InvalidDecimalSeparator { invalid: '|' };
        assert_eq!(expected, parse(real).unwrap_err());
    }

    #[test]
    fn parse_invalid_exponent_separator() {
        let real = "-1.2345d+12";
        let expected = ParseEndfRealError::InvalidExponentSeparator { invalid: 'd' };
        assert_eq!(expected, parse(real).unwrap_err());
        let real = "-1.2345f+12";
        let expected = ParseEndfRealError::InvalidExponentSeparator { invalid: 'f' };
        assert_eq!(expected, parse(real).unwrap_err());
        let real = "-1.2345^+12";
        let expected = ParseEndfRealError::InvalidExponentSeparator { invalid: '^' };
        assert_eq!(expected, parse(real).unwrap_err());
    }

    #[test]
    fn parse_invalid_sign() {
        let real = "a1.23456789";
        let expected = ParseEndfRealError::InvalidSign { invalid: 'a' };
        assert_eq!(expected, parse(real).unwrap_err());
        let real = "1.234567ea1";
        let expected = ParseEndfRealError::InvalidExponentSign { invalid: 'a' };
        assert_eq!(expected, parse(real).unwrap_err())
    }

    #[test]
    fn parse_non_ascii() {
        let real = "µ";
        let expected = ParseEndfRealError::NonASCII;
        assert_eq!(expected, parse(real).unwrap_err());
    }

    #[test]
    fn parse_invalid_length() {
        let real = "+1.234567+12";
        let expected = ParseEndfRealError::TooLong;
        assert_eq!(expected, parse(real).unwrap_err());
        let real = "+1.23456e+12";
        let expected = ParseEndfRealError::TooLong;
        assert_eq!(expected, parse(real).unwrap_err());
        let real = " 12345.67890";
        let expected = ParseEndfRealError::TooLong;
        assert_eq!(expected, parse(real).unwrap_err());
        let real = "+12345.67890";
        let expected = ParseEndfRealError::TooLong;
        assert_eq!(expected, parse(real).unwrap_err());
        let real = "-12345.67890";
        let expected = ParseEndfRealError::TooLong;
        assert_eq!(expected, parse(real).unwrap_err());
    }

    #[test]
    fn parse_valid_integer() {
        assert_endf_real_eq(1_234_567_890_f64, parse(" 1234567890").unwrap());
        assert_endf_real_eq(1_234_567_890_f64, parse("+1234567890").unwrap());
        assert_endf_real_eq(-1_234_567_890_f64, parse("-1234567890").unwrap());
    }

    #[test]
    fn parse_valid_real_max_precision() {
        assert_endf_real_eq(0., parse(" 0.00000000").unwrap());
        assert_endf_real_eq(0., parse("+0.00000000").unwrap());
        assert_endf_real_eq(0., parse("-0.00000000").unwrap());
        assert_endf_real_eq(1.234_567_89, parse(" 1.23456789").unwrap());
        assert_endf_real_eq(1.234_567_89, parse("+1.23456789").unwrap());
        assert_endf_real_eq(-1.234_567_89, parse("-1.23456789").unwrap());
    }

    #[test]
    fn parse_valid_real_eless_mid_precision() {
        assert_endf_real_eq(1.234_567e+1, parse(" 1.234567+1").unwrap());
        assert_endf_real_eq(1.234_567e+1, parse("+1.234567+1").unwrap());
        assert_endf_real_eq(-1.234_567e+1, parse("-1.234567+1").unwrap());
        assert_endf_real_eq(1.234_567e-1, parse(" 1.234567-1").unwrap());
        assert_endf_real_eq(1.234_567e-1, parse("+1.234567-1").unwrap());
        assert_endf_real_eq(-1.234_567e-1, parse("-1.234567-1").unwrap());
    }

    #[test]
    fn parse_valid_real_eless_min_precision() {
        assert_endf_real_eq(1.23456e+12, parse(" 1.23456+12").unwrap());
        assert_endf_real_eq(1.23456e+12, parse("+1.23456+12").unwrap());
        assert_endf_real_eq(-1.23456e+12, parse("-1.23456+12").unwrap());
        assert_endf_real_eq(1.23456e-12, parse(" 1.23456-12").unwrap());
        assert_endf_real_eq(1.23456e-12, parse("+1.23456-12").unwrap());
        assert_endf_real_eq(-1.23456e-12, parse("-1.23456-12").unwrap());
    }

    #[test]
    fn parse_valid_real_scientific_mid_precision() {
        assert_endf_real_eq(1.23456e+1, parse(" 1.23456e+1").unwrap());
        assert_endf_real_eq(1.23456e+1, parse("+1.23456e+1").unwrap());
        assert_endf_real_eq(-1.23456e+1, parse("-1.23456e+1").unwrap());
        assert_endf_real_eq(1.23456e+1, parse(" 1.23456E+1").unwrap());
        assert_endf_real_eq(1.23456e+1, parse("+1.23456E+1").unwrap());
        assert_endf_real_eq(-1.23456e+1, parse("-1.23456E+1").unwrap());
        assert_endf_real_eq(1.23456e-1, parse(" 1.23456e-1").unwrap());
        assert_endf_real_eq(1.23456e-1, parse("+1.23456e-1").unwrap());
        assert_endf_real_eq(-1.23456e-1, parse("-1.23456e-1").unwrap());
        assert_endf_real_eq(1.23456e-1, parse(" 1.23456E-1").unwrap());
        assert_endf_real_eq(1.23456e-1, parse("+1.23456E-1").unwrap());
        assert_endf_real_eq(-1.23456e-1, parse("-1.23456E-1").unwrap());
    }

    #[test]
    fn parse_valid_real_scientific_min_precision() {
        assert_endf_real_eq(1.2345e+12, parse(" 1.2345e+12").unwrap());
        assert_endf_real_eq(1.2345e+12, parse("+1.2345e+12").unwrap());
        assert_endf_real_eq(-1.2345e+12, parse("-1.2345e+12").unwrap());
        assert_endf_real_eq(1.2345e+12, parse(" 1.2345E+12").unwrap());
        assert_endf_real_eq(1.2345e+12, parse("+1.2345E+12").unwrap());
        assert_endf_real_eq(-1.2345e+12, parse("-1.2345E+12").unwrap());
        assert_endf_real_eq(1.2345e-12, parse(" 1.2345e-12").unwrap());
        assert_endf_real_eq(1.2345e-12, parse("+1.2345e-12").unwrap());
        assert_endf_real_eq(-1.2345e-12, parse("-1.2345e-12").unwrap());
        assert_endf_real_eq(1.2345e-12, parse(" 1.2345E-12").unwrap());
        assert_endf_real_eq(1.2345e-12, parse("+1.2345E-12").unwrap());
        assert_endf_real_eq(-1.2345e-12, parse("-1.2345E-12").unwrap());
    }

    #[test]
    fn regex_integer() {
        let regex = Regex::new(ENDF_REAL_REGEX).unwrap();
        assert!(regex.is_match("1"));
        assert!(regex.is_match("+1"));
        assert!(regex.is_match("-1"));
        assert!(regex.is_match(" 1234567890"));
        assert!(regex.is_match("-1234567890"));
        assert!(regex.is_match("+1234567890"));
        assert!(regex.is_match("          1"));
        assert!(regex.is_match("     1     "));
        assert!(regex.is_match("1          "));
        assert!(regex.is_match("         +1"));
        assert!(regex.is_match("    +1     "));
        assert!(regex.is_match("+1         "));
        assert!(regex.is_match("         -1"));
        assert!(regex.is_match("    -1     "));
        assert!(regex.is_match("-1         "));
    }

    #[test]
    fn regex_decimal() {
        let regex = Regex::new(ENDF_REAL_REGEX).unwrap();
        assert!(regex.is_match("-1.23456789"));
        assert!(regex.is_match("+1.23456789"));
        assert!(regex.is_match(" 1.23456789"));
    }

    #[test]
    fn regex_scientific() {
        let regex = Regex::new(ENDF_REAL_REGEX).unwrap();
        assert!(regex.is_match(" +1.2345e+1"));
        assert!(regex.is_match(" +1.2345E+1"));
        assert!(regex.is_match(" -1.2345e+1"));
        assert!(regex.is_match("  1.2345e+1"));
        assert!(regex.is_match(" +1.2345e-1"));
        assert!(regex.is_match(" -1.2345e-1"));
        assert!(regex.is_match("  1.2345e-1"));
        assert!(regex.is_match("  1.2345-1 "));
        assert!(regex.is_match(" -1.2345-1 "));
        assert!(regex.is_match(" +1.2345-1 "));
        assert!(regex.is_match(" +1.2345-12"));
        assert!(regex.is_match(" -1.2345-12"));
        assert!(regex.is_match("  1.2345-12"));
    }

    #[test]
    fn regex_invalid() {
        let regex = Regex::new(ENDF_REAL_REGEX).unwrap();
        assert!(!regex.is_match(""));
        assert!(!regex.is_match(" "));
        assert!(!regex.is_match("."));
        assert!(!regex.is_match("e"));
        assert!(!regex.is_match("E"));
        assert!(!regex.is_match("0."));
        assert!(!regex.is_match("1."));
        assert!(!regex.is_match("-1."));
        assert!(!regex.is_match("+1."));
        assert!(!regex.is_match("1e1"));
        assert!(!regex.is_match("1e"));
    }
}