Rename stream_extend to extend (#464)

Stjepan Glavina · web-flow · commit f8e82564d985 · 2019-11-07T21:46:58.000Z
* Rename stream_extend to extend

* Remove Extend from prelude

* Add stream::extend()
diff --git a/src/collections/binary_heap/extend.rs b/src/collections/binary_heap/extend.rs
@@ -2,10 +2,10 @@ use std::collections::BinaryHeap;
 use std::pin::Pin;
 
 use crate::prelude::*;
-use crate::stream::{Extend, IntoStream};
+use crate::stream::{self, IntoStream};
 
-impl<T: Ord> Extend<T> for BinaryHeap<T> {
-    fn stream_extend<'a, S: IntoStream<Item = T> + 'a>(
+impl<T: Ord> stream::Extend<T> for BinaryHeap<T> {
+    fn extend<'a, S: IntoStream<Item = T> + 'a>(
         &'a mut self,
         stream: S,
     ) -> Pin<Box<dyn Future<Output = ()> + 'a>> {
diff --git a/src/collections/binary_heap/from_stream.rs b/src/collections/binary_heap/from_stream.rs
@@ -1,7 +1,7 @@
 use std::collections::BinaryHeap;
 use std::pin::Pin;
 
-use crate::stream::{Extend, FromStream, IntoStream};
+use crate::stream::{self, FromStream, IntoStream};
 
 impl<T: Ord> FromStream<T> for BinaryHeap<T> {
     #[inline]
@@ -17,7 +17,7 @@ impl<T: Ord> FromStream<T> for BinaryHeap<T> {
             pin_utils::pin_mut!(stream);
 
             let mut out = BinaryHeap::new();
-            out.stream_extend(stream).await;
+            stream::extend(&mut out, stream).await;
             out
         })
     }
diff --git a/src/collections/btree_map/extend.rs b/src/collections/btree_map/extend.rs
@@ -2,10 +2,10 @@ use std::collections::BTreeMap;
 use std::pin::Pin;
 
 use crate::prelude::*;
-use crate::stream::{Extend, IntoStream};
+use crate::stream::{self, IntoStream};
 
-impl<K: Ord, V> Extend<(K, V)> for BTreeMap<K, V> {
-    fn stream_extend<'a, S: IntoStream<Item = (K, V)> + 'a>(
+impl<K: Ord, V> stream::Extend<(K, V)> for BTreeMap<K, V> {
+    fn extend<'a, S: IntoStream<Item = (K, V)> + 'a>(
         &'a mut self,
         stream: S,
     ) -> Pin<Box<dyn Future<Output = ()> + 'a>> {
diff --git a/src/collections/btree_map/from_stream.rs b/src/collections/btree_map/from_stream.rs
@@ -1,7 +1,7 @@
 use std::collections::BTreeMap;
 use std::pin::Pin;
 
-use crate::stream::{Extend, FromStream, IntoStream};
+use crate::stream::{self, FromStream, IntoStream};
 
 impl<K: Ord, V> FromStream<(K, V)> for BTreeMap<K, V> {
     #[inline]
@@ -17,7 +17,7 @@ impl<K: Ord, V> FromStream<(K, V)> for BTreeMap<K, V> {
             pin_utils::pin_mut!(stream);
 
             let mut out = BTreeMap::new();
-            out.stream_extend(stream).await;
+            stream::extend(&mut out, stream).await;
             out
         })
     }
diff --git a/src/collections/btree_set/extend.rs b/src/collections/btree_set/extend.rs
@@ -2,10 +2,10 @@ use std::collections::BTreeSet;
 use std::pin::Pin;
 
 use crate::prelude::*;
-use crate::stream::{Extend, IntoStream};
+use crate::stream::{self, IntoStream};
 
-impl<T: Ord> Extend<T> for BTreeSet<T> {
-    fn stream_extend<'a, S: IntoStream<Item = T> + 'a>(
+impl<T: Ord> stream::Extend<T> for BTreeSet<T> {
+    fn extend<'a, S: IntoStream<Item = T> + 'a>(
         &'a mut self,
         stream: S,
     ) -> Pin<Box<dyn Future<Output = ()> + 'a>> {
diff --git a/src/collections/btree_set/from_stream.rs b/src/collections/btree_set/from_stream.rs
@@ -1,7 +1,7 @@
 use std::collections::BTreeSet;
 use std::pin::Pin;
 
-use crate::stream::{Extend, FromStream, IntoStream};
+use crate::stream::{self, FromStream, IntoStream};
 
 impl<T: Ord> FromStream<T> for BTreeSet<T> {
     #[inline]
@@ -17,7 +17,7 @@ impl<T: Ord> FromStream<T> for BTreeSet<T> {
             pin_utils::pin_mut!(stream);
 
             let mut out = BTreeSet::new();
-            out.stream_extend(stream).await;
+            stream::extend(&mut out, stream).await;
             out
         })
     }
diff --git a/src/collections/hash_map/extend.rs b/src/collections/hash_map/extend.rs
@@ -3,14 +3,14 @@ use std::hash::{BuildHasher, Hash};
 use std::pin::Pin;
 
 use crate::prelude::*;
-use crate::stream::{Extend, IntoStream};
+use crate::stream::{self, IntoStream};
 
-impl<K, V, H> Extend<(K, V)> for HashMap<K, V, H>
+impl<K, V, H> stream::Extend<(K, V)> for HashMap<K, V, H>
 where
     K: Eq + Hash,
     H: BuildHasher + Default,
 {
-    fn stream_extend<'a, S: IntoStream<Item = (K, V)> + 'a>(
+    fn extend<'a, S: IntoStream<Item = (K, V)> + 'a>(
         &'a mut self,
         stream: S,
     ) -> Pin<Box<dyn Future<Output = ()> + 'a>> {
diff --git a/src/collections/hash_map/from_stream.rs b/src/collections/hash_map/from_stream.rs
@@ -2,7 +2,7 @@ use std::collections::HashMap;
 use std::hash::{BuildHasher, Hash};
 use std::pin::Pin;
 
-use crate::stream::{Extend, FromStream, IntoStream};
+use crate::stream::{self, FromStream, IntoStream};
 
 impl<K, V, H> FromStream<(K, V)> for HashMap<K, V, H>
 where
@@ -22,7 +22,7 @@ where
             pin_utils::pin_mut!(stream);
 
             let mut out = HashMap::with_hasher(Default::default());
-            out.stream_extend(stream).await;
+            stream::extend(&mut out, stream).await;
             out
         })
     }
diff --git a/src/collections/hash_set/extend.rs b/src/collections/hash_set/extend.rs
@@ -3,14 +3,14 @@ use std::hash::{BuildHasher, Hash};
 use std::pin::Pin;
 
 use crate::prelude::*;
-use crate::stream::{Extend, IntoStream};
+use crate::stream::{self, IntoStream};
 
-impl<T, H> Extend<T> for HashSet<T, H>
+impl<T, H> stream::Extend<T> for HashSet<T, H>
 where
     T: Eq + Hash,
     H: BuildHasher + Default,
 {
-    fn stream_extend<'a, S: IntoStream<Item = T> + 'a>(
+    fn extend<'a, S: IntoStream<Item = T> + 'a>(
         &'a mut self,
         stream: S,
     ) -> Pin<Box<dyn Future<Output = ()> + 'a>> {
diff --git a/src/collections/hash_set/from_stream.rs b/src/collections/hash_set/from_stream.rs
@@ -2,7 +2,7 @@ use std::collections::HashSet;
 use std::hash::{BuildHasher, Hash};
 use std::pin::Pin;
 
-use crate::stream::{Extend, FromStream, IntoStream};
+use crate::stream::{self, FromStream, IntoStream};
 
 impl<T, H> FromStream<T> for HashSet<T, H>
 where
@@ -22,7 +22,7 @@ where
             pin_utils::pin_mut!(stream);
 
             let mut out = HashSet::with_hasher(Default::default());
-            out.stream_extend(stream).await;
+            stream::extend(&mut out, stream).await;
             out
         })
     }
diff --git a/src/collections/linked_list/extend.rs b/src/collections/linked_list/extend.rs
@@ -2,10 +2,10 @@ use std::collections::LinkedList;
 use std::pin::Pin;
 
 use crate::prelude::*;
-use crate::stream::{Extend, IntoStream};
+use crate::stream::{self, IntoStream};
 
-impl<T> Extend<T> for LinkedList<T> {
-    fn stream_extend<'a, S: IntoStream<Item = T> + 'a>(
+impl<T> stream::Extend<T> for LinkedList<T> {
+    fn extend<'a, S: IntoStream<Item = T> + 'a>(
         &'a mut self,
         stream: S,
     ) -> Pin<Box<dyn Future<Output = ()> + 'a>> {
diff --git a/src/collections/linked_list/from_stream.rs b/src/collections/linked_list/from_stream.rs
@@ -1,7 +1,7 @@
 use std::collections::LinkedList;
 use std::pin::Pin;
 
-use crate::stream::{Extend, FromStream, IntoStream};
+use crate::stream::{self, FromStream, IntoStream};
 
 impl<T> FromStream<T> for LinkedList<T> {
     #[inline]
@@ -17,7 +17,7 @@ impl<T> FromStream<T> for LinkedList<T> {
             pin_utils::pin_mut!(stream);
 
             let mut out = LinkedList::new();
-            out.stream_extend(stream).await;
+            stream::extend(&mut out, stream).await;
             out
         })
     }
diff --git a/src/collections/vec_deque/extend.rs b/src/collections/vec_deque/extend.rs
@@ -2,10 +2,10 @@ use std::collections::VecDeque;
 use std::pin::Pin;
 
 use crate::prelude::*;
-use crate::stream::{Extend, IntoStream};
+use crate::stream::{self, IntoStream};
 
-impl<T> Extend<T> for VecDeque<T> {
-    fn stream_extend<'a, S: IntoStream<Item = T> + 'a>(
+impl<T> stream::Extend<T> for VecDeque<T> {
+    fn extend<'a, S: IntoStream<Item = T> + 'a>(
         &'a mut self,
         stream: S,
     ) -> Pin<Box<dyn Future<Output = ()> + 'a>> {
diff --git a/src/collections/vec_deque/from_stream.rs b/src/collections/vec_deque/from_stream.rs
@@ -1,7 +1,7 @@
 use std::collections::VecDeque;
 use std::pin::Pin;
 
-use crate::stream::{Extend, FromStream, IntoStream};
+use crate::stream::{self, FromStream, IntoStream};
 
 impl<T> FromStream<T> for VecDeque<T> {
     #[inline]
@@ -17,7 +17,7 @@ impl<T> FromStream<T> for VecDeque<T> {
             pin_utils::pin_mut!(stream);
 
             let mut out = VecDeque::new();
-            out.stream_extend(stream).await;
+            stream::extend(&mut out, stream).await;
             out
         })
     }
diff --git a/src/path/pathbuf.rs b/src/path/pathbuf.rs
@@ -6,7 +6,7 @@ use crate::path::Path;
 #[cfg(feature = "unstable")]
 use crate::prelude::*;
 #[cfg(feature = "unstable")]
-use crate::stream::{Extend, FromStream, IntoStream};
+use crate::stream::{self, FromStream, IntoStream};
 
 /// This struct is an async version of [`std::path::PathBuf`].
 ///
@@ -241,8 +241,8 @@ impl AsRef<std::path::Path> for PathBuf {
 }
 
 #[cfg(feature = "unstable")]
-impl<P: AsRef<Path>> Extend<P> for PathBuf {
-    fn stream_extend<'a, S: IntoStream<Item = P>>(
+impl<P: AsRef<Path>> stream::Extend<P> for PathBuf {
+    fn extend<'a, S: IntoStream<Item = P>>(
         &'a mut self,
         stream: S,
     ) -> Pin<Box<dyn Future<Output = ()> + 'a>>
@@ -275,7 +275,7 @@ impl<'b, P: AsRef<Path> + 'b> FromStream<P> for PathBuf {
             pin_utils::pin_mut!(stream);
 
             let mut out = Self::new();
-            out.stream_extend(stream).await;
+            stream::extend(&mut out, stream).await;
             out
         })
     }
diff --git a/src/stream/extend.rs b/src/stream/extend.rs
@@ -3,7 +3,7 @@ use std::pin::Pin;
 use crate::prelude::*;
 use crate::stream::IntoStream;
 
-/// Extend a collection with the contents of a stream.
+/// Extends a collection with the contents of a stream.
 ///
 /// Streams produce a series of values asynchronously, and collections can also be thought of as a
 /// series of values. The `Extend` trait bridges this gap, allowing you to extend a collection
@@ -17,11 +17,11 @@ use crate::stream::IntoStream;
 /// # async_std::task::block_on(async {
 /// #
 /// use async_std::prelude::*;
-/// use async_std::stream::{self, Extend};
+/// use async_std::stream;
 ///
 /// let mut v: Vec<usize> = vec![1, 2];
 /// let s = stream::repeat(3usize).take(3);
-/// v.stream_extend(s).await;
+/// stream::Extend::extend(&mut v, s).await;
 ///
 /// assert_eq!(v, vec![1, 2, 3, 3, 3]);
 /// #
@@ -31,23 +31,45 @@ use crate::stream::IntoStream;
 #[cfg_attr(feature = "docs", doc(cfg(unstable)))]
 pub trait Extend<A> {
     /// Extends a collection with the contents of a stream.
-    fn stream_extend<'a, T: IntoStream<Item = A> + 'a>(
+    fn extend<'a, T: IntoStream<Item = A> + 'a>(
         &'a mut self,
         stream: T,
     ) -> Pin<Box<dyn Future<Output = ()> + 'a>>
     where
         A: 'a;
 }
 
-impl Extend<()> for () {
-    fn stream_extend<'a, T: IntoStream<Item = ()> + 'a>(
-        &'a mut self,
-        stream: T,
-    ) -> Pin<Box<dyn Future<Output = ()> + 'a>> {
-        let stream = stream.into_stream();
-        Box::pin(async move {
-            pin_utils::pin_mut!(stream);
-            while let Some(_) = stream.next().await {}
-        })
-    }
+/// Extends a collection with the contents of a stream.
+///
+/// Streams produce a series of values asynchronously, and collections can also be thought of as a
+/// series of values. The [`Extend`] trait bridges this gap, allowing you to extend a collection
+/// asynchronously by including the contents of that stream. 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.
+///
+/// [`Extend`]: trait.Extend.html
+///
+/// ## Examples
+///
+/// ```
+/// # async_std::task::block_on(async {
+/// #
+/// use async_std::prelude::*;
+/// use async_std::stream;
+///
+/// let mut v: Vec<usize> = vec![1, 2];
+/// let s = stream::repeat(3usize).take(3);
+/// stream::extend(&mut v, s).await;
+///
+/// assert_eq!(v, vec![1, 2, 3, 3, 3]);
+/// #
+/// # })
+/// ```
+pub async fn extend<'a, C, A, T>(collection: &mut C, stream: T)
+where
+    C: Extend<A>,
+    A: 'a,
+    T: IntoStream<Item = A> + 'a,
+{
+    Extend::extend(collection, stream).await
 }
diff --git a/src/stream/from_stream.rs b/src/stream/from_stream.rs
@@ -45,8 +45,7 @@ use std::pin::Pin;
 ///
 /// ```
 /// use async_std::prelude::*;
-/// use async_std::stream::{Extend, FromStream, IntoStream};
-/// use async_std::stream;
+/// use async_std::stream::{self, FromStream, IntoStream};
 /// use std::pin::Pin;
 ///
 /// // A sample collection, that's just a wrapper over Vec<T>
@@ -76,7 +75,7 @@ use std::pin::Pin;
 ///             let mut c = MyCollection::new();
 ///
 ///             let mut v = vec![];
-///             v.stream_extend(stream).await;
+///             stream::extend(&mut v, stream).await;
 ///
 ///             for i in v {
 ///                 c.add(i);
diff --git a/src/stream/mod.rs b/src/stream/mod.rs
@@ -332,7 +332,7 @@ cfg_unstable! {
 
     pub use double_ended_stream::DoubleEndedStream;
     pub use exact_size_stream::ExactSizeStream;
-    pub use extend::Extend;
+    pub use extend::{extend, Extend};
     pub use from_stream::FromStream;
     pub use fused_stream::FusedStream;
     pub use interval::{interval, Interval};
diff --git a/src/string/extend.rs b/src/string/extend.rs
diff --git a/src/string/from_stream.rs b/src/string/from_stream.rs
diff --git a/src/unit/extend.rs b/src/unit/extend.rs
diff --git a/src/unit/mod.rs b/src/unit/mod.rs
diff --git a/src/vec/extend.rs b/src/vec/extend.rs
diff --git a/src/vec/from_stream.rs b/src/vec/from_stream.rs
