either/
lib.rs

1//! The enum [`Either`] with variants `Left` and `Right` is a general purpose
2//! sum type with two cases.
3//!
4//! [`Either`]: enum.Either.html
5//!
6//! **Crate features:**
7//!
8//! * `"use_std"`
9//!   Enabled by default. Disable to make the library `#![no_std]`.
10//!
11//! * `"serde"`
12//!   Disabled by default. Enable to `#[derive(Serialize, Deserialize)]` for `Either`
13//!
14
15#![doc(html_root_url = "https://docs.rs/either/1/")]
16#![no_std]
17
18#[cfg(any(test, feature = "use_std"))]
19extern crate std;
20
21#[cfg(feature = "serde")]
22pub mod serde_untagged;
23
24#[cfg(feature = "serde")]
25pub mod serde_untagged_optional;
26
27use core::convert::{AsMut, AsRef};
28use core::fmt;
29use core::future::Future;
30use core::ops::Deref;
31use core::ops::DerefMut;
32use core::pin::Pin;
33
34#[cfg(any(test, feature = "use_std"))]
35use std::error::Error;
36#[cfg(any(test, feature = "use_std"))]
37use std::io::{self, BufRead, Read, Seek, SeekFrom, Write};
38
39pub use crate::Either::{Left, Right};
40
41/// The enum `Either` with variants `Left` and `Right` is a general purpose
42/// sum type with two cases.
43///
44/// The `Either` type is symmetric and treats its variants the same way, without
45/// preference.
46/// (For representing success or error, use the regular `Result` enum instead.)
47#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
48#[derive(Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
49pub enum Either<L, R> {
50    /// A value of type `L`.
51    Left(L),
52    /// A value of type `R`.
53    Right(R),
54}
55
56/// Evaluate the provided expression for both [`Either::Left`] and [`Either::Right`].
57///
58/// This macro is useful in cases where both sides of [`Either`] can be interacted with
59/// in the same way even though the don't share the same type.
60///
61/// Syntax: `either::for_both!(` *expression* `,` *pattern* `=>` *expression* `)`
62///
63/// # Example
64///
65/// ```
66/// use either::Either;
67///
68/// fn length(owned_or_borrowed: Either<String, &'static str>) -> usize {
69///     either::for_both!(owned_or_borrowed, s => s.len())
70/// }
71///
72/// fn main() {
73///     let borrowed = Either::Right("Hello world!");
74///     let owned = Either::Left("Hello world!".to_owned());
75///
76///     assert_eq!(length(borrowed), 12);
77///     assert_eq!(length(owned), 12);
78/// }
79/// ```
80#[macro_export]
81macro_rules! for_both {
82    ($value:expr, $pattern:pat => $result:expr) => {
83        match $value {
84            $crate::Either::Left($pattern) => $result,
85            $crate::Either::Right($pattern) => $result,
86        }
87    };
88}
89
90/// Macro for unwrapping the left side of an [`Either`], which fails early
91/// with the opposite side. Can only be used in functions that return
92/// `Either` because of the early return of `Right` that it provides.
93///
94/// See also [`try_right!`] for its dual, which applies the same just to the
95/// right side.
96///
97/// # Example
98///
99/// ```
100/// use either::{Either, Left, Right};
101///
102/// fn twice(wrapper: Either<u32, &str>) -> Either<u32, &str> {
103///     let value = either::try_left!(wrapper);
104///     Left(value * 2)
105/// }
106///
107/// fn main() {
108///     assert_eq!(twice(Left(2)), Left(4));
109///     assert_eq!(twice(Right("ups")), Right("ups"));
110/// }
111/// ```
112#[macro_export]
113macro_rules! try_left {
114    ($expr:expr) => {
115        match $expr {
116            $crate::Left(val) => val,
117            $crate::Right(err) => return $crate::Right(::core::convert::From::from(err)),
118        }
119    };
120}
121
122/// Dual to [`try_left!`], see its documentation for more information.
123#[macro_export]
124macro_rules! try_right {
125    ($expr:expr) => {
126        match $expr {
127            $crate::Left(err) => return $crate::Left(::core::convert::From::from(err)),
128            $crate::Right(val) => val,
129        }
130    };
131}
132
133macro_rules! map_either {
134    ($value:expr, $pattern:pat => $result:expr) => {
135        match $value {
136            Left($pattern) => Left($result),
137            Right($pattern) => Right($result),
138        }
139    };
140}
141
142mod iterator;
143pub use self::iterator::IterEither;
144
145mod into_either;
146pub use self::into_either::IntoEither;
147
148impl<L: Clone, R: Clone> Clone for Either<L, R> {
149    fn clone(&self) -> Self {
150        match self {
151            Left(inner) => Left(inner.clone()),
152            Right(inner) => Right(inner.clone()),
153        }
154    }
155
156    fn clone_from(&mut self, source: &Self) {
157        match (self, source) {
158            (Left(dest), Left(source)) => dest.clone_from(source),
159            (Right(dest), Right(source)) => dest.clone_from(source),
160            (dest, source) => *dest = source.clone(),
161        }
162    }
163}
164
165impl<L, R> Either<L, R> {
166    /// Return true if the value is the `Left` variant.
167    ///
168    /// ```
169    /// use either::*;
170    ///
171    /// let values = [Left(1), Right("the right value")];
172    /// assert_eq!(values[0].is_left(), true);
173    /// assert_eq!(values[1].is_left(), false);
174    /// ```
175    pub fn is_left(&self) -> bool {
176        match self {
177            Left(_) => true,
178            Right(_) => false,
179        }
180    }
181
182    /// Return true if the value is the `Right` variant.
183    ///
184    /// ```
185    /// use either::*;
186    ///
187    /// let values = [Left(1), Right("the right value")];
188    /// assert_eq!(values[0].is_right(), false);
189    /// assert_eq!(values[1].is_right(), true);
190    /// ```
191    pub fn is_right(&self) -> bool {
192        !self.is_left()
193    }
194
195    /// Convert the left side of `Either<L, R>` to an `Option<L>`.
196    ///
197    /// ```
198    /// use either::*;
199    ///
200    /// let left: Either<_, ()> = Left("some value");
201    /// assert_eq!(left.left(),  Some("some value"));
202    ///
203    /// let right: Either<(), _> = Right(321);
204    /// assert_eq!(right.left(), None);
205    /// ```
206    pub fn left(self) -> Option<L> {
207        match self {
208            Left(l) => Some(l),
209            Right(_) => None,
210        }
211    }
212
213    /// Convert the right side of `Either<L, R>` to an `Option<R>`.
214    ///
215    /// ```
216    /// use either::*;
217    ///
218    /// let left: Either<_, ()> = Left("some value");
219    /// assert_eq!(left.right(),  None);
220    ///
221    /// let right: Either<(), _> = Right(321);
222    /// assert_eq!(right.right(), Some(321));
223    /// ```
224    pub fn right(self) -> Option<R> {
225        match self {
226            Left(_) => None,
227            Right(r) => Some(r),
228        }
229    }
230
231    /// Convert `&Either<L, R>` to `Either<&L, &R>`.
232    ///
233    /// ```
234    /// use either::*;
235    ///
236    /// let left: Either<_, ()> = Left("some value");
237    /// assert_eq!(left.as_ref(), Left(&"some value"));
238    ///
239    /// let right: Either<(), _> = Right("some value");
240    /// assert_eq!(right.as_ref(), Right(&"some value"));
241    /// ```
242    pub fn as_ref(&self) -> Either<&L, &R> {
243        map_either!(self, inner => inner)
244    }
245
246    /// Convert `&mut Either<L, R>` to `Either<&mut L, &mut R>`.
247    ///
248    /// ```
249    /// use either::*;
250    ///
251    /// fn mutate_left(value: &mut Either<u32, u32>) {
252    ///     if let Some(l) = value.as_mut().left() {
253    ///         *l = 999;
254    ///     }
255    /// }
256    ///
257    /// let mut left = Left(123);
258    /// let mut right = Right(123);
259    /// mutate_left(&mut left);
260    /// mutate_left(&mut right);
261    /// assert_eq!(left, Left(999));
262    /// assert_eq!(right, Right(123));
263    /// ```
264    pub fn as_mut(&mut self) -> Either<&mut L, &mut R> {
265        map_either!(self, inner => inner)
266    }
267
268    /// Convert `Pin<&Either<L, R>>` to `Either<Pin<&L>, Pin<&R>>`,
269    /// pinned projections of the inner variants.
270    pub fn as_pin_ref(self: Pin<&Self>) -> Either<Pin<&L>, Pin<&R>> {
271        // SAFETY: We can use `new_unchecked` because the `inner` parts are
272        // guaranteed to be pinned, as they come from `self` which is pinned.
273        unsafe { map_either!(Pin::get_ref(self), inner => Pin::new_unchecked(inner)) }
274    }
275
276    /// Convert `Pin<&mut Either<L, R>>` to `Either<Pin<&mut L>, Pin<&mut R>>`,
277    /// pinned projections of the inner variants.
278    pub fn as_pin_mut(self: Pin<&mut Self>) -> Either<Pin<&mut L>, Pin<&mut R>> {
279        // SAFETY: `get_unchecked_mut` is fine because we don't move anything.
280        // We can use `new_unchecked` because the `inner` parts are guaranteed
281        // to be pinned, as they come from `self` which is pinned, and we never
282        // offer an unpinned `&mut L` or `&mut R` through `Pin<&mut Self>`. We
283        // also don't have an implementation of `Drop`, nor manual `Unpin`.
284        unsafe { map_either!(Pin::get_unchecked_mut(self), inner => Pin::new_unchecked(inner)) }
285    }
286
287    /// Convert `Either<L, R>` to `Either<R, L>`.
288    ///
289    /// ```
290    /// use either::*;
291    ///
292    /// let left: Either<_, ()> = Left(123);
293    /// assert_eq!(left.flip(), Right(123));
294    ///
295    /// let right: Either<(), _> = Right("some value");
296    /// assert_eq!(right.flip(), Left("some value"));
297    /// ```
298    pub fn flip(self) -> Either<R, L> {
299        match self {
300            Left(l) => Right(l),
301            Right(r) => Left(r),
302        }
303    }
304
305    /// Apply the function `f` on the value in the `Left` variant if it is present rewrapping the
306    /// result in `Left`.
307    ///
308    /// ```
309    /// use either::*;
310    ///
311    /// let left: Either<_, u32> = Left(123);
312    /// assert_eq!(left.map_left(|x| x * 2), Left(246));
313    ///
314    /// let right: Either<u32, _> = Right(123);
315    /// assert_eq!(right.map_left(|x| x * 2), Right(123));
316    /// ```
317    pub fn map_left<F, M>(self, f: F) -> Either<M, R>
318    where
319        F: FnOnce(L) -> M,
320    {
321        match self {
322            Left(l) => Left(f(l)),
323            Right(r) => Right(r),
324        }
325    }
326
327    /// Apply the function `f` on the value in the `Right` variant if it is present rewrapping the
328    /// result in `Right`.
329    ///
330    /// ```
331    /// use either::*;
332    ///
333    /// let left: Either<_, u32> = Left(123);
334    /// assert_eq!(left.map_right(|x| x * 2), Left(123));
335    ///
336    /// let right: Either<u32, _> = Right(123);
337    /// assert_eq!(right.map_right(|x| x * 2), Right(246));
338    /// ```
339    pub fn map_right<F, S>(self, f: F) -> Either<L, S>
340    where
341        F: FnOnce(R) -> S,
342    {
343        match self {
344            Left(l) => Left(l),
345            Right(r) => Right(f(r)),
346        }
347    }
348
349    /// Apply the functions `f` and `g` to the `Left` and `Right` variants
350    /// respectively. This is equivalent to
351    /// [bimap](https://hackage.haskell.org/package/bifunctors-5/docs/Data-Bifunctor.html)
352    /// in functional programming.
353    ///
354    /// ```
355    /// use either::*;
356    ///
357    /// let f = |s: String| s.len();
358    /// let g = |u: u8| u.to_string();
359    ///
360    /// let left: Either<String, u8> = Left("loopy".into());
361    /// assert_eq!(left.map_either(f, g), Left(5));
362    ///
363    /// let right: Either<String, u8> = Right(42);
364    /// assert_eq!(right.map_either(f, g), Right("42".into()));
365    /// ```
366    pub fn map_either<F, G, M, S>(self, f: F, g: G) -> Either<M, S>
367    where
368        F: FnOnce(L) -> M,
369        G: FnOnce(R) -> S,
370    {
371        match self {
372            Left(l) => Left(f(l)),
373            Right(r) => Right(g(r)),
374        }
375    }
376
377    /// Similar to [`map_either`][Self::map_either], with an added context `ctx` accessible to
378    /// both functions.
379    ///
380    /// ```
381    /// use either::*;
382    ///
383    /// let mut sum = 0;
384    ///
385    /// // Both closures want to update the same value, so pass it as context.
386    /// let mut f = |sum: &mut usize, s: String| { *sum += s.len(); s.to_uppercase() };
387    /// let mut g = |sum: &mut usize, u: usize| { *sum += u; u.to_string() };
388    ///
389    /// let left: Either<String, usize> = Left("loopy".into());
390    /// assert_eq!(left.map_either_with(&mut sum, &mut f, &mut g), Left("LOOPY".into()));
391    ///
392    /// let right: Either<String, usize> = Right(42);
393    /// assert_eq!(right.map_either_with(&mut sum, &mut f, &mut g), Right("42".into()));
394    ///
395    /// assert_eq!(sum, 47);
396    /// ```
397    pub fn map_either_with<Ctx, F, G, M, S>(self, ctx: Ctx, f: F, g: G) -> Either<M, S>
398    where
399        F: FnOnce(Ctx, L) -> M,
400        G: FnOnce(Ctx, R) -> S,
401    {
402        match self {
403            Left(l) => Left(f(ctx, l)),
404            Right(r) => Right(g(ctx, r)),
405        }
406    }
407
408    /// Apply one of two functions depending on contents, unifying their result. If the value is
409    /// `Left(L)` then the first function `f` is applied; if it is `Right(R)` then the second
410    /// function `g` is applied.
411    ///
412    /// ```
413    /// use either::*;
414    ///
415    /// fn square(n: u32) -> i32 { (n * n) as i32 }
416    /// fn negate(n: i32) -> i32 { -n }
417    ///
418    /// let left: Either<u32, i32> = Left(4);
419    /// assert_eq!(left.either(square, negate), 16);
420    ///
421    /// let right: Either<u32, i32> = Right(-4);
422    /// assert_eq!(right.either(square, negate), 4);
423    /// ```
424    pub fn either<F, G, T>(self, f: F, g: G) -> T
425    where
426        F: FnOnce(L) -> T,
427        G: FnOnce(R) -> T,
428    {
429        match self {
430            Left(l) => f(l),
431            Right(r) => g(r),
432        }
433    }
434
435    /// Like [`either`][Self::either], but provide some context to whichever of the
436    /// functions ends up being called.
437    ///
438    /// ```
439    /// // In this example, the context is a mutable reference
440    /// use either::*;
441    ///
442    /// let mut result = Vec::new();
443    ///
444    /// let values = vec![Left(2), Right(2.7)];
445    ///
446    /// for value in values {
447    ///     value.either_with(&mut result,
448    ///                       |ctx, integer| ctx.push(integer),
449    ///                       |ctx, real| ctx.push(f64::round(real) as i32));
450    /// }
451    ///
452    /// assert_eq!(result, vec![2, 3]);
453    /// ```
454    pub fn either_with<Ctx, F, G, T>(self, ctx: Ctx, f: F, g: G) -> T
455    where
456        F: FnOnce(Ctx, L) -> T,
457        G: FnOnce(Ctx, R) -> T,
458    {
459        match self {
460            Left(l) => f(ctx, l),
461            Right(r) => g(ctx, r),
462        }
463    }
464
465    /// Apply the function `f` on the value in the `Left` variant if it is present.
466    ///
467    /// ```
468    /// use either::*;
469    ///
470    /// let left: Either<_, u32> = Left(123);
471    /// assert_eq!(left.left_and_then::<_,()>(|x| Right(x * 2)), Right(246));
472    ///
473    /// let right: Either<u32, _> = Right(123);
474    /// assert_eq!(right.left_and_then(|x| Right::<(), _>(x * 2)), Right(123));
475    /// ```
476    pub fn left_and_then<F, S>(self, f: F) -> Either<S, R>
477    where
478        F: FnOnce(L) -> Either<S, R>,
479    {
480        match self {
481            Left(l) => f(l),
482            Right(r) => Right(r),
483        }
484    }
485
486    /// Apply the function `f` on the value in the `Right` variant if it is present.
487    ///
488    /// ```
489    /// use either::*;
490    ///
491    /// let left: Either<_, u32> = Left(123);
492    /// assert_eq!(left.right_and_then(|x| Right(x * 2)), Left(123));
493    ///
494    /// let right: Either<u32, _> = Right(123);
495    /// assert_eq!(right.right_and_then(|x| Right(x * 2)), Right(246));
496    /// ```
497    pub fn right_and_then<F, S>(self, f: F) -> Either<L, S>
498    where
499        F: FnOnce(R) -> Either<L, S>,
500    {
501        match self {
502            Left(l) => Left(l),
503            Right(r) => f(r),
504        }
505    }
506
507    /// Convert the inner value to an iterator.
508    ///
509    /// This requires the `Left` and `Right` iterators to have the same item type.
510    /// See [`factor_into_iter`][Either::factor_into_iter] to iterate different types.
511    ///
512    /// ```
513    /// use either::*;
514    ///
515    /// let left: Either<_, Vec<u32>> = Left(vec![1, 2, 3, 4, 5]);
516    /// let mut right: Either<Vec<u32>, _> = Right(vec![]);
517    /// right.extend(left.into_iter());
518    /// assert_eq!(right, Right(vec![1, 2, 3, 4, 5]));
519    /// ```
520    #[allow(clippy::should_implement_trait)]
521    pub fn into_iter(self) -> Either<L::IntoIter, R::IntoIter>
522    where
523        L: IntoIterator,
524        R: IntoIterator<Item = L::Item>,
525    {
526        map_either!(self, inner => inner.into_iter())
527    }
528
529    /// Borrow the inner value as an iterator.
530    ///
531    /// This requires the `Left` and `Right` iterators to have the same item type.
532    /// See [`factor_iter`][Either::factor_iter] to iterate different types.
533    ///
534    /// ```
535    /// use either::*;
536    ///
537    /// let left: Either<_, &[u32]> = Left(vec![2, 3]);
538    /// let mut right: Either<Vec<u32>, _> = Right(&[4, 5][..]);
539    /// let mut all = vec![1];
540    /// all.extend(left.iter());
541    /// all.extend(right.iter());
542    /// assert_eq!(all, vec![1, 2, 3, 4, 5]);
543    /// ```
544    pub fn iter(&self) -> Either<<&L as IntoIterator>::IntoIter, <&R as IntoIterator>::IntoIter>
545    where
546        for<'a> &'a L: IntoIterator,
547        for<'a> &'a R: IntoIterator<Item = <&'a L as IntoIterator>::Item>,
548    {
549        map_either!(self, inner => inner.into_iter())
550    }
551
552    /// Mutably borrow the inner value as an iterator.
553    ///
554    /// This requires the `Left` and `Right` iterators to have the same item type.
555    /// See [`factor_iter_mut`][Either::factor_iter_mut] to iterate different types.
556    ///
557    /// ```
558    /// use either::*;
559    ///
560    /// let mut left: Either<_, &mut [u32]> = Left(vec![2, 3]);
561    /// for l in left.iter_mut() {
562    ///     *l *= *l
563    /// }
564    /// assert_eq!(left, Left(vec![4, 9]));
565    ///
566    /// let mut inner = [4, 5];
567    /// let mut right: Either<Vec<u32>, _> = Right(&mut inner[..]);
568    /// for r in right.iter_mut() {
569    ///     *r *= *r
570    /// }
571    /// assert_eq!(inner, [16, 25]);
572    /// ```
573    pub fn iter_mut(
574        &mut self,
575    ) -> Either<<&mut L as IntoIterator>::IntoIter, <&mut R as IntoIterator>::IntoIter>
576    where
577        for<'a> &'a mut L: IntoIterator,
578        for<'a> &'a mut R: IntoIterator<Item = <&'a mut L as IntoIterator>::Item>,
579    {
580        map_either!(self, inner => inner.into_iter())
581    }
582
583    /// Converts an `Either` of `Iterator`s to be an `Iterator` of `Either`s
584    ///
585    /// Unlike [`into_iter`][Either::into_iter], this does not require the
586    /// `Left` and `Right` iterators to have the same item type.
587    ///
588    /// ```
589    /// use either::*;
590    /// let left: Either<_, Vec<u8>> = Left(&["hello"]);
591    /// assert_eq!(left.factor_into_iter().next(), Some(Left(&"hello")));
592    ///
593    /// let right: Either<&[&str], _> = Right(vec![0, 1]);
594    /// assert_eq!(right.factor_into_iter().collect::<Vec<_>>(), vec![Right(0), Right(1)]);
595    ///
596    /// ```
597    // TODO(MSRV): doc(alias) was stabilized in Rust 1.48
598    // #[doc(alias = "transpose")]
599    pub fn factor_into_iter(self) -> IterEither<L::IntoIter, R::IntoIter>
600    where
601        L: IntoIterator,
602        R: IntoIterator,
603    {
604        IterEither::new(map_either!(self, inner => inner.into_iter()))
605    }
606
607    /// Borrows an `Either` of `Iterator`s to be an `Iterator` of `Either`s
608    ///
609    /// Unlike [`iter`][Either::iter], this does not require the
610    /// `Left` and `Right` iterators to have the same item type.
611    ///
612    /// ```
613    /// use either::*;
614    /// let left: Either<_, Vec<u8>> = Left(["hello"]);
615    /// assert_eq!(left.factor_iter().next(), Some(Left(&"hello")));
616    ///
617    /// let right: Either<[&str; 2], _> = Right(vec![0, 1]);
618    /// assert_eq!(right.factor_iter().collect::<Vec<_>>(), vec![Right(&0), Right(&1)]);
619    ///
620    /// ```
621    pub fn factor_iter(
622        &self,
623    ) -> IterEither<<&L as IntoIterator>::IntoIter, <&R as IntoIterator>::IntoIter>
624    where
625        for<'a> &'a L: IntoIterator,
626        for<'a> &'a R: IntoIterator,
627    {
628        IterEither::new(map_either!(self, inner => inner.into_iter()))
629    }
630
631    /// Mutably borrows an `Either` of `Iterator`s to be an `Iterator` of `Either`s
632    ///
633    /// Unlike [`iter_mut`][Either::iter_mut], this does not require the
634    /// `Left` and `Right` iterators to have the same item type.
635    ///
636    /// ```
637    /// use either::*;
638    /// let mut left: Either<_, Vec<u8>> = Left(["hello"]);
639    /// left.factor_iter_mut().for_each(|x| *x.unwrap_left() = "goodbye");
640    /// assert_eq!(left, Left(["goodbye"]));
641    ///
642    /// let mut right: Either<[&str; 2], _> = Right(vec![0, 1, 2]);
643    /// right.factor_iter_mut().for_each(|x| if let Right(r) = x { *r = -*r; });
644    /// assert_eq!(right, Right(vec![0, -1, -2]));
645    ///
646    /// ```
647    pub fn factor_iter_mut(
648        &mut self,
649    ) -> IterEither<<&mut L as IntoIterator>::IntoIter, <&mut R as IntoIterator>::IntoIter>
650    where
651        for<'a> &'a mut L: IntoIterator,
652        for<'a> &'a mut R: IntoIterator,
653    {
654        IterEither::new(map_either!(self, inner => inner.into_iter()))
655    }
656
657    /// Return left value or given value
658    ///
659    /// Arguments passed to `left_or` are eagerly evaluated; if you are passing
660    /// the result of a function call, it is recommended to use
661    /// [`left_or_else`][Self::left_or_else], which is lazily evaluated.
662    ///
663    /// # Examples
664    ///
665    /// ```
666    /// # use either::*;
667    /// let left: Either<&str, &str> = Left("left");
668    /// assert_eq!(left.left_or("foo"), "left");
669    ///
670    /// let right: Either<&str, &str> = Right("right");
671    /// assert_eq!(right.left_or("left"), "left");
672    /// ```
673    pub fn left_or(self, other: L) -> L {
674        match self {
675            Either::Left(l) => l,
676            Either::Right(_) => other,
677        }
678    }
679
680    /// Return left or a default
681    ///
682    /// # Examples
683    ///
684    /// ```
685    /// # use either::*;
686    /// let left: Either<String, u32> = Left("left".to_string());
687    /// assert_eq!(left.left_or_default(), "left");
688    ///
689    /// let right: Either<String, u32> = Right(42);
690    /// assert_eq!(right.left_or_default(), String::default());
691    /// ```
692    pub fn left_or_default(self) -> L
693    where
694        L: Default,
695    {
696        match self {
697            Either::Left(l) => l,
698            Either::Right(_) => L::default(),
699        }
700    }
701
702    /// Returns left value or computes it from a closure
703    ///
704    /// # Examples
705    ///
706    /// ```
707    /// # use either::*;
708    /// let left: Either<String, u32> = Left("3".to_string());
709    /// assert_eq!(left.left_or_else(|_| unreachable!()), "3");
710    ///
711    /// let right: Either<String, u32> = Right(3);
712    /// assert_eq!(right.left_or_else(|x| x.to_string()), "3");
713    /// ```
714    pub fn left_or_else<F>(self, f: F) -> L
715    where
716        F: FnOnce(R) -> L,
717    {
718        match self {
719            Either::Left(l) => l,
720            Either::Right(r) => f(r),
721        }
722    }
723
724    /// Return right value or given value
725    ///
726    /// Arguments passed to `right_or` are eagerly evaluated; if you are passing
727    /// the result of a function call, it is recommended to use
728    /// [`right_or_else`][Self::right_or_else], which is lazily evaluated.
729    ///
730    /// # Examples
731    ///
732    /// ```
733    /// # use either::*;
734    /// let right: Either<&str, &str> = Right("right");
735    /// assert_eq!(right.right_or("foo"), "right");
736    ///
737    /// let left: Either<&str, &str> = Left("left");
738    /// assert_eq!(left.right_or("right"), "right");
739    /// ```
740    pub fn right_or(self, other: R) -> R {
741        match self {
742            Either::Left(_) => other,
743            Either::Right(r) => r,
744        }
745    }
746
747    /// Return right or a default
748    ///
749    /// # Examples
750    ///
751    /// ```
752    /// # use either::*;
753    /// let left: Either<String, u32> = Left("left".to_string());
754    /// assert_eq!(left.right_or_default(), u32::default());
755    ///
756    /// let right: Either<String, u32> = Right(42);
757    /// assert_eq!(right.right_or_default(), 42);
758    /// ```
759    pub fn right_or_default(self) -> R
760    where
761        R: Default,
762    {
763        match self {
764            Either::Left(_) => R::default(),
765            Either::Right(r) => r,
766        }
767    }
768
769    /// Returns right value or computes it from a closure
770    ///
771    /// # Examples
772    ///
773    /// ```
774    /// # use either::*;
775    /// let left: Either<String, u32> = Left("3".to_string());
776    /// assert_eq!(left.right_or_else(|x| x.parse().unwrap()), 3);
777    ///
778    /// let right: Either<String, u32> = Right(3);
779    /// assert_eq!(right.right_or_else(|_| unreachable!()), 3);
780    /// ```
781    pub fn right_or_else<F>(self, f: F) -> R
782    where
783        F: FnOnce(L) -> R,
784    {
785        match self {
786            Either::Left(l) => f(l),
787            Either::Right(r) => r,
788        }
789    }
790
791    /// Returns the left value
792    ///
793    /// # Examples
794    ///
795    /// ```
796    /// # use either::*;
797    /// let left: Either<_, ()> = Left(3);
798    /// assert_eq!(left.unwrap_left(), 3);
799    /// ```
800    ///
801    /// # Panics
802    ///
803    /// When `Either` is a `Right` value
804    ///
805    /// ```should_panic
806    /// # use either::*;
807    /// let right: Either<(), _> = Right(3);
808    /// right.unwrap_left();
809    /// ```
810    pub fn unwrap_left(self) -> L
811    where
812        R: core::fmt::Debug,
813    {
814        match self {
815            Either::Left(l) => l,
816            Either::Right(r) => {
817                panic!("called `Either::unwrap_left()` on a `Right` value: {:?}", r)
818            }
819        }
820    }
821
822    /// Returns the right value
823    ///
824    /// # Examples
825    ///
826    /// ```
827    /// # use either::*;
828    /// let right: Either<(), _> = Right(3);
829    /// assert_eq!(right.unwrap_right(), 3);
830    /// ```
831    ///
832    /// # Panics
833    ///
834    /// When `Either` is a `Left` value
835    ///
836    /// ```should_panic
837    /// # use either::*;
838    /// let left: Either<_, ()> = Left(3);
839    /// left.unwrap_right();
840    /// ```
841    pub fn unwrap_right(self) -> R
842    where
843        L: core::fmt::Debug,
844    {
845        match self {
846            Either::Right(r) => r,
847            Either::Left(l) => panic!("called `Either::unwrap_right()` on a `Left` value: {:?}", l),
848        }
849    }
850
851    /// Returns the left value
852    ///
853    /// # Examples
854    ///
855    /// ```
856    /// # use either::*;
857    /// let left: Either<_, ()> = Left(3);
858    /// assert_eq!(left.expect_left("value was Right"), 3);
859    /// ```
860    ///
861    /// # Panics
862    ///
863    /// When `Either` is a `Right` value
864    ///
865    /// ```should_panic
866    /// # use either::*;
867    /// let right: Either<(), _> = Right(3);
868    /// right.expect_left("value was Right");
869    /// ```
870    pub fn expect_left(self, msg: &str) -> L
871    where
872        R: core::fmt::Debug,
873    {
874        match self {
875            Either::Left(l) => l,
876            Either::Right(r) => panic!("{}: {:?}", msg, r),
877        }
878    }
879
880    /// Returns the right value
881    ///
882    /// # Examples
883    ///
884    /// ```
885    /// # use either::*;
886    /// let right: Either<(), _> = Right(3);
887    /// assert_eq!(right.expect_right("value was Left"), 3);
888    /// ```
889    ///
890    /// # Panics
891    ///
892    /// When `Either` is a `Left` value
893    ///
894    /// ```should_panic
895    /// # use either::*;
896    /// let left: Either<_, ()> = Left(3);
897    /// left.expect_right("value was Right");
898    /// ```
899    pub fn expect_right(self, msg: &str) -> R
900    where
901        L: core::fmt::Debug,
902    {
903        match self {
904            Either::Right(r) => r,
905            Either::Left(l) => panic!("{}: {:?}", msg, l),
906        }
907    }
908
909    /// Convert the contained value into `T`
910    ///
911    /// # Examples
912    ///
913    /// ```
914    /// # use either::*;
915    /// // Both u16 and u32 can be converted to u64.
916    /// let left: Either<u16, u32> = Left(3u16);
917    /// assert_eq!(left.either_into::<u64>(), 3u64);
918    /// let right: Either<u16, u32> = Right(7u32);
919    /// assert_eq!(right.either_into::<u64>(), 7u64);
920    /// ```
921    pub fn either_into<T>(self) -> T
922    where
923        L: Into<T>,
924        R: Into<T>,
925    {
926        for_both!(self, inner => inner.into())
927    }
928}
929
930impl<L, R> Either<Option<L>, Option<R>> {
931    /// Factors out `None` from an `Either` of [`Option`].
932    ///
933    /// ```
934    /// use either::*;
935    /// let left: Either<_, Option<String>> = Left(Some(vec![0]));
936    /// assert_eq!(left.factor_none(), Some(Left(vec![0])));
937    ///
938    /// let right: Either<Option<Vec<u8>>, _> = Right(Some(String::new()));
939    /// assert_eq!(right.factor_none(), Some(Right(String::new())));
940    /// ```
941    // TODO(MSRV): doc(alias) was stabilized in Rust 1.48
942    // #[doc(alias = "transpose")]
943    pub fn factor_none(self) -> Option<Either<L, R>> {
944        match self {
945            Left(l) => l.map(Either::Left),
946            Right(r) => r.map(Either::Right),
947        }
948    }
949}
950
951impl<L, R, E> Either<Result<L, E>, Result<R, E>> {
952    /// Factors out a homogenous type from an `Either` of [`Result`].
953    ///
954    /// Here, the homogeneous type is the `Err` type of the [`Result`].
955    ///
956    /// ```
957    /// use either::*;
958    /// let left: Either<_, Result<String, u32>> = Left(Ok(vec![0]));
959    /// assert_eq!(left.factor_err(), Ok(Left(vec![0])));
960    ///
961    /// let right: Either<Result<Vec<u8>, u32>, _> = Right(Ok(String::new()));
962    /// assert_eq!(right.factor_err(), Ok(Right(String::new())));
963    /// ```
964    // TODO(MSRV): doc(alias) was stabilized in Rust 1.48
965    // #[doc(alias = "transpose")]
966    pub fn factor_err(self) -> Result<Either<L, R>, E> {
967        match self {
968            Left(l) => l.map(Either::Left),
969            Right(r) => r.map(Either::Right),
970        }
971    }
972}
973
974impl<T, L, R> Either<Result<T, L>, Result<T, R>> {
975    /// Factors out a homogenous type from an `Either` of [`Result`].
976    ///
977    /// Here, the homogeneous type is the `Ok` type of the [`Result`].
978    ///
979    /// ```
980    /// use either::*;
981    /// let left: Either<_, Result<u32, String>> = Left(Err(vec![0]));
982    /// assert_eq!(left.factor_ok(), Err(Left(vec![0])));
983    ///
984    /// let right: Either<Result<u32, Vec<u8>>, _> = Right(Err(String::new()));
985    /// assert_eq!(right.factor_ok(), Err(Right(String::new())));
986    /// ```
987    // TODO(MSRV): doc(alias) was stabilized in Rust 1.48
988    // #[doc(alias = "transpose")]
989    pub fn factor_ok(self) -> Result<T, Either<L, R>> {
990        match self {
991            Left(l) => l.map_err(Either::Left),
992            Right(r) => r.map_err(Either::Right),
993        }
994    }
995}
996
997impl<T, L, R> Either<(T, L), (T, R)> {
998    /// Factor out a homogeneous type from an either of pairs.
999    ///
1000    /// Here, the homogeneous type is the first element of the pairs.
1001    ///
1002    /// ```
1003    /// use either::*;
1004    /// let left: Either<_, (u32, String)> = Left((123, vec![0]));
1005    /// assert_eq!(left.factor_first().0, 123);
1006    ///
1007    /// let right: Either<(u32, Vec<u8>), _> = Right((123, String::new()));
1008    /// assert_eq!(right.factor_first().0, 123);
1009    /// ```
1010    pub fn factor_first(self) -> (T, Either<L, R>) {
1011        match self {
1012            Left((t, l)) => (t, Left(l)),
1013            Right((t, r)) => (t, Right(r)),
1014        }
1015    }
1016}
1017
1018impl<T, L, R> Either<(L, T), (R, T)> {
1019    /// Factor out a homogeneous type from an either of pairs.
1020    ///
1021    /// Here, the homogeneous type is the second element of the pairs.
1022    ///
1023    /// ```
1024    /// use either::*;
1025    /// let left: Either<_, (String, u32)> = Left((vec![0], 123));
1026    /// assert_eq!(left.factor_second().1, 123);
1027    ///
1028    /// let right: Either<(Vec<u8>, u32), _> = Right((String::new(), 123));
1029    /// assert_eq!(right.factor_second().1, 123);
1030    /// ```
1031    pub fn factor_second(self) -> (Either<L, R>, T) {
1032        match self {
1033            Left((l, t)) => (Left(l), t),
1034            Right((r, t)) => (Right(r), t),
1035        }
1036    }
1037}
1038
1039impl<T> Either<T, T> {
1040    /// Extract the value of an either over two equivalent types.
1041    ///
1042    /// ```
1043    /// use either::*;
1044    ///
1045    /// let left: Either<_, u32> = Left(123);
1046    /// assert_eq!(left.into_inner(), 123);
1047    ///
1048    /// let right: Either<u32, _> = Right(123);
1049    /// assert_eq!(right.into_inner(), 123);
1050    /// ```
1051    pub fn into_inner(self) -> T {
1052        for_both!(self, inner => inner)
1053    }
1054
1055    /// Map `f` over the contained value and return the result in the
1056    /// corresponding variant.
1057    ///
1058    /// ```
1059    /// use either::*;
1060    ///
1061    /// let value: Either<_, i32> = Right(42);
1062    ///
1063    /// let other = value.map(|x| x * 2);
1064    /// assert_eq!(other, Right(84));
1065    /// ```
1066    pub fn map<F, M>(self, f: F) -> Either<M, M>
1067    where
1068        F: FnOnce(T) -> M,
1069    {
1070        match self {
1071            Left(l) => Left(f(l)),
1072            Right(r) => Right(f(r)),
1073        }
1074    }
1075}
1076
1077impl<L, R> Either<&L, &R> {
1078    /// Maps an `Either<&L, &R>` to an `Either<L, R>` by cloning the contents of
1079    /// either branch.
1080    pub fn cloned(self) -> Either<L, R>
1081    where
1082        L: Clone,
1083        R: Clone,
1084    {
1085        map_either!(self, inner => inner.clone())
1086    }
1087
1088    /// Maps an `Either<&L, &R>` to an `Either<L, R>` by copying the contents of
1089    /// either branch.
1090    pub fn copied(self) -> Either<L, R>
1091    where
1092        L: Copy,
1093        R: Copy,
1094    {
1095        map_either!(self, inner => *inner)
1096    }
1097}
1098
1099impl<L, R> Either<&mut L, &mut R> {
1100    /// Maps an `Either<&mut L, &mut R>` to an `Either<L, R>` by cloning the contents of
1101    /// either branch.
1102    pub fn cloned(self) -> Either<L, R>
1103    where
1104        L: Clone,
1105        R: Clone,
1106    {
1107        map_either!(self, inner => inner.clone())
1108    }
1109
1110    /// Maps an `Either<&mut L, &mut R>` to an `Either<L, R>` by copying the contents of
1111    /// either branch.
1112    pub fn copied(self) -> Either<L, R>
1113    where
1114        L: Copy,
1115        R: Copy,
1116    {
1117        map_either!(self, inner => *inner)
1118    }
1119}
1120
1121/// Convert from `Result` to `Either` with `Ok => Right` and `Err => Left`.
1122impl<L, R> From<Result<R, L>> for Either<L, R> {
1123    fn from(r: Result<R, L>) -> Self {
1124        match r {
1125            Err(e) => Left(e),
1126            Ok(o) => Right(o),
1127        }
1128    }
1129}
1130
1131/// Convert from `Either` to `Result` with `Right => Ok` and `Left => Err`.
1132impl<L, R> From<Either<L, R>> for Result<R, L> {
1133    fn from(val: Either<L, R>) -> Self {
1134        match val {
1135            Left(l) => Err(l),
1136            Right(r) => Ok(r),
1137        }
1138    }
1139}
1140
1141/// `Either<L, R>` is a future if both `L` and `R` are futures.
1142impl<L, R> Future for Either<L, R>
1143where
1144    L: Future,
1145    R: Future<Output = L::Output>,
1146{
1147    type Output = L::Output;
1148
1149    fn poll(
1150        self: Pin<&mut Self>,
1151        cx: &mut core::task::Context<'_>,
1152    ) -> core::task::Poll<Self::Output> {
1153        for_both!(self.as_pin_mut(), inner => inner.poll(cx))
1154    }
1155}
1156
1157#[cfg(any(test, feature = "use_std"))]
1158/// `Either<L, R>` implements `Read` if both `L` and `R` do.
1159///
1160/// Requires crate feature `"use_std"`
1161impl<L, R> Read for Either<L, R>
1162where
1163    L: Read,
1164    R: Read,
1165{
1166    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
1167        for_both!(self, inner => inner.read(buf))
1168    }
1169
1170    fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> {
1171        for_both!(self, inner => inner.read_exact(buf))
1172    }
1173
1174    fn read_to_end(&mut self, buf: &mut std::vec::Vec<u8>) -> io::Result<usize> {
1175        for_both!(self, inner => inner.read_to_end(buf))
1176    }
1177
1178    fn read_to_string(&mut self, buf: &mut std::string::String) -> io::Result<usize> {
1179        for_both!(self, inner => inner.read_to_string(buf))
1180    }
1181}
1182
1183#[cfg(any(test, feature = "use_std"))]
1184/// `Either<L, R>` implements `Seek` if both `L` and `R` do.
1185///
1186/// Requires crate feature `"use_std"`
1187impl<L, R> Seek for Either<L, R>
1188where
1189    L: Seek,
1190    R: Seek,
1191{
1192    fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
1193        for_both!(self, inner => inner.seek(pos))
1194    }
1195}
1196
1197#[cfg(any(test, feature = "use_std"))]
1198/// Requires crate feature `"use_std"`
1199impl<L, R> BufRead for Either<L, R>
1200where
1201    L: BufRead,
1202    R: BufRead,
1203{
1204    fn fill_buf(&mut self) -> io::Result<&[u8]> {
1205        for_both!(self, inner => inner.fill_buf())
1206    }
1207
1208    fn consume(&mut self, amt: usize) {
1209        for_both!(self, inner => inner.consume(amt))
1210    }
1211
1212    fn read_until(&mut self, byte: u8, buf: &mut std::vec::Vec<u8>) -> io::Result<usize> {
1213        for_both!(self, inner => inner.read_until(byte, buf))
1214    }
1215
1216    fn read_line(&mut self, buf: &mut std::string::String) -> io::Result<usize> {
1217        for_both!(self, inner => inner.read_line(buf))
1218    }
1219}
1220
1221#[cfg(any(test, feature = "use_std"))]
1222/// `Either<L, R>` implements `Write` if both `L` and `R` do.
1223///
1224/// Requires crate feature `"use_std"`
1225impl<L, R> Write for Either<L, R>
1226where
1227    L: Write,
1228    R: Write,
1229{
1230    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
1231        for_both!(self, inner => inner.write(buf))
1232    }
1233
1234    fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
1235        for_both!(self, inner => inner.write_all(buf))
1236    }
1237
1238    fn write_fmt(&mut self, fmt: fmt::Arguments<'_>) -> io::Result<()> {
1239        for_both!(self, inner => inner.write_fmt(fmt))
1240    }
1241
1242    fn flush(&mut self) -> io::Result<()> {
1243        for_both!(self, inner => inner.flush())
1244    }
1245}
1246
1247impl<L, R, Target> AsRef<Target> for Either<L, R>
1248where
1249    L: AsRef<Target>,
1250    R: AsRef<Target>,
1251{
1252    fn as_ref(&self) -> &Target {
1253        for_both!(self, inner => inner.as_ref())
1254    }
1255}
1256
1257macro_rules! impl_specific_ref_and_mut {
1258    ($t:ty, $($attr:meta),* ) => {
1259        $(#[$attr])*
1260        impl<L, R> AsRef<$t> for Either<L, R>
1261            where L: AsRef<$t>, R: AsRef<$t>
1262        {
1263            fn as_ref(&self) -> &$t {
1264                for_both!(self, inner => inner.as_ref())
1265            }
1266        }
1267
1268        $(#[$attr])*
1269        impl<L, R> AsMut<$t> for Either<L, R>
1270            where L: AsMut<$t>, R: AsMut<$t>
1271        {
1272            fn as_mut(&mut self) -> &mut $t {
1273                for_both!(self, inner => inner.as_mut())
1274            }
1275        }
1276    };
1277}
1278
1279impl_specific_ref_and_mut!(str,);
1280impl_specific_ref_and_mut!(
1281    ::std::path::Path,
1282    cfg(feature = "use_std"),
1283    doc = "Requires crate feature `use_std`."
1284);
1285impl_specific_ref_and_mut!(
1286    ::std::ffi::OsStr,
1287    cfg(feature = "use_std"),
1288    doc = "Requires crate feature `use_std`."
1289);
1290impl_specific_ref_and_mut!(
1291    ::std::ffi::CStr,
1292    cfg(feature = "use_std"),
1293    doc = "Requires crate feature `use_std`."
1294);
1295
1296impl<L, R, Target> AsRef<[Target]> for Either<L, R>
1297where
1298    L: AsRef<[Target]>,
1299    R: AsRef<[Target]>,
1300{
1301    fn as_ref(&self) -> &[Target] {
1302        for_both!(self, inner => inner.as_ref())
1303    }
1304}
1305
1306impl<L, R, Target> AsMut<Target> for Either<L, R>
1307where
1308    L: AsMut<Target>,
1309    R: AsMut<Target>,
1310{
1311    fn as_mut(&mut self) -> &mut Target {
1312        for_both!(self, inner => inner.as_mut())
1313    }
1314}
1315
1316impl<L, R, Target> AsMut<[Target]> for Either<L, R>
1317where
1318    L: AsMut<[Target]>,
1319    R: AsMut<[Target]>,
1320{
1321    fn as_mut(&mut self) -> &mut [Target] {
1322        for_both!(self, inner => inner.as_mut())
1323    }
1324}
1325
1326impl<L, R> Deref for Either<L, R>
1327where
1328    L: Deref,
1329    R: Deref<Target = L::Target>,
1330{
1331    type Target = L::Target;
1332
1333    fn deref(&self) -> &Self::Target {
1334        for_both!(self, inner => &**inner)
1335    }
1336}
1337
1338impl<L, R> DerefMut for Either<L, R>
1339where
1340    L: DerefMut,
1341    R: DerefMut<Target = L::Target>,
1342{
1343    fn deref_mut(&mut self) -> &mut Self::Target {
1344        for_both!(self, inner => &mut *inner)
1345    }
1346}
1347
1348#[cfg(any(test, feature = "use_std"))]
1349/// `Either` implements `Error` if *both* `L` and `R` implement it.
1350///
1351/// Requires crate feature `"use_std"`
1352impl<L, R> Error for Either<L, R>
1353where
1354    L: Error,
1355    R: Error,
1356{
1357    fn source(&self) -> Option<&(dyn Error + 'static)> {
1358        for_both!(self, inner => inner.source())
1359    }
1360
1361    #[allow(deprecated)]
1362    fn description(&self) -> &str {
1363        for_both!(self, inner => inner.description())
1364    }
1365
1366    #[allow(deprecated)]
1367    fn cause(&self) -> Option<&dyn Error> {
1368        for_both!(self, inner => inner.cause())
1369    }
1370}
1371
1372impl<L, R> fmt::Display for Either<L, R>
1373where
1374    L: fmt::Display,
1375    R: fmt::Display,
1376{
1377    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1378        for_both!(self, inner => inner.fmt(f))
1379    }
1380}
1381
1382impl<L, R> fmt::Write for Either<L, R>
1383where
1384    L: fmt::Write,
1385    R: fmt::Write,
1386{
1387    fn write_str(&mut self, s: &str) -> fmt::Result {
1388        for_both!(self, inner => inner.write_str(s))
1389    }
1390
1391    fn write_char(&mut self, c: char) -> fmt::Result {
1392        for_both!(self, inner => inner.write_char(c))
1393    }
1394
1395    fn write_fmt(&mut self, args: fmt::Arguments<'_>) -> fmt::Result {
1396        for_both!(self, inner => inner.write_fmt(args))
1397    }
1398}
1399
1400#[test]
1401fn basic() {
1402    let mut e = Left(2);
1403    let r = Right(2);
1404    assert_eq!(e, Left(2));
1405    e = r;
1406    assert_eq!(e, Right(2));
1407    assert_eq!(e.left(), None);
1408    assert_eq!(e.right(), Some(2));
1409    assert_eq!(e.as_ref().right(), Some(&2));
1410    assert_eq!(e.as_mut().right(), Some(&mut 2));
1411}
1412
1413#[test]
1414fn macros() {
1415    use std::string::String;
1416
1417    fn a() -> Either<u32, u32> {
1418        let x: u32 = try_left!(Right(1337u32));
1419        Left(x * 2)
1420    }
1421    assert_eq!(a(), Right(1337));
1422
1423    fn b() -> Either<String, &'static str> {
1424        Right(try_right!(Left("foo bar")))
1425    }
1426    assert_eq!(b(), Left(String::from("foo bar")));
1427}
1428
1429#[test]
1430fn deref() {
1431    use std::string::String;
1432
1433    fn is_str(_: &str) {}
1434    let value: Either<String, &str> = Left(String::from("test"));
1435    is_str(&value);
1436}
1437
1438#[test]
1439fn iter() {
1440    let x = 3;
1441    let mut iter = match x {
1442        3 => Left(0..10),
1443        _ => Right(17..),
1444    };
1445
1446    assert_eq!(iter.next(), Some(0));
1447    assert_eq!(iter.count(), 9);
1448}
1449
1450#[test]
1451fn seek() {
1452    use std::io;
1453
1454    let use_empty = false;
1455    let mut mockdata = [0x00; 256];
1456    for (i, data) in mockdata.iter_mut().enumerate() {
1457        *data = i as u8;
1458    }
1459
1460    let mut reader = if use_empty {
1461        // Empty didn't impl Seek until Rust 1.51
1462        Left(io::Cursor::new([]))
1463    } else {
1464        Right(io::Cursor::new(&mockdata[..]))
1465    };
1466
1467    let mut buf = [0u8; 16];
1468    assert_eq!(reader.read(&mut buf).unwrap(), buf.len());
1469    assert_eq!(buf, mockdata[..buf.len()]);
1470
1471    // the first read should advance the cursor and return the next 16 bytes thus the `ne`
1472    assert_eq!(reader.read(&mut buf).unwrap(), buf.len());
1473    assert_ne!(buf, mockdata[..buf.len()]);
1474
1475    // if the seek operation fails it should read 16..31 instead of 0..15
1476    reader.seek(io::SeekFrom::Start(0)).unwrap();
1477    assert_eq!(reader.read(&mut buf).unwrap(), buf.len());
1478    assert_eq!(buf, mockdata[..buf.len()]);
1479}
1480
1481#[test]
1482fn read_write() {
1483    use std::io;
1484
1485    let use_stdio = false;
1486    let mockdata = [0xff; 256];
1487
1488    let mut reader = if use_stdio {
1489        Left(io::stdin())
1490    } else {
1491        Right(&mockdata[..])
1492    };
1493
1494    let mut buf = [0u8; 16];
1495    assert_eq!(reader.read(&mut buf).unwrap(), buf.len());
1496    assert_eq!(&buf, &mockdata[..buf.len()]);
1497
1498    let mut mockbuf = [0u8; 256];
1499    let mut writer = if use_stdio {
1500        Left(io::stdout())
1501    } else {
1502        Right(&mut mockbuf[..])
1503    };
1504
1505    let buf = [1u8; 16];
1506    assert_eq!(writer.write(&buf).unwrap(), buf.len());
1507}
1508
1509#[test]
1510fn error() {
1511    let invalid_utf8 = b"\xff";
1512    #[allow(invalid_from_utf8)]
1513    let res = if let Err(error) = ::std::str::from_utf8(invalid_utf8) {
1514        Err(Left(error))
1515    } else if let Err(error) = "x".parse::<i32>() {
1516        Err(Right(error))
1517    } else {
1518        Ok(())
1519    };
1520    assert!(res.is_err());
1521    #[allow(deprecated)]
1522    res.unwrap_err().description(); // make sure this can be called
1523}
1524
1525/// A helper macro to check if AsRef and AsMut are implemented for a given type.
1526macro_rules! check_t {
1527    ($t:ty) => {{
1528        fn check_ref<T: AsRef<$t>>() {}
1529        fn propagate_ref<T1: AsRef<$t>, T2: AsRef<$t>>() {
1530            check_ref::<Either<T1, T2>>()
1531        }
1532        fn check_mut<T: AsMut<$t>>() {}
1533        fn propagate_mut<T1: AsMut<$t>, T2: AsMut<$t>>() {
1534            check_mut::<Either<T1, T2>>()
1535        }
1536    }};
1537}
1538
1539// This "unused" method is here to ensure that compilation doesn't fail on given types.
1540fn _unsized_ref_propagation() {
1541    check_t!(str);
1542
1543    fn check_array_ref<T: AsRef<[Item]>, Item>() {}
1544    fn check_array_mut<T: AsMut<[Item]>, Item>() {}
1545
1546    fn propagate_array_ref<T1: AsRef<[Item]>, T2: AsRef<[Item]>, Item>() {
1547        check_array_ref::<Either<T1, T2>, _>()
1548    }
1549
1550    fn propagate_array_mut<T1: AsMut<[Item]>, T2: AsMut<[Item]>, Item>() {
1551        check_array_mut::<Either<T1, T2>, _>()
1552    }
1553}
1554
1555// This "unused" method is here to ensure that compilation doesn't fail on given types.
1556#[cfg(feature = "use_std")]
1557fn _unsized_std_propagation() {
1558    check_t!(::std::path::Path);
1559    check_t!(::std::ffi::OsStr);
1560    check_t!(::std::ffi::CStr);
1561}