jwangsadinata / go-multimap

Go-Multimap is an implementation of the `multimap` data structure in Go.

Go-Multimap

This is the missing multimap collection for the Go language (also a simple practice in creating a proper library/package).

A multimap (sometimes also multihash or multidict) is a generalization of a map or associative array abstract data type in which more than one value may be associated with and returned for a given key.

Some use cases and examples for this data type includes:

• The index of a book may report any number of references for a given index term, and thus may be coded as a multimap from index terms to any number of reference locations or pages.
• Address location, such as ZIP code, that maps to any number of people living in that area.

There are two different multimap implementations, slicemultimap and setmultimap, which has slices and sets as the map values respectively. slicemultimap is useful when duplicate key/value pairs is allowed and insertion ordering is important. On the other hand, setmultimap is suitable when duplicates of key/value pairs are not allowed.

This package was heavily inspired by the Google Guava interface of MultiMap and written in the style of the container package.

References: Wikipedia, Guava

Installation

Install the package via the following:

go get -u github.com/jwangsadinata/go-multimap

Usage

The go-multimap package can be used similarly to the following:

// example/example.go
package main

import (
	"fmt"

	"github.com/jwangsadinata/go-multimap/slicemultimap"
)

func main() {
	usPresidents := []struct {
		firstName  string
		middleName string
		lastName   string
		termStart  int
		termEnd    int
	}{
		{"George", "", "Washington", 1789, 1797},
		{"John", "", "Adams", 1797, 1801},
		{"Thomas", "", "Jefferson", 1801, 1809},
		{"James", "", "Madison", 1809, 1817},
		{"James", "", "Monroe", 1817, 1825},
		{"John", "Quincy", "Adams", 1825, 1829},
		{"John", "", "Tyler", 1841, 1845},
		{"James", "", "Polk", 1845, 1849},
		{"Grover", "", "Cleveland", 1885, 1889},
		{"Benjamin", "", "Harrison", 1889, 1893},
		{"Grover", "", "Cleveland", 1893, 1897},
		{"George", "Herbert Walker", "Bush", 1989, 1993},
		{"George", "Walker", "Bush", 2001, 2009},
		{"Barack", "Hussein", "Obama", 2009, 2017},
	}

	m := slicemultimap.New()

	for _, president := range usPresidents {
		m.Put(president.firstName, president.lastName)
	}

	for _, firstName := range m.KeySet() {
		lastNames, _ := m.Get(firstName)
		fmt.Printf("%v: %v\n", firstName, lastNames)
	}
}

Example output:

$ go run example.go
George: [Washington Bush Bush]
John: [Adams Adams Tyler]
Thomas: [Jefferson]
James: [Madison Monroe Polk]
Grover: [Cleveland Cleveland]
Benjamin: [Harrison]
Barack: [Obama]

Benchmarks

To see the benchmark, run the following on each of the sub-packages:

go test -run=NO_TEST -bench . -benchmem -benchtime 1s ./...

Please see the GoDoc API page for a full API listing. For more examples, please consult example_test.go file located in each subpackages.

go-multimap's Issues

Add benchmark measurements to README.

Using go test -run=NO_TEST -bench . -benchmem -benchtime 1s ./..., you can get the following measurement.

Separate implementation of List and Set based multimap?

A separate implementation of multimap, one that accepts duplicates of key/value pair and one that does not might be really helpful to be implemented.

A small bug with multimap.Entries()

When playing around with the package, entries return type is currently interface{}. Although it works, it is much harder to get the values out into key/value pair from entries, as the current implementation hides the fields of the struct.

A suggestion is to make the return type of Entries to be:

struct {Key interface{}; value interface{}}

This way, the key and value can be accessed relatively easy, and there is a clear type assertions. Thank you.