diff --git a/eth2/utils/ssz_types/src/bitfield.rs b/eth2/utils/ssz_types/src/bitfield.rs index 465f26f67..23231e09d 100644 --- a/eth2/utils/ssz_types/src/bitfield.rs +++ b/eth2/utils/ssz_types/src/bitfield.rs @@ -5,43 +5,61 @@ use serde_hex::{encode as hex_encode, PrefixedHexVisitor}; use ssz::{Decode, Encode}; use typenum::Unsigned; -/// A marker trait applied to `BitList` and `BitVector` that defines the behaviour of a `Bitfield`. +/// A marker trait applied to `Variable` and `Fixed` that defines the behaviour of a `Bitfield`. pub trait BitfieldBehaviour: Clone {} -/// A marker struct used to declare SSZ `BitList` behaviour on a `Bitfield`. +/// A marker struct used to declare SSZ `Variable` behaviour on a `Bitfield`. /// /// See the [`Bitfield`](struct.Bitfield.html) docs for usage. #[derive(Clone, PartialEq, Debug)] -pub struct BitList { +pub struct Variable { _phantom: PhantomData, } -/// A marker struct used to declare SSZ `BitVector` behaviour on a `Bitfield`. +/// A marker struct used to declare SSZ `Fixed` behaviour on a `Bitfield`. /// /// See the [`Bitfield`](struct.Bitfield.html) docs for usage. #[derive(Clone, PartialEq, Debug)] -pub struct BitVector { +pub struct Fixed { _phantom: PhantomData, } -impl BitfieldBehaviour for BitList {} -impl BitfieldBehaviour for BitVector {} +impl BitfieldBehaviour for Variable {} +impl BitfieldBehaviour for Fixed {} -/// A heap-allocated, ordered, fixed-length, collection of `bool` values. Must be used with the `BitList` or -/// `BitVector` marker structs. +/// A heap-allocated, ordered, variable-length collection of `bool` values, limited to `N` bits. +pub type BitList = Bitfield>; + +/// A heap-allocated, ordered, fixed-length collection of `bool` values, with `N` bits. +/// +/// See [Bitfield](struct.Bitfield.html) documentation. +pub type BitVector = Bitfield>; + +/// A heap-allocated, ordered, fixed-length, collection of `bool` values. Use of +/// [`BitList`](type.BitList.html) or [`BitVector`](type.BitVector.html) type aliases is preferred +/// over direct use of this struct. +/// +/// The `T` type parameter is used to define length behaviour with the `Variable` or `Fixed` marker +/// structs. /// /// The length of the Bitfield is set at instantiation (i.e., runtime, not compile time). However, -/// use with a `BitList` sets a type-level (i.e., compile-time) maximum length and `BitVector` +/// use with a `Variable` sets a type-level (i.e., compile-time) maximum length and `Fixed` /// provides a type-level fixed length. /// /// ## Example +/// +/// The example uses the following crate-level type aliases: +/// +/// - `BitList` is an alias for `Bitfield>` +/// - `BitVector` is an alias for `Bitfield>` +/// /// ``` -/// use ssz_types::{Bitfield, BitVector, BitList, typenum}; +/// use ssz_types::{BitVector, BitList, typenum}; /// /// // `BitList` has a type-level maximum length. The length of the list is specified at runtime /// // and it must be less than or equal to `N`. After instantiation, `BitList` cannot grow or /// // shrink. -/// type BitList8 = Bitfield>; +/// type BitList8 = BitList; /// /// // Creating a `BitList` with a larger-than-`N` capacity returns `None`. /// assert!(BitList8::with_capacity(9).is_none()); @@ -52,7 +70,7 @@ impl BitfieldBehaviour for BitVector {} /// /// // `BitVector` has a type-level fixed length. Unlike `BitList`, it cannot be instantiated with a custom length /// // or grow/shrink. -/// type BitVector8 = Bitfield>; +/// type BitVector8 = BitVector; /// /// let mut bitvector = BitVector8::new(); /// assert_eq!(bitvector.len(), 8); // `BitVector` length is fixed at the type-level. @@ -73,7 +91,7 @@ pub struct Bitfield { _phantom: PhantomData, } -impl Bitfield> { +impl Bitfield> { /// Instantiate with capacity for `num_bits` boolean values. The length cannot be grown or /// shrunk after instantiation. /// @@ -104,11 +122,11 @@ impl Bitfield> { /// /// ## Example /// ``` - /// use ssz_types::{Bitfield, typenum}; + /// use ssz_types::{BitList, typenum}; /// - /// type BitList = Bitfield>; + /// type BitList8 = BitList; /// - /// let b = BitList::with_capacity(4).unwrap(); + /// let b = BitList8::with_capacity(4).unwrap(); /// /// assert_eq!(b.into_bytes(), vec![0b0001_0000]); /// ``` @@ -120,7 +138,7 @@ impl Bitfield> { bytes.insert(0, 0); } - let mut bitfield: Bitfield> = Bitfield::from_raw_bytes(bytes, len + 1) + let mut bitfield: Bitfield> = Bitfield::from_raw_bytes(bytes, len + 1) .expect("Bitfield capacity has been confirmed earlier."); bitfield.set(len, true).expect("Bitfield index must exist."); @@ -132,7 +150,7 @@ impl Bitfield> { /// /// Returns `None` if `bytes` are not a valid encoding. pub fn from_bytes(bytes: Vec) -> Option { - let mut initial_bitfield: Bitfield> = { + let mut initial_bitfield: Bitfield> = { let num_bits = bytes.len() * 8; Bitfield::from_raw_bytes(bytes, num_bits) .expect("Must have adequate bytes for bit count.") @@ -158,7 +176,7 @@ impl Bitfield> { } } -impl Bitfield> { +impl Bitfield> { /// Instantiate a new `Bitfield` with a fixed-length of `N` bits. /// /// All bits are initialized to `false`. @@ -181,11 +199,11 @@ impl Bitfield> { /// /// ## Example /// ``` - /// use ssz_types::{Bitfield, typenum}; + /// use ssz_types::{BitVector, typenum}; /// - /// type BitVector = Bitfield>; + /// type BitVector4 = BitVector; /// - /// assert_eq!(BitVector::new().into_bytes(), vec![0b0000_0000]); + /// assert_eq!(BitVector4::new().into_bytes(), vec![0b0000_0000]); /// ``` pub fn into_bytes(self) -> Vec { self.into_raw_bytes() @@ -200,7 +218,7 @@ impl Bitfield> { } } -impl Default for Bitfield> { +impl Default for Bitfield> { fn default() -> Self { Self::new() } @@ -437,7 +455,7 @@ impl<'a, T: BitfieldBehaviour> Iterator for BitIter<'a, T> { } } -impl Encode for Bitfield> { +impl Encode for Bitfield> { fn is_ssz_fixed_len() -> bool { false } @@ -447,18 +465,18 @@ impl Encode for Bitfield> { } } -impl Decode for Bitfield> { +impl Decode for Bitfield> { fn is_ssz_fixed_len() -> bool { false } fn from_ssz_bytes(bytes: &[u8]) -> Result { Self::from_bytes(bytes.to_vec()) - .ok_or_else(|| ssz::DecodeError::BytesInvalid("BitList failed to decode".to_string())) + .ok_or_else(|| ssz::DecodeError::BytesInvalid("Variable failed to decode".to_string())) } } -impl Encode for Bitfield> { +impl Encode for Bitfield> { fn is_ssz_fixed_len() -> bool { true } @@ -472,18 +490,18 @@ impl Encode for Bitfield> { } } -impl Decode for Bitfield> { +impl Decode for Bitfield> { fn is_ssz_fixed_len() -> bool { false } fn from_ssz_bytes(bytes: &[u8]) -> Result { Self::from_bytes(bytes.to_vec()) - .ok_or_else(|| ssz::DecodeError::BytesInvalid("BitVector failed to decode".to_string())) + .ok_or_else(|| ssz::DecodeError::BytesInvalid("Fixed failed to decode".to_string())) } } -impl Serialize for Bitfield> { +impl Serialize for Bitfield> { /// Serde serialization is compliant with the Ethereum YAML test format. fn serialize(&self, serializer: S) -> Result where @@ -493,7 +511,7 @@ impl Serialize for Bitfield> { } } -impl<'de, N: Unsigned + Clone> Deserialize<'de> for Bitfield> { +impl<'de, N: Unsigned + Clone> Deserialize<'de> for Bitfield> { /// Serde serialization is compliant with the Ethereum YAML test format. fn deserialize(deserializer: D) -> Result where @@ -508,7 +526,7 @@ impl<'de, N: Unsigned + Clone> Deserialize<'de> for Bitfield> { } } -impl Serialize for Bitfield> { +impl Serialize for Bitfield> { /// Serde serialization is compliant with the Ethereum YAML test format. fn serialize(&self, serializer: S) -> Result where @@ -518,7 +536,7 @@ impl Serialize for Bitfield> { } } -impl<'de, N: Unsigned + Clone> Deserialize<'de> for Bitfield> { +impl<'de, N: Unsigned + Clone> Deserialize<'de> for Bitfield> { /// Serde serialization is compliant with the Ethereum YAML test format. fn deserialize(deserializer: D) -> Result where @@ -533,7 +551,7 @@ impl<'de, N: Unsigned + Clone> Deserialize<'de> for Bitfield> { } } -impl tree_hash::TreeHash for Bitfield> { +impl tree_hash::TreeHash for Bitfield> { fn tree_hash_type() -> tree_hash::TreeHashType { tree_hash::TreeHashType::List } @@ -552,7 +570,7 @@ impl tree_hash::TreeHash for Bitfield> { } } -impl tree_hash::TreeHash for Bitfield> { +impl tree_hash::TreeHash for Bitfield> { fn tree_hash_type() -> tree_hash::TreeHashType { // TODO: move this to be a vector. tree_hash::TreeHashType::List @@ -573,7 +591,7 @@ impl tree_hash::TreeHash for Bitfield> { } } -impl cached_tree_hash::CachedTreeHash for Bitfield> { +impl cached_tree_hash::CachedTreeHash for Bitfield> { fn new_tree_hash_cache( &self, depth: usize, @@ -619,7 +637,7 @@ impl cached_tree_hash::CachedTreeHash for Bitfield cached_tree_hash::CachedTreeHash for Bitfield> { +impl cached_tree_hash::CachedTreeHash for Bitfield> { fn new_tree_hash_cache( &self, depth: usize, @@ -653,8 +671,8 @@ impl cached_tree_hash::CachedTreeHash for Bitfield = crate::Bitfield>; pub type BitVector0 = BitVector; pub type BitVector1 = BitVector; pub type BitVector4 = BitVector; @@ -753,8 +771,8 @@ mod bitvector { #[cfg(test)] mod bitlist { use super::*; + use crate::BitList; - pub type BitList = super::Bitfield>; pub type BitList0 = BitList; pub type BitList1 = BitList; pub type BitList8 = BitList; diff --git a/eth2/utils/ssz_types/src/lib.rs b/eth2/utils/ssz_types/src/lib.rs index 42989f173..8e7595d48 100644 --- a/eth2/utils/ssz_types/src/lib.rs +++ b/eth2/utils/ssz_types/src/lib.rs @@ -2,8 +2,8 @@ //! //! - `FixedVector`: A heap-allocated list with a size that is fixed at compile time. //! - `VariableList`: A heap-allocated list that cannot grow past a type-level maximum length. -//! - `Bitfield`: A heap-allocated bitfield that with a type-level _maximum_ length. -//! - `Bitfield`: A heap-allocated bitfield that with a type-level _fixed__ length. +//! - `BitList`: A heap-allocated bitfield that with a type-level _maximum_ length. +//! - `BitVector`: A heap-allocated bitfield that with a type-level _fixed__ length. //! //! These structs are required as SSZ serialization and Merklization rely upon type-level lengths //! for padding and verification. @@ -13,8 +13,8 @@ //! use ssz_types::*; //! //! pub struct Example { -//! bit_vector: Bitfield>, -//! bit_list: Bitfield>, +//! bit_vector: BitVector, +//! bit_list: BitList, //! variable_list: VariableList, //! fixed_vector: FixedVector, //! } @@ -43,6 +43,10 @@ pub use fixed_vector::FixedVector; pub use typenum; pub use variable_list::VariableList; +pub mod length { + pub use crate::bitfield::{Fixed, Variable}; +} + /// Returned when an item encounters an error. #[derive(PartialEq, Debug)] pub enum Error {