maps

README

Maps

Maps is a library of functions for manipulating and working with maps in Go. Generics being added in Go 1.18 added new possibilities for writing type safe libraries to bring common idioms from other languages into Golang. However, at its core, this library is useful functions I've found myself writing or wanting when working in Go.

Installation / Adding Dependency

go get github.com/jkratz/55/maps-go

Documentation

Index

• func Clear[M ~map[K]V, K comparable, V any](m M)
• func Clone[M ~map[K]V, K comparable, V any](m M) M
• func Copy[M ~map[K]V, K comparable, V any](src, dst M)
• func Diff[M ~map[K]V, K, V comparable](left M, right M) map[K]EntryComparison[V]
• func Equal[M ~map[K]V, K, V comparable](m1, m2 M) bool
• func Filter[M ~map[K]V, K comparable, V any](m M, fn Predicate[K, V]) M
• func GetOrDefault[M ~map[K]V, K comparable, V any](m M, key K, defaultVal V) V
• func GetOrPanic[M ~map[K]V, K comparable, V any](m M, key K) V
• func Invert[M ~map[K]V, K, V comparable](m M) map[V]K
• func KeyDiff[M ~map[K]V, K comparable, V any](left M, right M) ([]K, []K)
• func Keys[M ~map[K]V, K comparable, V any](m M) []K
• func MapEntries[M1 ~map[K1]V1, M2 ~map[K2]V2, K1, K2 comparable, V1, V2 any](in M1, mapper EntryMapper[K1, K2, V1, V2]) M2
• func MapToSlice[M ~map[K]V, K comparable, V any, R any](m M, mapper func(key K, val V) R) []R
• func Merge[M ~map[K]V, K comparable, V any](fn ConflictResolver[V], src ...M) map[K]V
• func SetIfAbsent[M ~map[K]V, K comparable, V any](m M, key K, val V) bool
• func SetIfPresent[M ~map[K]V, K comparable, V any](m M, key K, val V) bool
• func TakeIf[M ~map[K]V, K comparable, V any](m M, pred Predicate[K, V], fn func(key K, val V))
• func Values[M ~map[K]V, K comparable, V any](m M) []V
• type ConflictResolver
  • func NopResolver[V any]() ConflictResolver[V]
  • func OverwriteResolver[V any]() ConflictResolver[V]
• type DiffReason
• type Entry
  • func Entries[M ~map[K]V, K comparable, V any](m M) []Entry[K, V]
• type EntryComparison
• type EntryMapper
• type Predicate

Functions

func Clear

func Clear[M ~map[K]V, K comparable, V any](m M)

Clear removes all entries from the map.

func Clone

func Clone[M ~map[K]V, K comparable, V any](m M) M

Clone clones a map adding all the entries of the map into a new map.

Note: If V is a pointer type or contains types backed by a pointer or maps, slices, channels, functions, etc. this will not be a deep copy.

func Copy

func Copy[M ~map[K]V, K comparable, V any](src, dst M)

Copy copies all the entries from the source map into the destination map. If the key already exist in the dest map its value will be overwritten.

func Diff

func Diff[M ~map[K]V, K, V comparable](left M, right M) map[K]EntryComparison[V]

Diff compares two maps and returns a map containing the keys that differ along with the differences.

func Equal

func Equal[M ~map[K]V, K, V comparable](m1, m2 M) bool

Equal compares two maps and returns a boolean value indicating if they are equal.

func Filter

func Filter[M ~map[K]V, K comparable, V any](m M, fn Predicate[K, V]) M

Filter iterates through the entries of the map and tests if they satisfy the predicate. Entries that satisfy the predicate added to a newly returned map, effectively filtering the map entries.

func GetOrDefault

func GetOrDefault[M ~map[K]V, K comparable, V any](m M, key K, defaultVal V) V

GetOrDefault returns the value for a given key in the provided map, or returns the default value if the key doesn't exist.

func GetOrPanic

func GetOrPanic[M ~map[K]V, K comparable, V any](m M, key K) V

GetOrPanic returns the value for a given key in the provided map or panics if the key doesn't exist in the map.

func Invert

func Invert[M ~map[K]V, K, V comparable](m M) map[V]K

Invert creates a map composed of inverted keys and values. If the values are duplicated it will result in overwrites in the inverted map.

func KeyDiff

func KeyDiff[M ~map[K]V, K comparable, V any](left M, right M) ([]K, []K)

KeyDiff inspects the left and right map returning two slices of keys: the keys in the left map that don't exist in the right map, and the keys that exist in the right map but don't exist in the left map.

func Keys

func Keys[M ~map[K]V, K comparable, V any](m M) []K

Keys returns all the keys in the provided map.

The keys will be in an indeterminate order.

func MapEntries

func MapEntries[M1 ~map[K1]V1, M2 ~map[K2]V2, K1, K2 comparable, V1, V2 any](in M1, mapper EntryMapper[K1, K2, V1, V2]) M2

MapEntries manipulates a maps entries and transforms it to another map.

func MapToSlice

func MapToSlice[M ~map[K]V, K comparable, V any, R any](m M, mapper func(key K, val V) R) []R

MapToSlice transforms a map into a slice by invoking the mapper on each entry.

func Merge

func Merge[M ~map[K]V, K comparable, V any](fn ConflictResolver[V], src ...M) map[K]V

Merge merges multiple maps into a single new map. If a key exists in multiple maps the ConflictResolver function is called to resolve the conflict. The value returns by the ConflictResolver is the value set in the new merged map.

func SetIfAbsent

func SetIfAbsent[M ~map[K]V, K comparable, V any](m M, key K, val V) bool

SetIfAbsent sets the value for the key in the map only if the key does not already exist in the map. If the value is set SetIfAbsent returns true, otherwise returns false.

func SetIfPresent

func SetIfPresent[M ~map[K]V, K comparable, V any](m M, key K, val V) bool

SetIfPresent sets the value for the key in the map only if the key already exist in the map. If the value is set SetIfPresent returns true, otherwise returns false.

func TakeIf

func TakeIf[M ~map[K]V, K comparable, V any](m M, pred Predicate[K, V], fn func(key K, val V))

TakeIf iterates over a map and for all entries that satisfy the predicate the entry is passed to the function/closure provided. TakeIf is similar to Filter but avoids the overhead of creating another map and instead directly passes the entries to a callback to be processed.

func Values

func Values[M ~map[K]V, K comparable, V any](m M) []V

Values return all the values in the provided map.

The values will be in an indeterminate order.

Types

type ConflictResolver

type ConflictResolver[V any] func(left, right V) V

ConflictResolver is a function type that is invoked when Merge is merging maps that contains the same key, hence a conflict. The role of ConflictResolver is to handle the conflict and return the resolved value.

func NopResolver

func NopResolver[V any]() ConflictResolver[V]

NopResolver returns a ConflictResolver that always keeps the existing value.

func OverwriteResolver

func OverwriteResolver[V any]() ConflictResolver[V]

OverwriteResolver returns a ConflictResolver that always overrides the existing value.

type DiffReason

type DiffReason int

const (
	// DiffValue is a flag indicating the values for a given key differ between maps
	DiffValue DiffReason = 0
	// DiffMissingLeft is a flag indicating a key exists in the right map but doesn't
	// exist in the left map
	DiffMissingLeft DiffReason = 1
	// DiffMissingRight is a flag indicating a key exist in the left map but doesn't
	// exist in the right map
	DiffMissingRight DiffReason = 2
)

type Entry

type Entry[K comparable, V any] struct {
	Key   K
	Value V
}

Entry is a data structure representing a single entry in a map.

func Entries

func Entries[M ~map[K]V, K comparable, V any](m M) []Entry[K, V]

Entries returns all entries in the given map as a slice of Entry.

The results will be in an indeterminate order.

type EntryComparison

type EntryComparison[V comparable] struct {
	Left   V
	Right  V
	Diff   string
	Reason DiffReason
}

type EntryMapper

type EntryMapper[K1, K2 comparable, V1, V2 any] func(key K1, val V1) (K2, V2)

EntryMapper is a function type that maps an entry from a map to a new map, possibly of different types.

type Predicate

type Predicate[K comparable, V any] func(key K, val V) bool

Predicate represents a predicate (boolean-value function).