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

Template Example

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

append

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

Signature	Append(v any, list any) ([]any, error)

Template Example

{{ list "a" "b" | append "c"  }} // Output: [a b c]
{{ nil | append "c"  }} // Error

The list you pass in is never modified, a new one is returned. To accumulate in a range, assign the result back:

{{- $stages := list -}}
{{- range .Stages -}}
  {{- $stages = $stages | append .Name -}}
{{- end -}}

Without the =, the list stays empty and each intermediate result is printed into the output.

prepend

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

Signature	Prepend(v any, list any) ([]any, error)

Template Example

{{ list "b" "c" | prepend "a" }} // Output: [a b c]
{{ nil | prepend "c" }} // Error

Like append, the list you pass in is never modified: assign the result back to accumulate it.

concat

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

Signature	Concat(lists ...any) any

Template Example

{{ list "c" "d" | concat (list "a" "b") }} // Output: [a b c d]

chunk

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

Signature	Chunk(size int, list any) ([][]any, error)

Template Example

{{ list "a" "b" "c" "d" | chunk 2 }} // Output: [[a b] [c d]]
{{ chunk 2 nil }} // Error

uniq

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

Signature	Uniq(list any) ([]any, error)

Template Example

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

compact

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

Signature	Compact(list any) ([]any, error)

Template Example

{{ list 1 2 3 "" .Nil | compact }} // Output: [1 2 3]
{{ nil | compact }} // Error

flatten

The function flattens a list into a single-dimensional array, removing nested lists and combining all elements into a single list.

Signature	Flatten(list any) ([]any, error)

Template Example

{{ flatten (list (list 1 2) (list 3 4) 5) }} // Output: [1 2 3 4 5]
{{ flatten (list (list 1 (list 2)) (list 3 4) 5) }} // Output: [1 2 3 4 5]
{{ nil | flatten }} // Error

flattenDepth

The function flattens a list into a single-dimensional array up to a specified depth, removing nested lists and combining all elements into a single list up to the specified depth.

Signature	FlattenDepth(deep int, list any) ([]any, error)

Template Example

{{ (list (list 1 (list 2)) (list 3 4) 5) | flattenDepth -1 }} // Output: [1 2 3 4 5]
{{ (list (list 1 (list 2)) (list 3 (list 4)) 5) | flattenDepth 1 }} // Output: [1 [2] 3 [4] 5]
{{ nil | flattenDepth }} // Error

slice

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

Signature	Slice(indices ...any, list any) (any, error)

Template Example

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

has

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

Template Example

{{ list 1 2 3 4 | has 3 }} // Output: true
{{ 3 | has 3 }} // Error

without

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

Signature	Without(omit ...any, list any) ([]any, error)

Template Example

{{ list 1 2 3 4 | without 2 4 }} // Output: [1 3]
{{ without nil }} // Error

rest

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

Template Example

{{ list 1 2 3 4 | rest }} // Output: [2 3 4]
{{ rest 1 }} // Error

initial

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

Template Example

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

first

The function returns the first element of a list.

Signature	First(list any) (any, error)

Template Example

{{ list 1 2 3 4 | first }} // Output: 1
{{ first nil }} // Error

last

The function returns the last element of a list.

Signature	Last(list any) (any, error)

Template Example

{{ list 1 2 3 4 | last }} // Output: 4
{{ last nil }} // Error

reverse

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

Signature	Reverse(list any) ([]any, error)

Template Example

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

sortAlpha

The function sorts a list of strings in alphabetical order.

Signature	SortAlpha(list any) []string

Template Example

{{ list "d" "b" "a" "c" | sortAlpha }} // Output: [a b c d]
{{ list 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

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

Template Example

{{ strSlice (list "a" "b" "c") }} // Output: [a b c]
{{ strSlice (list 5 "a" true 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

Template Example

{{ until 5 }} // 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

Template Example

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