@@ -354,6 +354,43 @@ impl<K: Hash + Eq, V> HashMap<K, V> {
354354
355355 /// Modify and return the value corresponding to the key in the map, or
356356/// insert and return a new value if it doesn't exist.
357+ ///
358+ /// This method allows for all insertion behaviours of a hashmap,
359+ /// see methods like `insert`, `find_or_insert` and
360+ /// `insert_or_update_with` for less general and more friendly
361+ /// variations of this.
362+ ///
363+ /// # Example
364+ ///
365+ /// ```rust
366+ /// use std::hashmap::HashMap;
367+ ///
368+ /// // map some strings to vectors of strings
369+ /// let mut map = HashMap::<~str, ~[~str]>::new();
370+ /// map.insert(~"a key", ~[~"value"]);
371+ /// map.insert(~"z key", ~[~"value"]);
372+ ///
373+ /// let new = ~[~"a key", ~"b key", ~"z key"];
374+ /// for k in new.move_iter() {
375+ /// map.mangle(k, ~"new value",
376+ /// // if the key doesn't exist in the map yet, add it in
377+ /// // the obvious way.
378+ /// |_k, v| ~[v],
379+ /// // if the key does exist either prepend or append this
380+ /// // new value based on the first letter of the key.
381+ /// |key, already, new| {
382+ /// if key.starts_with("z") {
383+ /// already.unshift(new);
384+ /// } else {
385+ /// already.push(new);
386+ /// }
387+ /// });
388+ /// }
389+ ///
390+ /// for (k, v) in map.iter() {
391+ /// println!("{} -> {:?}", *k, *v);
392+ /// }
393+ /// ```
357394pub fn mangle < ' a ,
358395 A > (
359396 & ' a mut self ,
0 commit comments