Struct bee_ternary::Trits

#[repr(transparent)]pub struct Trits<T: RawEncoding + ?Sized = T1B1<Btrit>>(_);

A type that represents a buffer of trits of unknown length.

This type is roughly analogous to [T] or str. It is an unsized type and hence is rarely used directly. Instead, it's more common to see it used from behind a reference (in a similar manner to &[T] and &str.

Implementations

impl<T: ?Sized> Trits<T> where
    T: RawEncoding, 

pub fn empty() -> &'static Self

Create an empty trit slice.

pub unsafe fn from_raw_unchecked(raw: &[i8], num_trits: usize) -> &Self

Interpret an (std::i8) slice as a trit slice with the given encoding without first checking that the slice is valid in the given encoding. The num_trits parameter is used to specify the exact length, in trits, that the slice should be taken to have. Providing a slice that is not valid for this encoding is undefined behaviour.

Panics

This function will panic if num_trits is more than can be represented with the slice in the given encoding.

Safety

This function must only be called with an i8 slice that is valid for this trit encoding given the specified num_trits length. Right now, this validity is not well-defined and so it is suggested that only i8 slices created from existing trit slices or trit buffers be used. Calling this function with an invalid i8 slice is undefined behaviour.

pub unsafe fn from_raw_unchecked_mut(
    raw: &mut [i8],
    num_trits: usize
) -> &mut Self

Interpret a mutable (std::i8) slice as a mutable trit slice with the given encoding without first checking that the slice is valid in the given encoding. The num_trits parameter is used to specify the exact length, in trits, that the slice should be taken to have. Providing a slice that is not valid for this encoding is undefined behaviour.

Panics

This function will panic if num_trits is more than can be represented with the slice in the given encoding.

Safety

This function must only be called with an i8 slice that is valid for this trit encoding given the specified num_trits length. Right now, this validity is not well-defined and so it is suggested that only i8 slices created from existing trit slices or trit buffers be used. Calling this function with an invalid i8 slice is undefined behaviour.

pub fn try_from_raw(raw: &[i8], num_trits: usize) -> Result<&Self, Error>

Interpret an (std::i8) slice as a trit slice with the given encoding, checking to ensure that the slice is valid in the given encoding. The num_trits parameter is used to specify the exact length, in trits, that the slice should be taken to have.

Panics

This function will panic if num_trits is more than can be represented with the slice in the given encoding.

pub fn try_from_raw_mut(
    raw: &mut [i8],
    num_trits: usize
) -> Result<&mut Self, Error>

Interpret a mutable (std::i8) slice as a mutable trit slice with the given encoding, checking to ensure that the slice is valid in the given encoding. The num_trits parameter is used to specify the exact length, in trits, that the slice should be taken to have.

Panics

This function will panic if num_trits is more than can be represented with the slice in the given encoding.

pub fn is_empty(&self) -> bool

Returns true if the trit slice is empty.

pub fn len(&self) -> usize

Returns the number of trits in this trit slice.

pub fn as_i8_slice(&self) -> &[i8]

Interpret this slice as an (std::i8) slice.

Panics

This function will panic if the slice is not byte-aligned.

pub unsafe fn as_i8_slice_mut(&mut self) -> &mut [i8]

Interpret this slice as a mutable (std::i8) slice.

Panics

This function will panic if the slice is not byte-aligned.

Safety

This function is marked unsafe because modification of the trit slice in a manner that is not valid for this encoding is undefined behaviour.

pub unsafe fn get_unchecked(&self, index: usize) -> T::Trit

Fetch the trit at the given index of this trit slice without first checking whether the index is in bounds. Providing an index that is not less than the length of this slice is undefined behaviour.

This is perhaps the 'least bad' unsafe function in this crate: not because any form of undefined behaviour is better or worse than another (after all, the point of undefined behaviour is that it is undefined) but because it's the easiest to use correctly.

Safety

An index with a value less then the result of Trits::len must be used. Any other value is undefined behaviour.

pub unsafe fn set_unchecked(&mut self, index: usize, trit: T::Trit)

Set the trit at the given index of this trit slice without first checking whether the index is in bounds. Providing an index that is not less than the length of this slice is undefined behaviour.

This is perhaps the 'least bad' unsafe function in this crate: not because any form of undefined behaviour is better or worse than another (after all, the point of undefined behaviour is that it is undefined) but because it's the easiest to use correctly.

Safety

An index with a value less then the result of Trits::len must be used. Any other value is undefined behaviour.

pub fn get(&self, index: usize) -> Option<T::Trit>

Fetch the trit at the given index of this trit slice, if the index is valid.

pub fn set(&mut self, index: usize, trit: T::Trit)

Set the trit at the given index of this mutable trit slice, if the index is valid.

Panics

This function will panic if the index is not less than the length of this slice.

pub fn iter(
    &self
) -> impl DoubleEndedIterator<Item = T::Trit> + ExactSizeIterator<Item = T::Trit> + '_

Returns an iterator over the trits in this slice.

Using this function is significantly faster than calling Trits::get in a loop and should be used where possible.

pub fn subslice(&self, range: Range<usize>) -> &Self

Returns a subslice of this slice with the given range of trits.

Panics

This function will panic if called with a range that contains indices outside this slice, or the start of the range is greater than its end.

pub fn subslice_mut(&mut self, range: Range<usize>) -> &mut Self

Returns a mutable subslice of this mutable slice with the given range of trits.

Panics

This function will panic if called with a range that contains indices outside this slice, or the start of the range is greater than its end.

pub fn copy_from<U: RawEncoding<Trit = T::Trit> + ?Sized>(
    &mut self,
    trits: &Trits<U>
)

Copy the trits from a trit slice into this mutable trit slice (the encoding need not be equivalent).

Panics

This function will panic if the length of the slices are different.

pub fn fill(&mut self, trit: T::Trit)

Fill this mutable trit slice with copied of the given trit.

pub fn to_buf<U: RawEncodingBuf<Slice = T>>(&self) -> TritBuf<U>

Copy the contents of this trit slice into a new TritBuf with the same encoding. This function is analogous to to_vec method implemented on ordinary slices.

pub fn chunks(
    &self,
    chunk_len: usize
) -> impl DoubleEndedIterator<Item = &Self> + ExactSizeIterator<Item = &Self> + '_

Return an iterator over distinct, non-overlapping subslices of this trit slice, each with the given chunk length. If the length of the trit slice is not a multiple of the given chunk length, the last slice provided by the iterator will be smaller to compensate.

Panics

This function will panic if the given chunk length is 0.

pub fn encode<U>(&self) -> TritBuf<U> where
    U: RawEncodingBuf,
    U::Slice: RawEncoding<Trit = T::Trit>, 

Encode the contents of this trit slice into a TritBuf with a different encoding.

impl<T: ?Sized> Trits<T> where
    T: RawEncoding<Trit = Btrit>, 

pub fn iter_trytes(
    &self
) -> impl DoubleEndedIterator<Item = Tryte> + ExactSizeIterator<Item = Tryte> + '_

Returns an iterator over the trytes represented within this slice.

For encodings that are representation-compatible with trytes, such as T3B1, use Trits::as_trytes instead since it is faster and more capable.

pub fn negate(&mut self)

Negate each trit in this buffer.

This has the effect of making the trit buffer negative when expressed in numeric form.

impl<T: Trit> Trits<T1B1<T>>

These functions are only implemented for trit slices with the T1B1 encoding because other encodings are compressed and do not support handing out references to their internal trits. T1B1 is an exception because its trits are strictly byte-aligned.

This fact also implies that T1B1 is the fastest encoding for general-purpose manipulation of trits.

pub fn as_raw_slice(&self) -> &[T]

View this trit slice as an ordinary slice of trits.

pub fn as_raw_slice_mut(&mut self) -> &mut [T]

View this mutable trit slice as an ordinary slice of mutable trits.

pub fn chunks_mut(
    &mut self,
    chunk_len: usize
) -> impl Iterator<Item = &mut Self> + '_

Return an iterator over distinct, non-overlapping mutable subslices of this mutable trit slice, each with the given chunk length. If the length of the trit slice is not a multiple of the given chunk length, the last slice provided by the iterator will be smaller to compensate.

Panics

This function will panic if the given chunk length is 0.

pub fn iter_mut(&mut self) -> IterMut<T>

Returns a mutable iterator over the trits in this slice.

Using this function is significantly faster than calling Trits::set in a loop and should be used where possible.

impl Trits<T3B1>

These functions are only implemented for trit slices with the T3B1 encoding because only the T3B1 encoding has a representation compatible with a slice of Trytes. If you find yourself commonly needing to convert between trits and trytes, T3B1 is the encoding to use.

pub fn as_trytes(&self) -> &[Tryte]

Interpret this trit slice as a Tryte slice.

Panics

This function will panic if the length of the slice is not a multiple of 3, or if the slice is not byte-aligned.

pub fn as_trytes_mut(&mut self) -> &mut [Tryte]

Interpret this mutable trit slice as a mutable Tryte slice.

Panics

This function will panic if the length of the slice is not a multiple of 3, or if the slice is not byte-aligned.

Trait Implementations

impl<T: RawEncodingBuf> Borrow<Trits<<T as RawEncodingBuf>::Slice>> for TritBuf<T>

fn borrow(&self) -> &Trits<T::Slice>

Immutably borrows from an owned value.

impl<T: RawEncodingBuf> BorrowMut<Trits<<T as RawEncodingBuf>::Slice>> for TritBuf<T>

fn borrow_mut(&mut self) -> &mut Trits<T::Slice>

Mutably borrows from an owned value.

impl<'a, T: RawEncoding + ?Sized> Debug for &'a Trits<T>

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

Formats the value using the given formatter.

impl<T: RawEncoding + ?Sized> Display for Trits<T>

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

Formats the value using the given formatter.

impl<T: Hash + RawEncoding + ?Sized> Hash for Trits<T>

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, 

Feeds a slice of this type into the given [Hasher].

impl<T: RawEncoding + ?Sized> Index<Range<usize>> for Trits<T>

type Output = Self

The returned type after indexing.

fn index(&self, range: Range<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T: RawEncoding + ?Sized> Index<RangeFrom<usize>> for Trits<T>

type Output = Self

The returned type after indexing.

fn index(&self, range: RangeFrom<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T: RawEncoding + ?Sized> Index<RangeFull> for Trits<T>

type Output = Self

The returned type after indexing.

fn index(&self, _range: RangeFull) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T: RawEncoding + ?Sized> Index<RangeInclusive<usize>> for Trits<T>

type Output = Self

The returned type after indexing.

fn index(&self, range: RangeInclusive<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T: RawEncoding + ?Sized> Index<RangeTo<usize>> for Trits<T>

type Output = Self

The returned type after indexing.

fn index(&self, range: RangeTo<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T: RawEncoding + ?Sized> Index<RangeToInclusive<usize>> for Trits<T>

type Output = Self

The returned type after indexing.

fn index(&self, range: RangeToInclusive<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T: RawEncoding + ?Sized> Index<usize> for Trits<T>

type Output = T::Trit

The returned type after indexing.

fn index(&self, index: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T: RawEncoding + ?Sized> IndexMut<Range<usize>> for Trits<T>

fn index_mut(&mut self, range: Range<usize>) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<T: RawEncoding + ?Sized> IndexMut<RangeFrom<usize>> for Trits<T>

fn index_mut(&mut self, range: RangeFrom<usize>) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<T: RawEncoding + ?Sized> IndexMut<RangeFull> for Trits<T>

fn index_mut(&mut self, _range: RangeFull) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<T: RawEncoding + ?Sized> IndexMut<RangeInclusive<usize>> for Trits<T>

fn index_mut(&mut self, range: RangeInclusive<usize>) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<T: RawEncoding + ?Sized> IndexMut<RangeTo<usize>> for Trits<T>

fn index_mut(&mut self, range: RangeTo<usize>) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<T: RawEncoding + ?Sized> IndexMut<RangeToInclusive<usize>> for Trits<T>

fn index_mut(&mut self, range: RangeToInclusive<usize>) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<T: ?Sized, U: ?Sized> PartialEq<Trits<U>> for Trits<T> where
    T: RawEncoding,
    U: RawEncoding<Trit = T::Trit>, 

fn eq(&self, other: &Trits<U>) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T: ?Sized, U: ?Sized> PartialOrd<Trits<U>> for Trits<T> where
    T: RawEncoding,
    U: RawEncoding<Trit = T::Trit>,
    T::Trit: PartialOrd, 

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

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

#[must_use]fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]fn le(&self, other: &Rhs) -> bool

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

#[must_use]fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]fn ge(&self, other: &Rhs) -> bool

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

impl<T: RawEncoding + ?Sized> ToOwned for Trits<T>

type Owned = TritBuf<T::Buf>

The resulting type after obtaining ownership.

fn to_owned(&self) -> Self::Owned

Creates owned data from borrowed data, usually by cloning.

fn clone_into(&self, target: &mut Self::Owned)

🔬 This is a nightly-only experimental API. (toowned_clone_into)

recently added

Uses borrowed data to replace owned data, usually by cloning.

impl<'a, T: RawEncoding<Trit = Btrit> + ?Sized> TryFrom<&'a Trits<T>> for i128

type Error = Error

The type returned in the event of a conversion error.

fn try_from(trits: &'a Trits<T>) -> Result<Self, Self::Error>

Performs the conversion.

impl<'a, T: RawEncoding<Trit = Btrit> + ?Sized> TryFrom<&'a Trits<T>> for i64

type Error = Error

The type returned in the event of a conversion error.

fn try_from(trits: &'a Trits<T>) -> Result<Self, Self::Error>

Performs the conversion.

impl<'a, T: RawEncoding<Trit = Btrit> + ?Sized> TryFrom<&'a Trits<T>> for i32

type Error = Error

The type returned in the event of a conversion error.

fn try_from(trits: &'a Trits<T>) -> Result<Self, Self::Error>

Performs the conversion.

impl<'a, T: RawEncoding<Trit = Btrit> + ?Sized> TryFrom<&'a Trits<T>> for i16

type Error = Error

The type returned in the event of a conversion error.

fn try_from(trits: &'a Trits<T>) -> Result<Self, Self::Error>

Performs the conversion.

impl<'a, T: RawEncoding<Trit = Btrit> + ?Sized> TryFrom<&'a Trits<T>> for i8

type Error = Error

The type returned in the event of a conversion error.

fn try_from(trits: &'a Trits<T>) -> Result<Self, Self::Error>

Performs the conversion.

impl<'a, T: RawEncoding<Trit = Utrit> + ?Sized> TryFrom<&'a Trits<T>> for u128

type Error = Error

The type returned in the event of a conversion error.

fn try_from(trits: &'a Trits<T>) -> Result<Self, Self::Error>

Performs the conversion.

impl<'a, T: RawEncoding<Trit = Utrit> + ?Sized> TryFrom<&'a Trits<T>> for u64

type Error = Error

The type returned in the event of a conversion error.

fn try_from(trits: &'a Trits<T>) -> Result<Self, Self::Error>

Performs the conversion.

impl<'a, T: RawEncoding<Trit = Utrit> + ?Sized> TryFrom<&'a Trits<T>> for u32

type Error = Error

The type returned in the event of a conversion error.

fn try_from(trits: &'a Trits<T>) -> Result<Self, Self::Error>

Performs the conversion.

impl<'a, T: RawEncoding<Trit = Utrit> + ?Sized> TryFrom<&'a Trits<T>> for u16

type Error = Error

The type returned in the event of a conversion error.

fn try_from(trits: &'a Trits<T>) -> Result<Self, Self::Error>

Performs the conversion.

impl<'a, T: RawEncoding<Trit = Utrit> + ?Sized> TryFrom<&'a Trits<T>> for u8

type Error = Error

The type returned in the event of a conversion error.

fn try_from(trits: &'a Trits<T>) -> Result<Self, Self::Error>

Performs the conversion.