Struct CellSlice

pub struct CellSlice<'a> { /* private fields */ }

A read-only view for a subrange of a cell.

Implementations

impl<'a> CellSlice<'a>

pub fn new(cell: &'a DynCell) -> Result<Self, Error>

Constructs a new cell slice from the specified cell. Returns an error if the cell is not ordinary.

pub fn new_allow_exotic(cell: &'a DynCell) -> Self

Constructs a new cell slice from the specified cell.

pub fn apply((range, cell): &'a CellSliceParts) -> Result<Self, Error>

Alias for CellSliceRange::apply.

NOTE: the resulting range will be truncated to cell bounds.

pub fn apply_allow_exotic((range, cell): &'a CellSliceParts) -> Self

Alias for CellSliceRange::apply_allow_exotic.

Safety

The following must be true:

• cell is not pruned
• range is in cell bounds

pub const fn range(&self) -> CellSliceRange

Returns an underlying range indices.

pub const fn cell(&self) -> &'a DynCell

Returns a reference to the underlying cell.

pub fn cell_type(&self) -> CellType

Computes cell type from descriptor bytes.

pub fn level(&self) -> u8

Computes the cell level from the level mask.

pub fn level_mask(&self) -> LevelMask

Computes the level mask from the descriptor bytes.

pub const fn is_empty(&self) -> bool

Returns whether there are no data bits and refs left.

pub const fn is_data_empty(&self) -> bool

Returns whether there are no bits of data left.

Examples

// Cell with empty data
let empty_cell = Cell::empty_cell();
assert!(empty_cell.as_slice()?.is_data_empty());

// Cell with some bits in data
let not_empty_cell = {
    let mut builder = CellBuilder::new();
    builder.store_bit_zero()?;
    builder.build()?
};
assert!(!not_empty_cell.as_slice()?.is_data_empty());

pub const fn is_refs_empty(&self) -> bool

Returns whether there are no references left.

Examples

// Cell without references
let empty_cell = Cell::empty_cell();
assert!(empty_cell.as_slice()?.is_refs_empty());

// Cell with some references
let not_empty_cell = {
    let mut builder = CellBuilder::new();
    builder.store_reference(empty_cell)?;
    builder.build()?
};
assert!(!not_empty_cell.as_slice()?.is_refs_empty());

pub const fn size(&self) -> Size

Returns the number of remaining bits and refs in the slice.

pub const fn size_bits(&self) -> u16

Returns the number of remaining bits of data in the slice.

pub const fn size_refs(&self) -> u8

Returns the number of remaining references in the slice.

pub const fn offset(&self) -> Size

Returns the start of data and reference windows.

pub const fn offset_bits(&self) -> u16

Returns the start of the data window.

Examples

let cell = {
    let mut builder = CellBuilder::new();
    builder.store_zeros(100)?;
    builder.build()?
};
let mut slice = cell.as_slice()?;
slice.load_u8()?;
assert_eq!(slice.offset_bits(), 8);

pub const fn offset_refs(&self) -> u8

Returns the start of the references window.

Examples

let cell = {
    let mut builder = CellBuilder::new();
    builder.store_reference(Cell::empty_cell())?;
    builder.build()?
};
let mut slice = cell.as_slice()?;

slice.load_reference()?;
assert_eq!(slice.offset_refs(), 1);

pub const fn has_remaining(&self, bits: u16, refs: u8) -> bool

Returns true if the slice contains at least bits and refs.

Examples

let cell = {
    let mut builder = CellBuilder::new();
    builder.store_zeros(100)?;
    builder.store_reference(Cell::empty_cell())?;
    builder.store_reference(Cell::empty_cell())?;
    builder.build()?
};
let mut slice = cell.as_slice()?;

assert!(slice.has_remaining(10, 2));
assert!(!slice.has_remaining(500, 2)); // too many bits
assert!(!slice.has_remaining(0, 4)); // too many refs
//

pub fn is_full(&self) -> bool

Returns whether this slice is untouched.

pub fn compute_unique_stats(&self, limit: usize) -> Option<CellTreeStats>

Recursively computes the count of distinct cells returning the total storage used by this dag taking into account the identification of equal cells.

Root slice does not count as cell. A slice subrange of cells is used during computation.

pub fn skip_first(&mut self, bits: u16, refs: u8) -> Result<(), Error>

Tries to advance the start of data and refs windows.

pub fn only_first(&mut self, bits: u16, refs: u8) -> Result<(), Error>

Leaves only the first bits and refs in the slice.

pub fn skip_last(&mut self, bits: u16, refs: u8) -> Result<(), Error>

Removes the last bits and refs from the slice.

pub fn only_last(&mut self, bits: u16, refs: u8) -> Result<(), Error>

Leaves only the last bits and refs in the slice.

pub fn lex_cmp(&self, rhs: &CellSlice<'_>) -> Result<Ordering, Error>

Lexicographically compares slice data.

NOTE: this method is quite computationally heavy as it compares the content of two potentially unaligned slices. Use it with caution or check by cell.

pub fn contents_eq(&self, rhs: &CellSlice<'_>) -> Result<bool, Error>

Returns true if two slices have the same data bits and refs.

NOTE: this method is quite computationally heavy as it compares the content of two potentially unaligned slices. Use it with caution or check by cell.

pub fn get_prefix(&self, bits: u16, refs: u8) -> Self

Returns a slice starting at the same bits and refs offsets, and containing no more than bits of data and refs of children.

pub fn is_data_prefix_of(&self, other: &Self) -> Result<bool, Error>

Returns true if this slice data is a prefix of the other slice data.

pub fn is_data_suffix_of(&self, other: &Self) -> Result<bool, Error>

Returns true if this slice data is a suffix of the other slice data.

pub fn strip_data_prefix<'b>( &self, prefix: &CellSlice<'b>, ) -> Option<CellSlice<'a>>

Returns a subslice with the data prefix removed.

If the slice starts with prefix, returns the subslice after the prefix, wrapped in Some. If prefix is empty, simply returns the original slice.

If the slice does not start with prefix, returns None.

Examples

let cell = {
    let mut builder = CellBuilder::new();
    builder.store_u32(0xdeadbeaf)?;
    builder.build()?
};
let slice = cell.as_slice()?;

let prefix = {
    let mut builder = CellBuilder::new();
    builder.store_u16(0xdead)?;
    builder.build()?
};

let without_prefix = slice.strip_data_prefix(&prefix.as_slice()?).unwrap();
assert_eq!(without_prefix.get_u16(0)?, 0xbeaf);

pub fn longest_common_data_prefix(&self, other: &Self) -> Self

Returns the longest common data prefix.

NOTE: The returned subslice will be a subslice of the current slice.

Examples

let cell = {
    let mut builder = CellBuilder::new();
    builder.store_u32(0xdeadbeaf)?;
    builder.build()?
};
let slice = cell.as_slice()?;

let prefix = {
    let mut builder = CellBuilder::new();
    builder.store_u16(0xdead)?;
    builder.build()?
};

let lcp = slice.longest_common_data_prefix(&prefix.as_slice()?);
assert_eq!(lcp.get_u16(0)?, 0xdead);
assert_eq!(lcp.size_bits(), 16);

pub fn count_leading(&self, bit: bool) -> Result<u16, Error>

Returns the number of leading bits of self.

pub fn count_trailing(&self, bit: bool) -> Result<u16, Error>

Returns the number of trailing bits of self.

pub fn test_uniform(&self) -> Option<bool>

Checks whether the current slice consists of the same bits, returns None if there are 0s and 1s, returns Some(bit) otherwise.

Examples

// Uniform cell consisting of only 0s
let uniform_cell = {
    let mut builder = CellBuilder::new();
    builder.store_zeros(10)?;
    builder.build()?
};
assert_eq!(uniform_cell.as_slice()?.test_uniform(), Some(false));

// Non-uniform cell consisting of 0s and 1s
let non_uniform_cell = {
    let mut builder = CellBuilder::new();
    builder.store_zeros(9)?;
    builder.store_bit_one()?;
    builder.build()?
};
assert_eq!(non_uniform_cell.as_slice()?.test_uniform(), None);

// Empty cell is non-uniform
let non_uniform_cell = Cell::empty_cell();
assert_eq!(non_uniform_cell.as_slice()?.test_uniform(), None);

pub fn get_bit(&self, offset: u16) -> Result<bool, Error>

Tries to read the bit at the specified offset (relative to the current bits window).

pub fn load_bit(&mut self) -> Result<bool, Error>

Tries to read the next bit, incrementing the bits window start.

pub fn get_u8(&self, offset: u16) -> Result<u8, Error>

Reads u8 starting from the offset.

pub fn load_u8(&mut self) -> Result<u8, Error>

Tries to read the next u8, incrementing the bits window start.

pub fn get_u16(&self, offset: u16) -> Result<u16, Error>

Reads u16 starting from the offset.

pub fn load_u16(&mut self) -> Result<u16, Error>

Tries to read the next u16, incrementing the bits window start.

pub fn get_u32(&self, offset: u16) -> Result<u32, Error>

Reads u32 starting from the offset.

pub fn load_u32(&mut self) -> Result<u32, Error>

Tries to read the next u32, incrementing the bits window start.

pub fn get_u64(&self, offset: u16) -> Result<u64, Error>

Reads u64 starting from the offset.

pub fn load_u64(&mut self) -> Result<u64, Error>

Tries to read the next u64, incrementing the bits window start.

pub fn get_u128(&self, offset: u16) -> Result<u128, Error>

Reads u128 starting from the offset.

pub fn load_u128(&mut self) -> Result<u128, Error>

Tries to read the next u128, incrementing the bits window start.

pub fn get_u256(&self, offset: u16) -> Result<HashBytes, Error>

Reads 32 bytes starting from the offset.

pub fn load_u256(&mut self) -> Result<HashBytes, Error>

Tries to read the next 32 bytes, incrementing the bits window start.

pub fn get_small_uint(&self, offset: u16, bits: u16) -> Result<u8, Error>

Returns a small subset of bits (0..=8) starting from the offset.

NOTE: Reading zero bits always succeeds, and reading more than 8 bits always fails.

pub fn load_small_uint(&mut self, bits: u16) -> Result<u8, Error>

Tries to read the next small subset of bits (0..=8), incrementing the bits window start.

NOTE: Reading zero bits always succeeds, and reading more than 8 bits always fails.

pub fn get_uint(&self, offset: u16, bits: u16) -> Result<u64, Error>

Reads u64 from the cell (but only the specified number of bits) starting from the offset.

NOTE: Reading zero bits always succeeds, and reading more than 64 bits always fails.

pub fn load_uint(&mut self, bits: u16) -> Result<u64, Error>

Tries to read the next u64 (but only the specified number of bits), incrementing the bits window start.

NOTE: Reading zero bits always succeeds, and reading more than 64 bits always fails.

pub fn load_bigint(&mut self, bits: u16, signed: bool) -> Result<BigInt, Error>

Loads bits-width int from the slice.

pub fn load_biguint(&mut self, bits: u16) -> Result<BigUint, Error>

Loads bits-width int from the slice.

pub fn load_var_bigint( &mut self, len_bits: u16, signed: bool, ) -> Result<BigInt, Error>

Loads variable length int from the slice.

pub fn load_var_biguint(&mut self, len_bits: u16) -> Result<BigUint, Error>

Loads variable length unsigned int from the slice.

pub fn get_raw<'b>( &self, offset: u16, target: &'b mut [u8], bits: u16, ) -> Result<&'b mut [u8], Error>

Reads the specified number of bits to the target starting from the offset.

pub fn load_raw<'b>( &mut self, target: &'b mut [u8], bits: u16, ) -> Result<&'b mut [u8], Error>

Tries to read the specified number of bits, incrementing the bits window start. Returns the minimum subslice containing all bits.

pub fn load_remaining(&mut self) -> CellSlice<'a>

Reads all remaining bits and refs into the new slice.

pub fn load_prefix(&mut self, bits: u16, refs: u8) -> Result<Self, Error>

Returns the first bits and refs of the slice and advances the start of data and refs windows.

pub fn load_suffix(&mut self, bits: u16, refs: u8) -> Result<Self, Error>

Returns the last bits and refs of the slice and shrinks the data and refs windows.

pub fn get_reference(&self, index: u8) -> Result<&'a DynCell, Error>

Returns a reference to the Nth child cell (relative to this slice’s refs window).

pub fn get_reference_cloned(&self, index: u8) -> Result<Cell, Error>

Returns the Nth child cell (relative to this slice’s refs window).

pub fn get_reference_as_slice(&self, index: u8) -> Result<CellSlice<'a>, Error>

Tries to load the specified child cell as slice. Returns an error if the loaded cell is absent or is pruned.

pub fn references(&self) -> RefsIter<'a>

Creates an iterator through child nodes.

pub fn into_references(self) -> RefsIter<'a>

Converts this slice into an iterator through child nodes.

pub fn without_references(self) -> Self

Returns this slice, but with references skipped.

pub fn load_reference(&mut self) -> Result<&'a DynCell, Error>

Returns a reference to the next child cell (relative to this slice’s refs window), incrementing the refs window start.

pub fn load_reference_cloned(&mut self) -> Result<Cell, Error>

Returns the next child cell (relative to this slice’s refs window), incrementing the refs window start.

pub fn load_reference_as_slice(&mut self) -> Result<CellSlice<'a>, Error>

Tries to load the next child cell as slice. Returns an error if the loaded cell is absent or is pruned.

NOTE: In case of pruned cell access the current slice remains unchanged.

pub fn display_data<'b: 'a>(&'b self) -> DisplayCellSliceData<'b, 'a>

Returns an object which will display data as a bitstring with a termination bit.

Trait Implementations

impl<'a> AsMut<CellSlice<'a>> for CellSlice<'a>

fn as_mut(&mut self) -> &mut CellSlice<'a>

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

impl<'a> AsRef<CellSlice<'a>> for CellSlice<'a>

fn as_ref(&self) -> &CellSlice<'a>

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

impl<'a> Clone for CellSlice<'a>

fn clone(&self) -> CellSlice<'a>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for CellSlice<'a>

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

Formats the value using the given formatter.

impl Default for CellSlice<'_>

fn default() -> Self

Returns the “default value” for a type.

impl ExactSize for CellSlice<'_>

fn exact_size(&self) -> Size

Exact size of the value when it is stored in a slice.

impl<'a> Load<'a> for CellSlice<'a>

fn load_from(slice: &mut CellSlice<'a>) -> Result<Self, Error>

Tries to load itself from a cell slice.

impl<'a> PartialEq for CellSlice<'a>

fn eq(&self, other: &CellSlice<'a>) -> bool

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

const 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 Store for CellSlice<'_>

fn store_into( &self, builder: &mut CellBuilder, _: &dyn CellContext, ) -> Result<(), Error>

Tries to store itself into the cell builder.

impl<'a> Copy for CellSlice<'a>

impl<'a> Eq for CellSlice<'a>

impl<'a> StructuralPartialEq for CellSlice<'a>