Crate calc_lib

calc_lib

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, <space>, <tab>, <line feed>, <carriage return>, 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::Errors 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.

Modules

• cache
  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 that only adds new data or reads old data.
• lending_iterator
  Generalizes Iterator by using generic associated types.

Structs

• EvalIter
  Reads data from R passing each line to an Evaluator to be evaluated.
• Evaluator
  Evaluates the supplied input.

Enums

• Estd
  Error returned from EvalIter when an expression has an error.
• LangErr
  Error due to a language violation.
• O
  A successful evaluation of an input.