Trait Collection

pub trait Collection {
    type Item;

    // Required methods
    fn len(&self) -> usize;
    fn capacity(&self) -> usize;
    fn extend_object(&mut self, items: &mut dyn Iterator<Item = Self::Item>)
       where Self: AddRemove;
    fn drain<'a>(&'a mut self) -> Box<dyn Iterator<Item = Self::Item> + 'a>
       where Self: AddRemove;
    fn reserve(&mut self, additional: usize)
       where Self: AddRemove;
    fn shrink_to_fit(&mut self)
       where Self: AddRemove;

    // Provided methods
    fn is_empty(&self) -> bool { ... }
    fn append(&mut self, other: &mut Self)
       where Self: Sized + AddRemove { ... }
    fn clear(&mut self)
       where Self: AddRemove { ... }
    fn with_capacity(capacity: usize) -> Self
       where Self: Sized + Default { ... }
    fn into_vec(self) -> Vec<Self::Item>
       where Self: Sized { ... }
}

A collection.

A collection maintains a finite number of items.

Required Associated Types

type Item

The type of the collection’s items.

Required Methods

fn len(&self) -> usize

Returns the number of items in the collection.

fn capacity(&self) -> usize

Returns the number of items the collection can hold without reallocating.

Node-based collections should report a capacity of self.len().

fn extend_object(&mut self, items: &mut dyn Iterator<Item = Self::Item>)

where Self: AddRemove,

Inserts the items yielded by the given iterator into the collection.

This method is provided for use with trait objects, and generic code should prefer Extend::extend, which this method must be equivalent to.

The exact behavior of this method is unspecified, but may be refined by subtraits.

Note that this trait cannot extend Extend due to object-safety limitations.

fn drain<'a>(&'a mut self) -> Box<dyn Iterator<Item = Self::Item> + 'a>

where Self: AddRemove,

Removes all items from the collection and returns an iterator that yields them.

All items are removed even if the iterator is not exhausted. However, the behavior of this method is unspecified if the iterator is leaked (e.g. via mem::forget).

The iteration order is unspecified, but subtraits may place a requirement on it.

self’s capacity should remain the same, when possible.

fn reserve(&mut self, additional: usize)

where Self: AddRemove,

Reserves capacity for the given number of additional items to be inserted into the collection.

This method may do nothing (e.g. for node-based collections).

fn shrink_to_fit(&mut self)

where Self: AddRemove,

Shrinks the collection’s capacity as much as possible.

This method may do nothing (e.g. for node-based collections).

Provided Methods

fn is_empty(&self) -> bool

Checks if the collection contains no items.

fn append(&mut self, other: &mut Self)

where Self: Sized + AddRemove,

Drains the given collection and inserts its items into the collection.

The exact behavior of this method is unspecified, but it must be equivalent to self.extend_object(&mut other.drain()). other’s capacity should remain the same, when possible.

fn clear(&mut self)

where Self: AddRemove,

Removes all items from the collection.

fn with_capacity(capacity: usize) -> Self

where Self: Sized + Default,

Returns a new collection with the given capacity.

Collections (e.g. node-based ones) may ignore the capacity hint.

fn into_vec(self) -> Vec<Self::Item>

where Self: Sized,

Converts the collection into a vector.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl<K: Eq + Hash, V> Collection for HashMap<K, V>

type Item = (K, V)

fn len(&self) -> usize

fn capacity(&self) -> usize

fn append(&mut self, other: &mut Self)

fn extend_object(&mut self, items: &mut dyn Iterator<Item = (K, V)>)

fn clear(&mut self)

fn drain<'a>(&'a mut self) -> Box<dyn Iterator<Item = (K, V)> + 'a>

fn reserve(&mut self, additional: usize)

fn shrink_to_fit(&mut self)

fn with_capacity(capacity: usize) -> Self

fn into_vec(self) -> Vec<(K, V)>

impl<K: Ord, V> Collection for BTreeMap<K, V>

type Item = (K, V)

fn len(&self) -> usize

fn capacity(&self) -> usize

fn append(&mut self, other: &mut Self)

fn extend_object(&mut self, items: &mut dyn Iterator<Item = (K, V)>)

fn clear(&mut self)

fn drain<'a>(&'a mut self) -> Box<dyn Iterator<Item = (K, V)> + 'a>

fn reserve(&mut self, _additional: usize)

fn shrink_to_fit(&mut self)

fn with_capacity(_capacity: usize) -> Self

fn into_vec(self) -> Vec<(K, V)>

impl<T> Collection for [T]

type Item = T

fn len(&self) -> usize

fn capacity(&self) -> usize

fn extend_object(&mut self, _items: &mut dyn Iterator<Item = T>)

where Self: AddRemove,

fn drain<'a>(&'a mut self) -> Box<dyn Iterator<Item = T> + 'a>

where Self: AddRemove,

fn reserve(&mut self, _additional: usize)

where Self: AddRemove,

fn shrink_to_fit(&mut self)

where Self: AddRemove,

impl<T> Collection for LinkedList<T>

type Item = T

fn len(&self) -> usize

fn capacity(&self) -> usize

fn append(&mut self, other: &mut Self)

fn extend_object(&mut self, items: &mut dyn Iterator<Item = T>)

fn clear(&mut self)

fn drain<'a>(&'a mut self) -> Box<dyn Iterator<Item = T> + 'a>

fn reserve(&mut self, _additional: usize)

fn shrink_to_fit(&mut self)

fn with_capacity(_capacity: usize) -> Self

fn into_vec(self) -> Vec<T>

impl<T> Collection for VecDeque<T>

type Item = T

fn len(&self) -> usize

fn capacity(&self) -> usize

fn clear(&mut self)

fn append(&mut self, other: &mut Self)

fn extend_object(&mut self, items: &mut dyn Iterator<Item = T>)

fn drain<'a>(&'a mut self) -> Box<dyn Iterator<Item = T> + 'a>

fn reserve(&mut self, additional: usize)

fn shrink_to_fit(&mut self)

fn with_capacity(capacity: usize) -> Self

fn into_vec(self) -> Vec<T>

impl<T> Collection for Vec<T>

type Item = T

fn len(&self) -> usize

fn capacity(&self) -> usize

fn append(&mut self, other: &mut Self)

fn extend_object(&mut self, items: &mut dyn Iterator<Item = T>)

fn clear(&mut self)

fn drain<'a>(&'a mut self) -> Box<dyn Iterator<Item = T> + 'a>

fn reserve(&mut self, additional: usize)

fn shrink_to_fit(&mut self)

fn with_capacity(capacity: usize) -> Self

fn into_vec(self) -> Vec<T>

impl<T: Eq + Hash> Collection for HashSet<T>

type Item = T

fn len(&self) -> usize

fn capacity(&self) -> usize

fn append(&mut self, other: &mut Self)

fn extend_object(&mut self, items: &mut dyn Iterator<Item = T>)

fn clear(&mut self)

fn drain<'a>(&'a mut self) -> Box<dyn Iterator<Item = T> + 'a>

fn reserve(&mut self, additional: usize)

fn shrink_to_fit(&mut self)

fn with_capacity(capacity: usize) -> Self

fn into_vec(self) -> Vec<T>

impl<T: Ord> Collection for BinaryHeap<T>

type Item = T

fn len(&self) -> usize

fn capacity(&self) -> usize

fn append(&mut self, other: &mut Self)

fn extend_object(&mut self, items: &mut dyn Iterator<Item = T>)

fn clear(&mut self)

fn drain<'a>(&'a mut self) -> Box<dyn Iterator<Item = T> + 'a>

fn reserve(&mut self, additional: usize)

fn shrink_to_fit(&mut self)

fn with_capacity(capacity: usize) -> Self

fn into_vec(self) -> Vec<T>

impl<T: Ord> Collection for BTreeSet<T>

type Item = T

fn len(&self) -> usize

fn capacity(&self) -> usize

fn append(&mut self, other: &mut Self)

fn extend_object(&mut self, items: &mut dyn Iterator<Item = T>)

fn clear(&mut self)

fn drain<'a>(&'a mut self) -> Box<dyn Iterator<Item = T> + 'a>

fn reserve(&mut self, _additional: usize)

fn shrink_to_fit(&mut self)

fn with_capacity(_capacity: usize) -> Self

fn into_vec(self) -> Vec<T>

Implementors