first step of restoring deprecated methods

Author: glebpom

src/header/map.rs

@@ -445,9 +445,30 @@ impl HeaderMap {
 }
 
 impl<T> HeaderMap<T> {
-    #[deprecated = "use `try_with_capacity` instead"]
+    /// Create an empty `HeaderMap` with the specified capacity.
+    ///
+    /// The returned map will allocate internal storage in order to hold about
+    /// `capacity` elements without reallocating. However, this is a "best
+    /// effort" as there are usage patterns that could cause additional
+    /// allocations before `capacity` headers are stored in the map.
+    ///
+    /// More capacity than requested may be allocated.
+    ///
+    /// # Panics
+    ///
+    /// if capacity is >=
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use http::HeaderMap;
+    /// let map: HeaderMap<u32> = HeaderMap::with_capacity(10);
+    ///
+    /// assert!(map.is_empty());
+    /// assert_eq!(12, map.capacity());
+    /// ```
     pub fn with_capacity(capacity: usize) -> HeaderMap<T> {
-        Self::try_with_capacity(capacity).expect("failed to reserve")
+        Self::try_with_capacity(capacity).expect("size overflows MAX_SIZE")
     }
 
     /// Create an empty `HeaderMap` with the specified capacity.
@@ -614,7 +635,28 @@ impl<T> HeaderMap<T> {
         usable_capacity(self.indices.len())
     }
 
-    #[deprecated = "use try_reserve instead"]
+    /// Reserves capacity for at least `additional` more headers to be inserted
+    /// into the `HeaderMap`.
+    ///
+    /// The header map may reserve more space to avoid frequent reallocations.
+    /// Like with `with_capacity`, this will be a "best effort" to avoid
+    /// allocations until `additional` more headers are inserted. Certain usage
+    /// patterns could cause additional allocations before the number is
+    /// reached.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the new allocation size overflows `HeaderMap` `MAX_SIZE`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use http::HeaderMap;
+    /// # use http::header::HOST;
+    /// let mut map = HeaderMap::new();
+    /// map.try_reserve(10).unwrap();
+    /// # map.insert(HOST, "bar".parse().unwrap());
+    /// ```
     pub fn reserve(&mut self, additional: usize) {
         self.try_reserve(additional).expect("reservation failed")
     }
@@ -628,9 +670,12 @@ impl<T> HeaderMap<T> {
     /// patterns could cause additional allocations before the number is
     /// reached.
     ///
-    /// # Panics
+    /// # Errors
     ///
-    /// Panics if the new allocation size overflows `usize`.
+    /// This method differs from `reserve` by allowing types that may not be
+    /// valid `HeaderName`s to passed as the key (such as `String`). If they
+    /// do not parse as a valid `HeaderName`, this returns an
+    /// `InvalidHeaderName` error.
     ///
     /// # Examples
     ///
@@ -639,7 +684,7 @@ impl<T> HeaderMap<T> {
     /// # use http::header::HOST;
     /// let mut map = HeaderMap::new();
     /// map.try_reserve(10).unwrap();
-    /// # map.insert(HOST, "bar".parse().unwrap());
+    /// # map.try_insert(HOST, "bar".parse().unwrap()).unwrap();
     /// ```
     pub fn try_reserve(&mut self, additional: usize) -> Result<(), CapacityOverflow> {
         // TODO: This can't overflow if done properly... since the max # of
@@ -1033,7 +1078,15 @@ impl<T> HeaderMap<T> {
         }
     }
 
-    #[deprecated = "use `try_entry` instead"]
+    /// Gets the given key's corresponding entry in the map for in-place
+    /// manipulation.
+    ///
+    /// # Errors
+    ///
+    /// This method differs from `entry` by allowing types that may not be
+    /// valid `HeaderName`s to passed as the key (such as `String`). If they
+    /// do not parse as a valid `HeaderName`, this returns an
+    /// `InvalidHeaderName` error.
     pub fn entry<K>(&mut self, key: K) -> Entry<'_, T>
         where
             K: IntoHeaderName,
@@ -1094,7 +1147,33 @@ impl<T> HeaderMap<T> {
                 ))
     }
 
-    #[deprecated = "use `try_insert` instead"]
+    /// Inserts a key-value pair into the map.
+    ///
+    /// 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 http::HeaderMap;
+    /// # use http::header::HOST;
+    /// let mut map = HeaderMap::new();
+    /// assert!(map.try_insert(HOST, "world".parse().unwrap()).unwrap().is_none());
+    /// assert!(!map.is_empty());
+    ///
+    /// let mut prev = map.try_insert(HOST, "earth".parse().unwrap()).unwrap().unwrap();
+    /// assert_eq!("world", prev);
+    /// ```
     pub fn insert<K>(&mut self, key: K, val: T) -> Option<T>
     where
         K: IntoHeaderName,
@@ -1206,7 +1285,32 @@ impl<T> HeaderMap<T> {
         }
     }
 
-    #[deprecated = "use `try_append` instead"]
+    /// Inserts a key-value pair into the map.
+    ///
+    /// If the map did not previously have this key present, then `false` is
+    /// returned.
+    ///
+    /// If the map did have this key present, the new value is pushed to the end
+    /// of the list of values currently associated with the key. The key is not
+    /// updated, though; this matters for types that can be `==` without being
+    /// identical.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use http::HeaderMap;
+    /// # use http::header::HOST;
+    /// let mut map = HeaderMap::new();
+    /// assert!(map.try_insert(HOST, "world".parse().unwrap()).unwrap().is_none());
+    /// assert!(!map.is_empty());
+    ///
+    /// map.try_append(HOST, "earth".parse().unwrap()).unwrap();
+    ///
+    /// let values = map.get_all("host");
+    /// let mut i = values.iter();
+    /// assert_eq!("world", *i.next().unwrap());
+    /// assert_eq!("earth", *i.next().unwrap());
+    /// ```
     pub fn append<K>(&mut self, key: K, value: T) -> bool
         where
             K: IntoHeaderName,
@@ -2278,7 +2382,34 @@ unsafe impl<'a, T: Send> Send for Drain<'a, T> {}
 // ===== impl Entry =====
 
 impl<'a, T> Entry<'a, T> {
-    #[deprecated = "user `or_try_insert` instead"]
+    /// Ensures a value is in the entry by inserting the default if empty.
+    ///
+    /// Returns a mutable reference to the **first** value in the entry.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use http::HeaderMap;
+    /// let mut map: HeaderMap<u32> = HeaderMap::default();
+    ///
+    /// let headers = &[
+    ///     "content-length",
+    ///     "x-hello",
+    ///     "Content-Length",
+    ///     "x-world",
+    /// ];
+    ///
+    /// for &header in headers {
+    ///     let counter = map.try_entry(header
+    ///         .unwrap()
+    ///         .or_try_insert(0)
+    ///         .unwrap());
+    ///     *counter += 1;
+    /// }
+    ///
+    /// assert_eq!(map["content-length"], 2);
+    /// assert_eq!(map["x-hello"], 1);
+    /// ```
     pub fn or_insert(self, default: T) -> &'a mut T {
         self.or_try_insert(default).expect("capacity error")
     }
@@ -2320,7 +2451,42 @@ impl<'a, T> Entry<'a, T> {
         }
     }
 
-    #[deprecated = "use `or_try_insert_with` instead"]
+    /// Ensures a value is in the entry by inserting the result of the default
+    /// function if empty.
+    ///
+    /// The default function is not called if the entry exists in the map.
+    /// Returns a mutable reference to the **first** value in the entry.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage.
+    ///
+    /// ```
+    /// # use http::HeaderMap;
+    /// let mut map = HeaderMap::new();
+    ///
+    /// let res = map.entry("x-hello")
+    ///     .or_insert_with(|| "world".parse().unwrap());
+    ///
+    /// assert_eq!(res, "world");
+    /// ```
+    ///
+    /// The default function is not called if the entry exists in the map.
+    ///
+    /// ```
+    /// # use http::HeaderMap;
+    /// # use http::header::HOST;
+    /// let mut map = HeaderMap::new();
+    /// map.try_insert(HOST, "world".parse().unwrap()).unwrap();
+    ///
+    /// let res = map.try_entry("host")
+    ///     .unwrap()
+    ///     .or_try_insert_with(|| unreachable!())
+    ///     .unwrap();
+    ///
+    ///
+    /// assert_eq!(res, "world");
+    /// ```
     pub fn or_insert_with<F: FnOnce() -> T>(self, default: F) -> &'a mut T {
         self.or_try_insert_with(default).expect("reservation error")
     }
@@ -2423,7 +2589,23 @@ impl<'a, T> VacantEntry<'a, T> {
         self.key
     }
 
-    #[deprecated = "use `try_insert` instead"]
+    /// Insert the value into the entry.
+    ///
+    /// The value will be associated with this entry's key. A mutable reference
+    /// to the inserted value will be returned.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use http::header::{HeaderMap, Entry};
+    /// let mut map = HeaderMap::new();
+    ///
+    /// if let Entry::Vacant(v) = map.entry("x-hello") {
+    ///     v.insert("world".parse().unwrap());
+    /// }
+    ///
+    /// assert_eq!(map["x-hello"], "world");
+    /// ```
     pub fn insert(self, value: T) -> &'a mut T {
         self.try_insert(value).expect("reservation failed")
     }
@@ -2454,7 +2636,24 @@ impl<'a, T> VacantEntry<'a, T> {
         Ok(&mut self.map.entries[index].value)
     }
 
-    #[deprecated = "user `try_insert_entry` instead"]
+    /// Insert the value into the entry.
+    ///
+    /// The value will be associated with this entry's key. The new
+    /// `OccupiedEntry` is returned, allowing for further manipulation.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use http::header::*;
+    /// let mut map = HeaderMap::new();
+    ///
+    /// if let Entry::Vacant(v) = map.try_entry("x-hello").unwrap() {
+    ///     let mut e = v.try_insert_entry("world".parse().unwrap()).unwrap();
+    ///     e.insert("world2".parse().unwrap());
+    /// }
+    ///
+    /// assert_eq!(map["x-hello"], "world2");
+    /// ```
     pub fn insert_entry(self, value: T) -> OccupiedEntry<'a, T> {
         self.try_insert_entry(value).expect("reserve failed")
     }