Chain zero or more iterators together into one sequence.

The comma-separated arguments must implement IntoIterator. The final argument may be followed by a trailing comma.

Examples

Empty invocations of chain! expand to an invocation of [std::iter::empty]:

use std::iter;
use itertools::chain;

let _: iter::Empty<()> = chain!();
let _: iter::Empty<i8> = chain!();

Invocations of chain! with one argument expand to arg.into_iter():

use std::ops::Range;
use itertools::chain;
let _: <Range<_> as IntoIterator>::IntoIter = chain!(2..6,); // trailing comma optional!
let _:     <&[_] as IntoIterator>::IntoIter = chain!(&[2, 3, 4]);

Invocations of chain! with multiple arguments .into_iter() each argument, and then chain them together:

use std::{iter::*, slice};
use itertools::{assert_equal, chain};

// e.g., this:
let with_macro:  Chain<Chain<Once<_>, Take<Repeat<_>>>, slice::Iter<_>> =
    chain![once(&0), repeat(&1).take(2), &[2, 3, 5],];

// ...is equivalent to this:
let with_method: Chain<Chain<Once<_>, Take<Repeat<_>>>, slice::Iter<_>> =
    once(&0)
        .chain(repeat(&1).take(2))
        .chain(&[2, 3, 5]);

assert_equal(with_macro, with_method);