calc_rational

lib.rs (53584B)

---

 //! [![git]](https://git.philomathiclife.com/calc_rational/log.html) [![crates-io]](https://crates.io/crates/calc_rational) [![docs-rs]](crate)
 //!
 //! [git]: https://git.philomathiclife.com/git_badge.svg
 //! [crates-io]: https://img.shields.io/badge/crates.io-fc8d62?style=for-the-badge&labelColor=555555&logo=rust
 //! [docs-rs]: https://img.shields.io/badge/docs.rs-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs
 //!
 //! `calc_lib` is a library for performing basic rational number arithmetic using standard operator precedence
 //! and associativity. Internally, it is based on
 //! [`Ratio<T>`] and [`BigInt`].
 //!   
 //! ## Expressions  
 //!   
 //! The following are the list of expressions in descending order of precedence:  
 //!   1. number literals, `@`, `()`, `||`, `round()`, `rand()`  
 //!   2. `!`  
 //!   3. `^`  
 //!   4. `-` (unary negation operator)  
 //!   5. `*`, `/`, `mod`  
 //!   6. `+`, `-`  
 //!   
 //! All binary operators are left-associative sans `^` which is right-associative.  
 //!   
 //! Any expression is allowed to be enclosed in `()`. Note that parentheses are purely for grouping expressions;
 //! in particular, you cannot use them to represent multiplication (e.g., `4(2)` is grammatically incorrect and
 //! will result in an error message).  
 //!   
 //! Any expression is allowed to be enclosed in `||`. This unary operator represents absolute value.  
 //!   
 //! `!` is the factorial operator. Due to its high precedence, something like *-i!^j!* for *i, j ∈ ℕ* is
 //! the same thing as *-((i!)^(j!))*. If the expression preceding it does not evaluate to a non-negative integer,
 //! then an error will be displayed. Spaces  and tabs are *not* ignored; so `1 !` is grammatically incorrect and
 //! will result in an error message.  
 //!   
 //! `^` is the exponentiation operator. The expression left of the operator can evaluate to any rational number;
 //! however the expression right of the operator must evaluate to an integer or ±1/2 unless the expression on
 //! the left evaluates to `0` or `1`. In the event of the former, the expression right of the operator must evaluate
 //! to a non-negative rational number. In the event of the latter, the expression right of the operator can evaluate to
 //! any rational number. Note that `0^0` is defined to be 1. When the operand right of `^` evaluates to ±1/2, then
 //! the left operand must be the square of a rational number.  
 //!   
 //! The unary operator `-` represents negation.  
 //!   
 //! The operators `*` and `/` represent multiplication and division respectively. Expressions right of `/`
 //! must evaluate to any non-zero rational number; otherwise an error will be displayed.  
 //!   
 //! The binary operator `mod` represents modulo such that *n mod m = r = n - m\*q* for *n,q ∈ ℤ, m ∈ ℤ\\{0}, and r ∈ ℕ*
 //! where *r* is the minimum non-negative solution.  
 //!   
 //! The binary operators `+` and `-` represent addition and subtraction respectively.  
 //!   
 //! With the aforementioned exception of `!`, all spaces and tabs before and after operators are ignored.  
 //!   
 //! ## Round expression  
 //!   
 //! `round(expression, digit)` rounds `expression` to `digit`-number of fractional digits. An error will
 //! be displayed if called incorrectly.  
 //!   
 //! ## Rand expression  
 //!   
 //! `rand(expression, expression)` generates a random 64-bit integer inclusively between the passed expressions.
 //! An error will be displayed if called incorrectly. `rand()` generates a random 64-bit integer.  
 //!   
 //! ## Numbers  
 //!   
 //! A number literal is a non-empty sequence of digits or a non-empty sequence of digits immediately followed by `.`
 //! which is immediately followed by a non-empty sequence of digits (e.g., `134.901`). This means that number
 //! literals represent precisely all rational numbers that are equivalent to a ratio of a non-negative integer
 //! to a positive integer whose sole prime factors are 2 or 5. To represent all other rational numbers, the unary
 //! operator `-` and binary operator `/` must be used.  
 //!   
 //! ## Empty expression  
 //!   
 //! The empty expression (i.e., expression that at most only consists of spaces and tabs) will return
 //! the result from the previous non-(empty/store) expression in *decimal* form using the minimum number of digits.
 //! In the event an infinite number of digits is required, it will be rounded to 9 fractional digits using normal rounding
 //! rules first.  
 //!   
 //! ## Store expression  
 //!   
 //! To store the result of the previous non-(empty/store) expression, one simply passes `s`. In addition to storing the
 //! result which will subsequently be available via `@`, it displays the result. At most 8 results can be stored at once;
 //! at which point, results that are stored overwrite the oldest result.  
 //!   
 //! ## Recall expression  
 //!   
 //! `@` is used to recall previously stored results. It can be followed by any *digit* from `1` to `8`.
 //! If such a digit does not immediately follow it, then it will be interpreted as if there were a `1`.
 //! `@i` returns the *i*-th most-previous stored result where *i ∈ {1, 2, 3, 4, 5, 6, 7, 8}*.
 //! Note that spaces and tabs are *not* ignored so `@ 2` is grammatically incorrect and will result in an error message.
 //! As emphasized, it does not work on expressions; so both `@@` and `@(1)` are grammatically incorrect.  
 //!   
 //! ## Character encoding  
 //!   
 //! All inputs must only contain the ASCII encoding of the following Unicode scalar values: `0`-`9`, `.`, `+`, `-`,
 //! `*`, `/`, `^`, `!`, `mod`, `|`, `(`, `)`, `round`, `rand`, `,`, `@`, `s`, &lt;space&gt;, &lt;tab&gt;,
 //! &lt;line feed&gt;, &lt;carriage return&gt;, and `q`. Any other byte sequences are grammatically incorrect and will
 //! lead to an error message.  
 //!   
 //! ## Errors  
 //!   
 //! Errors due to a language violation (e.g., dividing by `0`) manifest into an error message. `panic!`s
 //! and [`io::Error`](https://doc.rust-lang.org/std/io/struct.Error.html)s caused by writing to the global
 //! standard output stream lead to program abortion.  
 //!   
 //! ## Exiting  
 //!   
 //! `q` with any number of spaces and tabs before and after will cause the program to terminate.  
 //!   
 //! ### Formal language specification  
 //!   
 //! For a more precise specification of the “calc language”, one can read the
 //! [calc language specification](https://git.philomathiclife.com/calc_rational/lang.pdf).
 #![expect(
     clippy::doc_paragraphs_missing_punctuation,
     reason = "false positive for crate documentation having image links"
 )]
 #![expect(
     clippy::arithmetic_side_effects,
     reason = "calculator can't realistically avoid this"
 )]
 #![no_std]
 #![cfg_attr(docsrs, feature(doc_cfg))]
 extern crate alloc;
 /// Unit tests.
 #[cfg(test)]
 mod tests;
 use LangErr::{
     DivByZero, ExpDivByZero, ExpIsNotIntOrOneHalf, InvalidAbs, InvalidDec, InvalidPar, InvalidQuit,
     InvalidRound, InvalidStore, MissingTerm, ModIsNotInt, ModZero, NotEnoughPrevResults,
     NotNonNegIntFact, SqrtDoesNotExist, TrailingSyms,
 };
 use O::{Empty, Eval, Exit, Store};
 use alloc::{
     string::{String, ToString as _},
     vec,
     vec::Vec,
 };
 use cache::Cache;
 #[cfg(not(feature = "rand"))]
 use core::marker::PhantomData;
 use core::{
     convert,
     fmt::{self, Display, Formatter},
     ops::Index as _,
 };
 pub use num_bigint;
 use num_bigint::{BigInt, BigUint, Sign};
 use num_integer::Integer as _;
 pub use num_rational;
 use num_rational::Ratio;
 #[cfg(feature = "rand")]
 use num_traits::ToPrimitive as _;
 use num_traits::{Inv as _, Pow as _};
 #[cfg(target_os = "openbsd")]
 use priv_sep as _;
 #[cfg(feature = "rand")]
 pub use rand;
 #[cfg(feature = "rand")]
 use rand::{Rng as _, rngs::ThreadRng};
 /// Fixed-sized cache that automatically overwrites the oldest data
 /// when a new item is added and the cache is full.
 ///
 /// One can think of
 /// [`Cache`] as a very limited but more performant [`VecDeque`][alloc::collections::VecDeque] that only
 /// adds new data or reads old data.
 pub mod cache;
 /// Generalizes [`Iterator`] by using
 /// generic associated types.
 pub mod lending_iterator;
 /// Error due to a language violation.
 #[non_exhaustive]
 #[cfg_attr(test, derive(Eq, PartialEq))]
 #[derive(Debug)]
 pub enum LangErr {
     /// The input began with a `q` but had non-whitespace
     /// that followed it.
     InvalidQuit,
     /// The input began with an `s` but had non-whitespace
     /// that followed it.
     InvalidStore,
     /// A sub-expression in the input would have led
     /// to a division by zero.
     DivByZero(usize),
     /// A sub-expression in the input would have led
     /// to a rational number that was not 0 or 1 to be
     /// raised to a non-integer power that is not (+/-) 1/2.
     ExpIsNotIntOrOneHalf(usize),
     /// A sub-expression in the input would have led
     /// to 0 being raised to a negative power which itself
     /// would have led to a division by zero.
     ExpDivByZero(usize),
     /// A sub-expression in the input would have led
     /// to a number modulo 0.
     ModZero(usize),
     /// A sub-expression in the input would have led
     /// to the mod of two expressions with at least one
     /// not being an integer.
     ModIsNotInt(usize),
     /// A sub-expression in the input would have led
     /// to a non-integer factorial or a negative integer factorial.
     NotNonNegIntFact(usize),
     /// The input contained a non-empty sequence of digits followed
     /// by `.` which was not followed by a non-empty sequence of digits.
     InvalidDec(usize),
     /// A recall expression was used to recall the *i*-th most-recent stored result,
     /// but there are fewer than *i* stored where
     /// *i ∈ {1, 2, 3, 4, 5, 6, 7, 8}*.
     NotEnoughPrevResults(usize),
     /// The input did not contain a closing `|`.
     InvalidAbs(usize),
     /// The input did not contain a closing `)`.
     InvalidPar(usize),
     /// The input contained an invalid round expression.
     InvalidRound(usize),
     /// A sub-expression in the input had a missing terminal expression
     /// where a terminal expression is a decimal literal expression,
     /// recall expression, absolute value expression, parenthetical
     /// expression, or round expression.
     MissingTerm(usize),
     /// The expression that was passed to the square root does not have a solution
     /// in the field of rational numbers.
     SqrtDoesNotExist(usize),
     /// The input started with a valid expression but was immediately followed
     /// by symbols that could not be chained with the preceding expression.
     TrailingSyms(usize),
     /// The input contained an invalid random expression.
     #[cfg(feature = "rand")]
     InvalidRand(usize),
     /// Error when the second argument is less than first in the rand function.
     #[cfg(feature = "rand")]
     RandInvalidArgs(usize),
     /// Error when there are no 64-bit integers in the interval passed to the random function.
     #[cfg(feature = "rand")]
     RandNoInts(usize),
 }
 impl Display for LangErr {
     #[inline]
     fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
         match *self {
             InvalidStore => f.write_str("Invalid store expression. A store expression must be of the extended regex form: ^[ \\t]*s[ \\t]*$."),
             InvalidQuit => f.write_str("Invalid quit expression. A quit expression must be of the extended regex form: ^[ \\t]*q[ \\t]*$."),
             DivByZero(u) => write!(f, "Division by zero ending at position {u}."),
             ExpIsNotIntOrOneHalf(u) => write!(f, "Non-integer exponent that is not (+/-) 1/2 with a base that was not 0 or 1 ending at position {u}."),
             ExpDivByZero(u) => write!(f, "Non-negative exponent with a base of 0 ending at position {u}."),
             ModZero(u) => write!(f, "A number modulo 0 ending at position {u}."),
             ModIsNotInt(u) => write!(f, "The modulo expression was applied to at least one non-integer ending at position {u}."),
             NotNonNegIntFact(u) => write!(f, "Factorial of a rational number that was not a non-negative integer ending at position {u}."),
             InvalidDec(u) => write!(f, "Invalid decimal literal expression ending at position {u}. A decimal literal expression must be of the extended regex form: [0-9]+(\\.[0-9]+)?."),
             NotEnoughPrevResults(len) => write!(f, "There are only {len} previous results."),
             InvalidAbs(u) => write!(f, "Invalid absolute value expression ending at position {u}. An absolute value expression is an addition expression enclosed in '||'."),
             InvalidPar(u) => write!(f, "Invalid parenthetical expression ending at position {u}. A parenthetical expression is an addition expression enclosed in '()'."),
             InvalidRound(u) => write!(f, "Invalid round expression ending at position {u}. A round expression is of the form 'round(<mod expression>, digit)'"),
             SqrtDoesNotExist(u) => write!(f, "The square root of the passed expression does not have a solution in the field of rational numbers ending at position {u}."),
             #[cfg(not(feature = "rand"))]
             MissingTerm(u) => write!(f, "Missing terminal expression at position {u}. A terminal expression is a decimal literal expression, recall expression, absolute value expression, parenthetical expression, or round expression."),
             #[cfg(feature = "rand")]
             MissingTerm(u) => write!(f, "Missing terminal expression at position {u}. A terminal expression is a decimal literal expression, recall expression, absolute value expression, parenthetical expression, round expression, or rand expression."),
             TrailingSyms(u) => write!(f, "Trailing symbols starting at position {u}."),
             #[cfg(feature = "rand")]
             Self::InvalidRand(u) => write!(f, "Invalid rand expression ending at position {u}. A rand expression is of the form 'rand()' or 'rand(<mod expression>, <mod expression>)'."),
             #[cfg(feature = "rand")]
             Self::RandInvalidArgs(u) => write!(f, "The second expression passed to the random function evaluated to rational number less than the first ending at position {u}."),
             #[cfg(feature = "rand")]
             Self::RandNoInts(u) => write!(f, "There are no 64-bit integers within the interval passed to the random function ending at position {u}."),
         }
     }
 }
 /// A successful evaluation of an input.
 #[cfg_attr(test, derive(Eq, PartialEq))]
 #[derive(Debug)]
 pub enum O<'a> {
     /// The input only contained whitespace.
     /// This returns the previous `Eval`.
     /// It is `None` iff there have been no
     /// previous `Eval` results.
     Empty(&'a Option<Ratio<BigInt>>),
     /// The quit expression was issued to terminate the program.
     Exit,
     /// Result of a "normal" expression.
     Eval(&'a Ratio<BigInt>),
     /// The store expression stores and returns the previous `Eval`.
     /// It is `None` iff there have been no previous `Eval` results.
     Store(&'a Option<Ratio<BigInt>>),
 }
 impl Display for O<'_> {
     #[expect(
         unsafe_code,
         reason = "manually construct guaranteed UTF-8; thus avoid the needless check"
     )]
     #[expect(clippy::indexing_slicing, reason = "comment justifies correctness")]
     #[inline]
     fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
         match *self {
             Empty(o) => {
                 o.as_ref().map_or(Ok(()), |val| {
                     if val.is_integer() {
                         write!(f, "> {val}")
                     } else {
                         // If the prime factors of the denominator are only 2 and 5,
                         // then the number requires a finite number of digits and thus
                         // will be represented perfectly using the fewest number of digits.
                         // Any other situation will be rounded to 9 fractional digits.
                         // max{twos, fives} represents the minimum number of fractional
                         // digits necessary to represent val.
                         let mut twos = 0;
                         let mut fives = 0;
                         let zero = BigInt::from_biguint(Sign::NoSign, BigUint::new(Vec::new()));
                         let one = BigInt::from_biguint(Sign::Plus, BigUint::new(vec![1]));
                         let two = BigInt::from_biguint(Sign::Plus, BigUint::new(vec![2]));
                         let five = BigInt::from_biguint(Sign::Plus, BigUint::new(vec![5]));
                         let mut denom = val.denom().clone();
                         let mut div_rem;
                         while denom > one {
                             div_rem = denom.div_rem(&two);
                             if div_rem.1 == zero {
                                 twos += 1;
                                 denom = div_rem.0;
                             } else {
                                 break;
                             }
                         }
                         while denom > one {
                             div_rem = denom.div_rem(&five);
                             if div_rem.1 == zero {
                                 fives += 1;
                                 denom = div_rem.0;
                             } else {
                                 break;
                             }
                         }
                         // int < 0 iff val <= -1. frac < 0 iff val is a negative non-integer.
                         let (int, frac, digits) = if denom == one {
                             let (int, mut frac) = val.numer().div_rem(val.denom());
                             while twos > fives {
                                 frac *= &five;
                                 fives += 1;
                             }
                             while fives > twos {
                                 frac *= &two;
                                 twos += 1;
                             }
                             (int, frac, twos)
                         } else {
                             // Requires an infinite number of decimal digits to represent, so we display
                             // 9 digits after rounding.
                             let mult =
                                 BigInt::from_biguint(Sign::Plus, BigUint::new(vec![10])).pow(9u8);
                             let (int, frac) = (val * &mult).round().numer().div_rem(&mult);
                             (int, frac, 9)
                         };
                         let int_str = int.to_string().into_bytes();
                         let (mut v, frac_str) = if val.numer().sign() == Sign::Minus {
                             // Guaranteed to be non-empty.
                             if int_str[0] == b'-' {
                                 (
                                     Vec::with_capacity(int_str.len() + 1 + digits),
                                     (-frac).to_string().into_bytes(),
                                 )
                             } else {
                                 let mut tmp = Vec::with_capacity(int_str.len() + 2 + digits);
                                 tmp.push(b'-');
                                 (tmp, (-frac).to_string().into_bytes())
                             }
                         } else {
                             (
                                 Vec::with_capacity(int_str.len() + 1 + digits),
                                 frac.to_string().into_bytes(),
                             )
                         };
                         v.extend_from_slice(int_str.as_slice());
                         v.push(b'.');
                         // digits >= frac_str.len().
                         v.resize(v.len() + (digits - frac_str.len()), b'0');
                         v.extend_from_slice(frac_str.as_slice());
                         // SAFETY:
                         // v contains precisely the UTF-8 code units returned from Strings
                         // returned from the to_string function on the integer and fraction part of
                         // val plus optionally the single byte encodings of ".", "-", and "0".
                         write!(f, "> {}", unsafe { String::from_utf8_unchecked(v) })
                     }
                 })
             }
             Eval(r) => write!(f, "> {r}"),
             Exit => Ok(()),
             Store(o) => o.as_ref().map_or(Ok(()), |val| write!(f, "> {val}")),
         }
     }
 }
 /// Size of [`Evaluator::cache`].
 const CACHE_SIZE: usize = 8;
 /// Evaluates the supplied input.
 #[derive(Debug)]
 pub struct Evaluator<'input, 'cache, 'prev, 'scratch, 'rand> {
     /// The input to be evaluated.
     utf8: &'input [u8],
     /// The index within `utf8` that evaluation needs to continue.
     /// We use this instead of slicing from `utf8` since we want
     /// to be able to report the position within the input
     /// that an error occurs.
     i: usize,
     /// The cache of previously stored results.
     cache: &'cache mut Cache<Ratio<BigInt>, CACHE_SIZE>,
     /// The last result.
     prev: &'prev mut Option<Ratio<BigInt>>,
     /// Buffer used to evaluate right-associative sub-expressions.
     scratch: &'scratch mut Vec<Ratio<BigInt>>,
     /// Random number generator.
     #[cfg(feature = "rand")]
     rng: &'rand mut ThreadRng,
     /// Need to use `'rand`.
     #[cfg(not(feature = "rand"))]
     _rng: PhantomData<fn() -> &'rand ()>,
 }
 #[allow(
     single_use_lifetimes,
     clippy::allow_attributes,
     clippy::elidable_lifetime_names,
     reason = "unify rand and not rand"
 )]
 impl<'input, 'cache, 'prev, 'scratch, 'rand> Evaluator<'input, 'cache, 'prev, 'scratch, 'rand> {
     /// Creates an `Evaluator<'input, 'cache, 'prev, 'scratch, 'rand>` based on the supplied arguments.
     #[cfg(not(feature = "rand"))]
     #[inline]
     pub fn new(
         utf8: &'input [u8],
         cache: &'cache mut Cache<Ratio<BigInt>, 8>,
         prev: &'prev mut Option<Ratio<BigInt>>,
         scratch: &'scratch mut Vec<Ratio<BigInt>>,
     ) -> Self {
         Self {
             utf8,
             i: 0,
             cache,
             prev,
             scratch,
             _rng: PhantomData,
         }
     }
     /// Creates an `Evaluator<'input, 'cache, 'prev, 'scratch, 'rand>` based on the supplied arguments.
     #[cfg(feature = "rand")]
     #[inline]
     pub const fn new(
         utf8: &'input [u8],
         cache: &'cache mut Cache<Ratio<BigInt>, 8>,
         prev: &'prev mut Option<Ratio<BigInt>>,
         scratch: &'scratch mut Vec<Ratio<BigInt>>,
         rng: &'rand mut ThreadRng,
     ) -> Self {
         Self {
             utf8,
             i: 0,
             cache,
             prev,
             scratch,
             rng,
         }
     }
     /// Evaluates the input consuming the `Evaluator<'input, 'cache, 'exp>`.
     ///
     /// Requires the input to contain one expression (i.e., if there are
     /// multiple newlines, it will error).
     ///
     /// # Errors
     ///
     /// Returns a [`LangErr`] iff the input violates the calc language.
     #[expect(clippy::indexing_slicing, reason = "correct")]
     #[inline]
     pub fn evaluate(mut self) -> Result<O<'prev>, LangErr> {
         self.utf8 = if self.utf8.last().is_none_or(|b| *b != b'\n') {
             self.utf8
         } else {
             &self.utf8[..self.utf8.len()
                 - self
                     .utf8
                     .get(self.utf8.len().wrapping_sub(2))
                     .map_or(1, |b| if *b == b'\r' { 2 } else { 1 })]
         };
         self.consume_ws();
         let Some(b) = self.utf8.get(self.i) else {
             return Ok(Empty(self.prev));
         };
         if *b == b'q' {
             self.i += 1;
             self.consume_ws();
             if self.i == self.utf8.len() {
                 Ok(Exit)
             } else {
                 Err(InvalidQuit)
             }
         } else if *b == b's' {
             self.i += 1;
             self.consume_ws();
             if self.i == self.utf8.len() {
                 if let Some(ref val) = *self.prev {
                     self.cache.push(val.clone());
                 }
                 Ok(Store(self.prev))
             } else {
                 Err(InvalidStore)
             }
         } else {
             self.get_adds().and_then(move |val| {
                 self.consume_ws();
                 if self.i == self.utf8.len() {
                     Ok(Eval(self.prev.insert(val)))
                 } else {
                     Err(TrailingSyms(self.i))
                 }
             })
         }
     }
     /// Reads from the input until the next non-{space/tab} byte value.
     #[expect(clippy::indexing_slicing, reason = "correct")]
     fn consume_ws(&mut self) {
         // ControlFlow makes more sense to use in try_fold; however due to a lack
         // of a map_or_else function, it is easier to simply return a Result with
         // Err taking the role of ControlFlow::Break.
         self.i += self.utf8[self.i..]
             .iter()
             .try_fold(0, |val, b| match *b {
                 b' ' | b'\t' => Ok(val + 1),
                 _ => Err(val),
             })
             .unwrap_or_else(convert::identity);
     }
     /// Evaluates addition expressions as defined in the calc language.
     /// This function is used for both addition and subtraction operations which
     /// themselves are based on multiplication expressions.
     fn get_adds(&mut self) -> Result<Ratio<BigInt>, LangErr> {
         let mut left = self.get_mults()?;
         let mut j;
         self.consume_ws();
         while let Some(i) = self.utf8.get(self.i) {
             j = *i;
             self.consume_ws();
             if j == b'+' {
                 self.i += 1;
                 self.consume_ws();
                 left += self.get_mults()?;
             } else if j == b'-' {
                 self.i += 1;
                 self.consume_ws();
                 left -= self.get_mults()?;
             } else {
                 break;
             }
         }
         Ok(left)
     }
     /// Evaluates multiplication expressions as defined in the calc language.
     /// This function is used for both multiplication and division operations which
     /// themselves are based on negation expressions.
     fn get_mults(&mut self) -> Result<Ratio<BigInt>, LangErr> {
         let mut left = self.get_neg()?;
         let mut right;
         let mut j;
         let mut mod_val;
         let mut numer;
         self.consume_ws();
         while let Some(i) = self.utf8.get(self.i) {
             j = *i;
             self.consume_ws();
             if j == b'*' {
                 self.i += 1;
                 self.consume_ws();
                 left *= self.get_neg()?;
             } else if j == b'/' {
                 self.i += 1;
                 self.consume_ws();
                 right = self.get_neg()?;
                 if right.numer().sign() == Sign::NoSign {
                     return Err(DivByZero(self.i));
                 }
                 left /= right;
             } else if let Some(k) = self.utf8.get(self.i..self.i.saturating_add(3)) {
                 if k == b"mod" {
                     if !left.is_integer() {
                         return Err(ModIsNotInt(self.i));
                     }
                     self.i += 3;
                     self.consume_ws();
                     right = self.get_neg()?;
                     if !right.is_integer() {
                         return Err(ModIsNotInt(self.i));
                     }
                     numer = right.numer();
                     if numer.sign() == Sign::NoSign {
                         return Err(ModZero(self.i));
                     }
                     mod_val = left.numer() % numer;
                     left = Ratio::from_integer(if mod_val.sign() == Sign::Minus {
                         if numer.sign() == Sign::Minus {
                             mod_val - numer
                         } else {
                             mod_val + numer
                         }
                     } else {
                         mod_val
                     });
                 } else {
                     break;
                 }
             } else {
                 break;
             }
         }
         Ok(left)
     }
     /// Evaluates negation expressions as defined in the calc language.
     /// This function is based on exponentiation expressions.
     fn get_neg(&mut self) -> Result<Ratio<BigInt>, LangErr> {
         let mut count = 0usize;
         while let Some(b) = self.utf8.get(self.i) {
             if *b == b'-' {
                 self.i += 1;
                 self.consume_ws();
                 count += 1;
             } else {
                 break;
             }
         }
         self.get_exps()
             .map(|val| if count & 1 == 0 { val } else { -val })
     }
     /// Gets the square root of value so long as a solution exists.
     #[expect(
         clippy::unreachable,
         reason = "code that shouldn't happen did, so we want to crash"
     )]
     fn sqrt(val: Ratio<BigInt>) -> Option<Ratio<BigInt>> {
         /// Returns the square root of `n` if one exists; otherwise
         /// returns `None`.
         /// MUST NOT pass 0.
         #[expect(clippy::suspicious_operation_groupings, reason = "false positive")]
         fn calc(n: &BigUint) -> Option<BigUint> {
             let mut shift = n.bits();
             shift += shift & 1;
             let mut result = BigUint::new(Vec::new());
             let one = BigUint::new(vec![1]);
             let zero = BigUint::new(Vec::new());
             loop {
                 shift -= 2;
                 result <<= 1u32;
                 result |= &one;
                 result ^= if &result * &result > (n >> shift) {
                     &one
                 } else {
                     &zero
                 };
                 if shift == 0 {
                     break (&result * &result == *n).then_some(result);
                 }
             }
         }
         let numer = val.numer();
         if numer.sign() == Sign::NoSign {
             Some(val)
         } else {
             numer.try_into().map_or_else(
                 |_| None,
                 |num| {
                     calc(&num).and_then(|n| {
                         calc(&val.denom().try_into().unwrap_or_else(|_| {
                             unreachable!("Ratio must never have a negative denominator")
                         }))
                         .map(|d| Ratio::new(n.into(), d.into()))
                     })
                 },
             )
         }
     }
     /// Evaluates exponentiation expressions as defined in the calc language.
     /// This function is based on negation expressions.
     fn get_exps(&mut self) -> Result<Ratio<BigInt>, LangErr> {
         let mut t = self.get_fact()?;
         let ix = self.scratch.len();
         let mut prev;
         let mut numer;
         self.scratch.push(t);
         self.consume_ws();
         let mut j;
         let one = BigInt::new(Sign::Plus, vec![1]);
         let min_one = BigInt::new(Sign::Minus, vec![1]);
         let two = BigInt::new(Sign::Plus, vec![2]);
         while let Some(i) = self.utf8.get(self.i) {
             j = *i;
             self.consume_ws();
             if j == b'^' {
                 self.i += 1;
                 self.consume_ws();
                 t = self.get_neg()?;
                 // Safe since we always push at least one value, and we always
                 // return immediately once we encounter an error.
                 prev = self.scratch.index(self.scratch.len() - 1);
                 numer = prev.numer();
                 // Equiv to checking if prev is 0.
                 if numer.sign() == Sign::NoSign {
                     if t.numer().sign() == Sign::Minus {
                         self.scratch.clear();
                         return Err(ExpDivByZero(self.i));
                     }
                     self.scratch.push(t);
                 } else if prev.is_integer() {
                     let t_numer = t.numer();
                     // 1 raised to anything is 1, so we don't bother
                     // storing the exponent.
                     if *numer == one {
                     } else if t.is_integer()
                         || ((*t_numer == one || *t_numer == min_one) && *t.denom() == two)
                     {
                         self.scratch.push(t);
                     } else {
                         self.scratch.clear();
                         return Err(ExpIsNotIntOrOneHalf(self.i));
                     }
                 } else if t.is_integer()
                     || ((*t.numer() == one || *t.numer() == min_one) && *t.denom() == two)
                 {
                     self.scratch.push(t);
                 } else {
                     self.scratch.clear();
                     return Err(ExpIsNotIntOrOneHalf(self.i));
                 }
             } else {
                 break;
             }
         }
         self.scratch
             .drain(ix..)
             .try_rfold(Ratio::from_integer(one.clone()), |exp, base| {
                 if exp.is_integer() {
                     Ok(base.pow(exp.numer()))
                 } else if base.numer().sign() == Sign::NoSign {
                     Ok(base)
                 } else if *exp.denom() == two {
                     if *exp.numer() == one {
                         Self::sqrt(base).map_or_else(|| Err(SqrtDoesNotExist(self.i)), Ok)
                     } else if *exp.numer() == min_one {
                         Self::sqrt(base)
                             .map_or_else(|| Err(SqrtDoesNotExist(self.i)), |v| Ok(v.inv()))
                     } else {
                         Err(ExpIsNotIntOrOneHalf(self.i))
                     }
                 } else {
                     Err(ExpIsNotIntOrOneHalf(self.i))
                 }
             })
     }
     /// Evaluates factorial expressions as defined in the calc language.
     /// This function is based on terminal expressions.
     fn get_fact(&mut self) -> Result<Ratio<BigInt>, LangErr> {
         /// Calculates the factorial of `val`.
         fn fact(mut val: BigUint) -> BigUint {
             let zero = BigUint::new(Vec::new());
             let one = BigUint::new(vec![1]);
             let mut calc = BigUint::new(vec![1]);
             while val > zero {
                 calc *= &val;
                 val -= &one;
             }
             calc
         }
         let t = self.get_term()?;
         let Some(b) = self.utf8.get(self.i) else {
             return Ok(t);
         };
         if *b == b'!' {
             self.i += 1;
             if t.is_integer() {
                 // We can make a copy of self.i here, or call map_or instead
                 // of map_or_else.
                 let i = self.i;
                 t.numer().try_into().map_or_else(
                     |_| Err(NotNonNegIntFact(i)),
                     |val| {
                         let mut factorial = fact(val);
                         while let Some(b2) = self.utf8.get(self.i) {
                             if *b2 == b'!' {
                                 self.i += 1;
                                 factorial = fact(factorial);
                             } else {
                                 break;
                             }
                         }
                         Ok(Ratio::from_integer(BigInt::from_biguint(
                             Sign::Plus,
                             factorial,
                         )))
                     },
                 )
             } else {
                 Err(NotNonNegIntFact(self.i))
             }
         } else {
             Ok(t)
         }
     }
     /// Evaluates terminal expressions as defined in the calc language.
     /// This function is based on number literal expressions, parenthetical expressions,
     /// recall expressions, absolute value expressions, round expressions, and possibly
     /// rand expressions if that feature is enabled.
     fn get_term(&mut self) -> Result<Ratio<BigInt>, LangErr> {
         self.get_rational().map_or_else(Err, |o| {
             o.map_or_else(
                 || {
                     self.get_par().map_or_else(Err, |o2| {
                         o2.map_or_else(
                             || {
                                 self.get_recall().map_or_else(Err, |o3| {
                                     o3.map_or_else(
                                         || {
                                             self.get_abs().map_or_else(Err, |o4| {
                                                 o4.map_or_else(
                                                     || {
                                                         self.get_round().and_then(|o5| {
                                                             o5.map_or_else(
                                                                 #[cfg(not(feature = "rand"))]
                                                                 || Err(MissingTerm(self.i)),
                                                                 #[cfg(feature = "rand")]
                                                                 || self.get_rand(),
                                                                 Ok,
                                                             )
                                                         })
                                                     },
                                                     Ok,
                                                 )
                                             })
                                         },
                                         Ok,
                                     )
                                 })
                             },
                             Ok,
                         )
                     })
                 },
                 Ok,
             )
         })
     }
     /// Generates a random 64-bit integer. This function is based on add expressions. This is the last terminal
     /// expression attempted when needing a terminal expression; as a result, it is the only terminal expression
     /// that does not return an `Option`.
     #[cfg(feature = "rand")]
     fn get_rand(&mut self) -> Result<Ratio<BigInt>, LangErr> {
         /// Generates a random 64-bit integer.
         #[expect(clippy::host_endian_bytes, reason = "must keep platform endianness")]
         fn rand(rng: &mut ThreadRng) -> i64 {
             let mut bytes = [0; 8];
             // `ThreadRng::try_fill_bytes` is infallible, so easier to call `fill_bytes`.
             rng.fill_bytes(&mut bytes);
             i64::from_ne_bytes(bytes)
         }
         /// Generates a random 64-bit integer inclusively between the passed arguments.
         #[expect(
             clippy::integer_division_remainder_used,
             reason = "need for uniform randomness"
         )]
         #[expect(
             clippy::as_conversions,
             clippy::cast_possible_truncation,
             clippy::cast_possible_wrap,
             clippy::cast_sign_loss,
             reason = "lossless conversions between signed integers"
         )]
         fn rand_range(
             rng: &mut ThreadRng,
             lower: &Ratio<BigInt>,
             upper: &Ratio<BigInt>,
             i: usize,
         ) -> Result<i64, LangErr> {
             if lower > upper {
                 return Err(LangErr::RandInvalidArgs(i));
             }
             let lo = lower.ceil();
             let up = upper.floor();
             let lo_int = lo.numer();
             let up_int = up.numer();
             if lo_int > &BigInt::from(i64::MAX) || up_int < &BigInt::from(i64::MIN) {
                 return Err(LangErr::RandNoInts(i));
             }
             let lo_min = lo_int.to_i64().unwrap_or(i64::MIN);
             let up_max = up_int.to_i64().unwrap_or(i64::MAX);
             if up_max > lo_min || upper.is_integer() || lower.is_integer() {
                 let low = i128::from(lo_min);
                 // `i64::MAX >= up_max >= low`; so underflow and overflow cannot happen.
                 // range is [1, 2^64] so casting to a u128 is fine.
                 let modulus = (i128::from(up_max) - low + 1) as u128;
                 // range is [0, i64::MAX] so converting to a `u64` is fine.
                 // rem represents how many values need to be removed
                 // when generating a random i64 in order for uniformity.
                 let rem = (0x0001_0000_0000_0000_0000 % modulus) as u64;
                 let mut low_adj;
                 loop {
                     low_adj = rand(rng) as u64;
                     // Since rem is in [0, i64::MAX], this is the same as low_adj < 0 || low_adj >= rem.
                     if low_adj >= rem {
                         return Ok(
                             // range is [i64::MIN, i64::MAX]; thus casts are safe.
                             // modulus is up_max - low + 1; so as low grows,
                             // % shrinks by the same factor. i64::MAX happens
                             // when low = up_max = i64::MAX or when low = 0,
                             // up_max = i64::MAX and low_adj is i64::MAX.
                             ((u128::from(low_adj) % modulus) as i128 + low) as i64,
                         );
                     }
                 }
             } else {
                 Err(LangErr::RandNoInts(i))
             }
         }
         // This is the last kind of terminal expression that is attempted.
         // If there is no more data, then we have a missing terminal expression.
         let Some(b) = self.utf8.get(self.i..self.i.saturating_add(5)) else {
             return Err(MissingTerm(self.i));
         };
         if b == b"rand(" {
             self.i += 5;
             self.consume_ws();
             let i = self.i;
             self.utf8.get(self.i).map_or_else(
                 || Err(LangErr::InvalidRand(i)),
                 |p| {
                     if *p == b')' {
                         self.i += 1;
                         Ok(Ratio::from_integer(BigInt::from(rand(self.rng))))
                     } else {
                         let add = self.get_adds()?;
                         let Some(b2) = self.utf8.get(self.i) else {
                             return Err(LangErr::InvalidRand(self.i));
                         };
                         if *b2 == b',' {
                             self.i += 1;
                             self.consume_ws();
                             let add2 = self.get_adds()?;
                             self.consume_ws();
                             let Some(b3) = self.utf8.get(self.i) else {
                                 return Err(LangErr::InvalidRand(self.i));
                             };
                             if *b3 == b')' {
                                 self.i += 1;
                                 rand_range(self.rng, &add, &add2, self.i)
                                     .map(|v| Ratio::from_integer(BigInt::from(v)))
                             } else {
                                 Err(LangErr::InvalidRand(self.i))
                             }
                         } else {
                             Err(LangErr::InvalidRand(self.i))
                         }
                     }
                 },
             )
         } else {
             Err(MissingTerm(self.i))
         }
     }
     /// Rounds a value to the specified number of fractional digits.
     /// This function is based on add expressions.
     fn get_round(&mut self) -> Result<Option<Ratio<BigInt>>, LangErr> {
         let Some(b) = self.utf8.get(self.i..self.i.saturating_add(6)) else {
             return Ok(None);
         };
         if b == b"round(" {
             self.i += 6;
             self.consume_ws();
             let val = self.get_adds()?;
             self.consume_ws();
             let Some(b2) = self.utf8.get(self.i) else {
                 return Err(InvalidRound(self.i));
             };
             let b3 = *b2;
             if b3 == b',' {
                 self.i += 1;
                 self.consume_ws();
                 let Some(b4) = self.utf8.get(self.i) else {
                     return Err(InvalidRound(self.i));
                 };
                 let r = if b4.is_ascii_digit() {
                     self.i += 1;
                     *b4 - b'0'
                 } else {
                     return Err(InvalidRound(self.i));
                 };
                 self.consume_ws();
                 let i = self.i;
                 self.utf8.get(self.i).map_or_else(
                     || Err(InvalidRound(i)),
                     |p| {
                         if *p == b')' {
                             self.i += 1;
                             let mult =
                                 BigInt::from_biguint(Sign::Plus, BigUint::new(vec![10])).pow(r);
                             Ok(Some((val * &mult).round() / &mult))
                         } else {
                             Err(InvalidRound(self.i))
                         }
                     },
                 )
             } else {
                 Err(InvalidRound(self.i))
             }
         } else {
             Ok(None)
         }
     }
     /// Evaluates absolute value expressions as defined in the calc language.
     /// This function is based on add expressions.
     fn get_abs(&mut self) -> Result<Option<Ratio<BigInt>>, LangErr> {
         let Some(b) = self.utf8.get(self.i) else {
             return Ok(None);
         };
         if *b == b'|' {
             self.i += 1;
             self.consume_ws();
             let r = self.get_adds()?;
             self.consume_ws();
             let Some(b2) = self.utf8.get(self.i) else {
                 return Err(InvalidAbs(self.i));
             };
             let b3 = *b2;
             if b3 == b'|' {
                 self.i += 1;
                 Ok(Some(if r.numer().sign() == Sign::Minus {
                     -r
                 } else {
                     r
                 }))
             } else {
                 Err(InvalidAbs(self.i))
             }
         } else {
             Ok(None)
         }
     }
     /// Evaluates recall expressions as defined in the calc language.
     // This does not return a Result<Option<&Ratio<BigInt>>, LangErr>
     // since the only place this function is called is in get_term which
     // would end up needing to clone the Ratio anyway. By not forcing
     // get_term to clone, it can rely on map_or_else over match expressions.
     fn get_recall(&mut self) -> Result<Option<Ratio<BigInt>>, LangErr> {
         let Some(b) = self.utf8.get(self.i) else {
             return Ok(None);
         };
         if *b == b'@' {
             self.i += 1;
             self.cache
                 .get(self.utf8.get(self.i).map_or(0, |b2| {
                     if (b'1'..b'9').contains(b2) {
                         self.i += 1;
                         usize::from(*b2 - b'1')
                     } else {
                         0
                     }
                 }))
                 .map_or_else(
                     || Err(NotEnoughPrevResults(self.cache.len())),
                     |p| Ok(Some(p.clone())),
                 )
         } else {
             Ok(None)
         }
     }
     /// Evaluates parenthetical expressions as defined in the calc language.
     /// This function is based on add expressions.
     fn get_par(&mut self) -> Result<Option<Ratio<BigInt>>, LangErr> {
         let Some(b) = self.utf8.get(self.i) else {
             return Ok(None);
         };
         if *b == b'(' {
             self.i += 1;
             self.consume_ws();
             let r = self.get_adds()?;
             self.consume_ws();
             let Some(b2) = self.utf8.get(self.i) else {
                 return Err(InvalidPar(self.i));
             };
             let b3 = *b2;
             if b3 == b')' {
                 self.i += 1;
                 Ok(Some(r))
             } else {
                 Err(InvalidPar(self.i))
             }
         } else {
             Ok(None)
         }
     }
     /// Evaluates number literal expressions as defined in the calc language.
     #[expect(clippy::indexing_slicing, reason = "correct")]
     fn get_rational(&mut self) -> Result<Option<Ratio<BigInt>>, LangErr> {
         // ControlFlow makes more sense to use in try_fold; however due to a lack
         // of a map_or_else function, it is easier to simply return a Result with
         // Err taking the role of ControlFlow::Break.
         /// Used to parse a sequence of digits into an unsigned integer.
         fn to_biguint(v: &[u8]) -> (BigUint, usize) {
             v.iter()
                 .try_fold((BigUint::new(Vec::new()), 0), |mut prev, d| {
                     if d.is_ascii_digit() {
                         prev.1 += 1;
                         // `*d - b'0'` is guaranteed to return a integer between 0 and 9.
                         prev.0 = prev.0 * 10u8 + (*d - b'0');
                         Ok(prev)
                     } else {
                         Err(prev)
                     }
                 })
                 .unwrap_or_else(convert::identity)
         }
         let (int, len) = to_biguint(&self.utf8[self.i..]);
         if len == 0 {
             return Ok(None);
         }
         self.i += len;
         if let Some(b) = self.utf8.get(self.i) {
             if *b == b'.' {
                 self.i += 1;
                 let (numer, len2) = to_biguint(&self.utf8[self.i..]);
                 if len2 == 0 {
                     Err(InvalidDec(self.i))
                 } else {
                     self.i += len2;
                     Ok(Some(
                         Ratio::from_integer(BigInt::from_biguint(Sign::Plus, int))
                             + Ratio::new(
                                 BigInt::from_biguint(Sign::Plus, numer),
                                 BigInt::from_biguint(Sign::Plus, BigUint::new(vec![10]).pow(len2)),
                             ),
                     ))
                 }
             } else {
                 Ok(Some(Ratio::from_integer(BigInt::from_biguint(
                     Sign::Plus,
                     int,
                 ))))
             }
         } else {
             Ok(Some(Ratio::from_integer(BigInt::from_biguint(
                 Sign::Plus,
                 int,
             ))))
         }
     }
 }
 /// Reads data from `R` passing each line to an [`Evaluator`] to be evaluated.
 #[cfg(feature = "std")]
 #[derive(Debug)]
 pub struct EvalIter<R> {
     /// Reader that contains input data.
     reader: R,
     /// Buffer that is used by `reader` to read
     /// data into.
     input_buffer: Vec<u8>,
     /// Cache of stored results.
     cache: Cache<Ratio<BigInt>, 8>,
     /// Result of the previous expression.
     prev: Option<Ratio<BigInt>>,
     /// Buffer used by [`Evaluator`] to process
     /// sub-expressions.
     exp_buffer: Vec<Ratio<BigInt>>,
     /// Random number generator.
     #[cfg(feature = "rand")]
     rng: ThreadRng,
 }
 #[cfg(feature = "std")]
 impl<R> EvalIter<R> {
     /// Creates a new `EvalIter`.
     #[cfg(feature = "rand")]
     #[inline]
     pub fn new(reader: R) -> Self {
         Self {
             reader,
             input_buffer: Vec::new(),
             cache: Cache::new(),
             prev: None,
             exp_buffer: Vec::new(),
             rng: rand::rng(),
         }
     }
     /// Creates a new `EvalIter`.
     #[cfg(any(doc, not(feature = "rand")))]
     #[inline]
     pub fn new(reader: R) -> Self {
         Self {
             reader,
             input_buffer: Vec::new(),
             cache: Cache::new(),
             prev: None,
             exp_buffer: Vec::new(),
         }
     }
 }
 #[cfg(feature = "std")]
 extern crate std;
 #[cfg(feature = "std")]
 use std::io::{BufRead, Error};
 /// Error returned from [`EvalIter`] when an expression has an error.
 #[cfg(feature = "std")]
 #[derive(Debug)]
 pub enum E {
     /// Error containing [`Error`] which is returned
     /// from [`EvalIter`] when reading from the supplied
     /// [`BufRead`]er.
     Error(Error),
     /// Error containing [`LangErr`] which is returned
     /// from [`EvalIter`] when evaluating a single expression.
     LangErr(LangErr),
 }
 #[cfg(feature = "std")]
 impl Display for E {
     #[inline]
     fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
         match *self {
             Self::Error(ref e) => e.fmt(f),
             Self::LangErr(ref e) => e.fmt(f),
         }
     }
 }
 #[cfg(feature = "std")]
 use crate::lending_iterator::LendingIterator;
 #[cfg(feature = "std")]
 impl<R> LendingIterator for EvalIter<R>
 where
     R: BufRead,
 {
     type Item<'a>
         = Result<O<'a>, E>
     where
         Self: 'a;
     #[inline]
     fn lend_next(&mut self) -> Option<Result<O<'_>, E>> {
         self.input_buffer.clear();
         self.exp_buffer.clear();
         self.reader
             .read_until(b'\n', &mut self.input_buffer)
             .map_or_else(
                 |e| Some(Err(E::Error(e))),
                 |c| {
                     if c == 0 {
                         None
                     } else {
                         Evaluator::new(
                             self.input_buffer.as_slice(),
                             &mut self.cache,
                             &mut self.prev,
                             &mut self.exp_buffer,
                             #[cfg(feature = "rand")]
                             &mut self.rng,
                         )
                         .evaluate()
                         .map_or_else(
                             |e| Some(Err(E::LangErr(e))),
                             |o| match o {
                                 Empty(_) | Eval(_) | Store(_) => Some(Ok(o)),
                                 Exit => None,
                             },
                         )
                     }
                 },
             )
     }
 }