all-the-errors 0.1.0-beta3

Collect all the errors from iterators over results
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

# `all-the-errors`

[![Build Status]][actions] [![Latest Version]][crates_dot_io]

[Build Status]: https://img.shields.io/github/actions/workflow/status/avirshup/all-the-errors/ci.yml?branch=main

[actions]: https://github.com/avirshup/all-the-errors/actions?query=branch%3Amaster

[Latest Version]: https://img.shields.io/crates/v/all-the-errors.svg

[crates_dot_io]: https://crates.io/crates/all-the-errors

![("clean all the things!" meme except it says "collect all the errors!")](img.png) [^memesrc]

[^memesrc]: [meme source](https://hyperboleandahalf.blogspot.com/2010/06/this-is-why-ill-never-be-adult.html)

A silly little trait with a few methods for getting _all_ the errors out of a
`Iterator<Item=Result<T,E>>`.

When you bring the trait `all_the_errors::CollectAllTheErrors` into scope,
it automatically implements 3 methods on `Iterator`s: `partition_results`,
`collect_all_results`, and `collect_oks_or_iter_errs`.

No-std compatible: does not use `std` interally (although it's
mostly _useful_ with allocation, as in the example below).

## Example: collecting into `Vec`s

For clarity, let's assume you want to collect results into `Vec`s
(see the docs for the generic signature).

The methods available on an `iter: Iterable<Item=Result<T, E>>` are:

1. `iter.partition_results() -> (Vec<T>, Vec<E>)`
2. `iter.collected_results() -> Result<Vec<T>, Vec<E>>`
3. `iter.collect_oks_or_iter_errs() -> Result<Vec<T>, impl Iterator<Item=E>>`

For example:

```rust
use all_the_errors::CollectAllTheErrors;

assert_eq!(
    [Ok(1), Ok(2), Err("a"), Err("b")]
        .into_iter()
        .partition_results(),
    (vec![1, 2], vec!["a", "b"])
);

assert_eq!(
    [Ok(1), Ok(2)]
        .into_iter()
        .collected_results(),
    Ok(vec![1, 2])
);

assert_eq!(
    [Ok(1), Ok(2), Err("a"), Err("b")]
        .into_iter()
        .collected_results(),
    Err(vec!["a", "b"])
);
```

## Why?

This is useful because, given the stdlib's trait implementations,
`Iterator::collect` will stop collecting results after the first error.
This allows you to transform, for instance, `Iterator<Item=Result<T, E>>`
into an `Result<Vec<T>, E>` - i.e., either many `T`s or just one `E`.

But sometimes, though, you want all the errors - e.g.,
`Result<Vec<T>, Vec<E>>`, or even a tuple of `(Vec<T>, Vec<E>)`.

`Iterator::partition` can give you
`(Vec<Result<T, E>>, Vec<Result<T,E>>)`, which is annoying
because you have to unwrap everything yourself
_and_ it adds 2 unecessary allocations.

### What about splitting it into 2 different iterators?

## License and Copyright Boilerplate

- **License**:
  This project is provided under the [MIT License](./LICENSE).
- **Copyrightability**:
  All material here was written by (and for) the human authors.
  No LLM-derived content is present in any form.