single 1.0.1

Deprecated poor-man's version of Itertools::at_most_one
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
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

//! THIS CRATE IS DEPRECATED. Use [`Itertools::at_most_one`](https://docs.rs/itertools/latest/itertools/trait.Itertools.html#method.at_most_one) instead.
//!
//! Provides the `Single` trait for extracting the element from a
//! single-element iterator.
//!
//! # Examples
//!
//! ```
//! use single::{ Single, Error };
//! use std::iter;
//!
//! assert_eq!(iter::empty::<i32>().single(), Err(Error::NoElements));
//! assert_eq!(iter::once(0).single(), Ok(0));
//! assert_eq!(iter::repeat(0).single(), Err(Error::MultipleElements));
//! ```

#![cfg_attr(not(feature = "std"), no_std)]
#![forbid(
    missing_debug_implementations,
    unconditional_recursion,
    future_incompatible
)]
#![deny(bad_style, missing_docs, unsafe_code, unused)]
#![allow(deprecated)]
#![deprecated(
    since = "1.0.1",
    note = "use [`Itertools::at_most_one`](https://docs.rs/itertools/latest/itertools/trait.Itertools.html#method.at_most_one) instead"
)]

#[macro_use]
extern crate failure;
#[cfg(not(feature = "std"))]
use core as std;

#[allow(missing_docs)]
#[deprecated(
    since = "1.0.1",
    note = "use [`Itertools::at_most_one`](https://docs.rs/itertools/latest/itertools/trait.Itertools.html#method.at_most_one) instead"
)]
pub trait Single: Iterator {
    /// Get the single element from a single-element iterator.
    ///
    /// # Examples
    ///
    /// ```
    /// # use single::{ Single, Error };
    /// # use std::iter;
    /// assert_eq!(iter::empty::<i32>().single(), Err(Error::NoElements));
    /// assert_eq!(iter::once(0).single(), Ok(0));
    /// assert_eq!(iter::repeat(0).single(), Err(Error::MultipleElements));
    /// ```
    #[deprecated(
        since = "1.0.1",
        note = "use [`Itertools::at_most_one`](https://docs.rs/itertools/latest/itertools/trait.Itertools.html#method.at_most_one) instead"
    )]
    fn single(self) -> Result<Self::Item, Error>;
}

/// An error in the execution of [`Single::single`](trait.Single.html#tymethod.single).
#[derive(Copy, Clone, Eq, PartialEq, Fail)]
pub enum Error {
    /// Asked an empty iterator for the single element.
    #[fail(display = "Called single() on empty iterator")]
    NoElements,

    /// Asked an iterator with multiple elements for the single element.
    #[fail(display = "Called single() on multiple-element iterator")]
    MultipleElements,
}

impl std::fmt::Debug for Error {
    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
        write!(f, "{}", self)
    }
}

impl<I: Iterator> Single for I {
    fn single(mut self) -> Result<Self::Item, Error> {
        match self.next() {
            None => Err(Error::NoElements),
            Some(element) => match self.next() {
                None => Ok(element),
                Some(_) => Err(Error::MultipleElements),
            },
        }
    }
}

#[cfg(test)]
mod test {
    use super::Single;
    use std::iter;

    #[test]
    #[should_panic(expected = "Called single() on empty iterator")]
    fn panic_empty() {
        let _: i32 = iter::empty().single().unwrap();
    }

    #[test]
    #[should_panic(expected = "Called single() on multiple-element iterator")]
    fn panic_multiple() {
        let _ = iter::repeat(0).single().unwrap();
    }
}