array

func Append ¶

func Append[GA ~[]A, A any](as GA, a A) GA

Append appends a single element to as and returns the result. The result is never nil.

func Concat ¶

func Concat[GT ~[]T, T any](left, right GT) GT

Concat concatenates left and right into a new array. When either side is empty it is returned directly, so the result may be nil if that side was nil.

func ConstNil ¶

func ConstNil[GA ~[]A, A any]() GA

ConstNil always returns nil, the canonical representation of an empty array.

func Empty ¶

func Empty[GA ~[]A, A any]() GA

Empty returns nil, the canonical representation of an empty array.

func EmptyToNil ¶ added in v2.3.135

func EmptyToNil[GA ~[]A, A any](as GA) GA

EmptyToNil returns nil if as is empty and as otherwise, normalising every empty array to nil, the canonical representation of an empty array.

func IsEmpty ¶

func IsEmpty[GA ~[]A, A any](as GA) bool

func IsNil ¶

func IsNil[GA ~[]A, A any](as GA) bool

func IsNonNil ¶

func IsNonNil[GA ~[]A, A any](as GA) bool

func MakeBy ¶ added in v2.3.86

func MakeBy[AS ~[]A, F ~func(int) A, A any](n int, f F) AS

MakeBy returns an array of length n with element i initialised by f(i). Returns nil (representing an empty array) when n <= 0.

func MakeTraversable ¶ added in v2.3.12

func MakeTraversable[GA ~[]A, GB ~[]B, A, B, HKTB, HKTAB, HKTRB any](
	fof func(GB) HKTRB,
	fmap func(func(GB) func(B) GB) func(HKTRB) HKTAB,
	fap func(HKTB) func(HKTAB) HKTRB,
) func(func(A) HKTB) func(GA) HKTRB

MakeTraversable creates a fully curried traversal function that can be specialized for different effects. This is the most abstract form of traverse, returning a function that takes the transformation function and then the array, enabling maximum composability and reusability.

This function is useful when you want to create a reusable traversal operation that can be applied to different transformation functions and arrays. It's particularly valuable in point-free style programming and when building traversal pipelines.

Type Parameters:

• GA: The input array type (e.g., []A)
• GB: The output array type (e.g., []B)
• A: The input element type
• B: The output element type
• HKTB: The effect containing B (e.g., Option[B], Either[E, B])
• HKTAB: Intermediate applicative type for function application
• HKTRB: The effect containing the result array (e.g., Option[[]B])

Parameters:

• fof: Function to lift a value into the effect (Of/Pure from the applicative)
• fmap: Function to map over the effect (Map from the functor)
• fap: Function to apply an effect of a function to an effect of a value (Ap from the applicative)

Returns:

• A function that takes a transformation function and returns a function that takes an array and returns an effect containing the transformed array

Example:

import (
    O "github.com/IBM/fp-go/v2/option"
    A "github.com/IBM/fp-go/v2/array/generic"
    F "github.com/IBM/fp-go/v2/function"
)

// Create a reusable Option traversal for string arrays
traverseOption := A.MakeTraversable[[]string, []int](
    O.Of[[]int],
    O.Map[[]int, func(int) []int],
    O.Ap[int, []int],
)

// Use it with different transformation functions
parseInts := traverseOption(result.Eitherize1(strconv.Atoi))
result1 := parseInts([]string{"1", "2", "3"})  // Some([1, 2, 3])
result2 := parseInts([]string{"1", "x", "3"})  // None

See Also:

• Traverse: Non-curried version that takes the transformation function directly
• MonadTraverse: Version that takes the array as a direct parameter

func Map ¶

func Map[GA ~[]A, GB ~[]B, A, B any](f func(a A) B) func(GA) GB

Map returns a curried form of MonadMap. The returned function returns nil (representing an empty array) when its input is empty.

func MonadMap ¶

func MonadMap[GA ~[]A, GB ~[]B, A, B any](as GA, f func(a A) B) GB

MonadMap applies f to every element of as and returns the results. Returns nil (representing an empty array) when as is empty.

func MonadMapWithIndex ¶

func MonadMapWithIndex[GA ~[]A, GB ~[]B, A, B any](as GA, f func(idx int, a A) B) GB

MonadMapWithIndex applies f (with element index) to every element of as and returns the results. Returns nil (representing an empty array) when as is empty.

func MonadSequence ¶

func MonadSequence[GA ~[]HKTA, HKTA, HKTRA any](
	fof func(HKTA) HKTRA,
	empty func() HKTRA,
	concat func(HKTRA, HKTRA) HKTRA,

	ta GA) HKTRA

* We need to pass the members of the applicative explicitly, because golang does neither support higher kinded types nor template methods on structs or interfaces

HKTRB = HKT<GB> HKTB = HKT<B> HKTAB = HKT<func(A)B>

func MonadSequenceSegment ¶

func MonadSequenceSegment[HKTB, HKTRB any](
	fof func(HKTB) HKTRB,
	empty func() HKTRB,
	concat func(HKTRB, HKTRB) HKTRB,
	fbs []HKTB,
	start, end int,
) HKTRB

MonadSequenceSegment sequences a segment of an array of effects using a divide-and-conquer approach. It recursively splits the array segment in half, sequences each half, and concatenates the results.

This function is optimized for performance by using a divide-and-conquer strategy that reduces the depth of nested function calls compared to a linear fold approach.

Type parameters:

• HKTB: The higher-kinded type containing values (e.g., Option[B], Either[E, B])
• HKTRB: The higher-kinded type containing an array of values (e.g., Option[[]B], Either[E, []B])

Parameters:

• fof: Function to lift a single HKTB into HKTRB
• empty: The empty/identity value for HKTRB
• concat: Function to concatenate two HKTRB values
• fbs: The array of effects to sequence
• start: The starting index of the segment (inclusive)
• end: The ending index of the segment (exclusive)

Returns:

• HKTRB: The sequenced result for the segment

The function handles three cases:

• Empty segment (end - start == 0): returns empty
• Single element (end - start == 1): returns fof(fbs[start])
• Multiple elements: recursively divides and conquers

func MonadTraverse ¶

func MonadTraverse[GA ~[]A, GB ~[]B, A, B, HKTB, HKTAB, HKTRB any](
	fof func(GB) HKTRB,
	fmap func(func(GB) func(B) GB) func(HKTRB) HKTAB,
	fap func(HKTB) func(HKTAB) HKTRB,

	ta GA,
	f func(A) HKTB) HKTRB

MonadTraverse maps each element of an array to an effect, then sequences the results. This is the monadic version that takes the array as a direct parameter.

Traverse combines mapping and sequencing in one operation. It's useful when you want to transform each element of an array into an effect (like Option, Either, IO, etc.) and then collect all those effects into a single effect containing an array.

We need to pass the members of the applicative explicitly, because golang does neither support higher kinded types nor template methods on structs or interfaces.

Type parameters:

• GA: The input array type (e.g., []A)
• GB: The output array type (e.g., []B)
• A: The input element type
• B: The output element type
• HKTB: HKT<B> - The effect containing B (e.g., Option[B])
• HKTAB: HKT<func(B)GB> - Intermediate applicative type
• HKTRB: HKT<GB> - The effect containing the result array (e.g., Option[[]B])

Parameters:

• fof: Function to lift a value into the effect (Of/Pure)
• fmap: Function to map over the effect (Map)
• fap: Function to apply an effect of a function to an effect of a value (Ap)
• ta: The input array to traverse
• f: The function to apply to each element, producing an effect

Returns:

• HKTRB: An effect containing the array of transformed values

Note: traversing an empty array returns the effect of nil (not an empty non-nil slice), since nil is the canonical representation of the empty array.

Example:

If any element produces None, the entire result is None.
If all elements produce Some, the result is Some containing all values.
For an empty input, the result is Some(nil).

func MonadTraverseReduce ¶

func MonadTraverseReduce[GA ~[]A, GB, A, B, HKTB, HKTAB, HKTRB any](
	fof func(GB) HKTRB,
	fmap func(func(GB) func(B) GB) func(HKTRB) HKTAB,
	fap func(HKTB) func(HKTAB) HKTRB,

	ta GA,

	transform func(A) HKTB,
	reduce func(GB, B) GB,
	initial GB,
) HKTRB

func MonadTraverseReduceWithIndex ¶

func MonadTraverseReduceWithIndex[GA ~[]A, GB, A, B, HKTB, HKTAB, HKTRB any](
	fof func(GB) HKTRB,
	fmap func(func(GB) func(B) GB) func(HKTRB) HKTAB,
	fap func(HKTB) func(HKTAB) HKTRB,

	ta GA,

	transform func(int, A) HKTB,
	reduce func(GB, B) GB,
	initial GB,
) HKTRB

func MonadTraverseWithIndex ¶

func MonadTraverseWithIndex[GA ~[]A, GB ~[]B, A, B, HKTB, HKTAB, HKTRB any](
	fof func(GB) HKTRB,
	fmap func(func(GB) func(B) GB) func(HKTRB) HKTAB,
	fap func(HKTB) func(HKTAB) HKTRB,

	ta GA,
	f func(int, A) HKTB) HKTRB

MonadTraverseWithIndex is like MonadTraverse but the transformation function also receives the index. This is useful when the transformation depends on the element's position in the array.

Type parameters: Same as MonadTraverse

Parameters:

• fof: Function to lift a value into the effect (Of/Pure)
• fmap: Function to map over the effect (Map)
• fap: Function to apply an effect of a function to an effect of a value (Ap)
• ta: The input array to traverse
• f: The function to apply to each element with its index, producing an effect

Returns:

• HKTRB: An effect containing the array of transformed values

Note: traversing an empty array returns the effect of nil, consistent with MonadTraverse.

func Of ¶

func Of[GA ~[]A, A any](a A) GA

Of wraps a single value in a one-element array. The result is never nil.

func Prepend ¶

func Prepend[ENDO ~func(AS) AS, AS ~[]A, A any](head A) ENDO

Prepend returns a function that prepends head to an array. The result array is never nil (it always contains at least head).

func Push ¶

func Push[GA ~[]A, A any](as GA, a A) GA

Push appends a single element to a copy of as and returns the copy. The result is never nil.

func Reduce ¶

func Reduce[GA ~[]A, A, B any](fa GA, f func(B, A) B, initial B) B

func ReduceRight ¶

func ReduceRight[GA ~[]A, A, B any](fa GA, f func(A, B) B, initial B) B

func ReduceRightWithIndex ¶

func ReduceRightWithIndex[GA ~[]A, A, B any](fa GA, f func(int, A, B) B, initial B) B

func ReduceWithIndex ¶

func ReduceWithIndex[GA ~[]A, A, B any](fa GA, f func(int, B, A) B, initial B) B

func Reverse ¶

func Reverse[GT ~[]T, T any](as GT) GT

Reverse returns a new array with elements in reversed order. When as has zero or one elements it is returned as-is, so the result may be nil if as was nil.

func Sequence ¶

func Sequence[GA ~[]HKTA, HKTA, HKTRA any](
	fof func(HKTA) HKTRA,
	empty func() HKTRA,
	concat func(HKTRA, HKTRA) HKTRA,
) func(GA) HKTRA

func SequenceSegment ¶

func SequenceSegment[HKTB, HKTRB any](
	fof func(HKTB) HKTRB,
	empty HKTRB,
	concat func(HKTRB, HKTRB) HKTRB,
) func([]HKTB) HKTRB

SequenceSegment creates a function that sequences a segment of an array of effects. Unlike MonadSequenceSegment, this returns a curried function that can be reused.

This function builds a computation tree at construction time, which can be more efficient when the same sequencing pattern needs to be applied multiple times to arrays of the same length.

Type parameters:

• HKTB: The higher-kinded type containing values
• HKTRB: The higher-kinded type containing an array of values

Parameters:

• fof: Function to lift a single HKTB into HKTRB
• empty: The empty/identity value for HKTRB
• concat: Function to concatenate two HKTRB values

Returns:

• A function that takes an array of HKTB and returns HKTRB

func Slice ¶

func Slice[GA ~[]A, A any](low, high int) func(as GA) GA

Slice returns a sub-slice of as in the half-open range [low, high). Negative indices count backward from the end of the array. Returns nil (representing an empty array) when the resulting range is empty.

func SliceRight ¶

func SliceRight[GA ~[]A, A any](start int) func(as GA) GA

SliceRight returns the suffix of as starting at start. Negative indices count backward from the end of the array. Returns nil (representing an empty array) when start is at or beyond the end.

func Traverse ¶

func Traverse[GA ~[]A, GB ~[]B, A, B, HKTB, HKTAB, HKTRB any](
	fof func(GB) HKTRB,
	fmap func(func(GB) func(B) GB) func(HKTRB) HKTAB,
	fap func(HKTB) func(HKTAB) HKTRB,

	f func(A) HKTB) func(GA) HKTRB

Traverse creates a curried function that maps each element to an effect and sequences the results. This is the curried version of MonadTraverse, useful for partial application and composition.

Type parameters: Same as MonadTraverse

Parameters:

• fof: Function to lift a value into the effect (Of/Pure)
• fmap: Function to map over the effect (Map)
• fap: Function to apply an effect of a function to an effect of a value (Ap)
• f: The function to apply to each element, producing an effect

Returns:

• A function that takes an array and returns an effect containing the transformed array

func TraverseReduce ¶

func TraverseReduce[GA ~[]A, GB, A, B, HKTB, HKTAB, HKTRB any](
	fof func(GB) HKTRB,
	fmap func(func(GB) func(B) GB) func(HKTRB) HKTAB,
	fap func(HKTB) func(HKTAB) HKTRB,

	transform func(A) HKTB,
	reduce func(GB, B) GB,
	initial GB,
) func(GA) HKTRB

func TraverseReduceWithIndex ¶

func TraverseReduceWithIndex[GA ~[]A, GB, A, B, HKTB, HKTAB, HKTRB any](
	fof func(GB) HKTRB,
	fmap func(func(GB) func(B) GB) func(HKTRB) HKTAB,
	fap func(HKTB) func(HKTAB) HKTRB,

	transform func(int, A) HKTB,
	reduce func(GB, B) GB,
	initial GB,
) func(GA) HKTRB

TraverseReduceWithIndex creates a curried function for index-aware custom reduction during traversal. This is the curried version of MonadTraverseReduceWithIndex.

Type parameters: Same as MonadTraverseReduce

Parameters: Same as TraverseReduce, except:

• transform: Function that takes index and element, producing an effect

Returns:

• A function that takes an array and returns an effect containing the accumulated value

func TraverseWithIndex ¶

func TraverseWithIndex[GA ~[]A, GB ~[]B, A, B, HKTB, HKTAB, HKTRB any](
	fof func(GB) HKTRB,
	fmap func(func(GB) func(B) GB) func(HKTRB) HKTAB,
	fap func(HKTB) func(HKTAB) HKTRB,

	f func(int, A) HKTB) func(GA) HKTRB

TraverseWithIndex creates a curried function like Traverse but with index-aware transformation. This is the curried version of MonadTraverseWithIndex.

Type parameters: Same as MonadTraverse

Parameters:

• fof: Function to lift a value into the effect (Of/Pure)
• fmap: Function to map over the effect (Map)
• fap: Function to apply an effect of a function to an effect of a value (Ap)
• f: The function to apply to each element with its index, producing an effect

Returns:

• A function that takes an array and returns an effect containing the transformed array

func UnsafeUpdateAt ¶ added in v2.2.71

func UnsafeUpdateAt[GT ~[]T, T any](as GT, i int, v T) GT

UnsafeUpdateAt returns a copy of as with the element at index i replaced by v. The result is never nil.

func UpsertAt ¶

func UpsertAt[GA ~[]A, A any](a A) func(GA) GA

UpsertAt appends a at the end of a copy of ma. The result is never nil.