Struct Position 

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

A Position is an index into an MMR’s nodes. This is in contrast to a Location, which is an index into an MMR’s leaves.

Implementations

impl Position

pub const fn new(pos: u64) -> Self

Return a new Position from a raw u64.

pub const fn as_u64(self) -> u64

Return the underlying u64 value.

pub const fn is_valid(self) -> bool

Returns true iff this value is within the valid range (<= MAX_POSITION). This covers both node indices (< MAX_POSITION) and node counts (<= MAX_POSITION).

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

Return self + rhs returning None on overflow or if result exceeds MAX_POSITION.

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

Return self - rhs returning None on underflow.

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

Return self + rhs saturating at MAX_POSITION.

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

Return self - rhs saturating at zero.

pub const fn is_mmr_size(self) -> bool

Returns whether this is a valid MMR size.

The implementation verifies that (1) the size won’t result in overflow and (2) peaks in the MMR of the given size have strictly decreasing height, which is a necessary condition for MMR validity.

Methods from Deref<Target = u64>

pub const MIN: u64 = 0

pub const MAX: u64

pub const BITS: u32

Trait Implementations

impl Add<u64> for Position

Add a position and a u64.

Panics

Panics if the result overflows.

type Output = Position

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add for Position

Add two positions together.

Panics

Panics if the result overflows.

type Output = Position

The resulting type after applying the + operator.

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

Performs the + operation.

impl AddAssign<u64> for Position

Add a u64 to a position.

Panics

Panics if the result overflows.

fn add_assign(&mut self, rhs: u64)

Performs the += operation.

impl AsRef<u64> for Position

fn as_ref(&self) -> &u64

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for Position

fn clone(&self) -> Position

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Position

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

Formats the value using the given formatter.

impl Default for Position

fn default() -> Position

Returns the “default value” for a type.

impl Deref for Position

type Target = u64

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Display for Position

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

Formats the value using the given formatter.

impl EncodeSize for Position

fn encode_size(&self) -> usize

Returns the encoded size of this value (in bytes).

impl From<Position> for u64

fn from(position: Position) -> Self

Converts to this type from the input type.

impl From<u64> for Position

fn from(value: u64) -> Self

Converts to this type from the input type.

impl From<usize> for Position

fn from(value: usize) -> Self

Converts to this type from the input type.

impl Hash for Position

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 Ord for Position

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

fn eq(&self, other: &Position) -> 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 PartialEq<u64> for Position

fn eq(&self, other: &u64) -> 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 PartialEq for Position

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

fn partial_cmp(&self, other: &Position) -> 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 PartialOrd<u64> for Position

fn partial_cmp(&self, other: &u64) -> 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 PartialOrd for Position

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

type Cfg = ()

The Cfg type parameter allows passing configuration during the read process. This is crucial for safely decoding untrusted data, for example, by providing size limits for collections or strings.

fn read_cfg(buf: &mut impl Buf, _: &()) -> Result<Self, Error>

Reads a value from the buffer using the provided configuration cfg.

impl Sub<u64> for Position

Subtract a u64 from a position.

Panics

Panics if the result underflows.

type Output = Position

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub for Position

Subtract two positions.

Panics

Panics if the result underflows.

type Output = Position

The resulting type after applying the - operator.

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

Performs the - operation.

impl SubAssign<u64> for Position

Subtract a u64 from a position.

Panics

Panics if the result underflows.

fn sub_assign(&mut self, rhs: u64)

Performs the -= operation.

impl TryFrom<Location> for Position

Try to convert a leaf Location to its node Position.

Returns super::Error::LocationOverflow if !loc.is_valid().

Examples

use commonware_storage::mmr::{Location, Position, MAX_LOCATION};
use core::convert::TryFrom;

let loc = Location::new(5);
let pos = Position::try_from(loc).unwrap();
assert_eq!(pos, Position::new(8));

// MAX_LOCATION converts successfully (it is the leaf count for 2^62 leaves)
let pos = Position::try_from(MAX_LOCATION).unwrap();
assert!(pos.is_valid());

type Error = Error

The type returned in the event of a conversion error.

fn try_from(loc: Location) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Position> for Location

fn try_from(pos: Position) -> Result<Self, Self::Error>

Attempt to derive the Location of a given node Position.

Returns an error if the position does not correspond to an MMR leaf or if position overflow occurs.

This computation is O(log2(n)) in the given position.

type Error = LocationError

The type returned in the event of a conversion error.

impl Write for Position

fn write(&self, buf: &mut impl BufMut)

Writes the binary representation of self to the provided buffer buf.

impl Copy for Position

impl Eq for Position

impl StructuralPartialEq for Position