pub fn insert<K>(&mut self, key: K, val: MetadataValue<Ascii>) -> Option<MetadataValue<Ascii>>
    where
        K: IntoMetadataKey<Ascii>,
    {
        key.insert(self, val)
    }
Inserts an ascii key-value pair into the map. To insert a binary entry,
use `insert_bin`.

This method panics when the given key is a string and it cannot be
converted to a `MetadataKey<Ascii>`.

If the map did not previously have this key present, then `None` is
returned.

If the map did have this key present, the new value is associated with
the key and all previous values are removed. **Note** that only a single
one of the previous values is returned. If there are multiple values
that have been previously associated with the key, then the first one is
returned. See `insert_mult` on `OccupiedEntry` for an API that returns
all values.

The key is not updated, though; this matters for types that can be `==`
without being identical.

# Examples

```
# use tonic::metadata::*;
let mut map = MetadataMap::new();
assert!(map.insert("x-host", "world".parse().unwrap()).is_none());
assert!(!map.is_empty());

let mut prev = map.insert("x-host", "earth".parse().unwrap()).unwrap();
assert_eq!("world", prev);
```

```should_panic
# use tonic::metadata::*;
let mut map = MetadataMap::new();
// Trying to insert a key that is not valid panics.
map.insert("x{}host", "world".parse().unwrap());
```

```should_panic
# use tonic::metadata::*;
let mut map = MetadataMap::new();
// Trying to insert a key that is binary panics (use insert_bin).
map.insert("x-host-bin", "world".parse().unwrap());
```
tonic/src/metadata/map.rs