resiter/
lib.rs

1//
2// This Source Code Form is subject to the terms of the Mozilla Public
3// License, v. 2.0. If a copy of the MPL was not distributed with this
4// file, You can obtain one at http://mozilla.org/MPL/2.0/.
5//
6
7//! resiter
8//!
9//! This crate helps iterating over `Iterator<Item = Result<O, E>>`.
10//! All these things are trivial to build yourself, but why invest the effort if you can use a
11//! crate for this?
12//!
13//! # Contributions welcome
14//!
15//! If you have _anything_ that might fit the scope of this crate, don't hesitate opening a
16//! pull-request for it! This is considered a toolkit and convenience-crate, so everything which
17//! might fit its scope should be merged!
18//!
19//! # Dependencies and Feature-gates
20//!
21//! If a feature of this crate uses external dependencies, it should be hidden behind a feature
22//! gate. The crate itself should be usable without any dependencies besides `std`!
23//!
24//! # Features
25//!
26//! Features included in this crate:
27//!
28//! * Unwrap `Result<O, E>`s inside an Iterator
29//! * Select only `Err(_)`s from the Iterator
30//! * Select only `Ok(_)`s from the Iterator
31//! * Do something in the `Err(_)` case, but don't change the error-object
32//! * Do something in the `Ok(_)` case, but don't change the ok-object
33//!
34//! # Usecase
35//!
36//! * Consuming iterators until an error occurs
37//!
38//! ```
39//! use std::str::FromStr;
40//! use resiter::errors::*;
41//!
42//! let _ : Option<::std::num::ParseIntError> = ["1", "2", "foo", "4", "5"]
43//!     .into_iter()
44//!     .map(|e| usize::from_str(e))
45//!     .errors()
46//!     .next(); // "4" and "5" will never be processed by the iterator
47//! ```
48//!
49//! * Consuming iterators and collect all errors
50//!
51//! ```
52//! use std::str::FromStr;
53//! use resiter::errors::*;
54//!
55//! let len = ["1", "2", "foo", "4", "5"]
56//!     .into_iter()
57//!     .map(|e| usize::from_str(e))
58//!     .errors()
59//!     .collect::<Vec<::std::num::ParseIntError>>()
60//!     .len();
61//! assert_eq!(len, 1);
62//! ```
63//!
64//! * Consuming iterators and collect all oks
65//!
66//! ```
67//! use std::str::FromStr;
68//! use resiter::oks::*;
69//!
70//! let len = ["1", "2", "foo", "4", "5"]
71//!     .into_iter()
72//!     .map(|e| usize::from_str(e))
73//!     .oks() // Could also be done with .filter_map(Result::ok)
74//!     .collect::<Vec<_>>()
75//!     .len();
76//! assert_eq!(len, 4);
77//! ```
78//!
79//! * Printing errors / oks
80//!
81//! ```
82//! use std::str::FromStr;
83//! use resiter::oks::*;
84//! use resiter::onerr::*;
85//! use resiter::onok::*;
86//!
87//! let len = ["1", "2", "foo", "4", "5"]
88//!     .into_iter()
89//!     .map(|e| usize::from_str(e))
90//!     .on_err(|e| println!("Error happened: {:?}", e)) // ::std::process::exit(1) possible
91//!     .on_ok(|o| println!("Parsed : '{}'", o))
92//!     .oks()
93//!     .collect::<Vec<_>>()
94//!     .len();
95//! assert_eq!(len, 4);
96//! ```
97//!
98//! * Transforming oks
99//!
100//! ```
101//! use std::str::FromStr;
102//! use resiter::map::*;
103//!
104//! let doubles = ["1", "2", "foo", "4", "5"]
105//!     .into_iter()
106//!     .map(|e| usize::from_str(e))
107//!     .map_ok(|i| 2*i)
108//!     .collect::<Vec<_>>();
109//! assert_eq!(doubles[0], Ok(2));
110//! assert_eq!(doubles[1], Ok(4));
111//! ```
112//!
113//! * Transforming errors
114//!
115//! ```
116//! use std::str::FromStr;
117//! use resiter::map::*;
118//!
119//! let doubles = ["1", "2", "foo", "4", "5"]
120//!     .into_iter()
121//!     .map(|e| usize::from_str(e))
122//!     .map_err(|e| format!("{:?}", e))
123//!     .collect::<Vec<_>>();
124//! assert_eq!(doubles[2], Err("ParseIntError { kind: InvalidDigit }".to_string()));
125//! ```
126//!
127//! * Filtering oks (leaving errors as is)
128//!
129//! ```
130//! use std::str::FromStr;
131//! use resiter::filter::*;
132//!
133//! let doubles = ["1", "2", "foo", "4", "5"]
134//!     .into_iter()
135//!     .map(|e| usize::from_str(e))
136//!     .filter_ok(|i| i%2 == 0)
137//!     .collect::<Vec<_>>();
138//! assert_eq!(doubles.len(), 3);
139//! assert_eq!(doubles[0], Ok(2));
140//! ```
141//!
142//! * Filtering errors (leaving oks as is)
143//!
144//! ```
145//! use std::str::FromStr;
146//! use resiter::filter::*;
147//!
148//! let doubles = ["1", "2", "foo", "4", "5"]
149//!     .into_iter()
150//!     .map(|e| usize::from_str(e))
151//!     .filter_err(|_| false) // filter out all errors
152//!     .collect::<Vec<_>>();
153//! assert_eq!(doubles.len(), 4);
154//! assert_eq!(doubles[2], Ok(4));
155//! ```
156//!
157//! * Stopping the iteration on the first error
158//!
159//! ```
160//! use std::str::FromStr;
161//! use resiter::while_ok::*;
162//!
163//! let res = ["1", "2", "foo", "4", "5"]
164//!     .into_iter()
165//!     .map(|e| usize::from_str(e))
166//!     .while_ok(|i| {
167//!         println!("{} is a usize", i);
168//!     });
169//! if res.is_err() {
170//!     println!("An error occured");
171//! }
172//! ```
173//!
174//! # License
175//!
176//! MPL 2.0
177//!
178
179#![cfg_attr(not(test), no_std)]
180
181pub mod and_then;
182pub mod errors;
183pub mod filter;
184pub mod filter_map;
185pub mod flat_map;
186pub mod flatten;
187pub mod map;
188pub mod ok_or_else;
189pub mod oks;
190pub mod onerr;
191pub mod onok;
192pub mod prelude;
193pub mod try_filter;
194pub mod try_filter_map;
195pub mod try_map;
196pub mod unwrap;
197mod util;
198pub mod while_ok;
199
200pub use and_then::AndThen;
201pub use errors::GetErrors;
202pub use filter::Filter;
203pub use filter_map::FilterMap;
204pub use flat_map::FlatMap;
205pub use flatten::Flatten;
206pub use map::Map;
207pub use ok_or_else::{IterInnerOkOrElse, ResultOptionExt};
208pub use oks::GetOks;
209pub use onerr::OnErrDo;
210pub use onok::OnOkDo;
211pub use try_filter::TryFilter;
212pub use try_filter_map::TryFilterMap;
213pub use try_map::TryMap;
214pub use unwrap::UnwrapWithExt;
215pub use util::{GetErr, GetOk, Process};
216pub use while_ok::WhileOk;
resiter/lib.rs

resiter/
lib.rs
