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

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(key string, dict map[string]any) (any, error)

Template Example

{{ {"key": "value"} | get "key" }} // Output: "value"
{{ {"key": "value"} | get "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(key string, value any, dict map[string]any) (map[string]any, error)

Template Example

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

unset

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

Signature

Unset(key string, dict map[string]any) map[string]any

Template Example

{{ {"key": "value"} | unset "key" }} // Output: {}
{{ {"key": "value"} | unset "invalid" }} // 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

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 one or more dictionaries, returning them as a list.

Signature

Values(dicts ...map[string]any) []any

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

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(keys ...string, dict map[string]any) (map[string]any, error)

Template Example

{{ $d := dict "key1" "value1" "key2" "value2" "key3" "value3" }}
{{ $d | pick "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(keys ...string, dict map[string]any) (map[string]any, error)

Template Example

{{ $d := dict "key1" "value1" "key2" "value2" "key3" "value3" }}
{{ $d | omit "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)

Template Example

{{ $nest := dict "foo" "bar" }}
{{ $d := dict "key1" "value1" "nested" $nest }}
{{ $d | dig "nested" "foo" }} // Output: "bar"
{{ $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(key string, dict map[string]any) (bool, error)

Template Example

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

merge

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, error)

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

mergeOverwrite

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, error)

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