github.com/relengxing/go-multimap

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/relengxing/go-multimap

Usage

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

// example/example.go
package main

import (
	"fmt"

	"github.com/relengxing/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.