Struct Word 

pub struct Word(/* private fields */);

A word, 27 balanced trits.

Stores the numeric value in the host integer; see the module docs. Every value of this type is in range by construction, so value() never returns something out of bounds.

Implementations

impl Word

pub const TRITS: u32 = 27

Number of trits in this type.

pub const MODULUS: i128

3^TRITS, the number of distinct values.

pub const MAX: Self

The largest representable value, (3^n-1)/2.

pub const MIN: Self

The smallest representable value, -(3^n-1)/2.

The range is symmetric, so there is no value whose negation overflows (D-01).

pub const ZERO: Self

Zero.

pub const ONE: Self

One.

pub const NEG_ONE: Self

Negative one.

pub const fn in_range(v: i64) -> bool

True when v is representable in this many trits.

pub const fn new(v: i64) -> Option<Self>

Wraps a host value, or None if out of range.

pub const fn from_value(v: i64) -> Self

Wraps a host value, panicking if out of range.

For constants and tests where the range is known statically.

pub const fn from_i128_wrapping(v: i128) -> Self

Reduces an i128 into range modulo 3^n. Always succeeds.

pub const fn from_i128(v: i128) -> Option<Self>

Reduces an i128 into range, or None if it does not fit.

pub const fn value(self) -> i64

The numeric value.

pub const fn to_i128(self) -> i128

The numeric value widened to i128.

pub const fn trits(self) -> [Trit; 27]

The trits, least significant first.

pub const fn from_trits(trits: [Trit; 27]) -> Self

Rebuilds a value from trits, least significant first.

pub const fn trit(self, index: u32) -> Trit

The trit at index, counting from the least significant.

Panics

If index >= TRITS.

pub const fn to_bct(self) -> u64

Packs into BCT: two bits per trit, least significant trit in the low bits.

pub const fn from_bct(bits: u64) -> Result<Self, NatError>

Unpacks from BCT, rejecting the 10 NaT pattern.

NaT marks poisoned host memory and must never reach a guest, so decoding it is an error rather than a silent zero (D-03).

pub const fn checked_add(self, rhs: Self) -> Option<Self>

Addition, None on overflow.

pub const fn checked_sub(self, rhs: Self) -> Option<Self>

Subtraction, None on overflow.

pub const fn checked_mul(self, rhs: Self) -> Option<Self>

Multiplication, None on overflow.

pub const fn checked_div(self, rhs: Self) -> Option<Self>

Truncating division, None only when rhs is zero.

Division cannot overflow: the range is symmetric, so there is no MIN / -1 case (D-01).

pub const fn checked_rem(self, rhs: Self) -> Option<Self>

Remainder, None only when rhs is zero.

pub const fn neg(self) -> Self

Negation. Cannot overflow; the range is symmetric (D-01).

pub const fn abs(self) -> Self

Absolute value. Total; the range is symmetric (D-01).

pub const fn wrapping_add(self, rhs: Self) -> Self

Addition modulo 3^n.

pub const fn wrapping_sub(self, rhs: Self) -> Self

Subtraction modulo 3^n.

pub const fn checked_shl_trits(self, k: u32) -> Option<Self>

Shift left by k trits, multiplying by 3^k. None on overflow. Exact by construction.

pub const fn shr_trits(self, k: u32) -> Self

Shift right by k trits, dropping the low k digits. This is division by 3^k rounded to nearest: the dropped digits are worth at most (3^k-1)/2, half a unit in the last place.

This is not the host’s /, which truncates toward zero. For 1,598,046,941,971 / 27 truncation leaves a remainder of 19 against a ULP of 27. Implementing this as self.0 / pow3(k) was a bug, caught by truncation_is_round_to_nearest.

Ties cannot occur: 3^k is odd, so twice the remainder never equals it. No round-half-to-even rule is needed.

pub const fn cmp3(self, rhs: Self) -> Trit

Three-way comparison returning one trit (D-06).

Neg for less, Zero for equal, Pos for greater.

pub const fn signum(self) -> Trit

The sign, as a trit.

pub fn map_trits(self, f: impl Fn(Trit) -> Trit) -> Self

Applies a per-trit unary operation.

pub fn zip_trits(self, rhs: Self, f: impl Fn(Trit, Trit) -> Trit) -> Self

Applies a per-trit binary operation, used by MIN and MAX.

pub fn trit_and(self, rhs: Self) -> Self

Per-trit logical AND (minimum).

pub fn trit_or(self, rhs: Self) -> Self

Per-trit logical OR (maximum).

pub fn trit_not(self) -> Self

Per-trit logical NOT. Identical to arithmetic negation, since negating a balanced ternary number flips every digit (D-01).

impl Word

pub const TRYTES: usize = 3

Number of trytes in the representation.

pub const fn tryte(self, index: usize) -> Tryte

Tryte index, counting from the least significant.

Panics

If index >= TRYTES.

pub const fn from_trytes(trytes: [Tryte; 3]) -> Self

Rebuilds a value from its trytes, least significant first.

impl Word

pub const fn wrapping_mul(self, rhs: Self) -> Self

Multiplication modulo 3^n.

impl Word

pub const fn widen(self) -> DoubleWord

Widens to a DoubleWord. Always exact.

pub const fn widening_mul(self, rhs: Self) -> DoubleWord

The exact product of two words, as a double word.

Cannot overflow: the product of two p-trit values is exactly 2p trits, and 27 + 27 is the double-word width. A DoubleWord accumulator therefore holds each product exactly and only the summation rounds (D-02).

Trait Implementations

impl Clone for Word

fn clone(&self) -> Word

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for Word

impl Debug for Word

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

Formats the value using the given formatter.

impl Default for Word

fn default() -> Word

Returns the “default value” for a type.

impl Display for Word

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

Balanced ternary digits, most significant first, T for -1.

impl Eq for Word

impl FromStr for Word

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

Parses balanced ternary digits, most significant first. Underscores are ignored as separators.

type Err = ParseTritsError

The associated error which can be returned from parsing.

impl Hash for Word

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 Neg for Word

type Output = Word

The resulting type after applying the - operator.

fn neg(self) -> Self

Performs the unary - operation.

impl Ord for Word

fn cmp(&self, other: &Word) -> 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 Word

fn eq(&self, other: &Word) -> 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 Word

fn partial_cmp(&self, other: &Word) -> 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 StructuralPartialEq for Word