arrayr

README

arrayr

The arrayr package is a library, written in Go, that has several utility functions for handling arrays.

Documentation

Index

• func ChangeTo[V, R any](change typr.Resolver[V, R], a ...V) (r []R)
• func Filter[V any](ok typr.Qualifier[V], a ...V) (r []V)
• func First[V any](ok typr.Qualifier[V], a ...V) (r V, f bool)
• func FirstOr[V any](ok typr.Qualifier[V], defaultVal V, a ...V) (r V)
• func FirstOrZero[V any](ok typr.Qualifier[V], a ...V) (r V)
• func Frequency[V comparable](a ...V) (r []typr.Pair[V, int])
• func FrequencyR[V any](a ...V) (r []typr.Pair[V, int])
• func From[V any](a ...V) (r []V)
• func FromMap[K comparable, V any](m map[K]V) (r []typr.Pair[K, V])
• func Last[V any](ok typr.Qualifier[V], a ...V) (r V, f bool)
• func LastOr[V any](ok typr.Qualifier[V], defaultVal V, a ...V) (r V)
• func LastOrZero[V any](ok typr.Qualifier[V], a ...V) (r V)
• func Nth[V any](i int, a ...V) (r V, e error)
• func NthOr[V any](i int, defaultVal V, a ...V) (r V)
• func NthOrZero[V any](i int, a ...V) (r V)
• func Range[V any](doRange typr.Ranger[V], a []V, o ...RangeOpts[V])
• func Repeated[V comparable](a ...V) (r []V)
• func RepeatedR[V any](a ...V) (r []V)
• func Reverse[V any](a ...V) (r []V)
• func Unique[V comparable](a ...V) (r []V)
• func UniqueR[V any](a ...V) (r []V)
• func Unrepeated[V comparable](a ...V) (r []V)
• func UnrepeatedR[V any](a ...V) (r []V)
• func Valid[V any](validate typr.Validator[V], a ...V) (r []V)
• type RangeOpts

Functions

func ChangeTo

func ChangeTo[V, R any](change typr.Resolver[V, R], a ...V) (r []R)

applies the specified change function to each element, and returns an array of changed elements

Example sleet := ChangeTo[water,ice](freeze,[]water{drop01,drop02,drop03}...)

func Filter

func Filter[V any](ok typr.Qualifier[V], a ...V) (r []V)

applies the specified Qualifier function to each of the specified elements

each element, where the Qualifier function returns bool true is added to the array that is returned

func First

func First[V any](ok typr.Qualifier[V], a ...V) (r V, f bool)

returns the first element, where the specified Qualifier function returns bool true, and

• bool true, if an element was qualified
• bool false, otherwise

func FirstOr

func FirstOr[V any](ok typr.Qualifier[V], defaultVal V, a ...V) (r V)

returns the first element, where the specified Qualifier function returns bool true, or the specified default value, if no element was qualified

func FirstOrZero

func FirstOrZero[V any](ok typr.Qualifier[V], a ...V) (r V)

returns the first element, where the specified Qualifier function returns bool true, or the zero value of the given type, if no element was qualified

func Frequency

func Frequency[V comparable](a ...V) (r []typr.Pair[V, int])

returns an array of pairs based on the specified elements, where

• the X property of each pair represents the originally specified element
• the Y property of each pair represents the number of times the element occurred, in the original specification

func FrequencyR

func FrequencyR[V any](a ...V) (r []typr.Pair[V, int])

⚠ uses reflection

returns an array of pairs based on the specified elements, where

• the X property of each pair represents the originally specified element
• the Y property of each pair represents the number of times the element occurred, in the original specification

func From

func From[V any](a ...V) (r []V)

returns an array based on the specified values, in the specified order

func FromMap

func FromMap[K comparable, V any](m map[K]V) (r []typr.Pair[K, V])

returns an array of paired elements based on the specified map, where

• the X property of each array element represents a map key
• the Y property of each array element represents a map value

order of the resulting elements is not guaranteed

func Last

func Last[V any](ok typr.Qualifier[V], a ...V) (r V, f bool)

returns the last element, where the specified Qualifier function returns bool true, and

• bool true, if an element was qualified
• bool false, otherwise

func LastOr

func LastOr[V any](ok typr.Qualifier[V], defaultVal V, a ...V) (r V)

returns the last element, where the specified Qualifier function returns bool true, or the specified default value, if no element was qualified

func LastOrZero

func LastOrZero[V any](ok typr.Qualifier[V], a ...V) (r V)

returns the last element, where the specified Qualifier function returns bool true, or the zero value of the given type, if no element was qualified

func Nth

func Nth[V any](i int, a ...V) (r V, e error)

returns the element at the specified index, and a nil error, if the index is valid

• valid non-negative index values range from 0 to n-1, where n is the number of elements in the array
• valid negative index value range from -n to -1, where n is the number of elements in the array

a negative index references an offset from the end of the array, such that

• negative 1 (-1) references the last element
• negative 2 (-1) references the next to last element

and so forth

func NthOr

func NthOr[V any](i int, defaultVal V, a ...V) (r V)

returns the element at the specified index, if the index is valid, or the specified default value

valid index values range from -n to n-1, where n is the number of elements in the array

zero references the first element of the array

a negative index references an offset from the end of the array, such that

• negative 1 (-1) references the last element
• negative 2 (-2) references the next to last element

and so forth

func NthOrZero

func NthOrZero[V any](i int, a ...V) (r V)

returns the element at the specified index, if the index is valid, or the zero value of the given type

valid index values range from -n to n-1, where n is the number of elements in the array

zero references the first element of the array

a negative index references an offset from the end of the array, such that

• negative 1 (-1) references the last element
• negative 2 (-2) references the next to last element

and so forth

func Range

func Range[V any](doRange typr.Ranger[V], a []V, o ...RangeOpts[V])

apply the user-defined Ranger function to elements of the specified array (or slice) and behave according to the Range Options, if specified

func Repeated

func Repeated[V comparable](a ...V) (r []V)

returns an array comprised of any elements that appeared more than once in the original specification

• if no elements appeared more than once, then the resulting array has a length of zero
• the resulting array, if not empty, will have unique elements

func RepeatedR

func RepeatedR[V any](a ...V) (r []V)

⚠ uses reflection

returns an array comprised of any elements that appeared more than once in the original specification

• if no elements appeared more than once, then the resulting array has a length of zero
• the resulting array, if not empty, will have unique elements

func Reverse

func Reverse[V any](a ...V) (r []V)

returns an array of the specified elements in reverse order

func Unique

func Unique[V comparable](a ...V) (r []V)

returns an array comprised of the elements specified, where each element appears exactly once, in the resulting array

func UniqueR

func UniqueR[V any](a ...V) (r []V)

⚠ uses reflection

returns an array comprised of the elements specified, where each element appears exactly once, in the resulting array

func Unrepeated

func Unrepeated[V comparable](a ...V) (r []V)

returns an array comprised of any elements that only appeared once in the original specification

• if no elements appeared only once, then the resulting array has a length of zero
• the resulting array, if not empty, will have unique elements

func UnrepeatedR

func UnrepeatedR[V any](a ...V) (r []V)

⚠ uses reflection

returns an array comprised of any elements that only appeared once in the original specification

• if no elements appeared only once, then the resulting array has a length of zero
• the resulting array, if not empty, will have unique elements

func Valid

func Valid[V any](validate typr.Validator[V], a ...V) (r []V)

returns an array comprised of all of the specified elements considered to be valid, by the specified Validator function

• if no elements were considered valid, then the resulting array has a length of zero

Types

type RangeOpts

type RangeOpts[V any] struct {
	// a non-zero int value, where
	//  - positive values imply ranging in order, from index 0 to n
	//  - negative values imply ranging in order, from index n to 0
	// the value 1 (default) means handle each element, starting at index 0
	//
	// the value 2 means handle every second element, starting at index 0
	Step int
	// a function that returns bool true, when the given element
	// should be handled by the user-defined Ranger function, and bool false, otherwise
	//
	// filtered elements are not passed on to the user-defined Ranger function
	FilterElements typr.Qualifier[V]
	// a function that returns nil, unless the given element is not considered valid, otherwise
	// a non-nil error value is returned
	//
	// elements deemed to be invalid are not passed on to the user-defined Ranger function
	ValidateElements typr.Validator[V]
	// when set to true, stops ranging when the first "invalid" element is encountered
	//  - this option is only effective when a viable ValidateElements function has been defined
	HaltOnInvalidElements bool
	// ⚠ Use With Caution! ⚠
	//
	// when set to true:
	//  - the arrayr.Range(...) function (as usual) blocks, until all elements are finished processing
	//  - all eligible elements are submitted to the user-defined Ranger function and processed concurrently
	//  - the return value of the user-defined Ranger function (eg. typr.Break) is ignored
	//  - elements do not necessarily finish processing in order of submission
	//  - ValidateElements function behaves as a FilterElements function, and HaltOnInvalidElements
	//    is ignored, if set
	// ⚠ User-defined Ranger functions should generally take care to operate in a concurrent-safe
	// manner, when using this option ⚠
	Concurrently bool
}

directives and flags passed to the Range function