# Mapped Futures

This library contains several structs that map keys to asynchronous tasks. It contains `MappedFutures`, `BiMultiMapFutures`, `MappedStreams`, and `BiMultiMapStreams`. Once added, the futures or streams can be mutated or removed if you have the key. These modules add mapping data structures to FuturesUnordered, so futures will only be polled after being woken, and will complete out of order.

You can create the mapping, insert futures, cancel them, and wait for the next completing future, which will return the future's output and its key. If the future is `Unpin` then a reference can be retrieved for mutation with `MappedFutures::get_mut()`, otherwise `MappedFutures::get_pin_mut()` must be used.

```
use crate::mapped_futures::*;
use futures::executor::block_on;
use futures::future::LocalBoxFuture;
use futures_timer::Delay;
use futures_util::StreamExt;
use std::time::Duration;

let mut futures = MappedFutures::new();
futures.insert(1, Delay::new(Duration::from_millis(50)));
futures.insert(2, Delay::new(Duration::from_millis(75)));
futures.insert(3, Delay::new(Duration::from_millis(100)));
assert_eq!(futures.cancel(&1), true);
futures.get_pin_mut(&2).unwrap().reset(Duration::from_millis(125));
assert_eq!(block_on(futures.next()).unwrap().0, 3);
assert_eq!(block_on(futures.next()).unwrap().0, 2);
assert_eq!(block_on(futures.next()), None);
```

In order to retrieve any owned futures from the mapping, the futures have to be `Unpin`, such as by enclosing them in `Box::pin()`.

```
use crate::mapped_futures::*;
use futures::executor::block_on;
use futures::future::LocalBoxFuture;
use futures_timer::Delay;
use futures_util::StreamExt;
use std::time::Duration;

futures.insert(1, Box::pin(Delay::new(Duration::from_millis(50))));
futures.insert(2, Box::pin(Delay::new(Duration::from_millis(75))));
futures.insert(3, Box::pin(Delay::new(Duration::from_millis(100))));
assert_eq!(block_on(futures.remove(&1)).unwrap().0, ());
assert_eq!(block_on(futures.replace(&2, Delay::new(Duration::from_millis(125)))).unwrap().0, ());
assert_eq!(block_on(futures.next()).unwrap().0, 3);
```

A similar interface exists for `MappedStreams` but with streams instead of futures. If your future mapping needs are more complex, you can use `BiMultiMapFutures`, which suppports one-to-many relationships between futures and two kinds of key. So each key will be associated with zero or more futures, but each (leftkey, rightkey) pair will be associated with at most one future. `BiMultiMapStreams` does the same for streams.