Add Patricia::insert_str() doc

Author: sile

src/map.rs

@@ -142,7 +142,33 @@ impl<V> PatriciaMap<V> {
         self.tree.insert(key, value)
     }
 
-    #[allow(missing_docs)]
+    /// As with [`PatriciaMap::insert()`] except for that this method regards UTF-8 character boundaries of the input key.
+
+    /// # Examples
+    ///
+    /// ```
+    /// use patricia_tree::PatriciaMap;
+    ///
+    /// // Insert keys as opaque byte strings.
+    /// //
+    /// // Node labels can be arbitrary byte strings.
+    /// let mut map = PatriciaMap::new();
+    /// map.insert("🌏🗻", ()); // [240, 159, 140, 143, 240, 159, 151, 187]
+    /// map.insert("🌏🍔", ()); // [240, 159, 140, 143, 240, 159, 141, 148]
+    ///
+    /// let first_label = map.as_ref().child().unwrap().label();
+    /// assert_eq!(first_label, [240, 159, 140, 143, 240, 159]);
+    ///
+    /// // Insert keys as UTF-8 strings.
+    /// //
+    /// // Node labels are guaranteed to be UTF-8 byte strings.
+    /// let mut map = PatriciaMap::new();
+    /// map.insert_str("🌏🗻", ());
+    /// map.insert_str("🌏🍔", ());
+    ///
+    /// let first_label = map.as_ref().child().unwrap().label();
+    /// assert_eq!(first_label, "🌏".as_bytes());
+    /// ```
     pub fn insert_str(&mut self, key: &str, value: V) -> Option<V> {
         self.tree.insert_str(key, value)
     }