tame/tamer/src/iter/collect.rs

142 lines
5.2 KiB
Rust
Raw Normal View History

// Collecting and aggregating iterator values
//
// Copyright (C) 2014-2021 Ryan Specialty Group, LLC.
//
// This file is part of TAME.
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program. If not, see <http://www.gnu.org/licenses/>.
//! A [`FromIterator`] that can fail,
//! along with a [`try_collect`](TryCollect::try_collect) that is
//! analogous to [`collect`](Iterator::collect).
//!
//! Rust's built-in [`Iterator::collect`] is a powerful abstraction that is
//! able to remove a considerable amount of boilerplate and explicit
//! composition,
//! but it cannot handle failures.
//! These traits attempt to stay as faithful as possible to the Rust
//! standard library while permitting (and expecting) failures to occur.
//!
//! See the [parent module](super) for more information.
use super::TrippableIterator;
use std::convert::Infallible;
/// Conversion from an [`Iterator`] that may fail in a controlled way.
///
/// If the conversion cannot fail,
/// use Rust's built-in [`FromIterator`] instead;
/// [`TryFromIterator`] is implemented automatically anything
/// implementing [`FromIterator`].
pub trait TryFromIterator<A>: Sized {
/// Conversation failure.
type Error;
/// Attempts to create a value from an iterator,
/// failing in a controlled manner.
///
/// This is generally called through [`TryCollect::try_collect`].
///
/// See the [module-level documentation](super) for more information.
fn try_from_iter<I: IntoIterator<Item = A>>(
iter: I,
) -> Result<Self, Self::Error>;
}
impl<A, T> TryFromIterator<A> for T
where
T: FromIterator<A>,
{
type Error = Infallible;
/// Create a value from an iterator.
///
/// This is an automatic implementation for anything implementing
/// [`FromIterator`] and cannot fail;
/// it directly invokes [`FromIterator::from_iter`].
fn try_from_iter<I: IntoIterator<Item = A>>(
iter: I,
) -> Result<Self, Infallible> {
Ok(FromIterator::from_iter(iter))
}
}
/// Augment [`Iterator`]s with a [`try_collect`](TryCollect::try_collect)
/// method,
/// which is analogous to [`Iterator::collect`].
///
/// Where [`Iterator::collect`] uses [`FromIterator`],
/// `try_collect` uses [`TryFromIterator`].
pub trait TryCollect: Iterator + Sized {
/// Attempts to transform an iterator into a collection,
/// which may fail in a controlled manner under certain
/// circumstances.
///
/// If this operation is infailliable for all relevant types,
/// use [`Iterator::collect`] instead.
///
/// See the [module-level documentation](super) for more information.
#[inline]
fn try_collect<B: TryFromIterator<Self::Item>>(
self,
) -> Result<B, B::Error> {
TryFromIterator::try_from_iter(self)
}
/// Attempts to transform a [`Result<T, E>`](Result) iterator into a
/// collection of `T`,
/// which may fail in a controlled manner on either the source
/// iterator or the transformation.
///
/// Ideally, this method would not have to exist.
/// However,
/// at the time of writing,
/// `iter.while_ok(TryCollect::try_collect)` fails to compile,
/// requiring instead a more verbose closure.
/// This function exists purely to improve readability and reduce
/// boilerplate,
/// but at the expense of a somewhat confusing return type.
///
/// The outer [`Result`] represents the the source iterator,
/// in the sense of [`TrippableIterator::while_ok`].
/// The inner [`Result`] represents the result of the
/// [`try_collect`](TryCollect::try_collect) operation.
/// Since these two errors types are expected to be unrelated to
/// one-another
/// (after all, [`TrippableIterator`] exists precisely to decouple
/// the downstream iterators from upstream failures),
/// there is no obvious and correct conversion,
/// and so it is left up to the caller.
/// Often,
/// this call is simply suffixed with `??`,
/// leaving the containing function's return type to manage the
/// conversion via [`Into`].
#[inline]
fn try_collect_ok<T, E, B: TryFromIterator<T>>(
mut self,
) -> Result<Result<B, B::Error>, E>
where
Self: Iterator<Item = Result<T, E>>,
{
// At the time of writing,
// `self.while_ok(TryCollect::try_collect)` does not compile,
// stating that `FnOnce` is "not general enough" and appearing
// immune to any attempts to generalize lifetimes using
// higher-rank trait bounds (HRTBs).
self.while_ok(|iter| iter.try_collect())
}
}
impl<I: Iterator> TryCollect for I {}