add examples to README

README.md

@@ -41,6 +41,70 @@
   </h3>
 </div>
 
+Performant, portable, structured concurrency operations for async Rust. It
+works with any runtime, does not erase lifetimes, always handles
+cancellation, and always returns output to the caller.
+
+`futures-concurrency` provides concurrency operations for both groups of futures
+and streams. Both for bounded and unbounded sets of futures and streams. In both
+cases performance should be on par with, if not exceed conventional executor
+implementations.
+
+## Examples
+
+**Await multiple futures of different types**
+```rust
+use futures_concurrency::prelude::*;
+use std::future;
+
+let a = future::ready(1u8);
+let b = future::ready("hello");
+let c = future::ready(3u16);
+assert_eq!((a, b, c).join().await, (1, "hello", 3));
+```
+
+**Concurrently process items in a stream**
+
+```rust
+use futures_concurrency::prelude::*;
+use futures_lite::stream;
+
+# futures::executor::block_on(async {
+let v: Vec<_> = vec!["chashu", "nori"]
+    .into_co_stream()
+    .map(|msg| async move { format!("hello {msg}") })
+    .collect()
+    .await;
+
+assert_eq!(v, &["hello chashu", "hello nori"]);
+```
+
+**Access stack data outside the futures' scope**
+
+_Adapted from [`std::thread::scope`](https://doc.rust-lang.org/std/thread/fn.scope.html)._
+
+```rust
+use futures_concurrency::prelude::*;
+
+let mut container = vec![1, 2, 3];
+let mut num = 0;
+
+let a = async {
+    println!("hello from the first future");
+    dbg!(&container);
+};
+
+let b = async {
+    println!("hello from the second future");
+    num += container[0] + container[2];
+};
+
+println!("hello from the main future");
+let _ = (a, b).join().await;
+container.push(4);
+assert_eq!(num, container.len());
+```
+
 ## Installation
 ```sh
 $ cargo add futures-concurrency

src/lib.rs

@@ -7,7 +7,7 @@
 //! cases performance should be on par with, if not exceed conventional executor
 //! implementations.
 //!
-//! ## Examples
+//! # Examples
 //!
 //! **Await multiple futures of different types**
 //! ```rust
@@ -67,9 +67,9 @@
 //! # });
 //! ```
 //!
-//! ## Operations
+//! # Operations
 //!
-//! ### Futures
+//! ## Futures
 //!
 //! For futures which return a regular type `T` only the `join` and `race`
 //! operations are available. `join` waits for all futures to complete, while `race`
@@ -88,7 +88,7 @@
 //! - `array`: [`join`][future::Join#impl-Join-for-\[Fut;+N\]], [`try_join`][future::TryJoin#impl-TryJoin-for-\[Fut;+N\]], [`race`][future::Race#impl-Race-for-\[Fut;+N\]], [`race_ok`][future::RaceOk#impl-RaceOk-for-\[Fut;+N\]]
 //! - `Vec`: [`join`][future::Join#impl-Join-for-Vec<Fut>], [`try_join`][future::TryJoin#impl-TryJoin-for-Vec<Fut>], [`race`][future::Race#impl-Race-for-Vec<Fut>], [`race_ok`][future::RaceOk#impl-RaceOk-for-Vec<Fut>]
 //!
-//! ### Streams
+//! ## Streams
 //!
 //! Streams yield outputs one-by-one, which means that deciding to stop iterating is
 //! the same for fallible and infallible streams. The operations provided for
@@ -116,15 +116,15 @@
 //! - `array`: [`chain`][stream::Chain#impl-Chain-for-\[Fut;+N\]], [`merge`][stream::Merge#impl-Merge-for-\[Fut;+N\]], [`zip`][stream::Zip#impl-Zip-for-\[Fut;+N\]]
 //! - `Vec`: [`chain`][stream::Chain#impl-Chain-for-Vec<Fut>], [`merge`][stream::Merge#impl-Merge-for-Vec<Fut>], [`zip`][stream::Zip#impl-Zip-for-Vec<Fut>]
 //!
-//! ## Runtime Support
+//! # Runtime Support
 //!
 //! `futures-concurrency` does not depend on any runtime executor being present.
 //! This enables it to work out of the box with any async runtime, including:
 //! `tokio`, `async-std`, `smol`, `glommio`, and `monoio`. It also supports
 //! `#[no_std]` environments, allowing it to be used with embedded async
 //! runtimes such as `embassy`.
 //!
-//! ## Feature Flags
+//! # Feature Flags
 //!
 //! The `std` feature flag is enabled by default. To target `alloc` or `no_std`
 //! environments, you can enable the following configuration:
@@ -138,7 +138,7 @@
 //! futures-concurrency = { version = "7.5.0", default-features = false, features = ["alloc"] }
 //! ```
 //!
-//! ## Further Reading
+//! # Further Reading
 //!
 //! `futures-concurrency` has been developed over the span of several years. It is
 //! primarily maintained by Yosh Wuyts, a member of the Rust Async WG. You can read