- linked hashmap documentation and example

README.md

@@ -21,6 +21,7 @@ Implementation of various data structures and algorithms in Go.
   - [Maps](#maps)
     - [HashMap](#hashmap)
     - [TreeMap](#treemap)
+    - [LinkedHashMap](#linkedhashmap)
     - [HashBidiMap](#hashbidimap)
     - [TreeBidiMap](#treebidimap)
   - [Trees](#trees)
@@ -77,9 +78,10 @@ Containers are either ordered or unordered. All ordered containers provide [stat
 | [Maps](#maps) |
 |   | [HashMap](#hashmap) | no | no | no | key |
 |   | [TreeMap](#treemap) | yes | yes* | yes | key |
+|   | [LinkedHashMap](#linkedhashmap) | yes | yes* | yes | key |
 |   | [HashBidiMap](#hashbidimap) | no | no | no | key* |
-| [Trees](#trees) |
 |   | [TreeBidiMap](#treebidimap) | yes | yes* | yes | key* |
+| [Trees](#trees) |
 |   | [RedBlackTree](#redblacktree) | yes | yes* | no | key |
 |   | [AVLTree](#avltree) | yes | yes* | no | key |
 |   | [BTree](#btree) | yes | yes* | no | key |
@@ -487,6 +489,34 @@ func main() {
 }
 ```
 
+#### LinkedHashMap
+
+A [map](#maps) that preserves insertion-order. It is backed by a hash table to store values and [doubly-linked list](doublylinkedlist) to store ordering.
+
+Implements [Map](#maps), [IteratorWithKey](#iteratorwithkey), [EnumerableWithKey](#enumerablewithkey), [JSONSerializer](#jsonserializer) and [JSONDeserializer](#jsondeserializer) interfaces.
+
+```go
+package main
+
+import "github.com/emirpasic/gods/maps/linkedhashmap"
+
+func main() {
+	m := linkedhashmap.New() // empty (keys are of type int)
+	m.Put(2, "b")            // 2->b
+	m.Put(1, "x")            // 2->b, 1->x (insertion-order)
+	m.Put(1, "a")            // 2->b, 1->a (insertion-order)
+	_, _ = m.Get(2)          // b, true
+	_, _ = m.Get(3)          // nil, false
+	_ = m.Values()           // []interface {}{"b", "a"} (insertion-order)
+	_ = m.Keys()             // []interface {}{2, 1} (insertion-order)
+	m.Remove(1)              // 2->b
+	m.Clear()                // empty
+	m.Empty()                // true
+	m.Size()                 // 0
+}
+
+```
+
 #### HashBidiMap
 
 A [map](#maps) based on two hashmaps. Keys are unordered.

examples/linkedhashmap/linkedhashmap.go

@@ -0,0 +1,23 @@
+// Copyright (c) 2015, Emir Pasic. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import "github.com/emirpasic/gods/maps/linkedhashmap"
+
+// LinkedHashMapExample to demonstrate basic usage of LinkedHashMapExample
+func main() {
+	m := linkedhashmap.New() // empty (keys are of type int)
+	m.Put(2, "b")            // 2->b
+	m.Put(1, "x")            // 2->b, 1->x (insertion-order)
+	m.Put(1, "a")            // 2->b, 1->a (insertion-order)
+	_, _ = m.Get(2)          // b, true
+	_, _ = m.Get(3)          // nil, false
+	_ = m.Values()           // []interface {}{"b", "a"} (insertion-order)
+	_ = m.Keys()             // []interface {}{2, 1} (insertion-order)
+	m.Remove(1)              // 2->b
+	m.Clear()                // empty
+	m.Empty()                // true
+	m.Size()                 // 0
+}