Slices

The Slices registry provides utilities for working with slice data structures, including functions for filtering, sorting, and transforming slices in a flexible manner.

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

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

list

The function creates a list from the provided elements, collecting them into a single array-like structure.

Signature	List(values ...any) []any
Must version	❌

Template Example

{{ 1, 2, 3 | list }} // Output: [1, 2, 3]

append / mustAppend

The function adds an element to the end of an existing list, extending the list by one item.

Signature	Append(list any, v any) []any MustAppend(list any, v any) ([]any, error)
Must version	✅

Template Example

{{ append ["a", "b"], "c" }} // Output: ["a", "b", "c"]

Must version

{{ mustAppend ["a", "b"], "c"  }} // Output: ["a", "b", "c"], nil
{{ mustAppend nil, "c"  }} // Output: nil, error

prepend / mustPrepend

The function adds an element to the beginning of an existing list, placing the new item before all others.

Signature	Prepend(list any, v any) []any MustPrepend(list any, v any) ([]any, error)
Must version	✅

Template Example

{{ prepend  ["b", "c"], "a" }} // Output: ["a", "b", "c"]

Must version

{{ mustPrepend ["b", "c"], "a" }} // Output: ["a", "b", "c"], nil

concat

The function merges multiple lists into a single, unified list, combining all elements from the provided lists.

Signature	Concat(lists ...any) any
Must version	❌

Template Example

{{ ["c", "d"] | concat ["a", "b"] }} // Output: ["a", "b", "c", "d"]

chunk / mustChunk

The function divides a list into smaller, equally sized chunks based on the specified size, breaking the original list into manageable sublists.

Signature	Chunk(size int, list any) [][]any MustChunk(size int, list any) ([][]any, error)
Must version	✅

Template Example

{{ chunk 2, ["a", "b", "c", "d"] }} // Output: [["a", "b"], ["c", "d"]]

Must version

{{ ["a", "b", "c", "d"] | mustChunk 2 }}
// Output: [["a", "b"], ["c", "d"]], nil
{{ mustChunk 2 nil }}
// Output: nil, error

uniq / mustUniq

The function removes duplicate elements from a list, ensuring that each element appears only once in the resulting list.

Signature	Uniq(list any) []any MustUniq(list any) ([]any, error)
Must version	✅

Template Example

{{ ["a", "b", "a", "c"] | uniq }} // Output: ["a", "b", "c"]
{{ nil | uniq }} // Output: []

Must version

{{ ["a", "b", "a", "c"] | mustUniq }} // Output: ["a", "b", "c"], nil
{{ nil | mustUniq }} // Output: nil, error

compact / mustCompact

The function removes nil and zero-value elements from a list, leaving only non-empty and meaningful values.

Signature	Compact(list any) []any MustCompact(list any) ([]any, error)
Must version	✅

Template Example

{{ [0, 1, nil, 2, "", 3] | compact }} // Output: [1, 2, 3]
{{ nil | compact }} // Output: []

Must version

{{ [0, 1, nil, 2, "", 3] | mustCompact }} // Output: [1, 2, 3], nil
{{ nil | mustCompact }} // Output: nil, error

slice / mustSlice

The function extracts a portion of a list, creating a new slice based on the specified start and end indices.

Signature	Slice(list any, indices ...any) any MustSlice(list any, indices ...any) (any, error)
Must version	✅

Template Example

{{ slice [1, 2, 3, 4, 5], 1, 3 }} // Output: [2, 3]
{{ slice 1 }} // Output: []

Must version

{ mustSlice [1, 2, 3, 4, 5], 1, 3 }} // Output: [2, 3], nil
{{ mustSlice 1 }} // Output: nil, error

has / mustHas

The function checks if a specified element is present within a collection, returning true if the element is found.

Signature	Has(element any, list any) bool MustHas(element any, list any) (bool, error)
Must version	✅

Template Example

{{ ["value", "other"] | has "value" }} // Output: true

Must version

{{ [1, 2, 3, 4] | mustHas 3 }} // Output: true, nil
{{ 3 | mustHas 3 }} // Output: false, error

without / mustWithout

The function returns a new list that excludes the specified elements, effectively filtering out unwanted items from the original list.

Signature	Without(list any, omit ...any) []any MustWithout(list any, omit ...any) ([]any, error)
Must version	✅

Template Example

{{ without [1, 2, 3, 4], 2, 4 }} // Output: [1, 3]
{{ without nil, nil }} // Output: []

Must version

{{ mustWithout [1, 2, 3, 4], 2, 4 }} // Output: [1, 3], nil
{{ mustWithout nil, nil }} // Output: nil, error

rest / mustRest

The function returns all elements of a list except for the first one, effectively giving you the "rest" of the list.

Signature	Rest(list any) []any MustRest(list any) ([]any, error)
Must version	✅

Template Example

{{ [1, 2, 3, 4] | rest }} // Output: [2, 3, 4]
{{ rest nil }} // Output: []

Must version

{{ [1, 2, 3, 4] | mustRest }} // Output: [2, 3, 4], nil
{{ mustRest 1 }} // Output: nil, error

initial / mustInitial

The function returns all elements of a list except the last one, effectively providing the "initial" portion of the list.

Signature	Initial(list any) []any MustInitial(list any) ([]any, error)
Must version	✅

Template Example

{{ [1, 2, 3, 4] | initial }} // Output: [1, 2, 3]
{{ initial 1 }} // Output: []

Must version

{{ [1, 2, 3, 4] | mustInitial }} // Output: [1, 2, 3], nil
{{ mustInitial 1 }} // Output: nil, error

first / mustFirst

The function returns the first element of a list.

Signature	First(list any) any MustFirst(list any) (any, error)
Must version	✅

Template Example

{{ [1, 2, 3, 4] | first }} // Output: 1
{{ first 1 }} // Output: nil

Must version

{{ [1, 2, 3, 4] | mustFirst }} // Output: 1, nil
{{ mustFirst 1 }} // Output: nil, error

last / mustLast

The function returns the last element of a list.

Signature	Last(list any) any MustLast(list any) (any, error)
Must version	✅

Template Example

{{ [1, 2, 3, 4] | last }} // Output: 4
{{ last 1 }} // Output: nil

Must version

{{ [1, 2, 3, 4] | mustLast }} // Output: 4, nil
{{ mustLast 1 }} // Output: nil, error

reverse / mustReverse

The function returns a new list with the elements in reverse order, flipping the sequence of the original list.

Signature	Reverse(list any) []any MustReverse(list any) ([]any, error)
Must version	✅

Template Example

{{ [1, 2, 3, 4] | reverse }} // Output: [4, 3, 2, 1]
{{ reverse nil }} // Output: []

Must version

{{ [1, 2, 3, 4] | mustReverse }} // Output: [4, 3, 2, 1], nil
{{ mustReverse nil }} // Output: nil, error

sortAlpha

The function sorts a list of strings in alphabetical order.

Signature	SortAlpha(list any) []string
Must version	❌

Template Example

{{ ["d", "b", "a", "c"] | sortAlpha }} // Output: ["a", "b", "c", "d"]
{{ [4, 3, 2, 1, "a"] | sortAlpha }} // Output: ["1", "2", "3", "4", "a"]

splitList

The function splits a string into a slice of substrings based on the specified separator.

This function may be renamed in the future to better reflect its purpose.

Signature	SplitList(sep string, str string) []string
Must version	❌

Template Example

{{ "one, two, three" | splitList ", " }} // Output: ["one", "two", "three"]

strSlice

The function converts a given value into a slice of strings, handling various input types including []string, []any, and other slice types, ensuring flexible type conversion to a string slice.

Signature	StrSlice(value any) []string
Must version	❌

Template Example

{{ strSlice ["a", "b", "c"] }} // Output: ["a", "b", "c"]
{{ strSlice [5, "a", true, nil, 1] }} // Output: ["5", "a", "true", "1"]

until

The function generates a slice of integers starting from 0 up to, but not including, the specified count. If count is negative, it produces a descending slice from 0 down to count, inclusive, stepping by -1. The function utilizes UntilStep to dynamically determine the range and step size.

Signature	Until(count int) []int
Must version	❌

Template Example

{{ 5 | until }} // Output: [0 1 2 3 4]
{{ -3 | until }} // Output: [0 -1 -2]

untilStep

The function generates a slice of integers from start to stop (exclusive), incrementing by the specified step. If step is positive, the sequence ascends; if negative, it descends. The function returns an empty slice if the sequence is logically invalid, such as when a positive step is used but start is greater than stop, or vice versa.

Signature	UntilStep(start, stop, step int) []int
Must version	❌

Template Example

{{ 0, 10, 2 | untilStep }} // Output: [0 2 4 6 8]
{{ 10, 0, -2 | untilStep }} // Output: [10 8 6 4 2]