genmap

README

GenMap

GenMap provides a generic map, able to store any type, and retrieve values with type safety.

This is done by associating types with key types.

Example

Basic example

package main

import (
	"fmt"
	"github.com/iofic/genmap"
)

const (
	id1 int = iota
	id2
)

type Foo struct {
	a int
}

type Bar struct {
	b int
}

func main() {
	// In this example we'll be storing values of types *Foo and *Bar, against int type keys.
	
	// Create keys for the objects we'll be storing in our map.
	// We need to declare both the value types, and the key type on keys. This allows for type-safety when fetching
	// values, as each key is 'tied' to a type.
	// key1 can only store and load values of type *Foo
	key1 := genmap.NewKey[*Foo, int](id1)
	// key2 can only store and load values of type *Bar
	key2 := genmap.NewKey[*Bar, int](id2)
	
	// Create a genmap.Map, we only need to declare the key type, as Maps can store any type.
	m := genmap.New[int]()
	
	// Create some values to store.
	foo := &Foo{a: 1}
	bar := &Bar{b: 2}
	
	genmap.Store[*Foo, int](m, key1, foo)
	genmap.Store[*Bar, int](m, key2, bar)
	
	// We can then use the keys to load those values.
	// No need to type cast as we specify the types in the generic function Load.
	fmt.Println(genmap.Load[*Foo, int](m, key1).a) // 1
	fmt.Println(genmap.Load[*Bar, int](m, key2).b) // 2
}

Using 'string' functions

GenMap offers 'string' varieties of top level functions. This allows for calling code to use string keys, which is very common, without having to specify the string type during initialisation.

package main

import (
	"fmt"
	"github.com/iofic/genmap"
)

func main() {
	// This example uses the 'string' version of map and keys. This allows the calling code to worry less about key and
	// map types, and only specify value store and load types.

	// Create two keys, both of these store and load int type values, however use unique IDs to differentiate.
	primaryIDKey := genmap.NewStringKey[int]("primary")
	secondaryIDKey := genmap.NewStringKey[int]("secondary")

	stringMap := genmap.NewStringMap()

	// Set the initial values against the keys
	genmap.StoreS[int](stringMap, primaryIDKey, 1)
	genmap.StoreS[int](stringMap, secondaryIDKey, 2)

	// Fetch values via keys.
	fmt.Println(genmap.LoadS[int](stringMap, primaryIDKey))
	// Output: 1 true
	fmt.Println(genmap.LoadS[int](stringMap, secondaryIDKey))
	// Output: 2 true

	// Override the first key.
	genmap.StoreS[int](stringMap, primaryIDKey, 3)

	// Fetch new values, only the first key value should have been changed.
	fmt.Println(genmap.LoadS[int](stringMap, primaryIDKey))
	// Output: 3 true
	fmt.Println(genmap.LoadS[int](stringMap, secondaryIDKey))
	// Output: 2 true

	// Delete the second key.
	genmap.DeleteS[int](stringMap, secondaryIDKey)

	// Fetch a missing key.
	fmt.Println(genmap.LoadS[int](stringMap, primaryIDKey))
	// Output: 3 true
	fmt.Println(genmap.LoadS[int](stringMap, secondaryIDKey))
	// Output: 0 false
}

Documentation

Overview

Example

package main

import (
	"fmt"

	"github.com/iofic/genmap"
)

func main() {
	// This example uses the 'string' version of map and keys. This allows the calling code to worry less about key and
	// map types, and only specify value store and load types.

	// Create two keys, both of these store and load int type values, however use unique IDs to differentiate.
	primaryIDKey := genmap.NewStringKey[int]("primary")
	secondaryIDKey := genmap.NewStringKey[int]("secondary")

	stringMap := genmap.NewStringMap()

	// Set the initial values against the keys
	genmap.StoreS[int](stringMap, primaryIDKey, 1)
	genmap.StoreS[int](stringMap, secondaryIDKey, 2)

	// Fetch values via keys.
	fmt.Println(genmap.LoadS[int](stringMap, primaryIDKey))
	fmt.Println(genmap.LoadS[int](stringMap, secondaryIDKey))

	// Override the first key.
	genmap.StoreS[int](stringMap, primaryIDKey, 3)

	// Fetch new values, only the first key value should have been changed.
	fmt.Println(genmap.LoadS[int](stringMap, primaryIDKey))
	fmt.Println(genmap.LoadS[int](stringMap, secondaryIDKey))

	// Delete the second key.
	genmap.DeleteS[int](stringMap, secondaryIDKey)

	// Fetch a missing key.
	fmt.Println(genmap.LoadS[int](stringMap, primaryIDKey))
	fmt.Println(genmap.LoadS[int](stringMap, secondaryIDKey))

}

Output:

1 true
2 true
3 true
2 true
3 true
0 false

Index

• func Delete[T any, K comparable](m Map[K], key Key[T, K])
• func DeleteS[T any](m Map[string], key Key[T, string])
• func DeleteSync[T any, K comparable](m SyncMap, key Key[T, K])
• func Load[T any, K comparable](m Map[K], key Key[T, K]) (value T, ok bool)
• func LoadAndDelete[T any, K comparable](m SyncMap, key Key[T, K]) (value T, loaded bool)
• func LoadOrStore[T any, K comparable](m SyncMap, key Key[T, K], value T) (actual T, loaded bool)
• func LoadS[T any](m Map[string], key Key[T, string]) (value T, ok bool)
• func LoadSync[T any, K comparable](m SyncMap, key Key[T, K]) (value T, ok bool)
• func Store[T any, K comparable](m Map[K], key Key[T, K], value T)
• func StoreS[T any](m Map[string], key Key[T, string], value T)
• func StoreSync[T any, K comparable](m SyncMap, key Key[T, K], value T)
• type Key
  • func NewKey[T any, K comparable](id K) Key[T, K]
  • func NewStringKey[T any](id string) Key[T, string]
• type Map
  • func New[K comparable]() Map[K]
  • func NewStringMap() Map[string]
• type SyncMap
  • func NewSyncMap() SyncMap

Examples

• Package
• NewStringKey

Functions

func Delete

func Delete[T any, K comparable](m Map[K], key Key[T, K])

Delete will delete an entry from the Map which matches the Key provided. If there is no entry matching the Key, Delete is a no-op function.

func DeleteS

func DeleteS[T any](m Map[string], key Key[T, string])

DeleteS is a shortcut for Delete, for StringMaps.

func DeleteSync

func DeleteSync[T any, K comparable](m SyncMap, key Key[T, K])

DeleteSync deletes the value for a key.

func Load

func Load[T any, K comparable](m Map[K], key Key[T, K]) (value T, ok bool)

Load will fetch a value from the genMap. If found, ok will be true, otherwise false.

func LoadAndDelete

func LoadAndDelete[T any, K comparable](m SyncMap, key Key[T, K]) (value T, loaded bool)

LoadAndDelete deletes the value for a key, returning the previous value if any. The loaded result reports whether the key was present.

func LoadOrStore

func LoadOrStore[T any, K comparable](m SyncMap, key Key[T, K], value T) (actual T, loaded bool)

LoadOrStore returns the existing value for the key if present. Otherwise, it stores and returns the given value. The loaded result is true if the value was loaded, false if stored.

func LoadS

func LoadS[T any](m Map[string], key Key[T, string]) (value T, ok bool)

LoadS is a shortcut for Load, for StringMaps.

func LoadSync

func LoadSync[T any, K comparable](m SyncMap, key Key[T, K]) (value T, ok bool)

LoadSync returns the value stored in the map for a key, or nil if no value is present. The ok result indicates whether value was found in the map.

func Store

func Store[T any, K comparable](m Map[K], key Key[T, K], value T)

Store stores a value against a key on the genMap provided. This will override any value stored against this key.

func StoreS

func StoreS[T any](m Map[string], key Key[T, string], value T)

StoreS is a shortcut for Store, for StringMaps.

func StoreSync

func StoreSync[T any, K comparable](m SyncMap, key Key[T, K], value T)

StoreSync sets the value for a key.

Types

type Key

type Key[T any, K comparable] interface {
	// Key returns a serialisation of the key type. This should be unique for the type, and can be a combination of an
	// instance.
	// e.g. myStruct_objectName
	Key() K
}

Key associates a type with a key, ensuring type safety when setting and fetching values of this type.

func NewKey

func NewKey[T any, K comparable](id K) Key[T, K]

NewKey creates a new Key. The id provided should be unique to the object.

func NewStringKey

func NewStringKey[T any](id string) Key[T, string]

NewStringKey creates a new Key with a string id. This can be used with the string variety of top level functions.

Example

package main

import (
	"fmt"
	"github.com/iofic/genmap"
)

type MyStruct struct{}

func main() {
	kFloat64 := genmap.NewStringKey[float64]("foobar")
	// The key serialisation of a StringKey is a combination of the string id provided, and the type name.
	fmt.Println(kFloat64.Key())

	kMyStruct := genmap.NewStringKey[MyStruct]("yazbaz")
	// The key serialisation of a StringKey with a custom type will contain the package name.
	fmt.Println(kMyStruct.Key())

}

Output:

foobar_float64
yazbaz_genmap_test.MyStruct

type Map

type Map[K comparable] interface {
	// contains filtered or unexported methods
}

Map is a simple type-safe map, providing Store and Load functionality. Map is not thread safe. The Map generic type is the key type.

func New

func New[K comparable]() Map[K]

New creates a new genMap. Maps returned from New is ready to use. The New generic type is the key type.

func NewStringMap

func NewStringMap() Map[string]

NewStringMap returns a map of string type. This is provided as a more concise Map implementation than using New.

type SyncMap

type SyncMap interface {
	// contains filtered or unexported methods
}

func NewSyncMap

func NewSyncMap() SyncMap

NewSyncMap returns a type-safe generic map built upon a sync.Map.