maps

README

Functional Map

This package provides some functions for working Go maps, using generics (at least Go 1.18).

Get it

go get -u github.com/flowonyx/functional/maps

Use it

import "github.com/flowonyx/functional/maps"

Terminology

• A predicate is a function that returns a boolean (true or false), generally based on one or two parameters.
• A projection just means a function that takes a certain type and returns another type.

Functions

Creating Maps

• Clone creates a copy of a map.
• FromSlice creates a map from a slice of key, value pairs.
• FromSlices creates a map by combining a slice of keys with a slice of values.
• MapTo creates a new map by mapping each key:value pair in a map with a projection function.
• Partition returns two maps from a given map:
  • The first contains key:value pairs from the map that match a predicate function.
  • The second contains key:value pairs from the map that do not match a predicate function.

Maps -> Slices

• ToSlice converts the map into a slice of key, value functional.Pairs.
• Keys returns a slice of all the keys in a map.
• Values returns a slice of all the values in a map.

Removal

• Clear clears all keys in a map.
• Remove returns a copy of a map with a given key deleted.
• RemoveBy returns a copy of a map with all keys matched by a predicate function removed.
• Filter returns a copy of a map with only key:value pairs that match a predicate function.

Action

• CopyFrom returns a copy of a map with key:values added or replaced from another map.
• Iter performs the given action for each key, value pair in the map.
• Set returns a copy of the map with the key set to the new value.
  • Of course, if you wanted to update the current map, you would just use map[key]=value.
• FoldMap applies a folder function to each key:value pair in a map until it reaches the finished state. The key:value pairs in the map are sorted by key before processing.
• FoldBackMap is the same as FoldMap but in reverse order.

Retrieval

• Get returns the value of the given key. If the key does not exist, it will be the zero value of the value type.
• TryGet returns an option.Option value of the given key. If the key does not exist, the returned value will be None.
• Find either returns the value in a map belonging to a given key or returns a errors.KeyNotFoundErr error if the key is not present.
• FindKey finds the first key in a map that is matched by a predicate function. Remember that no order can be assumed. If no key is matched by the predicate, it returns a errors.KeyNotFoundErr error.
• TryFindKey is just like FindKey but it returns an option.Option with the value of None if the key is not found.

Properties / Tests

• Contains tests if a map contains a given key.
• Exists tests if a map contains a key:value pair that matches a predicate function.
• ForAll tests if all key:value pairs in a map match a predicate function.
• IsEmpty tests if the map contains nothing. This is only useful if you need to pass the function around because it just calls len(m) == 0.
• Len returns the count of items in a map. It just calls the builtin len so there is no advantage to using this one. It is only if you need to pass the function around.

Documentation

Overview

Package simpleMap provides a map[Key]Value that has some convenient methods.

Index

• func Clear[K comparable, T any](m map[K]T)
• func Clone[K comparable, T any](m map[K]T) map[K]T
• func Contains[K comparable, T any](key K, m map[K]T) bool
• func CopyFrom[K comparable, T any](src map[K]T, dest map[K]T) map[K]T
• func Exists[K comparable, T any](predicate func(K, T) bool, m map[K]T) bool
• func Filter[K comparable, T any](predicate func(K, T) bool, m map[K]T) map[K]T
• func Find[K comparable, T any](key K, m map[K]T) (T, error)
• func FindKey[K comparable, T any](predicate func(K, T) bool, m map[K]T) (K, error)
• func FoldBackMap[K constraints.Ordered, T, State any](folder func(K, T, State) State, initial State, table map[K]T) State
• func FoldMap[K constraints.Ordered, T, State any](folder func(State, K, T) State, initial State, table map[K]T) State
• func ForAll[K comparable, T any](predicate func(K, T) bool, m map[K]T) bool
• func FromSlice[K comparable, T any](s []Pair[K, T]) map[K]T
• func FromSlices[K comparable, T any](keys []K, values []T) map[K]T
• func Get[K comparable, T any](key K, m map[K]T) T
• func IsEmpty[K comparable, T any](m map[K]T) bool
• func Iter[K comparable, T any](action func(key K, value T), m map[K]T)
• func Keys[K comparable, T any](m map[K]T) []K
• func Len[K comparable, T any](m map[K]T) int
• func MapTo[K comparable, T, R any](mapping func(K, T) R, table map[K]T) map[K]R
• func Partition[K comparable, T any](predicate func(K, T) bool, m map[K]T) (trueMap map[K]T, falseMap map[K]T)
• func Remove[K comparable, T any](key K, m map[K]T) map[K]T
• func RemoveBy[K comparable, T any](del func(K, T) bool, m map[K]T) map[K]T
• func Set[K comparable, T any](key K, value T, m map[K]T) map[K]T
• func ToSlice[K comparable, T any](m map[K]T) []Pair[K, T]
• func TryFindKey[K comparable, T any](predicate func(K, T) bool, m map[K]T) option.Option[K]
• func TryGet[K comparable, T any](key K, m map[K]T) option.Option[T]
• func Values[K comparable, T any](m map[K]T) []T

Examples

• CopyFrom
• Exists
• Filter
• FoldBackMap
• FoldMap
• ForAll
• FromSlice
• FromSlices
• Iter
• MapTo
• Partition
• RemoveBy
• ToSlice
• TryFindKey

Functions

func Clear

func Clear[K comparable, T any](m map[K]T)

Clear clears all keys in a map.

func Clone

func Clone[K comparable, T any](m map[K]T) map[K]T

Clone creates a copy of the map.

func Contains

func Contains[K comparable, T any](key K, m map[K]T) bool

Contains test if the map contains the given key.

func CopyFrom

func CopyFrom[K comparable, T any](src map[K]T, dest map[K]T) map[K]T

CopyFrom returns a copy of the map with values copied from src.

Example

keyvalues := []Pair[string, int]{PairOf("1", 1), PairOf("2", 2), PairOf("3", 3)}
m := FromSlice(keyvalues)
m2 := map[string]int{"3": 4, "4": 5}

r := CopyFrom(m2, m)
fmt.Println(r["1"], r["2"], r["3"], r["4"])

Output:

1 2 4 5

func Exists

func Exists[K comparable, T any](predicate func(K, T) bool, m map[K]T) bool

Exists tests if the map contains a key, value pair that matches the predicate.

Example

keyvalues := []Pair[string, int]{PairOf("1", 1), PairOf("2", 2), PairOf("3", 3), PairOf("4", 5)}
m := FromSlice(keyvalues)
r := Exists(func(key string, val int) bool { return key != strings.FromInt(val) }, m)
fmt.Println(r)

Output:

true

func Filter

func Filter[K comparable, T any](predicate func(K, T) bool, m map[K]T) map[K]T

Filter returns a copy of the map with only key, value pairs matching the given predicate.

Example

keyvalues := []Pair[string, int]{PairOf("1", 1), PairOf("2", 2), PairOf("3", 3), PairOf("4", 5)}
m := FromSlice(keyvalues)
r := Filter(func(key string, value int) bool { return key != strings.FromInt(value) }, m)
fmt.Println(len(r), TryGet("3", r), TryGet("4", r))

Output:

1 None Some(5)

func Find

func Find[K comparable, T any](key K, m map[K]T) (T, error)

Find either returns the value belonging to the key or returns a KeyNotFoundErr error if the key is not present.

func FindKey

func FindKey[K comparable, T any](predicate func(K, T) bool, m map[K]T) (K, error)

FindKey finds the first key in the map that is matched by the predicate. Remember that no order can be assumed. If no key is matched by the predicate, it returns a KeyNotFoundErr error.

func FoldBackMap

func FoldBackMap[K constraints.Ordered, T, State any](folder func(K, T, State) State, initial State, table map[K]T) State

FoldBackMap applies the folder function to each key, value pair in table in reverse order until it reaches the finished state. The key, value pairs are sorted by key.

Example

keyvalues := []Pair[string, int]{PairOf("1", 1), PairOf("2", 2), PairOf("3", 3), PairOf("4", 5)}
m := FromSlice(keyvalues)
r := FoldBackMap(func(key string, val int, state int) int {
	i := strings.ToIntOpt(key)
	// ((((0 * 4 + 5) * 3 + 3) * 2 + 2) * 1 + 1) = 39
	return state*i.Value() + val
}, 0, m)
fmt.Println(r)

Output:

39

func FoldMap

func FoldMap[K constraints.Ordered, T, State any](folder func(State, K, T) State, initial State, table map[K]T) State

FoldMap applies the folder function to each key, value pair in table until it reaches the finished state. The key, value pairs are sorted by key.

Example

keyvalues := []Pair[string, int]{PairOf("1", 1), PairOf("2", 2), PairOf("3", 3), PairOf("4", 5)}
m := FromSlice(keyvalues)
r := FoldMap(func(state int, key string, val int) int {
	i := strings.ToIntOpt(key)
	// ((((0 * 1 + 1) * 2 + 2) * 3 + 3) * 4 + 5) = 65
	return state*i.Value() + val
}, 0, m)
fmt.Println(r)

Output:

65

func ForAll

func ForAll[K comparable, T any](predicate func(K, T) bool, m map[K]T) bool

ForAll tests if all key, value pairs in the map match the predicate.

Example

keyvalues := []Pair[string, int]{PairOf("1", 1), PairOf("2", 2), PairOf("3", 3), PairOf("4", 5)}
m := FromSlice(keyvalues)
r := ForAll(func(key string, val int) bool { return key != strings.FromInt(val) }, m)
fmt.Println(r)

Output:

false

func FromSlice

func FromSlice[K comparable, T any](s []Pair[K, T]) map[K]T

FromSlice creates a map from a slice of key, value pairs.

Example

keyvalues := []Pair[string, int]{PairOf("1", 1), PairOf("2", 2), PairOf("3", 3)}
m := FromSlice(keyvalues)
fmt.Println(m["2"])

Output:

2

func FromSlices

func FromSlices[K comparable, T any](keys []K, values []T) map[K]T

FromSlices creates a map by combining a slice of keys with a slice of values.

Example

m := FromSlices([]string{"1", "2", "3"}, []int{1, 2, 3})
fmt.Println(m["2"])

Output:

2

func Get

func Get[K comparable, T any](key K, m map[K]T) T

Get returns the value of the given key. If the key does not exist, it will be the zero value of the value type.

func IsEmpty

func IsEmpty[K comparable, T any](m map[K]T) bool

IsEmpty tests if the map contains nothing.

func Iter

func Iter[K comparable, T any](action func(key K, value T), m map[K]T)

Iter performs the given action for each key, value pair in the map.

Example

keyvalues := []Pair[string, int]{PairOf("1", 1), PairOf("2", 2), PairOf("3", 3)}
m := FromSlice(keyvalues)
Iter(func(key string, value int) {
	if value == 2 {
		fmt.Println(key)
	}
}, m)

Output:

2

func Keys

func Keys[K comparable, T any](m map[K]T) []K

Keys returns a slice of all the keys in the map.

func Len

func Len[K comparable, T any](m map[K]T) int

Len returns the count of items in the map.

func MapTo

func MapTo[K comparable, T, R any](mapping func(K, T) R, table map[K]T) map[K]R

MapTo creates a new map from mapping each key, value pair in table with the mapping function.

Example

keyvalues := []Pair[string, int]{PairOf("1", 1), PairOf("2", 2), PairOf("3", 3), PairOf("4", 5)}
m := FromSlice(keyvalues)
r := MapTo(func(key string, val int) string {
	return key
}, m)
fmt.Println(r["4"])

Output:

4

func Partition

func Partition[K comparable, T any](predicate func(K, T) bool, m map[K]T) (trueMap map[K]T, falseMap map[K]T)

Partition returns two maps: The first contains key, value pairs from this map that match the predicate. The second contains key, value pairs from this map that do not match the predicate.

Example

keyvalues := []Pair[string, int]{PairOf("1", 1), PairOf("2", 2), PairOf("3", 3), PairOf("4", 5)}
m := FromSlice(keyvalues)
rt, rf := Partition(func(key string, val int) bool { return key == strings.FromInt(val) }, m)
fmt.Println(Contains("3", rt), Contains("4", rt), Contains("4", rf))

Output:

true false true

func Remove

func Remove[K comparable, T any](key K, m map[K]T) map[K]T

Remove returns a copy of the map with the given key deleted.

func RemoveBy

func RemoveBy[K comparable, T any](del func(K, T) bool, m map[K]T) map[K]T

RemoveBy returns a copy of the map with all keys matched by the del predicate removed.

Example

keyvalues := []Pair[string, int]{PairOf("1", 1), PairOf("2", 2), PairOf("3", 3), PairOf("4", 5)}
m := FromSlice(keyvalues)
r := RemoveBy(func(key string, value int) bool { return key != strings.FromInt(value) }, m)
fmt.Println(len(r), TryGet("3", r), TryGet("4", r))

Output:

3 Some(3) None

func Set

func Set[K comparable, T any](key K, value T, m map[K]T) map[K]T

Set returns a copy of the map with the key set to the new value.

func ToSlice

func ToSlice[K comparable, T any](m map[K]T) []Pair[K, T]

ToSlice converts the map into a slice of key, value functional.Pairs.

Example

keyvalues := []Pair[string, int]{PairOf("1", 1), PairOf("2", 2), PairOf("3", 3)}
m := FromSlice(keyvalues)
r := ToSlice(m)
fmt.Println(list.Equal(keyvalues, r))

Output:

true

func TryFindKey

func TryFindKey[K comparable, T any](predicate func(K, T) bool, m map[K]T) option.Option[K]

TryFindKey is just like FindKey but it returns an option with the value of None if the key is not found.

Example

keyvalues := []Pair[string, int]{PairOf("1", 1), PairOf("2", 2), PairOf("3", 3), PairOf("4", 5)}
m := FromSlice(keyvalues)
r := TryFindKey(func(key string, val int) bool { return key != strings.FromInt(val) }, m)
fmt.Println(r)

Output:

Some("4")

func TryGet

func TryGet[K comparable, T any](key K, m map[K]T) option.Option[T]

TryGet returns an optional value of the given key. If the key does not exist, the returned value will be None.

func Values

func Values[K comparable, T any](m map[K]T) []T

Values returns a slice of all the values in the map.