Struct Ternary 

pub struct Ternary { /* private fields */ }

Represents a balanced ternary number using a sequence of Digits.

Provides functions for creating, parsing, converting, and manipulating balanced ternary numbers.

Implementations

impl Ternary

pub fn new(digits: Vec<Digit>) -> Ternary

Creates a new balanced ternary number from a vector of Digits.

pub fn log(&self) -> usize

Returns the number of digits (length) of the balanced ternary number.

pub fn to_digit_slice(&self) -> &[Digit]

Retrieves a slice containing the digits of the Ternary.

Returns

A slice referencing the digits vec of the Ternary.

This function allows access to the raw representation of the balanced ternary number as a slice of Digit values.

pub fn iter(&self) -> Iter<'_, Digit>

Returns an iterator over the digits from most significant to least significant.

pub fn get_digit(&self, index: usize) -> Option<&Digit>

Returns a reference to the Digit indexed by index if it exists.

Digits are indexed from the right:

use balanced_ternary::Ternary;

// Indexes :
//                              32
//                             4||1
//                            5||||0
//                            ||||||
//                            vvvvvv
let ternary = Ternary::parse("+++--+");
assert_eq!(ternary.get_digit(1).unwrap().to_char(), '-')

pub fn parse(str: &str) -> Self

Parses a string representation of a balanced ternary number into a Ternary object.

Each character in the string must be one of +, 0, or -.

Example

use balanced_ternary::Ternary;

let ternary = "+-0".parse::<Ternary>().unwrap();
assert_eq!(ternary.to_string(), "+-0");

pub fn to_dec(&self) -> i64

Converts the Ternary object to its integer (decimal) representation.

Calculates the sum of each digit’s value multiplied by the appropriate power of 3.

pub fn from_dec(dec: i64) -> Self

Creates a balanced ternary number from a decimal integer.

The input number is converted into its balanced ternary representation, with digits represented as Digits.

pub fn to_unbalanced(&self) -> String

Converts the balanced ternary number to its unbalanced representation as a string.

The unbalanced representation treats the digits as standard ternary (0, 1, 2), instead of balanced ternary (-1, 0, +1). Negative digits are handled by calculating the decimal value of the balanced ternary number and converting it back to an unbalanced ternary string.

Returns:

• String - The unbalanced ternary representation of the number, where each digit is one of 0, 1, or 2.

Example:

use balanced_ternary::Ternary;

let repr = Ternary::parse("+--");
assert_eq!(repr.to_unbalanced(), "12");
assert_eq!(repr.to_dec(), 5);
let repr = Ternary::parse("-++");
assert_eq!(repr.to_unbalanced(), "-12");
assert_eq!(repr.to_dec(), -5);

pub fn from_unbalanced(unbalanced: &str) -> Self

Parses a string representation of an unbalanced ternary number into a Ternary object.

The string must only contain characters valid in the unbalanced ternary numeral system (0, 1, or 2). Each character is directly converted into its decimal value and then interpreted as a balanced ternary number.

Arguments

• unbalanced - A string slice representing the unbalanced ternary number.

Returns

A Ternary object representing the same value as the input string in balanced ternary form.

Panics

This function will panic if the string is not a valid unbalanced ternary number. For instance, if it contains characters other than 0, 1, or 2.

Examples

use balanced_ternary::Ternary;

let ternary = Ternary::from_unbalanced("-12");
assert_eq!(ternary.to_string(), "-++");
assert_eq!(ternary.to_dec(), -5);

pub fn trim(&self) -> Self

Removes leading Zero digits from the Ternary number, effectively trimming it down to its simplest representation. The resulting Ternary number will still represent the same value.

Returns

• Self - A new Ternary object, trimmed of leading zeros.

Examples

use balanced_ternary::{ Neg, Pos, Ternary, Zero};

let ternary = Ternary::new(vec![Zero, Zero, Pos, Neg]);
let trimmed = ternary.trim();
assert_eq!(trimmed.to_string(), "+-");

Notes

This method does not mutate the original Ternary object but returns a new representation.

pub fn with_length(&self, length: usize) -> Self

Adjusts the representation of the Ternary number to have a fixed number of digits.

If the current Ternary has fewer digits than the specified length, leading zero digits will be added to the Ternary to match the desired length. If the current Ternary has more digits than the specified length, it will be returned unmodified.

Arguments

• length - The desired length of the Ternary number.

Returns

• Self - A new Ternary object with the specified fixed length.

Notes

If length is smaller than the existing number of digits, the function does not truncate the number but instead returns the original Ternary unchanged.

Examples

use balanced_ternary::{Ternary, Zero, Pos};

let ternary = Ternary::new(vec![Pos]);
let fixed = ternary.with_length(5);
assert_eq!(fixed.to_string(), "0000+");

let fixed = ternary.with_length(1);
assert_eq!(fixed.to_string(), "+");

pub fn to_string_repr<F: Fn(&Digit) -> char>(&self, transform: F) -> String

Converts the Ternary number into a string representation by applying a given transformation function to each digit of the ternary number.

Arguments

• transform - A function or closure that takes a Digit and returns a char, representing the digit.

Returns

A String-based representation of the Ternary number resulting from applying the transformation to its digits.

Examples

use balanced_ternary::{Digit, Pos, Neg, Zero, Ternary};

let ternary = Ternary::new(vec![Pos, Zero, Neg]);

let custom_repr = ternary.to_string_repr(Digit::to_char_t);
assert_eq!(custom_repr, "10T");
let custom_repr = ternary.to_string_repr(Digit::to_char_theta);
assert_eq!(custom_repr, "10Θ");
let custom_repr = ternary.to_string_repr(Digit::to_char);
assert_eq!(custom_repr, "+0-");

Notes

• The function provides flexibility to define custom string representations for the ternary number digits.
• Call to Ternary::to_string() is equivalent to Ternary::to_string_repr(Digit::to_char).

pub fn concat(&self, other: &Ternary) -> Ternary

Concatenates the current Ternary number with another Ternary number.

This function appends the digits of the provided Ternary object to the digits of the current Ternary object, creating a new Ternary number as the result.

Arguments

• other - A reference to the Ternary number to be concatenated to the current one.

Returns

• Ternary - A new Ternary object formed by concatenating the digits.

Examples

use balanced_ternary::{Ternary, Pos, Zero, Neg};

let ternary1 = Ternary::new(vec![Pos, Zero]);
let ternary2 = Ternary::new(vec![Neg, Pos]);

let concatenated = ternary1.concat(&ternary2);
assert_eq!(concatenated.to_string(), "+0-+");

Trait Implementations

impl Add<&Ternary> for &Ternary

type Output = Ternary

The resulting type after applying the + operator.

fn add(self, rhs: &Ternary) -> Self::Output

Performs the + operation.

impl Add<Digit> for &Ternary

type Output = Ternary

The resulting type after applying the + operator.

fn add(self, rhs: Digit) -> Self::Output

Performs the + operation.

impl BitAnd<&Ternary> for &Ternary

type Output = Ternary

The resulting type after applying the & operator.

fn bitand(self, rhs: &Ternary) -> Self::Output

Performs the & operation.

impl BitOr<&Ternary> for &Ternary

type Output = Ternary

The resulting type after applying the | operator.

fn bitor(self, rhs: &Ternary) -> Self::Output

Performs the | operation.

impl BitXor<&Ternary> for &Ternary

type Output = Ternary

The resulting type after applying the ^ operator.

fn bitxor(self, rhs: &Ternary) -> Self::Output

Performs the ^ operation.

impl Clone for Ternary

fn clone(&self) -> Ternary

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Ternary

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl DigitOperate for Ternary

fn to_digits(&self) -> Vec<Digit>

Returns every individual Digit of this DigitOperate object.

fn digit(&self, index: usize) -> Option<Digit>

Returns one individual Digit ot this DigitOperate object if it exists.

fn each(&self, f: impl Fn(Digit) -> Digit) -> Self

Applies a transformation function to each digit of the balanced ternary number, returning a new DigitOperate object with the transformed digits.

fn each_with(&self, f: impl Fn(Digit, Digit) -> Digit, other: Digit) -> Self

Applies a transformation function to each digit of the balanced ternary number, using an additional parameter for the transformation process, returning a new DigitOperate object with the transformed digits.

fn each_zip(&self, f: impl Fn(Digit, Digit) -> Digit, other: Self) -> Self

Applies a transformation function to each digit of the balanced ternary number, along with a corresponding digit from another DigitOperate number.

fn each_zip_carry( &self, f: impl Fn(Digit, Digit, Digit) -> (Digit, Digit), other: Self, ) -> Self

Applies a transformation function to each digit of the balanced ternary number, along with a corresponding digit from another DigitOperate number, and a carry digit.

impl Display for Ternary

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Div<&Ternary> for &Ternary

type Output = Ternary

The resulting type after applying the / operator.

fn div(self, rhs: &Ternary) -> Self::Output

Performs the / operation.

impl From<&str> for Ternary

fn from(value: &str) -> Self

Converts to this type from the input type.

impl From<DataTernary> for Ternary

fn from(value: DataTernary) -> Self

Converts to this type from the input type.

impl From<String> for Ternary

fn from(value: String) -> Self

Converts to this type from the input type.

impl From<Ter40> for Ternary

fn from(value: Ter40) -> Self

Converts to this type from the input type.

impl From<Ternary> for DataTernary

fn from(value: Ternary) -> Self

Converts to this type from the input type.

impl From<Ternary> for String

fn from(value: Ternary) -> Self

Converts to this type from the input type.

impl From<Ternary> for Ter40

fn from(value: Ternary) -> Self

Converts to this type from the input type.

impl<const SIZE: usize> From<Ternary> for Tryte<SIZE>

fn from(value: Ternary) -> Self

Converts to this type from the input type.

impl From<Ternary> for i64

fn from(value: Ternary) -> Self

Converts to this type from the input type.

impl<const SIZE: usize> From<Tryte<SIZE>> for Ternary

fn from(value: Tryte<SIZE>) -> Self

Converts to this type from the input type.

impl From<i64> for Ternary

fn from(value: i64) -> Self

Converts to this type from the input type.

impl FromStr for Ternary

type Err = ParseTernaryError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for Ternary

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl IntoIterator for Ternary

type Item = Digit

The type of the elements being iterated over.

type IntoIter = IntoIter<Digit>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl Mul<&Ternary> for &Ternary

type Output = Ternary

The resulting type after applying the * operator.

fn mul(self, rhs: &Ternary) -> Self::Output

Performs the * operation.

impl Neg for &Ternary

fn neg(self) -> Self::Output

Returns the negation of the current Ternary object.

Negates each digit in the number.

type Output = Ternary

The resulting type after applying the - operator.

impl Not for &Ternary

type Output = Ternary

The resulting type after applying the ! operator.

fn not(self) -> Self::Output

Performs the unary ! operation.

impl Ord for Ternary

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Ternary

fn eq(&self, other: &Ternary) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Ternary

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Shl<usize> for &Ternary

type Output = Ternary

The resulting type after applying the << operator.

fn shl(self, rhs: usize) -> Self::Output

Performs the << operation.

impl Shr<usize> for &Ternary

type Output = Ternary

The resulting type after applying the >> operator.

fn shr(self, rhs: usize) -> Self::Output

Performs the >> operation.

impl Sub<&Ternary> for &Ternary

type Output = Ternary

The resulting type after applying the - operator.

fn sub(self, rhs: &Ternary) -> Self::Output

Performs the - operation.

impl Sub<Digit> for &Ternary

type Output = Ternary

The resulting type after applying the - operator.

fn sub(self, rhs: Digit) -> Self::Output

Performs the - operation.

impl Eq for Ternary

impl StructuralPartialEq for Ternary