## no-std bin+lib calc_rational

CLI calculator for rational numbers

### 14 releases(8 breaking)

 0.9.1 Nov 8, 2023 Oct 22, 2023 Jul 26, 2023

#157 in Math

MIT/Apache

155KB
3.5K SLoC

# calc_rational

calc_rational consists of a binary crate `calc` and a library crate `calc_lib`. `calc` is a CLI calculator for basic rational number arithmetic using standard operator precedence and associativity. Internally, it is based on `Ratio<T>` and `BigInt`.

## Calc in action

``````[zack@laptop ~]\$ calc
2.71828^0^3.14159 + -1!
> 0
s
> 0
@^0
> 1
s
> 1
@/3 * 3
> 1
s
> 1
|@2 - 9|^(1 - 2*3)
> 1/32768
s
> 1/32768

> 0.000030517578125
round(@, 3)
> 0
round(@, 6)
> 31/1000000

> 0.000031
2/3
> 2/3

> 0.666666667
rand()
> 939435294927814822
rand(1+9,10!)
> 2660936
1+4 mod 2 + 1
> 2
-5 mod 2
> 1
-5 mod -2
> 1
5 mod -2
> 1
9^0.5
> 3
(4/9)^(-1/2)
> 3/2
q
[zack@laptop ~]\$
``````

## 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::Error`s caused by writing to the global standard output stream lead to program abortion. On OpenBSD-stable when compiled with the `priv_sep` feature, it will error if `pledge(2)` errors with the promise of `"stdio"`.

## Exiting

`q` with any number of spaces and tabs before and after or sending `EOF` will cause the program to terminate.

### Status

This package will be actively maintained until it is deemed “feature complete”. There are really only two properties that will always be true. First, the grammar that generates a “reasonable” superset of the language will be an unambiguous context-free grammar with expression precedence and binary operator associativity embedded within. Last, the language will only deal with the field of rational numbers.

The crates are only tested on the `x86_64-unknown-linux-gnu` and `x86_64-unknown-openbsd` targets, but they should work on any Tier 1 with Host Tools target. Note one must be aware of the ASCII encoding requirement. In particular there are platforms (e.g., Windows) where the default text encoding is not a superset of ASCII.

#### Formal language specification

For a more precise specification of the “calc language”, one can read the calc language specification.

~500–720KB
~16K SLoC