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: map[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

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

{{ dict "key" "oldValue" | set "key" "newValue" }} // Output: map[key:newValue]
{{ dict "foo" "bar" | set "far" "boo" }} // Output: map[far:boo foo:bar]

unset

The function removes a specified key-value pair from a dictionary, returning the modified dictionary without the specified key. If the key is not found, the original dictionary is returned unchanged.

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

Template Example

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

{{- $d := dict "key1" "value1" "key2" "value2" -}}
{{ keys $d | sortAlpha }} // Output: [key1 key2]

{{- $d1 := dict "key1" "value1" -}}
{{- $d2 := dict "key2" "value2" -}}
{{ keys $d1 $d2 | sortAlpha }} // 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

{{- $d := dict "key1" "value1" "key2" "value2" -}}
{{ values $d | sortAlpha }} // 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: map[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: map[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

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

{{- $d := dict "key1" "value1" "nested" (dict "foo" "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 := dict "key1" "value1" -}}
{{ $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: map[a:1 b:2 c:4]

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: map[a:1 b:3 c:4]