Maps

The Maps registry offers tools for creating, manipulating, and interacting with map data structures, facilitating efficient data organization and retrieval.

You can easily import all the functions from the maps registry by including the following import statement in your code

import "github.com/go-sprout/sprout/registry/maps"

dict

The function creates a dictionary (map) from a list of alternating keys and values, pairing each key with its corresponding value.

Signature	Dict(values ...any) map[string]any
Must version	❌

Template Example

{{ dict "key1", "value1", "key2", "value2" }}
// Output: {"key1": "value1", "key2": "value2"}

get

The function retrieves the value associated with a specified key from a dictionary (map). If the key is found, the corresponding value is returned.

Signature	Get(dict map[string]any, key string) any
Must version	❌

Template Example

{{ get {"key": "value"}, "key" }} // Output: "value"
{{ get {"key": "value"}, "invalid" }} // Output: ""

set

The function adds a new key-value pair to a dictionary or updates the value associated with an existing key.

Signature	Set(dict map[string]any, key string, value any) map[string]any
Must version	❌

Template Example

{{ set {"key": "oldValue"}, "key", "newValue" }} // Output: {"key": "newValue"}
{{ set {"foo": "bar"}, "far", "boo" }} // Output: {"foo": "bar", "far": "boo"}

unset

{{ {"key": "value"}, "key" | unset }} // Output: {}

Signature	Unset(dict map[string]any, key string) map[string]any
Must version	❌

Template Example

{{ {"key": "value"}, "key" | unset }} // Output: {}
{{ {"key": "value"}, "invalid" | unset }} // Output: {"key": "value"}

keys

The function retrieves all keys from one or more dictionaries, returning them as a list.

Signature	Keys(dicts ...map[string]any) []string
Must version	❌

Template Example

{{ keys {"key1": "value1", "key2": "value2"} }} // Output: ["key1", "key2"]
{{ keys {"key1": "value1"} {"key2": "value2"} }} // Output: ["key1", "key2"]

values

The function retrieves all values from a dictionary, returning them as a list.

Signature	Values(dict map[string]any) []any
Must version	❌

Template Example

{{ values {"key1": "value1", "key2": "value2"} }} // Output: ["value1", "value2"]

pluck

The function extracts values associated with a specified key from a list of dictionaries, returning a list of those values.

Signature	Pluck(key string, dicts ...map[string]any) []any
Must version	❌

Template Example

{{ $d1 := dict "key" "value1"}}
{{ $d2 := dict "key" "value2" }}
{{ pluck "key"	$d1 $d2 }} // Output: ["value1", "value2"]

pick

The function creates a new dictionary that includes only the specified keys from the original dictionary, effectively filtering out all other keys and their associated values.

Signature	Pick(dict map[string]any, keys ...string) map[string]any
Must version	❌

Template Example

{{ $d := dict "key1" "value1" "key2" "value2" "key3" "value3" }}
{{ pick $d "key1" "key3" }} // Output: {"key1": "value1", "key3": "value3"}

omit

The function creates a new dictionary by excluding the specified keys from the original dictionary, effectively removing those key-value pairs from the resulting dictionary.

Signature	Omit(dict map[string]any, keys ...string) map[string]any
Must version	❌

Template Example

{{ $d := dict "key1" "value1" "key2" "value2" "key3" "value3" }}
{{ omit $d "key1" "key3" }} // Output: {"key2": "value2"}

dig

The function navigates through a nested dictionary structure using a sequence of keys and returns the value found at the specified path, allowing access to deeply nested data. The last argument must be the map.

Signature	Dig(args ...any) (any, error)
Must version	❌

Template Example

{{ $nest := dict "foo" "bar" }}
{{ $d := dict "key1" "value1" "nested" $nest }}
{{ $d | dig "nested" "foo" }} // Output: "bar"

hasKey

The function checks whether a specified key exists in the dictionary, returning true if the key is found and false otherwise.

Signature	HasKey(dict map[string]any, key string) bool
Must version	❌

Template Example

{{ $d := dict "key1" "value1" }}
{{ hasKey $d "key1" }} // Output: true
{{ hasKey $d "key2" }} // Output: false

merge / mustMerge

The function combines multiple source maps into a single destination map, adding new key-value pairs without overwriting any existing keys in the destination map.

Signature	Merge(dest map[string]any, srcs ...map[string]any) any MustMerge(dest map[string]any, srcs ...map[string]any) (any, error)
Must version	✅

Template Example

{{ $d1 := dict "a" 1 "b" 2 }}
{{ $d2 := dict "b" 3 "c" 4 }}
{{ merge $d1, $d2 }} // Output: {"a": 1, "b": 2, "c": 4}, nil

Must version

{{ $d1 := dict "a" 1 "b" 2 }}
{{ $d2 := dict "b" 3 "c" 4 }}
{{ mustMerge $d1, $d2 }} // Output: {"a": 1, "b": 2, "c": 4}, nil

mergeOverwrite / mustMergeOverwrite

The function combines multiple source maps into a destination map, overwriting existing keys with values from the source maps.

Signature	MergeOverwrite(dest map[string]any, srcs ...map[string]any) any MustMergeOverwrite(dest map[string]any, srcs ...map[string]any) (any, error)
Must version	✅

Template Example

{{ $d1 := dict "a" 1 "b" 2 }}
{{ $d2 := dict "b" 3 "c" 4 }}
{{ mergeOverwrite $d1, $d2 }} // Output: {"a": 1, "b": 3, "c": 4}, nil

Must version

{{ $d1 := dict "a" 1 "b" 2 }}
{{ $d2 := dict "b" 3 "c" 4 }}
{{ mustMergeOverwrite $d1, $d2 }} // Output: {"a": 1, "b": 3, "c": 4}, nil