armv7a/usr/lib/rustlib/src/rust/library/core/src/iter/traits/collect.rs - manifest_repos/toolchain - Git at Google

 /// Conversion from an [`Iterator`].
 ///
 /// By implementing `FromIterator` for a type, you define how it will be
 /// created from an iterator. This is common for types which describe a
 /// collection of some kind.
 ///
 /// If you want to create a collection from the contents of an iterator, the
 /// [`Iterator::collect()`] method is preferred. However, when you need to
 /// specify the container type, [`FromIterator::from_iter()`] can be more
 /// readable than using a turbofish (e.g. `::<Vec<_>>()`). See the
 /// [`Iterator::collect()`] documentation for more examples of its use.
 ///
 /// See also: [`IntoIterator`].
 ///
 /// # Examples
 ///
 /// Basic usage:
 ///
 /// ```
 /// let five_fives = std::iter::repeat(5).take(5);
 ///
 /// let v = Vec::from_iter(five_fives);
 ///
 /// assert_eq!(v, vec![5, 5, 5, 5, 5]);
 /// ```
 ///
 /// Using [`Iterator::collect()`] to implicitly use `FromIterator`:
 ///
 /// ```
 /// let five_fives = std::iter::repeat(5).take(5);
 ///
 /// let v: Vec<i32> = five_fives.collect();
 ///
 /// assert_eq!(v, vec![5, 5, 5, 5, 5]);
 /// ```
 ///
 /// Using [`FromIterator::from_iter()`] as a more readable alternative to
 /// [`Iterator::collect()`]:
 ///
 /// ```
 /// use std::collections::VecDeque;
 /// let first = (0..10).collect::<VecDeque<i32>>();
 /// let second = VecDeque::from_iter(0..10);
 ///
 /// assert_eq!(first, second);
 /// ```
 ///
 /// Implementing `FromIterator` for your type:
 ///
 /// ```
 /// // A sample collection, that's just a wrapper over Vec<T>
 /// #[derive(Debug)]
 /// struct MyCollection(Vec<i32>);
 ///
 /// // Let's give it some methods so we can create one and add things
 /// // to it.
 /// impl MyCollection {
 ///     fn new() -> MyCollection {
 ///         MyCollection(Vec::new())
 ///     }
 ///
 ///     fn add(&mut self, elem: i32) {
 ///         self.0.push(elem);
 ///     }
 /// }
 ///
 /// // and we'll implement FromIterator
 /// impl FromIterator<i32> for MyCollection {
 ///     fn from_iter<I: IntoIterator<Item=i32>>(iter: I) -> Self {
 ///         let mut c = MyCollection::new();
 ///
 ///         for i in iter {
 ///             c.add(i);
 ///         }
 ///
 ///         c
 ///     }
 /// }
 ///
 /// // Now we can make a new iterator...
 /// let iter = (0..5).into_iter();
 ///
 /// // ... and make a MyCollection out of it
 /// let c = MyCollection::from_iter(iter);
 ///
 /// assert_eq!(c.0, vec![0, 1, 2, 3, 4]);
 ///
 /// // collect works too!
 ///
 /// let iter = (0..5).into_iter();
 /// let c: MyCollection = iter.collect();
 ///
 /// assert_eq!(c.0, vec![0, 1, 2, 3, 4]);
 /// ```
 #[stable(feature = "rust1", since = "1.0.0")]
 #[rustc_on_unimplemented(
     on(
         _Self = "[{A}]",
         message = "a slice of type `{Self}` cannot be built since `{Self}` has no definite size",
         label = "try explicitly collecting into a `Vec<{A}>`",
     ),
     on(
         all(A = "{integer}", any(_Self = "[{integral}]",)),
         message = "a slice of type `{Self}` cannot be built since `{Self}` has no definite size",
         label = "try explicitly collecting into a `Vec<{A}>`",
     ),
     on(
         _Self = "[{A}; _]",
         message = "an array of type `{Self}` cannot be built directly from an iterator",
         label = "try collecting into a `Vec<{A}>`, then using `.try_into()`",
     ),
     on(
         all(A = "{integer}", any(_Self = "[{integral}; _]",)),
         message = "an array of type `{Self}` cannot be built directly from an iterator",
         label = "try collecting into a `Vec<{A}>`, then using `.try_into()`",
     ),
     message = "a value of type `{Self}` cannot be built from an iterator \
                over elements of type `{A}`",
     label = "value of type `{Self}` cannot be built from `std::iter::Iterator<Item={A}>`"
 )]
 #[rustc_diagnostic_item = "FromIterator"]
 pub trait FromIterator<A>: Sized {
     /// Creates a value from an iterator.
     ///
     /// See the [module-level documentation] for more.
     ///
     /// [module-level documentation]: crate::iter
     ///
     /// # Examples
     ///
     /// Basic usage:
     ///
     /// ```
     /// let five_fives = std::iter::repeat(5).take(5);
     ///
     /// let v = Vec::from_iter(five_fives);
     ///
     /// assert_eq!(v, vec![5, 5, 5, 5, 5]);
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     fn from_iter<T: IntoIterator<Item = A>>(iter: T) -> Self;
 }

 /// Conversion into an [`Iterator`].
 ///
 /// By implementing `IntoIterator` for a type, you define how it will be
 /// converted to an iterator. This is common for types which describe a
 /// collection of some kind.
 ///
 /// One benefit of implementing `IntoIterator` is that your type will [work
 /// with Rust's `for` loop syntax](crate::iter#for-loops-and-intoiterator).
 ///
 /// See also: [`FromIterator`].
 ///
 /// # Examples
 ///
 /// Basic usage:
 ///
 /// ```
 /// let v = [1, 2, 3];
 /// let mut iter = v.into_iter();
 ///
 /// assert_eq!(Some(1), iter.next());
 /// assert_eq!(Some(2), iter.next());
 /// assert_eq!(Some(3), iter.next());
 /// assert_eq!(None, iter.next());
 /// ```
 /// Implementing `IntoIterator` for your type:
 ///
 /// ```
 /// // A sample collection, that's just a wrapper over Vec<T>
 /// #[derive(Debug)]
 /// struct MyCollection(Vec<i32>);
 ///
 /// // Let's give it some methods so we can create one and add things
 /// // to it.
 /// impl MyCollection {
 ///     fn new() -> MyCollection {
 ///         MyCollection(Vec::new())
 ///     }
 ///
 ///     fn add(&mut self, elem: i32) {
 ///         self.0.push(elem);
 ///     }
 /// }
 ///
 /// // and we'll implement IntoIterator
 /// impl IntoIterator for MyCollection {
 ///     type Item = i32;
 ///     type IntoIter = std::vec::IntoIter<Self::Item>;
 ///
 ///     fn into_iter(self) -> Self::IntoIter {
 ///         self.0.into_iter()
 ///     }
 /// }
 ///
 /// // Now we can make a new collection...
 /// let mut c = MyCollection::new();
 ///
 /// // ... add some stuff to it ...
 /// c.add(0);
 /// c.add(1);
 /// c.add(2);
 ///
 /// // ... and then turn it into an Iterator:
 /// for (i, n) in c.into_iter().enumerate() {
 ///     assert_eq!(i as i32, n);
 /// }
 /// ```
 ///
 /// It is common to use `IntoIterator` as a trait bound. This allows
 /// the input collection type to change, so long as it is still an
 /// iterator. Additional bounds can be specified by restricting on
 /// `Item`:
 ///
 /// ```rust
 /// fn collect_as_strings<T>(collection: T) -> Vec<String>
 /// where
 ///     T: IntoIterator,
 ///     T::Item: std::fmt::Debug,
 /// {
 ///     collection
 ///         .into_iter()
 ///         .map(|item| format!("{item:?}"))
 ///         .collect()
 /// }
 /// ```
 #[rustc_diagnostic_item = "IntoIterator"]
 #[rustc_skip_array_during_method_dispatch]
 #[stable(feature = "rust1", since = "1.0.0")]
 #[const_trait]
 pub trait IntoIterator {
     /// The type of the elements being iterated over.
     #[stable(feature = "rust1", since = "1.0.0")]
     type Item;

     /// Which kind of iterator are we turning this into?
     #[stable(feature = "rust1", since = "1.0.0")]
     type IntoIter: Iterator<Item = Self::Item>;

     /// Creates an iterator from a value.
     ///
     /// See the [module-level documentation] for more.
     ///
     /// [module-level documentation]: crate::iter
     ///
     /// # Examples
     ///
     /// Basic usage:
     ///
     /// ```
     /// let v = [1, 2, 3];
     /// let mut iter = v.into_iter();
     ///
     /// assert_eq!(Some(1), iter.next());
     /// assert_eq!(Some(2), iter.next());
     /// assert_eq!(Some(3), iter.next());
     /// assert_eq!(None, iter.next());
     /// ```
     #[lang = "into_iter"]
     #[stable(feature = "rust1", since = "1.0.0")]
     fn into_iter(self) -> Self::IntoIter;
 }

 #[rustc_const_unstable(feature = "const_intoiterator_identity", issue = "90603")]
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<I: Iterator> const IntoIterator for I {
     type Item = I::Item;
     type IntoIter = I;

     #[inline]
     fn into_iter(self) -> I {
         self
     }
 }

 /// Extend a collection with the contents of an iterator.
 ///
 /// Iterators produce a series of values, and collections can also be thought
 /// of as a series of values. The `Extend` trait bridges this gap, allowing you
 /// to extend a collection by including the contents of that iterator. When
 /// extending a collection with an already existing key, that entry is updated
 /// or, in the case of collections that permit multiple entries with equal
 /// keys, that entry is inserted.
 ///
 /// # Examples
 ///
 /// Basic usage:
 ///
 /// ```
 /// // You can extend a String with some chars:
 /// let mut message = String::from("The first three letters are: ");
 ///
 /// message.extend(&['a', 'b', 'c']);
 ///
 /// assert_eq!("abc", &message[29..32]);
 /// ```
 ///
 /// Implementing `Extend`:
 ///
 /// ```
 /// // A sample collection, that's just a wrapper over Vec<T>
 /// #[derive(Debug)]
 /// struct MyCollection(Vec<i32>);
 ///
 /// // Let's give it some methods so we can create one and add things
 /// // to it.
 /// impl MyCollection {
 ///     fn new() -> MyCollection {
 ///         MyCollection(Vec::new())
 ///     }
 ///
 ///     fn add(&mut self, elem: i32) {
 ///         self.0.push(elem);
 ///     }
 /// }
 ///
 /// // since MyCollection has a list of i32s, we implement Extend for i32
 /// impl Extend<i32> for MyCollection {
 ///
 ///     // This is a bit simpler with the concrete type signature: we can call
 ///     // extend on anything which can be turned into an Iterator which gives
 ///     // us i32s. Because we need i32s to put into MyCollection.
 ///     fn extend<T: IntoIterator<Item=i32>>(&mut self, iter: T) {
 ///
 ///         // The implementation is very straightforward: loop through the
 ///         // iterator, and add() each element to ourselves.
 ///         for elem in iter {
 ///             self.add(elem);
 ///         }
 ///     }
 /// }
 ///
 /// let mut c = MyCollection::new();
 ///
 /// c.add(5);
 /// c.add(6);
 /// c.add(7);
 ///
 /// // let's extend our collection with three more numbers
 /// c.extend(vec![1, 2, 3]);
 ///
 /// // we've added these elements onto the end
 /// assert_eq!("MyCollection([5, 6, 7, 1, 2, 3])", format!("{c:?}"));
 /// ```
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait Extend<A> {
     /// Extends a collection with the contents of an iterator.
     ///
     /// As this is the only required method for this trait, the [trait-level] docs
     /// contain more details.
     ///
     /// [trait-level]: Extend
     ///
     /// # Examples
     ///
     /// Basic usage:
     ///
     /// ```
     /// // You can extend a String with some chars:
     /// let mut message = String::from("abc");
     ///
     /// message.extend(['d', 'e', 'f'].iter());
     ///
     /// assert_eq!("abcdef", &message);
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     fn extend<T: IntoIterator<Item = A>>(&mut self, iter: T);

     /// Extends a collection with exactly one element.
     #[unstable(feature = "extend_one", issue = "72631")]
     fn extend_one(&mut self, item: A) {
         self.extend(Some(item));
     }

     /// Reserves capacity in a collection for the given number of additional elements.
     ///
     /// The default implementation does nothing.
     #[unstable(feature = "extend_one", issue = "72631")]
     fn extend_reserve(&mut self, additional: usize) {
         let _ = additional;
     }
 }

 #[stable(feature = "extend_for_unit", since = "1.28.0")]
 impl Extend<()> for () {
     fn extend<T: IntoIterator<Item = ()>>(&mut self, iter: T) {
         iter.into_iter().for_each(drop)
     }
     fn extend_one(&mut self, _item: ()) {}
 }

 #[stable(feature = "extend_for_tuple", since = "1.56.0")]
 impl<A, B, ExtendA, ExtendB> Extend<(A, B)> for (ExtendA, ExtendB)
 where
     ExtendA: Extend<A>,
     ExtendB: Extend<B>,
 {
     /// Allows to `extend` a tuple of collections that also implement `Extend`.
     ///
     /// See also: [`Iterator::unzip`]
     ///
     /// # Examples
     /// ```
     /// let mut tuple = (vec![0], vec![1]);
     /// tuple.extend([(2, 3), (4, 5), (6, 7)]);
     /// assert_eq!(tuple.0, [0, 2, 4, 6]);
     /// assert_eq!(tuple.1, [1, 3, 5, 7]);
     ///
     /// // also allows for arbitrarily nested tuples as elements
     /// let mut nested_tuple = (vec![1], (vec![2], vec![3]));
     /// nested_tuple.extend([(4, (5, 6)), (7, (8, 9))]);
     ///
     /// let (a, (b, c)) = nested_tuple;
     /// assert_eq!(a, [1, 4, 7]);
     /// assert_eq!(b, [2, 5, 8]);
     /// assert_eq!(c, [3, 6, 9]);
     /// ```
     fn extend<T: IntoIterator<Item = (A, B)>>(&mut self, into_iter: T) {
         let (a, b) = self;
         let iter = into_iter.into_iter();

         fn extend<'a, A, B>(
             a: &'a mut impl Extend<A>,
             b: &'a mut impl Extend<B>,
         ) -> impl FnMut((), (A, B)) + 'a {
             move |(), (t, u)| {
                 a.extend_one(t);
                 b.extend_one(u);
             }
         }

         let (lower_bound, _) = iter.size_hint();
         if lower_bound > 0 {
             a.extend_reserve(lower_bound);
             b.extend_reserve(lower_bound);
         }

         iter.fold((), extend(a, b));
     }

     fn extend_one(&mut self, item: (A, B)) {
         self.0.extend_one(item.0);
         self.1.extend_one(item.1);
     }

     fn extend_reserve(&mut self, additional: usize) {
         self.0.extend_reserve(additional);
         self.1.extend_reserve(additional);
     }
 }
	/// Conversion from an [`Iterator`].
	///
	/// By implementing `FromIterator` for a type, you define how it will be
	/// created from an iterator. This is common for types which describe a
	/// collection of some kind.
	///
	/// If you want to create a collection from the contents of an iterator, the
	/// [`Iterator::collect()`] method is preferred. However, when you need to
	/// specify the container type, [`FromIterator::from_iter()`] can be more
	/// readable than using a turbofish (e.g. `::<Vec<_>>()`). See the
	/// [`Iterator::collect()`] documentation for more examples of its use.
	///
	/// See also: [`IntoIterator`].
	///
	/// # Examples
	///
	/// Basic usage:
	///
	/// ```
	/// let five_fives = std::iter::repeat(5).take(5);
	///
	/// let v = Vec::from_iter(five_fives);
	///
	/// assert_eq!(v, vec![5, 5, 5, 5, 5]);
	/// ```
	///
	/// Using [`Iterator::collect()`] to implicitly use `FromIterator`:
	///
	/// ```
	/// let five_fives = std::iter::repeat(5).take(5);
	///
	/// let v: Vec<i32> = five_fives.collect();
	///
	/// assert_eq!(v, vec![5, 5, 5, 5, 5]);
	/// ```
	///
	/// Using [`FromIterator::from_iter()`] as a more readable alternative to
	/// [`Iterator::collect()`]:
	///
	/// ```
	/// use std::collections::VecDeque;
	/// let first = (0..10).collect::<VecDeque<i32>>();
	/// let second = VecDeque::from_iter(0..10);
	///
	/// assert_eq!(first, second);
	/// ```
	///
	/// Implementing `FromIterator` for your type:
	///
	/// ```
	/// // A sample collection, that's just a wrapper over Vec<T>
	/// #[derive(Debug)]
	/// struct MyCollection(Vec<i32>);
	///
	/// // Let's give it some methods so we can create one and add things
	/// // to it.
	/// impl MyCollection {
	/// fn new() -> MyCollection {
	/// MyCollection(Vec::new())
	/// }
	///
	/// fn add(&mut self, elem: i32) {
	/// self.0.push(elem);
	/// }
	/// }
	///
	/// // and we'll implement FromIterator
	/// impl FromIterator<i32> for MyCollection {
	/// fn from_iter<I: IntoIterator<Item=i32>>(iter: I) -> Self {
	/// let mut c = MyCollection::new();
	///
	/// for i in iter {
	/// c.add(i);
	/// }
	///
	/// c
	/// }
	/// }
	///
	/// // Now we can make a new iterator...
	/// let iter = (0..5).into_iter();
	///
	/// // ... and make a MyCollection out of it
	/// let c = MyCollection::from_iter(iter);
	///
	/// assert_eq!(c.0, vec![0, 1, 2, 3, 4]);
	///
	/// // collect works too!
	///
	/// let iter = (0..5).into_iter();
	/// let c: MyCollection = iter.collect();
	///
	/// assert_eq!(c.0, vec![0, 1, 2, 3, 4]);
	/// ```
	#[stable(feature = "rust1", since = "1.0.0")]
	#[rustc_on_unimplemented(
	on(
	_Self = "[{A}]",
	message = "a slice of type `{Self}` cannot be built since `{Self}` has no definite size",
	label = "try explicitly collecting into a `Vec<{A}>`",
	),
	on(
	all(A = "{integer}", any(_Self = "[{integral}]",)),
	message = "a slice of type `{Self}` cannot be built since `{Self}` has no definite size",
	label = "try explicitly collecting into a `Vec<{A}>`",
	),
	on(
	_Self = "[{A}; _]",
	message = "an array of type `{Self}` cannot be built directly from an iterator",
	label = "try collecting into a `Vec<{A}>`, then using `.try_into()`",
	),
	on(
	all(A = "{integer}", any(_Self = "[{integral}; _]",)),
	message = "an array of type `{Self}` cannot be built directly from an iterator",
	label = "try collecting into a `Vec<{A}>`, then using `.try_into()`",
	),
	message = "a value of type `{Self}` cannot be built from an iterator \
	over elements of type `{A}`",
	label = "value of type `{Self}` cannot be built from `std::iter::Iterator<Item={A}>`"
	)]
	#[rustc_diagnostic_item = "FromIterator"]
	pub trait FromIterator<A>: Sized {
	/// Creates a value from an iterator.
	///
	/// See the [module-level documentation] for more.
	///
	/// [module-level documentation]: crate::iter
	///
	/// # Examples
	///
	/// Basic usage:
	///
	/// ```
	/// let five_fives = std::iter::repeat(5).take(5);
	///
	/// let v = Vec::from_iter(five_fives);
	///
	/// assert_eq!(v, vec![5, 5, 5, 5, 5]);
	/// ```
	#[stable(feature = "rust1", since = "1.0.0")]
	fn from_iter<T: IntoIterator<Item = A>>(iter: T) -> Self;
	}

	/// Conversion into an [`Iterator`].
	///
	/// By implementing `IntoIterator` for a type, you define how it will be
	/// converted to an iterator. This is common for types which describe a
	/// collection of some kind.
	///
	/// One benefit of implementing `IntoIterator` is that your type will [work
	/// with Rust's `for` loop syntax](crate::iter#for-loops-and-intoiterator).
	///
	/// See also: [`FromIterator`].
	///
	/// # Examples
	///
	/// Basic usage:
	///
	/// ```
	/// let v = [1, 2, 3];
	/// let mut iter = v.into_iter();
	///
	/// assert_eq!(Some(1), iter.next());
	/// assert_eq!(Some(2), iter.next());
	/// assert_eq!(Some(3), iter.next());
	/// assert_eq!(None, iter.next());
	/// ```
	/// Implementing `IntoIterator` for your type:
	///
	/// ```
	/// // A sample collection, that's just a wrapper over Vec<T>
	/// #[derive(Debug)]
	/// struct MyCollection(Vec<i32>);
	///
	/// // Let's give it some methods so we can create one and add things
	/// // to it.
	/// impl MyCollection {
	/// fn new() -> MyCollection {
	/// MyCollection(Vec::new())
	/// }
	///
	/// fn add(&mut self, elem: i32) {
	/// self.0.push(elem);
	/// }
	/// }
	///
	/// // and we'll implement IntoIterator
	/// impl IntoIterator for MyCollection {
	/// type Item = i32;
	/// type IntoIter = std::vec::IntoIter<Self::Item>;
	///
	/// fn into_iter(self) -> Self::IntoIter {
	/// self.0.into_iter()
	/// }
	/// }
	///
	/// // Now we can make a new collection...
	/// let mut c = MyCollection::new();
	///
	/// // ... add some stuff to it ...
	/// c.add(0);
	/// c.add(1);
	/// c.add(2);
	///
	/// // ... and then turn it into an Iterator:
	/// for (i, n) in c.into_iter().enumerate() {
	/// assert_eq!(i as i32, n);
	/// }
	/// ```
	///
	/// It is common to use `IntoIterator` as a trait bound. This allows
	/// the input collection type to change, so long as it is still an
	/// iterator. Additional bounds can be specified by restricting on
	/// `Item`:
	///
	/// ```rust
	/// fn collect_as_strings<T>(collection: T) -> Vec<String>
	/// where
	/// T: IntoIterator,
	/// T::Item: std::fmt::Debug,
	/// {
	/// collection
	/// .into_iter()
	/// .map(\|item\| format!("{item:?}"))
	/// .collect()
	/// }
	/// ```
	#[rustc_diagnostic_item = "IntoIterator"]
	#[rustc_skip_array_during_method_dispatch]
	#[stable(feature = "rust1", since = "1.0.0")]
	#[const_trait]
	pub trait IntoIterator {
	/// The type of the elements being iterated over.
	#[stable(feature = "rust1", since = "1.0.0")]
	type Item;

	/// Which kind of iterator are we turning this into?
	#[stable(feature = "rust1", since = "1.0.0")]
	type IntoIter: Iterator<Item = Self::Item>;

	/// Creates an iterator from a value.
	///
	/// See the [module-level documentation] for more.
	///
	/// [module-level documentation]: crate::iter
	///
	/// # Examples
	///
	/// Basic usage:
	///
	/// ```
	/// let v = [1, 2, 3];
	/// let mut iter = v.into_iter();
	///
	/// assert_eq!(Some(1), iter.next());
	/// assert_eq!(Some(2), iter.next());
	/// assert_eq!(Some(3), iter.next());
	/// assert_eq!(None, iter.next());
	/// ```
	#[lang = "into_iter"]
	#[stable(feature = "rust1", since = "1.0.0")]
	fn into_iter(self) -> Self::IntoIter;
	}

	#[rustc_const_unstable(feature = "const_intoiterator_identity", issue = "90603")]
	#[stable(feature = "rust1", since = "1.0.0")]
	impl<I: Iterator> const IntoIterator for I {
	type Item = I::Item;
	type IntoIter = I;

	#[inline]
	fn into_iter(self) -> I {
	self
	}
	}

	/// Extend a collection with the contents of an iterator.
	///
	/// Iterators produce a series of values, and collections can also be thought
	/// of as a series of values. The `Extend` trait bridges this gap, allowing you
	/// to extend a collection by including the contents of that iterator. When
	/// extending a collection with an already existing key, that entry is updated
	/// or, in the case of collections that permit multiple entries with equal
	/// keys, that entry is inserted.
	///
	/// # Examples
	///
	/// Basic usage:
	///
	/// ```
	/// // You can extend a String with some chars:
	/// let mut message = String::from("The first three letters are: ");
	///
	/// message.extend(&['a', 'b', 'c']);
	///
	/// assert_eq!("abc", &message[29..32]);
	/// ```
	///
	/// Implementing `Extend`:
	///
	/// ```
	/// // A sample collection, that's just a wrapper over Vec<T>
	/// #[derive(Debug)]
	/// struct MyCollection(Vec<i32>);
	///
	/// // Let's give it some methods so we can create one and add things
	/// // to it.
	/// impl MyCollection {
	/// fn new() -> MyCollection {
	/// MyCollection(Vec::new())
	/// }
	///
	/// fn add(&mut self, elem: i32) {
	/// self.0.push(elem);
	/// }
	/// }
	///
	/// // since MyCollection has a list of i32s, we implement Extend for i32
	/// impl Extend<i32> for MyCollection {
	///
	/// // This is a bit simpler with the concrete type signature: we can call
	/// // extend on anything which can be turned into an Iterator which gives
	/// // us i32s. Because we need i32s to put into MyCollection.
	/// fn extend<T: IntoIterator<Item=i32>>(&mut self, iter: T) {
	///
	/// // The implementation is very straightforward: loop through the
	/// // iterator, and add() each element to ourselves.
	/// for elem in iter {
	/// self.add(elem);
	/// }
	/// }
	/// }
	///
	/// let mut c = MyCollection::new();
	///
	/// c.add(5);
	/// c.add(6);
	/// c.add(7);
	///
	/// // let's extend our collection with three more numbers
	/// c.extend(vec![1, 2, 3]);
	///
	/// // we've added these elements onto the end
	/// assert_eq!("MyCollection([5, 6, 7, 1, 2, 3])", format!("{c:?}"));
	/// ```
	#[stable(feature = "rust1", since = "1.0.0")]
	pub trait Extend<A> {
	/// Extends a collection with the contents of an iterator.
	///
	/// As this is the only required method for this trait, the [trait-level] docs
	/// contain more details.
	///
	/// [trait-level]: Extend
	///
	/// # Examples
	///
	/// Basic usage:
	///
	/// ```
	/// // You can extend a String with some chars:
	/// let mut message = String::from("abc");
	///
	/// message.extend(['d', 'e', 'f'].iter());
	///
	/// assert_eq!("abcdef", &message);
	/// ```
	#[stable(feature = "rust1", since = "1.0.0")]
	fn extend<T: IntoIterator<Item = A>>(&mut self, iter: T);

	/// Extends a collection with exactly one element.
	#[unstable(feature = "extend_one", issue = "72631")]
	fn extend_one(&mut self, item: A) {
	self.extend(Some(item));
	}

	/// Reserves capacity in a collection for the given number of additional elements.
	///
	/// The default implementation does nothing.
	#[unstable(feature = "extend_one", issue = "72631")]
	fn extend_reserve(&mut self, additional: usize) {
	let _ = additional;
	}
	}

	#[stable(feature = "extend_for_unit", since = "1.28.0")]
	impl Extend<()> for () {
	fn extend<T: IntoIterator<Item = ()>>(&mut self, iter: T) {
	iter.into_iter().for_each(drop)
	}
	fn extend_one(&mut self, _item: ()) {}
	}

	#[stable(feature = "extend_for_tuple", since = "1.56.0")]
	impl<A, B, ExtendA, ExtendB> Extend<(A, B)> for (ExtendA, ExtendB)
	where
	ExtendA: Extend<A>,
	ExtendB: Extend<B>,
	{
	/// Allows to `extend` a tuple of collections that also implement `Extend`.
	///
	/// See also: [`Iterator::unzip`]
	///
	/// # Examples
	/// ```
	/// let mut tuple = (vec![0], vec![1]);
	/// tuple.extend([(2, 3), (4, 5), (6, 7)]);
	/// assert_eq!(tuple.0, [0, 2, 4, 6]);
	/// assert_eq!(tuple.1, [1, 3, 5, 7]);
	///
	/// // also allows for arbitrarily nested tuples as elements
	/// let mut nested_tuple = (vec![1], (vec![2], vec![3]));
	/// nested_tuple.extend([(4, (5, 6)), (7, (8, 9))]);
	///
	/// let (a, (b, c)) = nested_tuple;
	/// assert_eq!(a, [1, 4, 7]);
	/// assert_eq!(b, [2, 5, 8]);
	/// assert_eq!(c, [3, 6, 9]);
	/// ```
	fn extend<T: IntoIterator<Item = (A, B)>>(&mut self, into_iter: T) {
	let (a, b) = self;
	let iter = into_iter.into_iter();

	fn extend<'a, A, B>(
	a: &'a mut impl Extend<A>,
	b: &'a mut impl Extend<B>,
	) -> impl FnMut((), (A, B)) + 'a {
	move \|(), (t, u)\| {
	a.extend_one(t);
	b.extend_one(u);
	}
	}

	let (lower_bound, _) = iter.size_hint();
	if lower_bound > 0 {
	a.extend_reserve(lower_bound);
	b.extend_reserve(lower_bound);
	}

	iter.fold((), extend(a, b));
	}

	fn extend_one(&mut self, item: (A, B)) {
	self.0.extend_one(item.0);
	self.1.extend_one(item.1);
	}

	fn extend_reserve(&mut self, additional: usize) {
	self.0.extend_reserve(additional);
	self.1.extend_reserve(additional);
	}
	}