Struct GranularId 

pub struct GranularId<T> { /* private fields */ }

The data type GranularId represents any ID which can have an arbitrary granularity, meaning that there is indefinitely many GranularIds in-between any two GranularIds. It is best used with unsized integer types such as u8, u16, u32, u64 and usize, but may be used with other data types implementing the required num_traits bounds.

An ID basically consists of multiple components

Implementations

impl<T> GranularId<T>

where T: SequentialId,

pub fn all_siblings(&self) -> SequentialIds<T>

where T: LowerBounded,

Gets all the siblings of this GranularId, ordered from the smallest sibling to the largest sibling. This is all the GranularIds which starts the same as this GranularId but has its last component changed.

use granular_id::GranularId;
let id = GranularId::from(vec![1u8, 2, 2]); // id 1.2.2
let mut all_siblings = id.all_siblings();
assert_eq!(all_siblings.next().unwrap(), vec![1, 2, 0].into()); // id 1.2.0
assert_eq!(all_siblings.next().unwrap(), vec![1, 2, 1].into()); // id 1.2.1
assert_eq!(all_siblings.next().unwrap(), vec![1, 2, 2].into()); // id 1.2.2
assert_eq!(all_siblings.next().unwrap(), vec![1, 2, 3].into()); // id 1.2.3

pub fn next_siblings(&self) -> SequentialIds<T>

where T: CheckedAdd,

Gets all the next siblings of this GranularId, ordered from the smallest sibling larger than this ID to the largest sibling. This is all the GranularIds which starts the same as this GranularId but has its last component changed to any larger value.

use granular_id::GranularId;
let id = GranularId::from(vec![1u8, 2, 2]); // id 1.2.2
let mut next_siblings = id.next_siblings();
assert_eq!(next_siblings.next().unwrap(), vec![1, 2, 3].into()); // id 1.2.3
assert_eq!(next_siblings.next().unwrap(), vec![1, 2, 4].into()); // id 1.2.4
assert_eq!(next_siblings.next().unwrap(), vec![1, 2, 5].into()); // id 1.2.5
assert_eq!(next_siblings.next().unwrap(), vec![1, 2, 6].into()); // id 1.2.6

pub fn children(&self) -> SequentialIds<T>

where T: LowerBounded,

Gets all direct children of this GranularId, ordered from the smallest child (which is larger than this ID, but smallest out of all children) to the largest child. This is all the GranularIds which starts with this GranularId but has one additional component.

use granular_id::GranularId;
let id = GranularId::from(vec![1u8, 2]); // id 1.2
let mut children = id.children();
assert_eq!(children.next().unwrap(), vec![1, 2, 0].into()); // id 1.2.0
assert_eq!(children.next().unwrap(), vec![1, 2, 1].into()); // id 1.2.1
assert_eq!(children.next().unwrap(), vec![1, 2, 2].into()); // id 1.2.2
assert_eq!(children.next().unwrap(), vec![1, 2, 3].into()); // id 1.2.3

impl<T> GranularId<T>

where T: BackSequentialId,

pub fn previous_siblings(&self) -> BackSequentialIds<T>

where T: Bounded + One + Clone + CheckedSub,

Gets all the previous siblings of this GranularId, ordered from the largest sibling smaller than this ID to the smallest sibling. This is all the GranularIds which starts the same as this GranularId but has its last component changed to any smaller value.

use granular_id::GranularId;
let id = GranularId::from(vec![1u8, 2, 3]); // id 1.2.3
let mut previous_siblings = id.previous_siblings();
assert_eq!(previous_siblings.next().unwrap(), vec![1, 2, 2].into()); // id 1.2.2
assert_eq!(previous_siblings.next().unwrap(), vec![1, 2, 1].into()); // id 1.2.1
assert_eq!(previous_siblings.next().unwrap(), vec![1, 2, 0].into()); // id 1.2.0
assert_eq!(previous_siblings.next(), None); // No more smaller siblings

impl<T> GranularId<T>

pub fn is_max_value(&self) -> bool

where T: UpperBounded + PartialEq,

Checks whether this GranularId is the maximum value of this type. If it is, no other larger GranularIds exist of the same type.

use granular_id::GranularId;
let not_max: GranularId<u8> = vec![254].into();
let max: GranularId<u8> = vec![255].into();
assert!(!not_max.is_max_value());
assert!(max.is_max_value());

pub fn granularity(&self) -> usize

Gets the granularity of this GranularId, which is the number of components it contains, or the “precision” it has

use granular_id::GranularId;
let id: GranularId<u8> = vec![1, 2, 3, 4].into(); // id 1.2.3.4, granularity 4
assert_eq!(id.granularity(), 4);
// Its children should have granularity 5:
assert_eq!(id.children().next().unwrap().granularity(), 5);

pub fn is_root(&self) -> bool

Checks whether this GranularId is the root, which means not having any components.

use granular_id::GranularId;
let not_root: GranularId<u8> = vec![254].into();
let root: GranularId<u8> = vec![].into();
assert!(!not_root.is_root());
assert!(root.is_root());

pub fn into_parent(self) -> Option<Self>

Turns this GranularId into its parent, that is, the same GranularId with the last component removed. If this GranularId is the root (has no components), this function returns the root. For a mutating version, see GranularId::pop, and for a copying version, see GranularId::parent. If this GranularId doesn’t have any components (is the root ID), this function returns None since the root ID doesn’t have a parent.

use granular_id::GranularId;
let id: GranularId<u8> = vec![1, 2, 3].into(); // id 1.2.3
assert_eq!(id.into_parent(), Some(vec![1, 2].into())); // id 1.2

pub fn parent(&self) -> Option<Self>

where T: Clone,

Gets the parent of this GranularId, that is, the same GranularId with the last component removed. If this GranularId doesn’t have any components (is the root ID), this function returns None since the root ID doesn’t have a parent.

use granular_id::GranularId;
let id: GranularId<u8> = vec![1, 2, 3].into(); // id 1.2.3
assert_eq!(id.parent(), Some(vec![1, 2].into())); // id 1.2

pub fn into_ancestors(self) -> Ancestors<T>

Returns an iterator over the ancestors of this GranularId. The iterator will yield all the ancestors, in order from the next-most parent until the root GranularId. This will give the same results as iteratively calling GranularId::parent. This function consumes the GranularId.

 use granular_id::GranularId;
 let id: GranularId<u8> = vec![1, 2, 3].into(); // id 1.2.3
 let mut ancestors = id.into_ancestors();
 assert_eq!(ancestors.next(), Some(vec![1, 2].into())); // id 1.2
 assert_eq!(ancestors.next(), Some(vec![1].into())); // id 1
 assert_eq!(ancestors.next(), Some(vec![].into())); // root id
 assert_eq!(ancestors.next(), None); // There are no more ancestors at this point

pub fn ancestors(&self) -> Ancestors<T>

where T: Clone,

Returns an iterator over the ancestors of this GranularId. The iterator will yield all the ancestors, in order from the next-most parent until the root GranularId. This will give the same results as iteratively calling GranularId::parent.

 use granular_id::GranularId;
 let id: GranularId<u8> = vec![1, 2, 3].into(); // id 1.2.3
 let mut ancestors = id.ancestors();
 assert_eq!(ancestors.next(), Some(vec![1, 2].into())); // id 1.2
 assert_eq!(ancestors.next(), Some(vec![1].into())); // id 1
 assert_eq!(ancestors.next(), Some(vec![].into())); // root id
 assert_eq!(ancestors.next(), None); // There are no more parents at this point

pub fn pop(&mut self) -> Option<T>

Removes the last component of this GranularId. To get the parent of any GranularId without mutating it, see GranularId::parent. The function returns the component popped, akin to Vec::pop, which is None if this GranularId doesn’t have a parent. In that case, this GranularId will remain unchanged as the root.

use granular_id::GranularId;
let mut id: GranularId<u8> = vec![1, 2, 3].into(); // id 1.2.3
assert_eq!(id.pop(), Some(3)); // popping the last component '3'
assert_eq!(id, vec![1, 2].into()); // id 1.2

pub fn push(&mut self, component: T)

where T: UpperBounded + PartialEq,

Pushes a new component to the GranularId, adding it as a new last component. Since the maximum bound for a GranularId of type T is [T::max], if any component is pushed to such an ID, the call doesn’t do anything.

use granular_id::GranularId;
let mut id: GranularId<u8> = vec![1, 2, 3].into(); // id 1.2.3
id.push(4);
assert_eq!(id, vec![1, 2, 3, 4].into()); // id 1.2.3.4

pub fn pushing(&self, component: T) -> Self

where T: UpperBounded + PartialEq + Clone,

Makes a new GranularId, adding the given component as its new last component. Since the maximum bound for a GranularId of type T is [T::max], if any component is pushed to such an ID, the call returns a plain copy of the original GranularId.

use granular_id::GranularId;
let mut id: GranularId<u8> = vec![1, 2, 3].into(); // id 1.2.3
assert_eq!(id.pushing(4), vec![1, 2, 3, 4].into()); // id 1.2.3.4

pub fn append(&mut self, other: GranularId<T>)

where T: UpperBounded + PartialEq,

Appends all components from another GranularId to this GranularId, adding them as a new last components. Since the maximum bound for a GranularId of type T is [T::max], if any components is appended to such an ID, the call doesn’t do anything.

use granular_id::GranularId;
let mut id: GranularId<u8> = vec![1, 2, 3].into(); // id 1.2.3
let id_2 = vec![4, 5, 6].into(); // id 4.5.6
id.append(id_2);
assert_eq!(id, vec![1, 2, 3, 4, 5, 6].into()); // id 1.2.3.4.5.6

pub fn appending(&self, other: GranularId<T>) -> GranularId<T>

where T: UpperBounded + PartialEq + Clone,

Makes a new GranularId, appending all components from another GranularId to that GranularId, adding them as a new last components. Since the maximum bound for a GranularId of type T is [T::max], if any components is appended to such an ID, the call returns a copy of the original GranularId.

use granular_id::GranularId;
let mut id: GranularId<u8> = vec![1, 2, 3].into(); // id 1.2.3
let id_2 = vec![4, 5, 6].into(); // id 4.5.6
assert_eq!(id.appending(id_2), vec![1, 2, 3, 4, 5, 6].into()); // id 1.2.3.4.5.6

pub fn append_vec(&mut self, other: Vec<T>)

where T: UpperBounded + PartialEq,

Appends all components from a Vec to this GranularId, adding them as a new last components. Since the maximum bound for a GranularId of type T is [T::max], if any components is appended to such an ID, the call doesn’t do anything.

use granular_id::GranularId;
let mut id: GranularId<u8> = vec![1, 2, 3].into(); // id 1.2.3
id.append_vec(vec![4, 5, 6]);
assert_eq!(id, vec![1, 2, 3, 4, 5, 6].into()); // id 1.2.3.4.5.6

pub fn appending_vec(&self, other: Vec<T>) -> GranularId<T>

where T: UpperBounded + PartialEq + Clone,

Makes a new GranularId, appending all components from a Vec to that GranularId, adding them as a new last components. Since the maximum bound for a GranularId of type T is [T::max], if any components is appended to such an ID, the call returns a copy of the original GranularId.

use granular_id::GranularId;
let mut id: GranularId<u8> = vec![1, 2, 3].into(); // id 1.2.3
assert_eq!(id.appending_vec(vec![4, 5, 6]), vec![1, 2, 3, 4, 5, 6].into()); // id 1.2.3.4.5.6

pub fn root() -> Self

Gets the root GranularId of any type, that is, a GranularId without any components. That GranularId is the smallest one of that type.

use granular_id::GranularId;
let id: GranularId<u8> = GranularId::root(); // id <root>
assert_eq!(Into::<Vec<u8>>::into(id), vec![]);

Trait Implementations

impl<T: Clone> Clone for GranularId<T>

fn clone(&self) -> GranularId<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for GranularId<T>

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

Formats the value using the given formatter.

impl<T: Default> Default for GranularId<T>

fn default() -> GranularId<T>

Returns the “default value” for a type.

impl<T: Display> Display for GranularId<T>

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

A GranularId is displayed similarly to a version string, where the GranularId created from the vector [1, 2, 3] is displayed as 1.2.3. If the GranularId is the root ID (doesn’t have any components), it is displayed as <root>.

impl<T> From<&[T]> for GranularId<T>

where T: PartialEq + UpperBounded + Clone,

fn from(other: &[T]) -> Self

A slice of components may be turned into a GranularId. Keep in mind that the maximum GranularId of any type T is the one containing just the component T::max, attempting to convert any vector starting with T::max will result in the upper bound GranularId for that type.

impl<T> From<GranularId<T>> for Vec<T>

fn from(other: GranularId<T>) -> Vec<T>

Turns a GranularId into a vector of its components.

impl<T> From<Vec<T>> for GranularId<T>

where T: PartialEq + UpperBounded,

fn from(other: Vec<T>) -> Self

A vector of components may be turned into a GranularId. Keep in mind that the maximum GranularId of any type T is the one containing just the component T::max, attempting to convert any vector starting with T::max will result in the upper bound GranularId for that type.

impl<T: Hash> Hash for GranularId<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, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T> IntoIterator for GranularId<T>

fn into_iter(self) -> Self::IntoIter

Turns this GranularId into an iterator over its components, consuming them.

type Item = T

The type of the elements being iterated over.

type IntoIter = <Vec<T> as IntoIterator>::IntoIter

Which kind of iterator are we turning this into?

impl<T> LowerBounded for GranularId<T>

fn min_value() -> Self

The lower bound for any GranularId (the smallest ID) is the empty ID which contains no components.

impl<T> Ord for GranularId<T>

where T: Ord,

fn cmp(&self, other: &Self) -> Ordering

When comparing two GranularIds, their relative positioning is determined by its first non-matching component. All ID:s starting with 1 is less than all ID:s starting with a 2 and 1.2 is ordered before 1.2.0. Here is an example of some ordered GranularIds:

use num_traits::bounds::LowerBounded;
use granular_id::GranularId;
let vec: Vec<GranularId<u8>> = vec![
    vec![1].into(),         // id 1
    vec![1, 0].into(),      // id 1.0
    vec![1, 1].into(),      // id 1.1
    vec![1, 1, 0].into(),   // id 1.1.0
    vec![1, 1, 1].into(),   // id 1.1.1
    vec![1, 1, 2].into(),   // id 1.1.2
    vec![1, 2].into(),      // id 1.2
    vec![2].into(),         // id 2
];
let mut min = GranularId::min_value();
for id in vec {
    assert!(id > min);
    min = id;
}

For a GranularId to have a total ordering, the component type must also have a total ordering.

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<T: PartialEq> PartialEq for GranularId<T>

fn eq(&self, other: &GranularId<T>) -> 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<T> PartialOrd for GranularId<T>

where T: Ord,

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

Since GranularIds does have a total ordering if and only if its type has a total ordering, this function never returns None and just returns the value GranularId<T>::cmp would return

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<T> UpperBounded for GranularId<T>

where T: UpperBounded,

fn max_value() -> Self

The upper bound for any GranularId (the largest ID) is the empty ID which contains one component, containing the upper bound of the component type.

impl<T: Eq> Eq for GranularId<T>

impl<T> StructuralPartialEq for GranularId<T>