Math::Logic::Ternary::Word - fixed-size ternary information compound
This documentation refers to version 0.003 of Math::Logic::Ternary::Word.
use Math::Logic::Ternary::Word; $a = Math::Logic::Ternary::Word->from_string(9, 'fnttffnnt'); $a = Math::Logic::Ternary::Word->from_base27(9, 'sea'); $a = Math::Logic::Ternary::Word->from_int (9, -5696); $b = $a->Neg; # word +5696 $c = $a->Cmp($b); # trit -1 ($d, $e) = $a->Add($b); # word 0, carry trit 0 ($f, $g) = $a->Mul($b); # word -6832, word -1648 ($h, $i, $e) = $f->Div($a); # word +1, word -1136, trit 0 ($j, $k, $l, $e) = $f->Ldiv($g, $b); # word -5696, word 0, word 0, trit 0 @m = $a->Trits; # (true, nil, nil, ..., false) $n = $a->Size; # 9 print $a->as_int; # print -5696 print $b->as_base27; # print '%hVZ' print $d->as_string; # print '@nnnnnnnnn'
Method naming conventions for Math::Logic::Ternary::Word are as follows:
Elementary logical operators can be applied in two ways to word objects. Words can be treated as single trits, so that only their truth values (read: signs) are taken into account. Operators with all uppercase names will treat words in this way.
Logical operators spelled all lowercase, on the other hand, will work tritwise on all trits of their operands in parallel. The least significant trit of the result will be the result of the operation on the least significant trits of the operands, and so on up to the most significant trit.
If words of different sizes are mixed in an operation, the leftmost argument determines the word size in which the operation is carried out. Other operands will be padded with nil trits or truncated accordingly, aligned on their least significant end.
Numerical operators treat their operands as numerical values, which usually means that different trits in multi-trit-words interfere with each other in the course of a computation. Their names are written in mixed case starting with an uppercase letter.
Most numerical and some logical functions have different variants for balanced, unbalanced, and base(-3) arithmetic, where unbalanced also means unsigned. Balanced ternary digits are -1, 0, and 1. Unbalanced base(3) and base(-3) ternary digits are 0, 1, and 2. As balanced ternary numbers are in many cases easier to deal with than unbalanced or negative base numbers, our naming scheme prefers the former, giving balanced arithmetic operators short names, while their unbalanced counterparts get a suffix letter u or U, and base(-3) operators v or V.
Comparisons are the ultimate challenge of standardizing ternary logic, since there are six ways to assign comparison results to trit values and six ways to order trit values. For three-way comparison results, we continue leaning towards balanced arithmetic and assign -1 (false) to "less than", 0 (nil) to "equal to" and 1 (true) to "greater than". We regard false < nil < true as the "natural" trit order, and nil < true < false as the "unbalanced" order. Again, the latter is flagged with a u or U suffix.
Conversions from objects to other data have a name prefix to_ or To_ depending on whether they convert a truth value or a word. The prefix is followed by a name for the data type they yield. If there is an unbalanced or base(-3) variant the final suffix is _u or _v, respectively. Alien type names are always separated by underscores from prefixes and suffixes (if there are any).
Conversions from other data to objects have a name prefix from_ or From_ depending on whether they yield single trits or words, followed by a name for the data type they accept. Again, the unbalanced and base(-3) suffixes are _u and _v, respectively. These constructors are class methods.
Conversions to and from floating point formats are not implemented here. A ternary floating point format with a whole bunch of operations and conversions is defined in the separate module Math::Logic::Ternary::TFP_81.
If an operand size does not match the word size of an operator, it is silently truncated to its least significant trits or padded with leading zeroes as appropriate.
None.
Operators on trits are carried over to word objects in two variants.
Spelled all uppercase they act as pure logical operators, using just the truth values (read: signs) of their arguments and returning a trit.
Spelled all lowercase they act as tritwise operators, performing the logical operation on each trit position of the arguments, and returning a word.
The leftmost argument of a tritwise operator determines the word size of the operation and thus the size of the result. In tritwise operations, all arguments are aligned at the least significant end. Smaller arguments are padded with nil trits and larger arguments are truncated at the other end.
Details about trit operators are documented in Math::Logic::Ternary::Trit.
Nil: Constant nil. No arguments, one result value.
True: Constant true. No arguments, one result value.
False: Constant false. No arguments, one result value.
Set to Nil: return nil. One argument, one result value.
Set to True: return true. One argument, one result value.
Set to False: return false. One argument, one result value.
Identity: return the argument. One argument, one result value.
Not. One argument, one result value.
Up One: increment modulo 3. One argument, one result value.
Not Up: swap nil/false. One argument, one result value.
Down One: decrement modulo 3. One argument, one result value.
Not Down: swap nil/true. One argument, one result value.
Equal to Nil. One argument, one result value.
Equal to True. One argument, one result value.
Equal to False. One argument, one result value.
Not Equal to Nil. One argument, one result value.
Not Equal to True. One argument, one result value.
Not Equal to False. One argument, one result value.
Hamlet: x or not x. One argument, one result value.
Up & Hamlet. One argument, one result value.
Down & Hamlet. One argument, one result value.
Or Nil. One argument, one result value.
Up & Or Nil. One argument, one result value.
Down & Or Nil. One argument, one result value.
Quantum: x and not x. One argument, one result value.
Up & Quantum. One argument, one result value.
Down & Quantum. One argument, one result value.
And Nil. One argument, one result value.
Up & And Nil. One argument, one result value.
Down & And Nil. One argument, one result value.
And. 2 arguments, one result value.
Or. 2 arguments, one result value.
Exclusive Or. 2 arguments, one result value.
Equivalent. 2 arguments, one result value.
Implication (x ==> y). 2 arguments, one result value.
Replication (x <== y). 2 arguments, one result value.
Not And. 2 arguments, one result value.
Not Or. 2 arguments, one result value.
Compare (false < nil < true). 2 arguments, one result value.
Ascending (false < nil < true). 2 arguments, one result value.
The Lesser (false < nil < true). 2 arguments, one result value.
The Greater (false < nil < true). 2 arguments, one result value.
Equal to. 2 arguments, one result value.
Not Equal to. 2 arguments, one result value.
Less Than (false < nil < true). 2 arguments, one result value.
Greater or Equal (false < nil < true). 2 arguments, one result value.
Greater Than (false < nil < true). 2 arguments, one result value.
Less or Equal (false < nil < true). 2 arguments, one result value.
Compare (unbalanced, nil < true < false). 2 arguments, one result value.
Ascending (unbalanced, nil < true < false). 2 arguments, one result value.
The Lesser (unbalanced, nil < true < false). 2 arguments, one result value.
The Greater (unbalanced, nil < true < false). 2 arguments, one result value.
Less Than (unbalanced, nil < true < false). 2 arguments, one result value.
Greater or Equal (unbalanced, nil < true < false). 2 arguments, one result value.
Greater Than (unbalanced, nil < true < false). 2 arguments, one result value.
Less or Equal (unbalanced, nil < true < false). 2 arguments, one result value.
Increment. 2 arguments, one result value.
Increment Carry. 2 arguments, one result value.
Increment Carry (unbalanced). 2 arguments, one result value.
Increment Carry (negative base). 2 arguments, one result value.
Decrement. 2 arguments, one result value.
Decrement Carry. 2 arguments, one result value.
Decrement Carry (unbalanced). 2 arguments, one result value.
Decrement Carry (negative base). 2 arguments, one result value.
Parity. 2 arguments, one result value.
Duplicate. 2 arguments, one result value.
Duplication Carry. 2 arguments, one result value.
Duplication Carry (unbalanced). 2 arguments, one result value.
Duplication Carry (negative base). 2 arguments, one result value.
Negation Carry (negative base). 2 arguments, one result value.
Multiplication Carry (unbalanced). 2 arguments, one result value.
Addition modulo 3. 3 arguments, one result value.
Addition Carry. 3 arguments, one result value.
Addition Carry (unbalanced). 3 arguments, one result value.
Addition Carry (negative base). 3 arguments, one result value.
Addition Carry (mixed base). 3 arguments, one result value.
Subtraction. 3 arguments, one result value.
Subtraction Carry. 3 arguments, one result value.
Subtraction Carry (unbalanced). 3 arguments, one result value.
Subtraction Carry (negative base). 3 arguments, one result value.
Ternary Comparison to Minimum. 3 arguments, one result value.
Ternary Comparison to Median. 3 arguments, one result value.
Ternary Comparison to Maximum. 3 arguments, one result value.
Ternary Comparison Validation. 3 arguments, one result value.
Interpolation Linear Coefficient. 3 arguments, one result value.
Interpolation Quadratic Coefficient. 3 arguments, one result value.
Linear Combination. 3 arguments, one result value.
Minimum of Three Values. 3 arguments, one result value.
Median of Three Values. 3 arguments, one result value.
Maximum of Three Values. 3 arguments, one result value.
Minimum of Three Values (unbalanced). 3 arguments, one result value.
Median of Three Values (unbalanced). 3 arguments, one result value.
Maximum of Three Values (unbalanced). 3 arguments, one result value.
Summation. 4 arguments, one result value.
Summation Carry. 4 arguments, one result value.
Summation Carry (unbalanced). 4 arguments, one result value.
Multiplex: first trit controls which of the other arguments is returned. 4 arguments, one result value.
Generic logical and tritwise operators, first argument acts as logical operator name.
Addition in balanced, unbalanced, or base(-3) arithmetic. Two operands with optional carry trit, returns value and carry trit.
Ascending. Comparison operator in balanced, unbalanced or base(-3) arithmetic. Two operands with optional carry trit, returns result trit. If carry is not nil, result is carry. Otherwise if first operand is less than second operand, result is true. Otherwise if first operand is greater than second operand, result is false. Otherwise result is nil.
Comparison operator in balanced, unbalanced or base(-3) arithmetic. Two operands with optional carry trit, returns result trit. If carry is not zero, result is carry. Otherwise if first operand is greater than second operand, result is +1. Otherwise if first operand is less than second operand, result is -1. Otherwise result is zero.
Decrement operator in balanced, unbalanced or base(-3) arithmetic. One operand with optional carry trit, returns value and carry trit. Carry defaults to one if omitted. The carry is subtracted from the value.
Short division operator in balanced, unbalanced or base(-3) arithmetic. Two operands, returns quotient and remainder values and error trit. If the second operand is zero, the error trit is true, otherwise nil.
Duplication operator in balanced, unbalanced or base(-3) arithmetic. One operand with optional carry trit, returns value and carry trit. The operand is multiplied by two.
Greater or equal. Comparison operator in balanced, unbalanced or base(-3) arithmetic. Two operands with optional carry trit, returns result trit. If carry is not nil, result is carry. Otherwise if first operand is not less than second operand, result is true. Otherwise result is false.
Greater than. Comparison operator in balanced, unbalanced or base(-3) arithmetic. Two operands with optional carry trit, returns result trit. If carry is not nil, result is carry. Otherwise if first operand is greater than second operand, result is true. Otherwise result is false.
Increment operator in balanced, unbalanced or base(-3) arithmetic. One operand with optional carry trit, returns value and carry trit. Carry defaults to one if omitted. The carry is added to the value.
Long division operator in balanced, unbalanced or base(-3) arithmetic. Three operands: lower word of first operand, upper word of first operand, second operand. Returns lower and upper word of quotient value, remainder value, and error trit. If the second operand is zero, the error trit is true, otherwise nil.
Less or equal. Comparison operator in balanced, unbalanced or base(-3) arithmetic. Two operands with optional carry trit, returns result trit. If carry is not nil, result is carry. Otherwise if first operand is not greater than second operand, result is true. Otherwise result is false.
Left shift operator. One operand with optional carry trit, returns value and carry trit. The operand is multiplied by the base and the carry is added. The base is 3 in balanced or unbalanced arithmetic, -3 in base(-3) arithmetic.
Less than. Comparison operator in balanced, unbalanced or base(-3) arithmetic. Two operands with optional carry trit, returns result trit. If carry is not nil, result is carry. Otherwise if first operand is less than second operand, result is true. Otherwise result is false.
Maximum. Ternary comparison operator in balanced, unbalanced or base(-3) arithmetic. Three operands, returns the largest of these as result value.
Median. Ternary comparison operator in balanced, unbalanced or base(-3) arithmetic. Three operands, returns the second largest of these as result value.
Minimum. Ternary comparison operator in balanced, unbalanced or base(-3) arithmetic. Three operands, returns the smallest of these as result value.
Multiplication in balanced or unbalanced arithmetic. Two or three operands, returns lower and upper part of the result value. The optional third operand is added to the multiplication result.
Multiplication in base(-3) arithmetic. Two or three operands, returns lower and upper part of the result value and a carry trit. The optional third operand is added to the multiplication result.
Negation in balanced arithmetic. One operand, one result value. In balanced arithmetic, negation is equivalent to bitwise not.
Negation in unbalanced arithmetic. One operand with optional carry trit, returns value and carry trit. The operand is multiplied by -1.
Right shift operator. One operand with optional carry trit, returns value and carry trit. The operand is divided by the base and the most significant trit is set to the carry. The old least significant trit is returned as new carry. The base is 3 in balanced or unbalanced arithmetic, -3 in base(-3) arithmetic.
Sign operator in balanced, unbalanced or base(-3) arithmetic. One operand, returns sign trit. Note that in unbalanced arithmetic the result can only be nil or true, as all values are representing zero or positive numbers.
Binary Sorting operator in balanced, unbalanced or base(-3) arithmetic. Two operands, returns smaller and larger operand.
Ternary sorting operator in balanced, unbalanced or base(-3) arithmetic. Three operands, returns smallest, middle and largest operand.
Subtraction in balanced, unbalanced, or base(-3) arithmetic. Two operands with optional carry trit, returns value and carry trit.
Three-operand summation in balanced or unbalanced arithmetic. Three operands with optional carry trit, returns value and carry trit. Note that the base(-3) variant is not implemented.
The greater - binary comparison operator in balanced, unbalanced or base(-3) arithmetic. Two operands, returns larger operand.
The lesser - binary comparison operator in balanced, unbalanced or base(-3) arithmetic. Two operands, returns smaller operand.
Trit inspection: $word->Trit($n) returns trit number $n, 0 indexing the least significant trit.
$word->Trit($n)
$n
Trit inspection: $word->Trits returns a list of precisely n trits for word size n, starting with the least significant trit.
$word->Trits
Trit inspection: $word->Trits returns a list of zero up to n trits for word size n, starting with the least significant trit, ending with the most significant non-nil trit.
Numeric sign operator in balanced, unbalanced or base(-3) arithmetic, returns a sign trit. Note that in all variants a return value of true means positive, nil zero and false negative.
$word->as_int returns the integer number represented by the word in balanced ternary arithmetic. The result will either be a native integer or a Math::BigInt object depending on the word size.
$word->as_int
$word->as_int_u returns the integer number represented by the word in unsigned unbalanced ternary arithmetic. The result will either be a native integer or a Math::BigInt object depending on the word size.
$word->as_int_u
$word->as_int_v returns the integer number represented by the word in base(-3) arithmetic. The result will either be a native integer or a Math::BigInt object depending on the word size.
$word->as_int_v
$word->res_mod3 returns the least significant trit of the word.
$word->res_mod3
$word->as_string returns a string of n | t | f characters for all trits in the word including leading zeroes, from most to least significant trit, prepended by an @ sigil.
$word->as_string
n
t
f
@
$word->is_equal($obj) returns true if $word->Rtrits and $obj->Rtrits are identical lists, otherwise false. This means that words of different sizes are regarded as equal if they represent equal numeric values.
$word->is_equal($obj)
$word->Rtrits
$obj->Rtrits
Multiplex. $word->Mpx($case_n, $case_t, $case_f) with three arbitrary arguments returns $case_n if $word is zero, $case_t if $word is positive, or $case_f if $word is negative. Thus it is equivalent to $word->Sign-Mpx($case_n, $case_t, $case_f)>.
$word->Mpx($case_n, $case_t, $case_f)
$case_n
$word
$case_t
$case_f
$word->Sign-
$word->as_base27 returns a string of base(27) letters (_, lower case a up to m, upper case N up to Z) for all groups of three trits in the word including leading zeroes, from most to least significant triplet, prepended by a % sigil. The most significant triplet will be taken as zero padded if the word size is not a multiple of three.
$word->as_base27
_
a
m
N
Z
%
Base(27) string representations of words of equal size will sort lexically in the same order as their balanced ternary values sort numerically. Zero values will yield a string of underscore characters, prepended by %.
$word->as_modint converts the numerical value of $word to a Math::ModInt object modulo 3 ** n for words of size n, using balanced arithmetic. The variants as_modint_u and as_modint_v do the same in unbalanced and base(-3) arithmetic.
$word->as_modint
The Perl extension Math::ModInt (available on CPAN) must be installed for this to work, otherwise as_modint etc. will raise a run-time exception.
Each of these object methods creates a new word of the same size as its invocant.
$word->convert_XXX(@args) is a shortcut for Math::Logic::Ternary::Word->from_XXX($word->Size, @args) . See "Constructors", below.
$word->convert_XXX(@args)
Math::Logic::Ternary::Word->from_XXX($word->Size, @args)
$word->Words($size) returns a list of new word objects of the given size, holding all the trits of the invocant, in lowest to highest significance order. This can be used to split a big word into smaller words.
$word->Words($size)
If the desired word size is not a divisor of the original size, some padding nil trits are added at the (most significant) end so that the words returned are all the same size.
$word->min_int returns a word representing the smallest integer of the same size as the invocant in balanced ternary arithmetic. This is a word full of false trits.
$word->min_int
$word->max_int returns a word representing the largest integer of the same size as the invocant in balanced ternary arithmetic. This is a word full of true trits.
$word->max_int
$word->min_int_u returns a word representing the smallest integer of the same size as the invocant in unbalanced ternary arithmetic. This is a word full of nil trits.
$word->min_int_u
$word->max_int_u returns a word representing the largest integer of the same size as the invocant in unbalanced ternary arithmetic. This is a word full of false trits.
$word->max_int_u
$word->min_int_v returns a word representing the smallest integer of the same size as the invocant in base(-3) ternary arithmetic. This is a word full of alternating nil and false trits, with the least significant trit nil.
$word->min_int_v
$word->max_int_v returns a word representing the largest integer of the same size as the invocant in base(-3) ternary arithmetic. This is a word full of alternating nil and false trits, with the least significant trit false.
$word->max_int_v
Word objects are fixed size containers for trits. All constructors take a size argument and additional information defining those trit values.
The size must be a positive integer. There may be an implementation-specific upper limit for the size. Sizes up to 3 ** 9 should always be valid, though.
3 ** 9
Math::Logic::Ternary::Word-from_trits($size, @trits)> creates a new word object of given size from the given trit values.
Math::Logic::Ternary::Word-
Trits must be enumerated from lowest to highest significance, without gaps. Trailing (i.e. highly significant) nil trits may be omitted. Trailing superfluous nil trits will be ignored. Non-nil trits beyond the given size will trigger an exception.
Math::Logic::Ternary::Word->from_words($size, @words) creates a new word object of given size from trit values taken from the given list of words.
Math::Logic::Ternary::Word->from_words($size, @words)
The words may be of any size and must be listed from lowest to highest significance. All of their trits are used.
Math::Logic::Ternary::Word->from_bools($size, @bools) creates a new word object of given size from trit values given as booleans rather than trit objects. Boolean values are taken as nil if undefined, false if defined but false, or true if true.
Math::Logic::Ternary::Word->from_bools($size, @bools)
Math::Logic::Ternary::Word->from_int($size, $int) creates a new word representing the given integer value in balanced arithmetic. If the integer value exceeds the range of the given word size an exception is raised.
Math::Logic::Ternary::Word->from_int($size, $int)
Math::Logic::Ternary::Word->from_int_u($size, $int) creates a new word representing the given integer value in unbalanced unsigned arithmetic. If the integer value is negative or exceeds the range of the given word size an exception is raised.
Math::Logic::Ternary::Word->from_int_u($size, $int)
Math::Logic::Ternary::Word->from_int_v($size, $int) creates a new word representing the given integer value in base(-3) arithmetic. If the integer value exceeds the range of the given word size an exception is raised.
Math::Logic::Ternary::Word->from_int_v($size, $int)
Math::Logic::Ternary::Word->from_base27($size, $string) creates a new word from a string of base(27) digits (underscore and letters, case not important), given in highest to lowest significance order. If the resulting value exceeds the range of the given word size an exception is raised. See also "as_base27".
Math::Logic::Ternary::Word->from_base27($size, $string)
Math::Logic::Ternary::Word->from_string($size, $string) creates a new word from a string of ternary digits (n, t, f, case not important), given in highest to lowest significance order. If the resulting value exceeds the range of the given word size an exception is raised.
Math::Logic::Ternary::Word->from_string($size, $string)
If the string begins with one of the sigils %, @, or $, it is interpreted as a base(27) string, ternary digit string, or single ternary digit name, respectively.
$
If the string is not syntactically correct, an exception is raised.
Math::Logic::Ternary::Word->from_modint($size, $string) creates a new word from a Math::ModInt object (i.e. a modular integer) representing the same value if interpreted as a balanced ternary number. The modulus must be a power of three. Size can be zero or the base 3 logarithm of the modulus, otherwise an exception will be raised.
Math::Logic::Ternary::Word->from_modint($size, $string)
Math::Logic::Ternary::Word->from_modint_u($size, $string) creates a new word from a Math::ModInt object (i.e. a modular integer) representing the same value if interpreted as an unsigned ternary number. The modulus must be a power of three. Size can be zero or the base 3 logarithm of the modulus, otherwise an exception will be raised.
Math::Logic::Ternary::Word->from_modint_u($size, $string)
Math::Logic::Ternary::Word->from_modint_v($size, $string) creates a new word from a Math::ModInt object (i.e. a modular integer) representing the same value if interpreted as a base(-3) number. The modulus must be a power of three. Size can be zero or the base 3 logarithm of the modulus, otherwise an exception will be raised.
Math::Logic::Ternary::Word->from_modint_v($size, $string)
Math::Logic::Ternary::Word->from_various($size, @args) creates a new word from its arguments, guided by their type. If the resulting value exceeds the range of the given word size an exception is raised.
Math::Logic::Ternary::Word->from_various($size, @args)
If the arguments are word or trit objects, they will be packed into a new word of the given size.
If the argument is a single string of decimal digits, optionally preceded by plus or minus, or it is a single Math::BigInt object, it will be converted as in from_int.
If the argument is a single Math::ModInt object, it will be converted as in from_modint.
If the arguments are plain perl scalars, they will be converted as in from_bools.
If the argument is a single string recognized by as_string, it will be converted accordingly.
Math::Logic::Ternary::Word->word_operators returns a list of arrayrefs, each holding an operator signature with five attributes:
Math::Logic::Ternary::Word->word_operators
$name
Operator method name.
$min_args
Number of mandatory arguments.
$var_args
Number of optional arguments.
$ret_vals
Number of returned values.
$is_arith
Arithmetic type: undef for general operators, 0 for balanced arithmetic, 1 for unbalanced arithmetic, 2 for base(-3) arithmetic.
Math::Logic::Ternary::Word->word_formatters returns a list of arrayrefs, each holding a method signature.
Math::Logic::Ternary::Word->word_formatters
These formatters all take no parameters and return a string value. Hence only two attributes are needed to individually describe them:
Formatter method name.
Arithmetic type: undef for general formatters, 0 for balanced arithmetic, 1 for unbalanced arithmetic, 2 for base(-3) arithmetic.
The range of numeric operators is by no means complete. In particular, conversions supporting input and output for binary architectures will have to be added.
Martin Becker <becker-cpan-mp@cozap.com>
Copyright (c) 2012-2017 by Martin Becker, Blaubeuren. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.0 or, at your option, any later version of Perl 5 you may have available.
To install Math::Logic::Ternary, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Math::Logic::Ternary
CPAN shell
perl -MCPAN -e shell install Math::Logic::Ternary
For more information on module installation, please visit the detailed CPAN module installation guide.