diff --git a/README.md b/README.md index a491abb..e73ffb1 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,7 @@ Implementation of various data structures and algorithms in Go. - [Maps](#maps) - [HashMap](#hashmap) - [TreeMap](#treemap) + - [HashBidiMap](#hashbidimap) - [Trees](#trees) - [RedBlackTree](#redblacktree) - [BinaryHeap](#binaryheap) @@ -53,7 +54,7 @@ type Container interface { Containers are either ordered or unordered. All ordered containers provide [stateful iterators](#iterator) and some of them allow [enumerable functions](#enumerable). -| Container | Ordered | [Iterator](#iterator) | [Enumerable](#enumerable) | Ordered by | +| Container | Ordered | [Iterator](#iterator) | [Enumerable](#enumerable) | Referenced by | | :--- | :---: | :---: | :---: | :---: | | [ArrayList](#arraylist) | yes | yes* | yes | index | | [SinglyLinkedList](#singlylinkedlist) | yes | yes | yes | index | @@ -64,9 +65,10 @@ Containers are either ordered or unordered. All ordered containers provide [stat | [ArrayStack](#arraystack) | yes | yes* | no | index | | [HashMap](#hashmap) | no | no | no | key | | [TreeMap](#treemap) | yes | yes* | yes | key | +| [HashBidiMap](#hashbidimap) | no | no | no | key* | | [RedBlackTree](#redblacktree) | yes | yes* | no | key | | [BinaryHeap](#binaryheap) | yes | yes* | no | index | -| | | *reversible | | | +| | | *reversible | | *bidirectional | ### Lists @@ -372,6 +374,16 @@ type Map interface { } ``` +A BidiMap is an extension to the Map. A bidirectional map (BidiMap), also called a hash bag, is an associative data structure in which the key-value pairs form a one-to-one relation. This relation works in both directions by allow the value to also act as a key to key, e.g. a pair (a,b) thus provides a coupling between 'a' and 'b' so that 'b' can be found when 'a' is used as a key and 'a' can be found when 'b' is used as a key. + +```go +type BidiMap interface { + GetKey(value interface{}) (key interface{}, found bool) + + Map +} +``` + #### HashMap A [map](#maps) based on hash tables. Keys are unordered. @@ -430,6 +442,35 @@ func main() { } ``` +#### HashBidiMap + +A [map](#maps) based on two hashmaps. Keys are unordered. + +Implements [BidiMap](#maps) interface. + +```go +package main + +import "github.com/emirpasic/gods/maps/hashbidimap" + +func main() { + m := hashbidimap.New() // empty + m.Put(1, "x") // 1->x + m.Put(3, "b") // 1->x, 3->b (random order) + m.Put(1, "a") // 1->a, 3->b (random order) + m.Put(2, "b") // 1->a, 2->b (random order) + _, _ = m.GetKey("a") // 1, true + _, _ = m.Get(2) // b, true + _, _ = m.Get(3) // nil, false + _ = m.Values() // []interface {}{"a", "b"} (random order) + _ = m.Keys() // []interface {}{1, 2} (random order) + m.Remove(1) // 2->b + m.Clear() // empty + m.Empty() // true + m.Size() // 0 +} +``` + ### Trees A tree is a widely used data data structure that simulates a hierarchical tree structure, with a root value and subtrees of children, represented as a set of linked nodes; thus no cyclic links. @@ -1057,6 +1098,10 @@ Collections and data structures found in other languages: Java Collections, C++ - Used in production. +**No dependencies**: + + - No external imports. + There is often a tug of war between speed and memory when crafting algorithms. We choose to optimize for speed in most cases within reasonable limits on memory consumption. Thread safety is not a concern of this project, this should be handled at a higher level. diff --git a/examples/hashbidimap.go b/examples/hashbidimap.go new file mode 100644 index 0000000..861fff9 --- /dev/null +++ b/examples/hashbidimap.go @@ -0,0 +1,25 @@ +// 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 examples + +import "github.com/emirpasic/gods/maps/hashbidimap" + +// HashBidiMapExample to demonstrate basic usage of HashMap +func HashBidiMapExample() { + m := hashbidimap.New() // empty + m.Put(1, "x") // 1->x + m.Put(3, "b") // 1->x, 3->b (random order) + m.Put(1, "a") // 1->a, 3->b (random order) + m.Put(2, "b") // 1->a, 2->b (random order) + _, _ = m.GetKey("a") // 1, true + _, _ = m.Get(2) // b, true + _, _ = m.Get(3) // nil, false + _ = m.Values() // []interface {}{"a", "b"} (random order) + _ = m.Keys() // []interface {}{1, 2} (random order) + m.Remove(1) // 2->b + m.Clear() // empty + m.Empty() // true + m.Size() // 0 +} diff --git a/maps/hashbidimap/hashbidimap.go b/maps/hashbidimap/hashbidimap.go new file mode 100644 index 0000000..11027fd --- /dev/null +++ b/maps/hashbidimap/hashbidimap.go @@ -0,0 +1,102 @@ +// 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 hashbidimap implements a bidirectional map backed by two hashmaps. +// +// A bidirectional map, or hash bag, is an associative data structure in which the (key,value) pairs form a one-to-one correspondence. +// Thus the binary relation is functional in each direction: value can also act as a key to key. +// A pair (a,b) thus provides a unique coupling between 'a' and 'b' so that 'b' can be found when 'a' is used as a key and 'a' can be found when 'b' is used as a key. +// +// Elements are unordered in the map. +// +// Structure is not thread safe. +// +// Reference: https://en.wikipedia.org/wiki/Bidirectional_map +package hashbidimap + +import ( + "fmt" + "github.com/emirpasic/gods/maps" + "github.com/emirpasic/gods/maps/hashmap" +) + +func assertMapImplementation() { + var _ maps.BidiMap = (*Map)(nil) +} + +// Map holds the elements in two hashmaps. +type Map struct { + forwardMap hashmap.Map + inverseMap hashmap.Map +} + +// New instantiates a bidirectional map. +func New() *Map { + return &Map{*hashmap.New(), *hashmap.New()} +} + +// Put inserts element into the map. +func (m *Map) Put(key interface{}, value interface{}) { + if valueByKey, ok := m.forwardMap.Get(key); ok { + m.inverseMap.Remove(valueByKey) + } + if keyByValue, ok := m.inverseMap.Get(value); ok { + m.forwardMap.Remove(keyByValue) + } + m.forwardMap.Put(key, value) + m.inverseMap.Put(value, key) +} + +// Get searches the element in the map by key and returns its value or nil if key is not found in map. +// Second return parameter is true if key was found, otherwise false. +func (m *Map) Get(key interface{}) (value interface{}, found bool) { + return m.forwardMap.Get(key) +} + +// GetKey searches the element in the map by value and returns its key or nil if value is not found in map. +// Second return parameter is true if value was found, otherwise false. +func (m *Map) GetKey(value interface{}) (key interface{}, found bool) { + return m.inverseMap.Get(value) +} + +// Remove removes the element from the map by key. +func (m *Map) Remove(key interface{}) { + if value, found := m.forwardMap.Get(key); found { + m.forwardMap.Remove(key) + m.inverseMap.Remove(value) + } +} + +// Empty returns true if map does not contain any elements +func (m *Map) Empty() bool { + return m.Size() == 0 +} + +// Size returns number of elements in the map. +func (m *Map) Size() int { + return m.forwardMap.Size() +} + +// Keys returns all keys (random order). +func (m *Map) Keys() []interface{} { + return m.forwardMap.Keys() +} + +// Values returns all values (random order). +func (m *Map) Values() []interface{} { + return m.inverseMap.Keys() +} + +// Clear removes all elements from the map. +func (m *Map) Clear() { + m.forwardMap.Clear() + m.inverseMap.Clear() +} + +// String returns a string representation of container +func (m *Map) String() string { + str := "HashMap\n" + str += fmt.Sprintf("%v", m.forwardMap) + return str +} diff --git a/maps/hashbidimap/hashbidimap_test.go b/maps/hashbidimap/hashbidimap_test.go new file mode 100644 index 0000000..ca46a06 --- /dev/null +++ b/maps/hashbidimap/hashbidimap_test.go @@ -0,0 +1,182 @@ +// 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 hashbidimap + +import ( + "fmt" + "testing" +) + +func TestMapPut(t *testing.T) { + m := New() + m.Put(5, "e") + m.Put(6, "f") + m.Put(7, "g") + m.Put(3, "c") + m.Put(4, "d") + m.Put(1, "x") + m.Put(2, "b") + m.Put(1, "a") //overwrite + + if actualValue := m.Size(); actualValue != 7 { + t.Errorf("Got %v expected %v", actualValue, 7) + } + if actualValue, expectedValue := m.Keys(), []interface{}{1, 2, 3, 4, 5, 6, 7}; !sameElements(actualValue, expectedValue) { + t.Errorf("Got %v expected %v", actualValue, expectedValue) + } + if actualValue, expectedValue := m.Values(), []interface{}{"a", "b", "c", "d", "e", "f", "g"}; !sameElements(actualValue, expectedValue) { + t.Errorf("Got %v expected %v", actualValue, expectedValue) + } + + // key,expectedValue,expectedFound + tests1 := [][]interface{}{ + {1, "a", true}, + {2, "b", true}, + {3, "c", true}, + {4, "d", true}, + {5, "e", true}, + {6, "f", true}, + {7, "g", true}, + {8, nil, false}, + } + + for _, test := range tests1 { + // retrievals + actualValue, actualFound := m.Get(test[0]) + if actualValue != test[1] || actualFound != test[2] { + t.Errorf("Got %v expected %v", actualValue, test[1]) + } + } +} + +func TestMapRemove(t *testing.T) { + m := New() + m.Put(5, "e") + m.Put(6, "f") + m.Put(7, "g") + m.Put(3, "c") + m.Put(4, "d") + m.Put(1, "x") + m.Put(2, "b") + m.Put(1, "a") //overwrite + + m.Remove(5) + m.Remove(6) + m.Remove(7) + m.Remove(8) + m.Remove(5) + + if actualValue, expectedValue := m.Keys(), []interface{}{1, 2, 3, 4}; !sameElements(actualValue, expectedValue) { + t.Errorf("Got %v expected %v", actualValue, expectedValue) + } + + if actualValue, expectedValue := m.Values(), []interface{}{"a", "b", "c", "d"}; !sameElements(actualValue, expectedValue) { + t.Errorf("Got %v expected %v", actualValue, expectedValue) + } + if actualValue := m.Size(); actualValue != 4 { + t.Errorf("Got %v expected %v", actualValue, 4) + } + + tests2 := [][]interface{}{ + {1, "a", true}, + {2, "b", true}, + {3, "c", true}, + {4, "d", true}, + {5, nil, false}, + {6, nil, false}, + {7, nil, false}, + {8, nil, false}, + } + + for _, test := range tests2 { + actualValue, actualFound := m.Get(test[0]) + if actualValue != test[1] || actualFound != test[2] { + t.Errorf("Got %v expected %v", actualValue, test[1]) + } + } + + m.Remove(1) + m.Remove(4) + m.Remove(2) + m.Remove(3) + m.Remove(2) + m.Remove(2) + + if actualValue, expectedValue := fmt.Sprintf("%s", m.Keys()), "[]"; actualValue != expectedValue { + t.Errorf("Got %v expected %v", actualValue, expectedValue) + } + if actualValue, expectedValue := fmt.Sprintf("%s", m.Values()), "[]"; actualValue != expectedValue { + t.Errorf("Got %v expected %v", actualValue, expectedValue) + } + if actualValue := m.Size(); actualValue != 0 { + t.Errorf("Got %v expected %v", actualValue, 0) + } + if actualValue := m.Empty(); actualValue != true { + t.Errorf("Got %v expected %v", actualValue, true) + } +} + +func TestMapGetKey(t *testing.T) { + m := New() + m.Put(5, "e") + m.Put(6, "f") + m.Put(7, "g") + m.Put(3, "c") + m.Put(4, "d") + m.Put(1, "x") + m.Put(2, "b") + m.Put(1, "a") //overwrite + + // key,expectedValue,expectedFound + tests1 := [][]interface{}{ + {1, "a", true}, + {2, "b", true}, + {3, "c", true}, + {4, "d", true}, + {5, "e", true}, + {6, "f", true}, + {7, "g", true}, + {nil, "x", false}, + } + + for _, test := range tests1 { + // retrievals + actualValue, actualFound := m.GetKey(test[1]) + if actualValue != test[0] || actualFound != test[2] { + t.Errorf("Got %v expected %v", actualValue, test[0]) + } + } +} + +func sameElements(a []interface{}, b []interface{}) bool { + if len(a) != len(b) { + return false + } + for _, av := range a { + found := false + for _, bv := range b { + if av == bv { + found = true + break + } + } + if !found { + return false + } + } + return true +} + +func BenchmarkMap(b *testing.B) { + for i := 0; i < b.N; i++ { + m := New() + for n := 0; n < 1000; n++ { + m.Put(n, n) + } + for n := 0; n < 1000; n++ { + m.Remove(n) + } + } +} diff --git a/maps/hashmap/hashmap.go b/maps/hashmap/hashmap.go index 7719233..3f42ffc 100644 --- a/maps/hashmap/hashmap.go +++ b/maps/hashmap/hashmap.go @@ -35,7 +35,7 @@ func (m *Map) Put(key interface{}, value interface{}) { m.m[key] = value } -// Get searches the elemnt in the map by key and returns its value or nil if key is not found in map. +// Get searches the element in the map by key and returns its value or nil if key is not found in map. // Second return parameter is true if key was found, otherwise false. func (m *Map) Get(key interface{}) (value interface{}, found bool) { value, found = m.m[key] diff --git a/maps/maps.go b/maps/maps.go index 6ee3b23..93c64c9 100644 --- a/maps/maps.go +++ b/maps/maps.go @@ -30,3 +30,10 @@ type Map interface { // Clear() // Values() []interface{} } + +// BidiMap interface that all bidirectional maps implement (extends the Map interface) +type BidiMap interface { + GetKey(value interface{}) (key interface{}, found bool) + + Map +}