Skip to content

README.md

Latest commit

 

History

History
1054 lines (754 loc) · 28.5 KB

README.md

File metadata and controls

1054 lines (754 loc) · 28.5 KB

xslice

import "github.com/dashjay/xiter/pkg/xslice"

Index

func All

func All[T any](in []T, f func(T) bool) bool

All returns true if all elements in the slice satisfy the condition provided by f. return false if any element in the slice does not satisfy the condition provided by f.

EXAMPLE:

xslice.All([]int{1, 2, 3}, func(x int) bool { return x > 0 }) 👉 true
xslice.All([]int{-1, 1, 2, 3}, func(x int) bool { return x > 0 }) 👉 false

func Any

func Any[T any](in []T, f func(T) bool) bool

Any returns true if any element in the slice satisfy the condition provided by f. return false if none of element in the slice satisfy the condition provided by f.

EXAMPLE:

xslice.Any([]int{0, 1, 2, 3}, func(x int) bool { return x == 0 }) 👉 true
xslice.Any([]int{0, 1, 2, 3}, func(x int) bool { return x == -1 }) 👉 false

func Avg

func Avg[T constraints.Number](in []T) float64

Avg returns the average value of the items in slice (float64).

EXAMPLE:

xslice.Avg([]int{1, 2, 3}) 👉 float(2)
xslice.Avg([]int{}) 👉 float(0)

func AvgBy

func AvgBy[V any, T constraints.Number](in []V, f func(V) T) float64

AvgBy returns the averaged of each item's value evaluated by f.

EXAMPLE:

xslice.AvgBy([]string{"1", "2", "3"}, func(x string) int {
	i, _ := strconv.Atoi(x)
	return i
}) 👉 float(2)

func AvgN

func AvgN[T constraints.Number](inputs ...T) float64

AvgN returns the average value of the items

EXAMPLE:

xslice.AvgN(1, 2, 3) 👉 float(2)
xslice.AvgN() 👉 float(0)

func Chunk

func Chunk[T any, Slice ~[]T](in Slice, chunkSize int) []Slice

Chunk returns a new slice with the elements in the slice chunked into smaller slices of the specified size.

EXAMPLE:

xslice.Chunk([]int{1, 2, 3, 4, 5}, 2) 👉 [[1, 2], [3, 4], [5]]
xslice.Chunk([]int{1, 2, 3, 4, 5}, 10) 👉 [[1, 2, 3, 4, 5]]
xslice.Chunk([]int{1, 2, 3, 4, 5}, 0) 👉 []int{}

func ChunkInPlace

func ChunkInPlace[T any, Slice ~[]T](in Slice, chunkSize int) []Slice

ChunkInPlace returns a new slice with the elements in the slice chunked into smaller slices of the specified size. This function will not copy the elements, has no extra costs. EXAMPLE:

xslice.Chunk([]int{1, 2, 3, 4, 5}, 2) 👉 [[1, 2], [3, 4], [5]]
xslice.Chunk([]int{1, 2, 3, 4, 5}, 10) 👉 [[1, 2, 3, 4, 5]]
xslice.Chunk([]int{1, 2, 3, 4, 5}, 0) 👉 []int{}

func Clone

func Clone[T any](in []T) []T

Clone returns a copy of the slice.

EXAMPLE:

xslice.Clone([]int{1, 2, 3}) 👉 [1, 2, 3]

func CloneBy

func CloneBy[T any, U any](in []T, f func(T) U) []U

CloneBy returns a copy of the slice with the results of applying the given function to every element in this slice.

EXAMPLE:

xslice.CloneBy([]int{1, 2, 3}, func(x int) int { return x * 2 }) 👉 [2, 4, 6]
xslice.CloneBy([]int{1, 2, 3}, strconv.Itoa) 👉 ["1", "2", "3"]

func Compact

func Compact[T comparable, Slice ~[]T](in Slice) Slice

Compact returns a new slice with the zero elements removed.

EXAMPLE:

xslice.Compact([]int{0, 1, 2, 3, 4}) 👉 [1 2 3 4]

func Concat

func Concat[T any](vs ...[]T) []T

Concat concatenates the slices.

EXAMPLE:

xslice.Concat([]int{1, 2, 3}, []int{4, 5, 6}) 👉 [1, 2, 3, 4, 5, 6]
xslice.Concat([]int{1, 2, 3}, []int{}) 👉 [1, 2, 3]

func Contains

func Contains[T comparable](in []T, v T) bool

Contains returns true if the slice contains the value v.

EXAMPLE:

xslice.Contains([]int{1, 2, 3}, 1) 👉 true
xslice.Contains([]int{-1, 2, 3}, 1) 👉 false

func ContainsAll

func ContainsAll[T comparable](in []T, v []T) bool

ContainsAll returns true if the slice contains all values in v.

EXAMPLE:

xslice.ContainsAll([]string{"1", "2", "3"}, []string{"1", "2", "3"})  👉 true
xslice.ContainsAll([]string{"1", "2", "3"}, []string{"1", "99", "1000"}) 👉 false
xslice.ContainsAll([]string{"1", "2", "3"}, []string{}) 👉 true

func ContainsAny

func ContainsAny[T comparable](in []T, v []T) bool

ContainsAny returns true if the slice contains any value in v.

EXAMPLE:

xslice.ContainsAny([]string{"1", "2", "3"}, []string{"1", "99", "1000"}) 👉 true
xslice.ContainsAny([]string{"1", "2", "3"}, []string{"-1"}) 👉 false
xslice.ContainsAny([]string{"1", "2", "3"}, []string{}) 👉 false

func ContainsBy

func ContainsBy[T any](in []T, f func(T) bool) bool

ContainsBy returns true if the slice contains the value v evaluated by f.

EXAMPLE:

xslice.ContainsBy([]string{"1", "2", "3"}, func(x string) bool {
	i, _ := strconv.Atoi(x)
	return i == 1
}) 👉 true

xslice.ContainsBy([]string{"1", "2", "3"}, func(x string) bool {
	i, _ := strconv.Atoi(x)
	return i == -1
}) 👉 false

func Count

func Count[T any](in []T) int

Count returns the number of items in the slice.

EXAMPLE:

xslice.Count([]int{1, 2, 3}) 👉 3
xslice.Count([]int{}) 👉 0

func Difference

func Difference[T comparable, Slice ~[]T](left, right Slice) (onlyLeft, onlyRight Slice)

Difference returns two slices: the first slice contains the elements that are in the left slice but not in the right slice, and the second slice contains the elements that are in the right slice but not in the left slice.

EXAMPLE:

left := []int{1, 2, 3, 4, 5}
right := []int{4, 5, 6, 7, 8}
onlyLeft, onlyRight := xslice.Difference(left, right)
fmt.Println(onlyLeft)  // [1 2 3]
fmt.Println(onlyRight) // [6 7 8]

func Filter

func Filter[T any, Slice ~[]T](in Slice, f func(T) bool) Slice

Filter returns a new slice with the elements that satisfy the given function f.

EXAMPLE:

xslice.Filter([]int{1, 2, 3, 2, 4}, func(x int) bool { return x%2 == 0 }) 👉 [2 4]

func Find

func Find[T any](in []T, f func(T) bool) (val T, found bool)

Find returns the first item in the slice that satisfies the condition provided by f.

EXAMPLE:

xslice.Find([]int{1, 2, 3}, func(x int) bool { return x == 1 })  👉 1, true
xslice.Find([]int{1, 2, 3}, func(x int) bool { return x == -1 }) 👉 0, false

func FindO

func FindO[T any](in []T, f func(T) bool) optional.O[T]

FindO returns the first item in the slice that satisfies the condition provided by f.

EXAMPLE:

xslice.FindO(_range(0, 10), func(x int) bool { return x == 1 }).Must() 👉 1
xslice.FindO(_range(0, 10), func(x int) bool { return x == -1 }).Ok() 👉 false

func First

func First[T any, Slice ~[]T](in Slice) (T, bool)

First returns the first element in the slice. If the slice is empty, the zero value of T is returned. EXAMPLE:

xslice.First([]int{1, 2, 3}) 👉 1
xslice.First([]int{}) 👉 0

func FirstO

func FirstO[T any, Slice ~[]T](in Slice) optional.O[T]

FirstO returns the first element in the slice as an optional.O[T]. If the slice is empty, the zero value of T is returned. EXAMPLE:

xslice.FirstO([]int{1, 2, 3}) 👉 1
xslice.FirstO([]int{}) 👉 0

func Flatten

func Flatten[T any](in [][]T) []T

Flatten returns a new slice with all nested slices flattened into a single slice.

EXAMPLE:

xslice.Flatten([][]int{{1, 2}, {3, 4}, {5}}) 👉 [1, 2, 3, 4, 5]
xslice.Flatten([][]int{{1, 2}, {}, {3, 4}}) 👉 [1, 2, 3, 4]
xslice.Flatten([][]int{}) 👉 []int{}
xslice.Flatten([][]int{{}, {}, {}}) 👉 []int{}

func ForEach

func ForEach[T any](in []T, f func(T) bool)

ForEach iterates over each item in the slice, stop if f returns false.

EXAMPLE:

ForEach([]int{1, 2, 3}, func(x int) bool {
	fmt.Println(x)
	return true
}
Output:
1
2
3

func ForEachIdx

func ForEachIdx[T any](in []T, f func(idx int, v T) bool)

ForEachIdx iterates over each item in the slice, stop if f returns false.

EXAMPLE:

ForEach([]int{1, 2, 3}, func(idx, x int) bool {
	fmt.Println(idx, x)
	return true
}
Output:
0 1
1 2
2 3

func GroupBy

func GroupBy[T any, K comparable, Slice ~[]T](in Slice, f func(T) K) map[K]Slice

GroupBy returns a map of the slice elements grouped by the given function f.

EXAMPLE:

xslice.GroupBy([]int{1, 2, 3, 2, 4}, func(x int) int { return x % 2 }) 👉 map[0:[2 4] 1:[1 3]]

func GroupByMap

func GroupByMap[T any, Slice ~[]T, K comparable, V any](in Slice, f func(T) (K, V)) map[K][]V

GroupByMap returns a map of the slice elements grouped by the given function f.

EXAMPLE:

xslice.GroupByMap([]int{1, 2, 3, 2, 4}, func(x int) (int, int) { return x % 2, x }) 👉 map[0:[2 4] 1:[1 3]]

func Head

func Head[T any](in []T) (v T, hasOne bool)

Head returns the first item in the slice.

EXAMPLE:

optional.FromValue2(xslice.Head(_range(0, 10))).Must() 👉 0
optional.FromValue2(xslice.Head(_range(0, 0))).Ok() 👉 false

func HeadO

func HeadO[T any](in []T) optional.O[T]

HeadO returns the first item in the slice.

EXAMPLE:

xslice.HeadO(_range(0, 10)).Must() 👉 0
xslice.HeadO(_range(0, 0)).Ok() 👉 false

func Index

func Index[T comparable, Slice ~[]T](in Slice, v T) int

Index returns the index of the first element in the slice that is equal to v. If no such element is found, -1 is returned. EXAMPLE:

xslice.Index([]int{1, 2, 3, 4, 5}, 1) 👉 0
xslice.Index([]int{1, 2, 3, 4, 5}, 3) 👉 2
xslice.Index([]int{1, 2, 3, 4, 5}, 666) 👉 -1

func Intersect

func Intersect[T comparable, Slice ~[]T](left, right Slice) Slice

Intersect returns a slice that contains the elements that are in both left and right slices.

EXAMPLE:

left := []int{1, 2, 3, 4, 5}
right := []int{4, 5, 6, 7, 8}
intersect := xslice.Intersect(left, right)
fmt.Println(intersect) // [4 5]

func Join

func Join[T ~string](in []T, sep T) T

Join joins the slice with sep.

EXAMPLE:

xslice.Join([]string{"1", "2", "3"}, ".") 👉 "1.2.3"
xslice.Join([]string{}, ".") 👉 ""

func Last

func Last[T any, Slice ~[]T](in Slice) (T, bool)

Last returns the last element in the slice. If the slice is empty, the zero value of T is returned. EXAMPLE:

xslice.Last([]int{1, 2, 3}) 👉 3
xslice.Last([]int{}) 👉 0

func LastO

func LastO[T any, Slice ~[]T](in Slice) optional.O[T]

LastO returns the last element in the slice as an optional.O[T]. If the slice is empty, the zero value of T is returned. EXAMPLE:

xslice.LastO([]int{1, 2, 3}) 👉 3
xslice.LastO([]int{}) 👉 0

func Map

func Map[T any, U any](in []T, f func(T) U) []U

Map returns a new slice with the results of applying the given function to every element in this slice.

EXAMPLE:

xslice.Map([]int{1, 2, 3}, func(x int) int { return x * 2 }) 👉 [2, 4, 6]
xslice.Map([]int{1, 2, 3}, strconv.Itoa) 👉 ["1", "2", "3"]

func Max

func Max[T constraints.Ordered](in []T) optional.O[T]

Max returns the maximum value in the slice.

EXAMPLE:

xslice.Max([]int{1, 2, 3}) 👉 3
xslice.Max([]int{}) 👉 0

func MaxBy

func MaxBy[T constraints.Ordered](in []T, f func(T, T) bool) optional.O[T]

MaxBy returns the maximum value evaluated by f in the slice.

EXAMPLE:

xslice.MaxBy([]int{1, 2, 3} /*less = */, func(a, b int) bool { return a > b }).Must() 👉 1

func MaxN

func MaxN[T constraints.Ordered](in ...T) optional.O[T]

MaxN returns the maximum value in the slice.

EXAMPLE:

xslice.MaxN(1, 2, 3) 👉 3

func Min

func Min[T constraints.Ordered](in []T) optional.O[T]

Min returns the minimum value in the slice.

EXAMPLE:

xslice.Min([]int{1, 2, 3}) 👉 1
xslice.Min([]int{}) 👉 0

func MinBy

func MinBy[T constraints.Ordered](in []T, f func(T, T) bool) optional.O[T]

MinBy returns the minimum value evaluated by f in the slice.

EXAMPLE:

xslice.MinBy([]int{3, 2, 1} /*less = */, func(a, b int) bool { return a > b }).Must() 👉 3

func MinN

func MinN[T constraints.Ordered](in ...T) optional.O[T]

MinN returns the minimum value in the slice.

EXAMPLE:

xslice.MinN(1, 2, 3) 👉 1

func RandomElement

func RandomElement[T any, Slice ~[]T](in Slice) optional.O[T]

RandomElement returns a random element from the slice as an optional.O[T]. If the slice is empty, it returns an optional.O[T] with Ok() == false.

EXAMPLE:

xslice.RandomElement([]int{1, 2, 3, 4, 5}) 👉 3 (random element)
xslice.RandomElement([]int{42}) 👉 42 (always returns the only element)
xslice.RandomElement([]int{}).Ok() 👉 false

func Remove

func Remove[T comparable, Slice ~[]T](in Slice, wantToRemove ...T) Slice

Remove returns a slice that remove all elements in wantToRemove

EXAMPLE:

arr := []int{1, 2, 3, 4}
arr1 := xslice.Remove(arr, 1)
fmt.Println(arr1) // [2, 3, 4]

func Repeat

func Repeat[T any, Slice ~[]T](in Slice, count int) Slice

Repeat returns a new slice with the elements repeated 'count' times.

EXAMPLE:

xslice.Repeat([]int{1, 2, 3}, 3) 👉 [1, 2, 3, 1, 2, 3, 1, 2, 3]
xslice.Repeat([]int{1, 2, 3}, 0) 👉 []int{}

func RepeatBy

func RepeatBy[T any](n int, f func(i int) T) []T

RepeatBy returns a new slice with the elements return by f repeated 'count' times.

EXAMPLE:

xslice.RepeatBy(3, func(i int) int { return i }) 👉 [0, 1, 2]
xslice.RepeatBy(3, func(i int) string { return strconv.Itoa(i) }) 👉 []string{"1", "2", "3"}

func Replace

func Replace[T comparable, Slice ~[]T](in Slice, from, to T, count int) []T

Replace replaces the count elements in the slice from 'from' to 'to'.

EXAMPLE:

xslice.Replace([]int{1, 2, 3}, 2, 4, 1) 👉 [1, 4, 3]
xslice.Replace([]int{1, 2, 2}, 2, 4, -1) 👉 [1, 4, 4]

func ReplaceAll

func ReplaceAll[T comparable, Slice ~[]T](in Slice, from, to T) []T

ReplaceAll replaces all elements in the slice from 'from' to 'to'.

EXAMPLE:

xslice.ReplaceAll([]int{1, 2, 3}, 2, 4) 👉 [1, 4, 3]
xslice.ReplaceAll([]int{1, 2, 2}, 2, 4) 👉 [1, 4, 4]

func Reverse

func Reverse[T any, Slice ~[]T](in Slice)

Reverse reverses the slice.

EXAMPLE:

xslice.Reverse([]int{1, 2, 3}) 👉 [3, 2, 1]
xslice.Reverse([]int{}) 👉 []int{}

func ReverseClone

func ReverseClone[T any, Slice ~[]T](in Slice) Slice

ReverseClone reverses the slice.

EXAMPLE:

xslice.ReverseClone([]int{1, 2, 3}) 👉 [3, 2, 1]
xslice.ReverseClone([]int{}) 👉 []int{}
xslice.ReverseClone([]int{3, 2, 1}) 👉 [1, 2, 3]

func Sample

func Sample[T any, Slice ~[]T](in Slice, n int) Slice

Sample returns a new slice with n randomly selected elements from the input slice. If n is greater than the length of the slice, it returns all elements in random order. If n is less than or equal to 0, it returns an empty slice.

EXAMPLE:

xslice.Sample([]int{1, 2, 3, 4, 5}, 3) 👉 [3, 1, 5] (random order, 3 elements)
xslice.Sample([]int{1, 2, 3}, 5) 👉 [2, 1, 3] (random order, all elements)
xslice.Sample([]int{1, 2, 3}, 0) 👉 []int{}
xslice.Sample([]int{}, 3) 👉 []int{}

func Shuffle

func Shuffle[T any, Slice ~[]T](in Slice) Slice

Shuffle shuffles the slice.

EXAMPLE:

xslice.Shuffle([]int{1, 2, 3}) 👉 [2, 1, 3] (random)
xslice.Shuffle([]int{}) 👉 []int{}

func ShuffleInPlace

func ShuffleInPlace[T any, Slice ~[]T](in Slice)

ShuffleInPlace shuffles the slice.

EXAMPLE:

array := []int{1, 2, 3}
xslice.ShuffleInPlace(array) 👉 [2, 1, 3] (random)

func Subset

func Subset[T any, Slice ~[]T](in Slice, start, count int) Slice

Subset returns a subset slice from the slice. if start < -1 means that we take subset from right-to-left

EXAMPLE:

xslice.Subset([]int{1, 2, 3}, 0, 2) 👉 [1, 2]
xslice.Subset([]int{1, 2, 3}, -1, 2) 👉 [2, 3]

func SubsetInPlace

func SubsetInPlace[T any, Slice ~[]T](in Slice, start int, count int) Slice

SubsetInPlace returns a subset slice copied from the slice. if start < -1 means that we take subset from right-to-left EXAMPLE:

xslice.SubsetInPlace([]int{1, 2, 3}, 0, 2) 👉 [1, 2]
xslice.SubsetInPlace([]int{1, 2, 3}, -1, 2) 👉 [2, 3]

func Sum

func Sum[T constraints.Number, Slice ~[]T](in Slice) T

Sum returns the sum of all elements in the slice.

EXAMPLE:

xslice.Sum([]int{1, 2, 3}) 👉 6
xslice.Sum([]int{}) 👉 0

func SumBy

func SumBy[T any, R constraints.Number, Slice ~[]T](in Slice, f func(T) R) R

SumBy returns the sum of all elements in the slice after applying the given function f to each element.

EXAMPLE:

xslice.SumBy([]string{"1", "2", "3"}, func(x string) int {
	i, _ := strconv.Atoi(x)
	return i
}) 👉 6
xslice.SumBy([]string{}, func(x string) int { return 0 }) 👉 0

func SumN

func SumN[T constraints.Number](in ...T) T

SumN returns the sum of all input arguments.

EXAMPLE:

xslice.SumN(1, 2, 3) 👉 6
xslice.SumN() 👉 0

func ToMap

func ToMap[T comparable, U any](in []T, f func(T) U) map[T]U

ToMap returns a map where keys are elements from the slice and values are the result of applying f to each element. If there are duplicate keys in the slice, only the last element with that key will be present in the map.

EXAMPLE:

xslice.ToMap([]string{"a", "b", "c"}, func(s string) int { return len(s) }) 👉 map[a:1 b:1 c:1]
xslice.ToMap([]int{1, 2, 3}, func(i int) string { return fmt.Sprintf("num_%d", i) }) 👉 map[1:num_1 2:num_2 3:num_3]
xslice.ToMap([]int{1, 2, 1, 3}, func(i int) string { return fmt.Sprintf("val_%d", i) }) 👉 map[1:val_1 2:val_2 3:val_3] (note: key 1 has "val_1" from the last occurrence)
xslice.ToMap([]int{}, func(i int) string { return "" }) 👉 map[int]string{}

func Union

func Union[T comparable, Slice ~[]T](left, right Slice) Slice

Union returns a slice that contains all elements in left and right slices.

EXAMPLE:

left := []int{1, 2, 3, 4}
right := []int{3, 4, 5, 6}
union := xslice.Union(left, right)
fmt.Println(union) // [1 2 3 4 5 6]

func Uniq

func Uniq[T comparable, Slice ~[]T](in Slice) Slice

Uniq returns a new slice with the duplicate elements removed.

EXAMPLE:

xslice.Uniq([]int{1, 2, 3, 2, 4}) 👉 [1, 2, 3, 4]

Generated by gomarkdoc