Takes each element in the Iterator: if it is an Err, no further elements are taken, and the Err is returned. Should no Err occur, a container with the values of each Result is returned.

Here is an example which increments every integer in a vector, checking for overflow:

let v = vec![1, 2];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|
    x.checked_add(1).ok_or("Overflow!")
).collect();
assert_eq!(res, Ok(vec![2, 3]));

Here is another example that tries to subtract one from another list of integers, this time checking for underflow:

let v = vec![1, 2, 0];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|
    x.checked_sub(1).ok_or("Underflow!")
).collect();
assert_eq!(res, Err("Underflow!"));

Here is a variation on the previous example, showing that no further elements are taken from iter after the first Err.

let v = vec![3, 2, 1, 10];
let mut shared = 0;
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| {
    shared += x;
    x.checked_sub(2).ok_or("Underflow!")
}).collect();
assert_eq!(res, Err("Underflow!"));
assert_eq!(shared, 6);

Since the third element caused an underflow, no further elements were taken, so the final value of shared is 6 (= 3 + 2 + 1), not 16.

Takes each element in the Iterator: if it is None, no further elements are taken, and the None is returned. Should no None occur, a container with the values of each Option is returned.

Examples

Here is an example which increments every integer in a vector. We use the checked variant of add that returns None when the calculation would result in an overflow.

let items = vec![0_u16, 1, 2];

let res: Option<Vec<u16>> = items
    .iter()
    .map(|x| x.checked_add(1))
    .collect();

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

As you can see, this will return the expected, valid items.

Here is another example that tries to subtract one from another list of integers, this time checking for underflow:

let items = vec![2_u16, 1, 0];

let res: Option<Vec<u16>> = items
    .iter()
    .map(|x| x.checked_sub(1))
    .collect();

assert_eq!(res, None);

Since the last element is zero, it would underflow. Thus, the resulting value is None.

Here is a variation on the previous example, showing that no further elements are taken from iter after the first None.

let items = vec![3_u16, 2, 1, 10];

let mut shared = 0;

let res: Option<Vec<u16>> = items
    .iter()
    .map(|x| { shared += x; x.checked_sub(2) })
    .collect();

assert_eq!(res, None);
assert_eq!(shared, 6);

Since the third element caused an underflow, no further elements were taken, so the final value of shared is 6 (= 3 + 2 + 1), not 16.

Takes each element in the Iterator and collects it into an Rc<[T]>.

Performance characteristics

The general case

In the general case, collecting into Rc<[T]> is done by first collecting into a Vec<T>. That is, when writing the following:

let evens: Rc<[u8]> = (0..10).filter(|&x| x % 2 == 0).collect();

this behaves as if we wrote:

let evens: Rc<[u8]> = (0..10).filter(|&x| x % 2 == 0)
    .collect::<Vec<_>>() // The first set of allocations happens here.
    .into(); // A second allocation for `Rc<[T]>` happens here.

This will allocate as many times as needed for constructing the Vec<T> and then it will allocate once for turning the Vec<T> into the Rc<[T]>.

Iterators of known length

When your Iterator implements TrustedLen and is of an exact size, a single allocation will be made for the Rc<[T]>. For example:

let evens: Rc<[u8]> = (0..10).collect(); // Just a single allocation happens here.

Takes each element in the Iterator and collects it into an Arc<[T]>.

Performance characteristics

The general case

In the general case, collecting into Arc<[T]> is done by first collecting into a Vec<T>. That is, when writing the following:

let evens: Arc<[u8]> = (0..10).filter(|&x| x % 2 == 0).collect();

this behaves as if we wrote:

let evens: Arc<[u8]> = (0..10).filter(|&x| x % 2 == 0)
    .collect::<Vec<_>>() // The first set of allocations happens here.
    .into(); // A second allocation for `Arc<[T]>` happens here.

This will allocate as many times as needed for constructing the Vec<T> and then it will allocate once for turning the Vec<T> into the Arc<[T]>.

Iterators of known length

When your Iterator implements TrustedLen and is of an exact size, a single allocation will be made for the Arc<[T]>. For example:

let evens: Arc<[u8]> = (0..10).collect(); // Just a single allocation happens here.