Trait VecExt 

pub trait VecExt<T> {
    // Required methods
    fn appended(self, other: &mut Self) -> Self;
    fn cleared(self) -> Self;
    fn deduped(self) -> Self
       where T: PartialEq;
    fn deduped_by<F>(self, same_bucket: F) -> Self
       where F: FnMut(&mut T, &mut T) -> bool;
    fn deduped_by_key<F, K>(self, key: F) -> Self
       where F: FnMut(&mut T) -> K,
             K: PartialEq<K>;
    fn resized(self, new_len: usize, value: T) -> Self
       where T: Clone;
    fn reversed(self) -> Self;
    fn shrinked_to_fit(self) -> Self;
    fn sorted(self) -> Self
       where T: Ord;
    fn sorted_by<F>(self, compare: F) -> Self
       where F: FnMut(&T, &T) -> Ordering;
    fn sorted_by_key<F, K>(self, f: F) -> Self
       where F: FnMut(&T) -> K,
             K: Ord;
    fn truncated(self, len: usize) -> Self;
}

Extension trait that contains functions that allow for chaining of Vec.

Before:

let mut vec = vec![2, 4, 3, 1, 5, 2, 3, 1];

vec.sort();

vec.dedup();

assert_eq!(vec, [1, 2, 3, 4, 5]);

After:

use fenn::VecExt;

let vec = vec![2, 4, 3, 1, 5, 2, 3, 1]
  .sorted()
  .deduped();

assert_eq!(vec, [1, 2, 3, 4, 5]);

Required Methods

fn appended(self, other: &mut Self) -> Self

Moves all the elements of other into Self, leaving other empty.

Panics

Panics if the number of elements in the vector overflows a usize.

Examples

use fenn::VecExt;

let mut vec2 = vec![4, 5, 6];
let vec = vec![1, 2, 3].appended(&mut vec2);

assert_eq!(vec, [1, 2, 3, 4, 5, 6]);
assert_eq!(vec2, []);

fn cleared(self) -> Self

Clears the vector, removing all values.

Note that this method has no effect on the allocated capacity of the vector.

Examples

use fenn::VecExt;

let v = vec![1, 2, 3].cleared();

assert!(v.is_empty());

fn deduped(self) -> Self

where T: PartialEq,

Removes consecutive repeated elements in the vector according to the PartialEq trait implementation.

If the vector is sorted, this removes all duplicates.

Examples

use fenn::VecExt;

let vec = vec![1, 2, 2, 3, 2].deduped();

assert_eq!(vec, [1, 2, 3, 2]);

fn deduped_by<F>(self, same_bucket: F) -> Self

where F: FnMut(&mut T, &mut T) -> bool,

Removes all but the first of consecutive elements in the vector satisfying a given equality relation.

The same_bucket function is passed references to two elements from the vector and must determine if the elements compare equal. The elements are passed in opposite order from their order in the vector, so if same_bucket(a, b) returns true, a is removed.

If the vector is sorted, this removes all duplicates.

Examples

use fenn::VecExt;

let vec = vec!["foo", "bar", "Bar", "baz", "bar"]
    .deduped_by(|a, b| a.eq_ignore_ascii_case(b));

assert_eq!(vec, ["foo", "bar", "baz", "bar"]);

fn deduped_by_key<F, K>(self, key: F) -> Self

where F: FnMut(&mut T) -> K, K: PartialEq<K>,

Removes all but the first of consecutive elements in the vector that resolve to the same key.

If the vector is sorted, this removes all duplicates.

Examples

use fenn::VecExt;

let vec = vec![10, 20, 21, 30, 20].deduped_by_key(|i| *i / 10);

assert_eq!(vec, [10, 20, 30, 20]);

fn resized(self, new_len: usize, value: T) -> Self

where T: Clone,

Resizes the Vec in-place so that len is equal to new_len.

If new_len is greater than len, the Vec is extended by the difference, with each additional slot filled with value. If new_len is less than len, the Vec is simply truncated.

This method requires T to implement Clone, in order to be able to clone the passed value.

Examples

use fenn::VecExt;

let vec = vec!["hello"].resized(3, "world");

assert_eq!(vec, ["hello", "world", "world"]);

use fenn::VecExt;

let vec = vec![1, 2, 3, 4].resized(2, 0);

assert_eq!(vec, [1, 2]);

fn reversed(self) -> Self

Reverses the order of elements in the vector.

Examples

use fenn::VecExt;

let v = vec![1, 2, 3].reversed();

assert!(v == [3, 2, 1]);

fn shrinked_to_fit(self) -> Self

Shrinks the capacity of the vector as much as possible.

It will drop down as close as possible to the length but the allocator may still inform the vector that there is space for a few more elements.

Examples

use fenn::{Peep, VecExt};

let mut vec2 = vec![1, 2, 3];
let vec = Vec::with_capacity(10)
    .appended(&mut vec2)
    .peep(|vec| assert_eq!(vec.capacity(), 10))
    .shrinked_to_fit();

assert!(vec.capacity() >= 3);
assert_eq!(vec2, []);

fn sorted(self) -> Self

where T: Ord,

Sorts the vector.

This sort is stable (i.e., does not reorder equal elements) and O(n * log(n)) worst-case.

Current implementation

The current algorithm is an adaptive, iterative merge sort inspired by timsort. It is designed to be very fast in cases where the vector is nearly sorted, or consists of two or more sorted sequences concatenated one after another.

Also, it allocates temporary storage half the size of self, but for short vectors a non-allocating insertion sort is used instead.

Examples

use fenn::VecExt;

let v = vec![-5, 4, 1, -3, 2].sorted();

assert!(v == [-5, -3, 1, 2, 4]);

fn sorted_by<F>(self, compare: F) -> Self

where F: FnMut(&T, &T) -> Ordering,

Sorts the vector with a comparator function.

This sort is stable (i.e., does not reorder equal elements) and O(n * log(n)) worst-case.

The comparator function must define a total ordering for the elements in the vector. If the ordering is not total, the order of the elements is unspecified. An order is a total order if it is (for all a, b and c):

• total and antisymmetric: exactly one of a < b, a == b or a > b is true, and
• transitive, a < b and b < c implies a < c. The same must hold for both == and >.

For example, while f64 doesn’t implement Ord because NaN != NaN, we can use partial_cmp as our sort function when we know the vector doesn’t contain a NaN.

use fenn::VecExt;

let mut floats = vec![5f64, 4.0, 1.0, 3.0, 2.0]
    .sorted_by(|a, b| a.partial_cmp(b).unwrap());

assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]);

Current implementation

The current algorithm is an adaptive, iterative merge sort inspired by timsort. It is designed to be very fast in cases where the vector is nearly sorted, or consists of two or more sorted sequences concatenated one after another.

Also, it allocates temporary storage half the size of self, but for short vectors a non-allocating insertion sort is used instead.

Examples

use fenn::VecExt;

let mut v = vec![5, 4, 1, 3, 2]
    .sorted_by(|a, b| a.cmp(b));

assert!(v == [1, 2, 3, 4, 5]);

use fenn::VecExt;

// reverse sorting
let v = vec![1, 2, 3, 4, 5]
    .sorted_by(|a, b| b.cmp(a));

assert!(v == [5, 4, 3, 2, 1]);

fn sorted_by_key<F, K>(self, f: F) -> Self

where F: FnMut(&T) -> K, K: Ord,

Sorts the vector with a key extraction function.

This sort is stable (i.e., does not reorder equal elements) and O(m * n * log(n)) worst-case, where the key function is O(m).

Current implementation

The current algorithm is an adaptive, iterative merge sort inspired by timsort. It is designed to be very fast in cases where the vector is nearly sorted, or consists of two or more sorted sequences concatenated one after another.

Also, it allocates temporary storage half the size of self, but for short vectors a non-allocating insertion sort is used instead.

Examples

use fenn::VecExt;

let v = vec![-5i32, 4, 1, -3, 2]
    .sorted_by_key(|k| k.abs());

assert!(v == [1, 2, -3, 4, -5]);

fn truncated(self, len: usize) -> Self

Shortens the vector, keeping the first len elements and dropping the rest.

If len is greater than the vector’s current length, this has no effect.

The drain method can emulate truncate, but causes the excess elements to be returned instead of dropped.

Note that this method has no effect on the allocated capacity of the vector.

Examples

Truncating a five element vector to two elements:

use fenn::VecExt;

let vec = vec![1, 2, 3, 4, 5].truncated(2);

assert_eq!(vec, [1, 2]);

No truncation occurs when len is greater than the vector’s current length:

use fenn::VecExt;

let vec = vec![1, 2, 3].truncated(8);

assert_eq!(vec, [1, 2, 3]);

Truncating when len == 0 is equivalent to calling the cleared method.

use fenn::VecExt;

let vec = vec![1, 2, 3].truncated(0);

assert_eq!(vec, []);

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<T> VecExt<T> for Vec<T>

fn appended(self, other: &mut Self) -> Self

fn cleared(self) -> Self

fn deduped(self) -> Self

where T: PartialEq,

fn deduped_by<F>(self, same_bucket: F) -> Self

where F: FnMut(&mut T, &mut T) -> bool,

fn deduped_by_key<F, K>(self, key: F) -> Self

where F: FnMut(&mut T) -> K, K: PartialEq<K>,

fn resized(self, new_len: usize, value: T) -> Self

where T: Clone,

fn reversed(self) -> Self

fn shrinked_to_fit(self) -> Self

fn sorted(self) -> Self

where T: Ord,

fn sorted_by<F>(self, compare: F) -> Self

where F: FnMut(&T, &T) -> Ordering,

fn sorted_by_key<F, K>(self, f: F) -> Self

where F: FnMut(&T) -> K, K: Ord,

fn truncated(self, len: usize) -> Self

Implementors