Documentation
Using Pnic.
Number strings must be non-negative and decimal (base-10). Negative numbers can be represented only as a Pnic object.
Except for divisions by zero, erroneous arguments will be processed as is.
Setup
Setting up Pnic.
Load Pnic by running its script pnic.sh
in the current shell:
$ . pnic.sh
Division
Optionally, you can set the division algorithm and precision either within or outside of Pnic. See the script for names.
The Pad, Count, Shift (pcs) algorithm allows for any
precision. It is not bound by Bash's limits, but a large precision like 9999 can make division unusable. The default precision should suffice,
so change it only when required by your application. This algorithm is the
default as we recommend using it.
The Padding Dividend (pdv) algorithm is still available, with
which your precision setting does not apply as it is fixed. Note that this
algorithm is very prone to rounding errors.
Objects
Associative arrays for and from functions.
A Pnic object refers to an associative array with the following keys:
- intinteger,
- fltfloat or fraction,
- resraw result,
- negnegative flag,
- pospositive flag, and
- errerror.
Empty ints and flts default to 0. A Pnic object representing the number zero is neither
positive nor negative, thus both its pos and neg are
empty.
As an example, the following expression declares a Pnic object for the number -0.41099:
declare -A number=([flt]=41099 [neg]='neg')
Functions
Interfacing with Pnic.
Function names are preceded by PNC..
add<type> <object> <term> <term>- Sets the sum of the given two terms to the given object.
alnFlt (<this> <that>)...- Aligns this float to that float--or vice versa, whichever is longer--so that they have an equal count of digits.
clrObj <object>...- Clears the given objects.
cmp<type> <object> <this> <that>- Sets the comparison of this to that to the given object, such that it is negative if this is less than that.
cpyObj <destination>... <source>- Copies the given source object to the given destination objects.
div<type> <object> <dividend> <divisor>- Sets the quotient of the given dividend and divisor to the given object.
eval [<word>]...- Evaluates the given expression. See [Expressions].
mul<type> <object> <factor> <factor>- Sets the product of the given two factors to the given object.
shlObj <object> <distance>- Shifts the given object leftwards by the given distance.
shrObj <object> <distance>- Shifts the given object rightwards by the given distance.
sub<type> <object> <minuend> <subtrahend>- Sets the difference of the given minuend and subtrahend to the given object.
trm<type> <item>...- Trims leading and/or trailing zeroes from the given items, such that their representations remain equal.
tstObj <object>...- Tests the given objects for occupancy.
Types
- FltFloat, with each part as its own argument.
- IntInteger.
- ObjObject, as name references to associative arrays.
Expressions
Basic interpreter syntax.
A basic interpreter of basic expressions is available as the function PNC.eval. It evaluates the given expression and prints the result--no Pnic objects.
Each word is either a number or an operator. A number word is parsed then evaluated with the current result and operator. As with all of Pnic, it must be non-negative and decimal. An operator word changes the current operator.
Expressions are evaluated left-to-right. Result printouts start with a
polarity symbol (+ or -), followed by the number.
However, errors--if present--are printed in their place.
Operator Words
Be careful with shell expansions.
+,addAddition.-,subSubtraction.*,mulMultiplication./,subDivision.<>,cmpComparison.<<,shlLeft shift.>>,shrRight shift.
Examples
$ PNC.eval 1 +1 $ PNC.eval 1 2 +2 $ PNC.eval 1 + 2 +3 $ PNC.eval + 1 2 +3 $ PNC.eval + 1 - 2 -1 $ PNC.eval + 1 - '*' 2 +2 $ PNC.eval 1 sub 2 cmp 3 - $ PNC.eval 1 shl 2 cmp 3 + $ PNC.eval 1 mul 2 div 0 cmp 3 Division by zero.