gslice

func All ¶

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

All determines whether all elements of the slice s satisfy the predicate f.

🚀 EXAMPLE:

All([]int{1, 2, 3}, func(x int) bool { return x > 0 }) ⏩ true

func Any ¶

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

Any determines whether any (at least one) element of the slice s satisfies the predicate f.

Any supports short-circuit evaluation.

🚀 EXAMPLE:

Any([]int{1, 2, 3}, func(x int) bool { return x > 2 }) ⏩ true

💡 HINT:

• Use All to known whether all elements satisfies the predicate f
• Use CountBy to known how many elements satisfies the predicate f

func Avg ¶

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

Avg returns the arithmetic mean of the elements of slice s.

🚀 EXAMPLE:

Avg([]int{1, 2, 3, 4, 5})      ⏩ 3.0
Avg([]float64{1, 2, 3, 4, 5})  ⏩ 3.0

💡 AKA: Mean, Average

func AvgBy ¶

func AvgBy[T any, N constraints.Number](s []T, f func(T) N) float64

AvgBy applies function f to each element of slice s, returns the arithmetic mean of function result.

💡 AKA: MeanBy, AverageBy

func Chunk ¶

func Chunk[S ~[]T, T any](s S, size int) []S

Chunk splits a slice into length-n chunks and returns chunks by a newly allocated slice.

The last chunk will be shorter if n does not evenly divide the length of the list.

🚀 EXAMPLE:

Chunk([]int{0, 1, 2, 3, 4}, 2) ⏩ [][]int{{0, 1}, {2, 3}, {4}}

💡 HINT:

• If you want to split list into n chunks, use function Divide.
• This function returns sub-slices of original slice, if you modify the sub-slices, the original slice is modified too. Use ChunkClone to prevent this.
• Use Flatten to restore chunks to flat slice.

💡 AKA: Page, Pagination

func ChunkClone ¶

func ChunkClone[S ~[]T, T any](s S, size int) []S

ChunkClone is variant of function Chunk. It clones the original slice before chunking it.

func Clone ¶

func Clone[S ~[]T, T any](s S) S

Clone returns a shallow copy of the slice. If the given slice is nil, nil is returned.

🚀 EXAMPLE:

Clone([]int{1, 2, 3}) ⏩ []int{1, 2, 3}
Clone([]int{})        ⏩ []int{}
Clone[int](nil)       ⏩ nil

💡 HINT: The elements are copied using assignment (=), so this is a shallow clone. If you want to do a deep clone, use CloneBy with an appropriate element clone function.

💡 AKA: Copy

func CloneBy ¶

func CloneBy[S ~[]T, T any](s S, f func(T) T) S

CloneBy is variant of Clone, it returns a copy of the slice. Elements are copied using function clone. If the given slice is nil, nil is returned.

💡 AKA: CopyBy

func Compact ¶

func Compact[S ~[]T, T comparable](s S) S

Compact removes all zero values from given slice s, returns a newly allocated slice.

🚀 EXAMPLE:

Compact([]int{0, 1, 2, 0, 3, 0, 0})     ⏩ []int{1, 2, 3}
Compact([]string{"", "foo", "", "bar"}) ⏩ []string{"foo", "bar"}

💡 HINT: See github.com/bytedance/gg/gvalue.Zero for details of zero value.

func Concat ¶

func Concat[S ~[]T, T any](ss ...S) S

Concat concatenates slices in order.

🚀 EXAMPLE:

Concat([]int{0}, []int{1, 2}, []int{3, 4}) ⏩ []int{0, 1, 2, 3, 4}

💡 AKA: Merge, Connect

func Contains ¶

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

Contains returns whether the element occur in slice.

🚀 EXAMPLE:

Contains([]int{0, 1, 2, 3, 4}, 1) ⏩ true
Contains([]int{0, 1, 2, 3, 4}, 5) ⏩ false
Contains([]int{}, 5)              ⏩ false

💡 HINT:

• Use ContainsAll, ContainsAny if you have multiple values to query
• Use Index if you also want to know index of the found value
• Use Any or Find if type of v is non-comparable

func ContainsAll ¶

func ContainsAll[T comparable](s []T, vs ...T) bool

ContainsAll returns whether all of given elements occur in slice.

🚀 EXAMPLE:

s := []int{0, 1, 2, 3, 4}
ContainsAll(s, 0)    ⏩ true
ContainsAll(s, 5)    ⏩ false
ContainsAll(s, 0, 1) ⏩ true
ContainsAll(s, 0, 5) ⏩ false

func ContainsAny ¶

func ContainsAny[T comparable](s []T, vs ...T) bool

ContainsAny returns whether any of given elements occur in slice.

🚀 EXAMPLE:

s := []int{0, 1, 2, 3, 4}
ContainsAny(s, 0)    ⏩ true
ContainsAny(s, 5)    ⏩ false
ContainsAny(s, 0, 1) ⏩ true
ContainsAny(s, 0, 5) ⏩ true

func Count ¶

func Count[T comparable](s []T, v T) int

Count returns the times of value v that occur in slice s.

🚀 EXAMPLE:

Count([]string{"a", "b", "c"}, "a") ⏩ 1
Count([]int{0, 1, 2, 0, 5, 3}, 0)   ⏩ 2

💡 HINT:

• Use Contains if you just want to know whether the element exitss or not
• Use CountBy if type of v is non-comparable

func CountBy ¶

func CountBy[T any](s []T, f func(T) bool) int

CountBy returns the times of element in slice s that satisfy the predicate f.

🚀 EXAMPLE:

CountBy([]string{"a", "b", "c"}, func (v string) bool { return v < "b" }) ⏩ 1
CountBy([]int{0, 1, 2, 3, 4}, func (v int) bool { return v % i == 0 })    ⏩ 3

💡 HINT: Use Any if you just want to know whether at least one element satisfies predicate f.

func CountValues ¶

func CountValues[T comparable](s []T) map[T]int

CountValues returns the occurrences of each element in slice s.

🚀 EXAMPLE:

CountValues([]string{"a", "b", "b"}) ⏩ map[string]int{"a": 1, "b": 2}
CountValues([]int{0, 1, 2, 0, 1, 1}) ⏩ map[int]int{0: 2, 1: 3, 2: 1}

💡 HINT:

• Use CountValuesBy if the element in slice s is non-comparable

func CountValuesBy ¶

func CountValuesBy[K comparable, T any](s []T, f func(T) K) map[K]int

CountValuesBy returns the times of each element in slice s that satisfy the predicate f.

🚀 EXAMPLE:

CountValuesBy([]int{0, 1, 2, 3, 4}, func(v int) bool { return v%2 == 0 }) ⏩ map[bool]int{true: 3, false: 2}
type Foo struct{ v int }
foos := []Foo{{1}, {2}, {3}}
CountValuesBy(foos, func(v Foo) bool { return v.v%2 == 0 }) ⏩ map[bool]int{true: 1, false: 2}

func Diff ¶

func Diff[S ~[]T, T comparable](s S, againsts ...S) S

Diff returns the difference of slice s against other slices as a newly allocated slice.

💡 NOTE: If the result is an empty set, always return an empty slice instead of nil

🚀 EXAMPLE:

Diff([]int{1, 2, 3}, []int{3, 4, 5}) ⏩ []int{1, 2}
Diff([]int{1, 2, 3}, []int{4, 5, 6}) ⏩ []int{1, 2, 3}
Diff([]int{1, 2, 3}, []int{1, 2, 3}) ⏩ []int{}

💡 HINT: if you need a set data structure, use github.com/bytedance/gg/collection/set.

func Divide ¶

func Divide[S ~[]T, T any](s S, n int) []S

Divide splits a list into exactly n slices and returns chunks by a newly allocated slice.

The length of chunks will be different if n does not evenly divide the length of the slice.

🚀 EXAMPLE:

s := []int{0, 1, 2, 3, 4}
Divide(s, 2)       ⏩ [][]int{{0, 1, 2},  {3, 4}}
Divide(s, 3)       ⏩ [][]int{{0, 1}, {2, 3}, {4}}
Divide([]int{}, 2) ⏩ [][]int{{}, {}}

💡 HINT:

• If you want to split list into length-n chunks, use Chunk.
• This function returns sub-slices of original slice, if you modify the sub-slices, the original slice is modified too. Use DivideClone to prevent this.
• Use Flatten to restore chunks to flat slice.

💡 AKA: Page, Pagination

func DivideClone ¶

func DivideClone[S ~[]T, T any](s S, n int) []S

DivideClone is variant of function Divide. It clones the original slice before dividing it.

func Drop ¶

func Drop[S ~[]T, T any](s S, n int) S

Drop drops the first n elements of slices s, returns the remaining part of slice, or empty slice if n > len(s).

🚀 EXAMPLE:

s := []int{1, 2, 3, 4, 5}
Drop(s, 0)  ⏩ []int{1, 2, 3, 4, 5}
Drop(s, 3)  ⏩ []int{4, 5}
Drop(s, 10) ⏩ []int{}

⚠️ WARNING: Panic when n < 0.

💡 NOTE: This function returns sub-slices of original slice, if you modify the sub-slices, the original slice is modified too. Use DropClone to prevent this.

func DropClone ¶

func DropClone[S ~[]T, T any](s S, n int) S

DropClone is variant of Drop.

func Dup ¶

func Dup[S ~[]T, T comparable](s S) S

Dup returns the repeated elements of slice. The result are sorted in order of recurrence.

🚀 EXAMPLE:

Dup([]int{0, 1, 1, 1})    ⏩ []int{1}
Dup([]int{3, 2, 2, 3, 3}) ⏩ []int{2, 3} // in order of recurrence

💡 HINT:

• If type is not comparable, use DupBy.
• If you need distinct elements, use Uniq.

💡 AKA: Duplicate.

func DupBy ¶

func DupBy[S ~[]T, K comparable, T any](s S, f func(T) K) S

DupBy returns the repeated elements of slice with key function f. The result is a newly allocated slice contains duplicate elements. The result are sorted in order of recurrence.

🚀 EXAMPLE:

type Foo struct{ Value int }
s := []Foo{{3}, {2}, {2}, {3}, {3}}
DupBy(s, func(v Foo) int { return v.Value }) ⏩ []Foo{{2}, {3}}

💡 AKA: DuplicateBy.

func Equal ¶

func Equal[T comparable](s1, s2 []T) bool

Equal returns whether two slices are equal.

🚀 EXAMPLE:

Equal([]int{1, 2, 3}, []int{1, 2, 3})    ⏩ true
Equal([]int{1, 2, 3}, []int{1, 2, 3, 4}) ⏩ false
Equal([]int{}, []int{})                  ⏩ true
Equal([]int{}, nil)                      ⏩ true

func EqualBy ¶

func EqualBy[T any](s1, s2 []T, eq func(T, T) bool) bool

EqualBy returns whether two slices are equal by function eq.

🚀 EXAMPLE:

eq := gvalue.Equal[int]
EqualBy([]int{1, 2, 3}, []int{1, 2, 3}, eq)    ⏩ true
EqualBy([]int{1, 2, 3}, []int{1, 2, 3, 4}, eq) ⏩ false
EqualBy([]int{}, []int{}, eq)                  ⏩ true
EqualBy([]int{}, nil, eq)                      ⏩ true

func Filter ¶

func Filter[S ~[]T, T any](s S, f func(T) bool) S

Filter applies predicate f to each element of slice s, returns those elements that satisfy the predicate f as a newly allocated slice.

🚀 EXAMPLE:

Filter([]int{0, 1, 2, 3}, gvalue.IsNotZero[int]) ⏩ []int{1, 2, 3}

💡 HINT:

• Use FilterMap if you also want to change the element during filtering.
• If you need elements that do not satisfy f, use Reject
• If you need both elements, use Partition

func FilterMap ¶

func FilterMap[F, T any](s []F, f func(F) (T, bool)) []T

FilterMap does Filter and Map at the same time, applies function f to each element of slice s. f returns (T, bool):

• If true ,the return value with type T will added to the result slice []T.
• If false, the return value with type T will be dropped.

🚀 EXAMPLE:

f := func(i int) (string, bool) { return strconv.Itoa(i), i != 0 }
FilterMap([]int{1, 2, 3, 0, 0}, f) ⏩ []string{"1", "2", "3"}

💡 HINT: Use TryFilterMap if function f returns (T, error).

func Find ¶

func Find[T any](s []T, f func(T) bool) goption.O[T]

Find returns the possible first element of slice that satisfies predicate f.

🚀 EXAMPLE:

s := []int{0, 1, 2, 3, 4}
Find(s, func(v int) bool { return v > 0 }) ⏩ goption.OK(1)
Find(s, func(v int) bool { return v < 0 }) ⏩ goption.Nil[int]()

💡 HINT:

• Use Contains if you just want to know whether the value exists
• Use IndexBy if you want to know the index of value
• Use FindRev if you want to find in reverse order
• Use Count if you want to count the occurrences of element

💡 AKA: Search

func FindRev ¶

func FindRev[T any](s []T, f func(T) bool) goption.O[T]

FindRev is a variant of Find in reverse order.

🚀 EXAMPLE:

s := []int{0, 1, 2, 3, 4}
FindRev(s, func(v int) bool { return v > 0 }) ⏩ goption.OK(4)
FindRev(s, func(v int) bool { return v < 0 }) ⏩ goption.Nil[int]()

func First ¶

func First[T any](s []T) goption.O[T]

First returns the possible first element of slice s. If the given slice is empty, goption.Nil[T]() is returned.

🚀 EXAMPLE:

First([]int{4, 3, 1, 4}) ⏩ goption.OK(4)
First([]int{})           ⏩ goption.Nil[int]()

💡 HINT: Use Get to access element at any index.

💡 AKA: Head

func FlatMap ¶

func FlatMap[F, T any](s []F, f func(F) []T) []T

FlatMap applies function f to each element of slice s with type F. Results of f are flatten and returned as a newly allocated slice with type T.

🚀 EXAMPLE:

type Site struct{ urls []string }
func (s Site) URLs() []string { return s.urls }

sites := []Site{
	{[]string{"url1", "url2"}},
	{[]string{"url3", "url4"}},
}

FlatMap(sites, Site.URLs) ⏩ []string{"url1", "url2", "url3", "url4"}

💡 HINT:

• Use Flatten if the element of given slice is also slice.
• Use FilterMap if you want to ignore some element during mapping

func Flatten ¶

func Flatten[S ~[]T, T any](s []S) S

Flatten collapses a tow-dimension slice to one dimension.

🚀 EXAMPLE:

Flatten([][]int{{0}, {1, 2}, {3, 4}}) ⏩ []int{0, 1, 2, 3, 4}

💡 HINT: Use FlatMap if you want to flatten non-slice elements.

func Fold ¶

func Fold[T1, T2 any](s []T1, f func(T2, T1) T2, init T2) T2

Fold applies function f cumulatively to each element of slice s, so as to fold the slice to a single value. An init element is needed as the initial value of accumulation. If the given slice is empty, the init element is returned.

🚀 EXAMPLE:

s := []int{0, 1, 2, 3}
Fold(s, gvalue.Add[int], 4)       ⏩ 10
Fold(s, gvalue.Add[int], 2)       ⏩ 8
Fold([]int{}, gvalue.Add[int], 1) ⏩ 1

func ForEach ¶

func ForEach[T any](s []T, f func(v T))

ForEach applies function f to each element of slice s.

💡 HINT: Use ForEachIndexed If you want to get element with index.

func ForEachIndexed ¶

func ForEachIndexed[T any](s []T, f func(i int, v T))

ForEachIndexed applies function f to each element of slice s. The argument i of function f represents the zero-based index of that element of slice.

func Get ¶

func Get[T any, I constraints.Integer](s []T, n I) goption.O[T]

Get returns the possible element at index n.

[Negative index] is supported. For example:

• Get(s, 0) returns the First element
• Get(s, -1) returns the Last element

🚀 EXAMPLE:

s := []int{1, 2, 3, 4}
Get(s, 0)  ⏩ goption.OK(1)
Get(s, 1)  ⏩ goption.OK(2)
Get(s, -1) ⏩ goption.OK(4)
Get(s, -2) ⏩ goption.OK(3)

💡 AKA: Nth, At, Access, ByIndex, Load

func GroupBy ¶

func GroupBy[S ~[]T, K comparable, T any](s S, f func(T) K) map[K]S

GroupBy adjacent elements according to key returned by function f.

🚀 EXAMPLE:

GroupBy([]int{1, 2, 3, 4},
func(v int) string {
    return gcond.If(v%2 == 0, "even", "odd")
})

⏩

map[string][]int{
    "odd": {1, 3},
    "even": {2, 4},
}

💡 HINT: If function f returns bool, use Partition instead.

func Index ¶

func Index[T comparable](s []T, e T) goption.O[int]

Index returns the index of the first occurrence of element in slice s, or nil if not present.

🚀 EXAMPLE:

s := []string{"a", "b", "b", "d"}
Index(s, "b") ⏩ goption.OK(1)
Index(s, "e") ⏩ goption.Nil[int]()

💡 HINT:

• Use IndexBy if complex comparison logic is required (instead of just ==)
• Use Contains if you just want to know whether the value exists
• Use IndexRev if you want to index element in reverse order.

func IndexBy ¶

func IndexBy[T any](s []T, f func(T) bool) goption.O[int]

IndexBy is variant of Index, returns the first index of element that satisfying predicate f, or nil if none do.

func IndexRev ¶

func IndexRev[T comparable](s []T, e T) goption.O[int]

IndexRev is a variant of Index in reverse order.

🚀 EXAMPLE:

s := []string{"a", "b", "b", "d"}
IndexRev(s, "b") ⏩ goption.OK(2)
IndexRev(s, "e") ⏩ goption.Nil[int]()

func IndexRevBy ¶

func IndexRevBy[T any](s []T, f func(T) bool) goption.O[int]

IndexRevBy is variant of IndexRev, returns the first index of element that satisfying predicate f, or nil if none do.

func Indirect ¶

func Indirect[T any](s []*T) []T

Indirect returns the values pointed to by the pointers. If the element is nil, filter it out of the returned slice.

🚀 EXAMPLE:

v1, v2 := 1, 2
Indirect([]*int{ &v1, &v2, nil})  ⏩ []int{1, 2}

💡 HINT: If you want to replace nil pointer with default value, use IndirectOr.

func IndirectOr ¶

func IndirectOr[T any](s []*T, fallback T) []T

IndirectOr safely dereferences slice of pointers. If the pointer is nil, returns the value fallback instead.

🚀 EXAMPLE:

v1, v2 := 1, 2
IndirectOr([]*int{ &v1, &v2, nil}, -1)  ⏩ []int{1, 2, -1}

func Insert ¶

func Insert[S ~[]T, T any, I constraints.Integer](s S, pos I, vs ...T) S

Insert inserts elements vs before position pos, returns a newly allocated slice. [Negative index] is supported.

• Insert(x, 0, ...) inserts at the front of the slice
• Insert(x, len(x), ...) is equivalent to append(x, ...)
• Insert(x, -1, ...) is equivalent to Insert(x, len(x)-1, ...)

🚀 EXAMPLE:

s := []int{0, 1, 2, 3}
Insert(s, 0, 99)      ⏩ []int{99, 0, 1, 2, 3}
Insert(s, 0, 98, 99)  ⏩ []int{98, 99, 0, 1, 2, 3}
Insert(s, 4, 99)      ⏩ []int{0, 1, 2, 3, 99}
Insert(s, 1, 99)      ⏩ []int{0, 99, 1, 2, 3}
Insert(s, -1, 99)     ⏩ []int{0, 1, 2, 99, 3}

func Intersect ¶

func Intersect[S ~[]T, T comparable](ss ...S) S

Intersect returns the intersection of slices as a newly allocated slice.

💡 NOTE: If the result is an empty set, always return an empty slice instead of nil

🚀 EXAMPLE:

Intersect([]int{1, 2, 3}, []int{2, 3, 4}) ⏩ []int{2, 3}
Intersect([]int{1, 2, 3}, []int{4, 5, 6}) ⏩ []int{}
Intersect([]int{1, 2, 3}, []int{1, 2, 3}) ⏩ []int{1, 2, 3}

💡 HINT: if you need a set data structure, use github.com/bytedance/gg/collection/set.

func Last ¶

func Last[T any](s []T) goption.O[T]

Last returns the possible last element of slice s. If the given slice is empty, goption.Nil[T]() is returned.

🚀 EXAMPLE:

Last([]int{4, 3, 1, 5}) ⏩ goption.OK(5)
Last([]int{})           ⏩ goption.Nil[int]()

💡 HINT: Use Get to access element at any index.

💡 AKA: Tail

func Len ¶

func Len[T any](s []T) int

Len returns the length of slice s.

💡 HINT: This function is designed for high-order function, because the builtin function can not be used as function pointer. For example, if you want to get the total length of a 2D slice:

var s [][]int
total1 := SumBy(s, len)      // ❌ERROR❌ len (built-in) must be called
total2 := SumBy(s, Len[int]) // OK

func Map ¶

func Map[F, T any](s []F, f func(F) T) []T

Map applies function f to each element of slice s with type F. Results of f are returned as a newly allocated slice with type T.

🚀 EXAMPLE:

Map([]int{1, 2, 3}, strconv.Itoa) ⏩ []string{"1", "2", "3"}
Map([]int{}, strconv.Itoa)        ⏩ []string{}
Map(nil, strconv.Itoa)            ⏩ []string{}

💡 HINT:

• Use FilterMap if you also want to ignore some element during mapping.
• Use TryMap if function f may fail (return (T, error))

func Max ¶

func Max[T constraints.Ordered](s []T) goption.O[T]

Max returns maximum element of slice s. If the given slice is empty, goption.Nil[T]() is returned.

🚀 EXAMPLE:

Max([]int{0, 1, 4, 3, 1, 4}) ⏩ goption.OK(4)
Max([]int{})                 ⏩ goption.Nil[int]()

💡 HINT: If type is not orderable, use MaxBy.

func MaxBy ¶

func MaxBy[T any](s []T, less func(T, T) bool) goption.O[T]

MaxBy returns the maximum element of slice s determined by function less. If the given slice is empty, goption.Nil[T]() is returned.

🚀 EXAMPLE:

type Foo struct { Value int }
less := func(x, y Foo) bool { return x.Value < y.Value }
s := []Foo{{10}, {1}, {-1}, {100}, {3}}
MaxBy(s, less) ⏩ goption.OK(Foo{100})

func Merge ¶

func Merge[S ~[]T, T any](ss ...S) S

Merge is alias of Concat.

func Min ¶

func Min[T constraints.Ordered](s []T) goption.O[T]

Min returns the minimum element of slices s. If the given slice is empty, goption.Nil[T]() is returned.

🚀 EXAMPLE:

Min([]int{1, 4, 3, 1, 4}) ⏩ goption.OK(1)
Min([]int{})              ⏩ goption.Nil[int]()

💡 HINT: If type is not orderable, use MinBy.

func MinBy ¶

func MinBy[T any](s []T, less func(T, T) bool) goption.O[T]

MinBy returns the minimum element of slices s determined by function less. If the given slice is empty, goption.Nil[T]() is returned.

🚀 EXAMPLE:

type Foo struct { Value int }
less := func(x, y Foo) bool { return x.Value < y.Value }
MinBy([]Foo{{10}, {1}, {-1}, {100}, {3}}, less) ⏩ goption.OK(Foo{-1})

func MinMax ¶

func MinMax[T constraints.Ordered](s []T) goption.O[tuple.T2[T, T]]

MinMax returns both minimum and maximum elements of slice s. If the given slice is empty, goption.Nil[tuple.T2[T, T]]() is returned.

🚀 EXAMPLE:

MinMax([]int{})                 ⏩ goption.Nil[int]()
MinMax([]int{1})                ⏩ goption.OK(tuple.T2{1, 1})
MinMax([]int{0, 1, 4, 3, 1, 4}) ⏩ goption.OK(tuple.T2{0, 4})

💡 HINT: If type is not orderable, use MinMaxBy.

💡 AKA: Bound

func MinMaxBy ¶

func MinMaxBy[T any](s []T, less func(T, T) bool) goption.O[tuple.T2[T, T]]

MinMaxBy returns both minimum and maximum elements of slice s. If the given slice is empty, goption.Nil[tuple.T2[T, T]]() is returned.

🚀 EXAMPLE:

type Foo struct { Value int }
less := func(x, y Foo) bool { return x.Value < y.Value }
MinMaxBy([]Foo{{10}, {1}, {-1}, {100}, {3}}, less) ⏩ goption.OK(tuple.T2{Foo{-1}, Foo{100}})

💡 NOTE: The returned min and max elements may be the same object when each element of the slice is equal

💡 AKA: BoundBy

func Of ¶

func Of[T any](v ...T) []T

Of creates a slice from variadic arguments. If no argument given, an empty (non-nil) slice []T{} is returned.

💡 HINT: This function is used to omit verbose types like "[]LooooongTypeName{}" when constructing slices.

🚀 EXAMPLE:

Of(1, 2, 3) ⏩ []int{1, 2, 3}
Of(1)       ⏩ []int{1}
Of[int]()   ⏩ []int{}

func Partition ¶

func Partition[S ~[]T, T any](s S, f func(T) bool) (S, S)

Partition applies predicate f to each element of slice s, divides elements into 2 parts: satisfy f and do not satisfy f.

🚀 EXAMPLE:

Partition([]int{0, 1, 2, 3}, gvalue.IsNotZero[int]) ⏩ []int{1, 2, 3}, []int{0}

💡 HINT:

• Use Filter or Reject if you need only one of the return values
• Use Chunk or Divide if you want to divide elements by index

func PtrOf ¶

func PtrOf[T any](s []T) []*T

PtrOf returns pointers that point to equivalent elements of slice s. ([]T → []*T).

🚀 EXAMPLE:

PtrOf([]int{1, 2, 3}) ⏩ []*int{ (*int)(1), (*int)(2), (*int)(3) },

⚠️ WARNING: The returned pointers do not point to elements of the original slice, user CAN NOT modify the element by modifying the pointer.

func Range ¶

func Range[I constraints.Number](start, stop I) []I

Range is a variant of RangeWithStep, with predefined step 1.

🚀 EXAMPLE:

Range(0, 0)    ⏩ []int{}
Range(0, -5)   ⏩ []int{}
Range(0, 5)    ⏩ []int{0, 1, 2, 3, 4}

func RangeWithStep ¶

func RangeWithStep[I constraints.Number](start, stop, step I) []I

RangeWithStep returns a slice of numbers from start (inclusive) to stop (exclusive) by step. If the interval does not exist, RangeWithStep returns an empty slice. If the step is positive, the returned slice is in ascending order. If the step is negative, the returned slice is in descending order.

🚀 EXAMPLE:

RangeWithStep(0, 0, 2)     ⏩ []int{}
RangeWithStep(0, -5, -1)   ⏩ []int{0, -1, -2, -3, -4}
RangeWithStep(0, 5, 2)     ⏩ []int{0, 2, 4}
RangeWithStep(0, 5, 3)     ⏩ []int{0, 3}
RangeWithStep(0.5, 2, 0.5) ⏩ []float64{0.5, 1, 1.5}

func Reduce ¶

func Reduce[T any](s []T, f func(T, T) T) goption.O[T]

Reduce is a variant of Fold, use possible first element of slice as the initial value of accumulation. If the given slice is empty, goption.Nil[T]() is returned.

🚀 EXAMPLE:

Reduce([]int{0, 1, 2, 3}, gvalue.Add[int]) ⏩ goption.OK(6)
Reduce([]int{}, gvalue.Add[int])           ⏩ goption.Nil[int]()

💡 HINT: Calculate the maximum value is only for example, you can directly use function Max.

func Reject ¶

func Reject[S ~[]T, T any](s S, f func(T) bool) S

Reject applies predicate f to each element of slice s, returns those elements that do not satisfy the predicate f as a newly allocated slice.

🚀 EXAMPLE:

Reject([]int{0, 1, 2, 3}, gvalue.IsZero[int]) ⏩ []int{1, 2, 3}

💡 HINT:

• If you need elements that satisfy f, use Filter
• If you need both elements, use Partition

func Remove ¶

func Remove[S ~[]T, T comparable](s S, v T) S

Remove removes all element v from the slice s, returns a newly allocated slice.

🚀 EXAMPLE:

Remove([]int{0, 1, 2, 3, 4}, 3)    ⏩ []int{0, 1, 2, 4}
Remove([]int{0, 1, 3, 2, 3, 4}, 3) ⏩ []int{0, 1, 2, 4}

💡 HINT:

• Use Compact if you just want to remove zero value.
• Use RemoveIndex if you want to remove value by index

💡 AKA: Delete

func RemoveIndex ¶

func RemoveIndex[S ~[]T, I constraints.Integer, T any](s S, index I) S

RemoveIndex removes the element at index i from slice s and returns a newly allocated slice. If s[i] does not exist or is invalid, this function just clone the original slice. [Negative index] is supported.

• RemoveIndex(x, 0) 🟰 Clone(s[1:])
• RemoveIndex(x, -1) 🟰 Clone(s[0:len(x)-1])
• RemoveIndex(x, len(x)) 🟰 Clone(s)

🚀 EXAMPLE:

RemoveIndex([]int{0, 1, 2, 3, 4}, 3)    ⏩ []int{0, 1, 2, 4}
RemoveIndex([]int{0, 1, 2, 3, 4}, -1)   ⏩ []int{0, 1, 2, 3}
RemoveIndex([]int{0, 1, 2, 3, 4}, 0)    ⏩ []int{1, 2, 3, 4}
RemoveIndex([]int{0, 1, 2, 3, 4}, 100)  ⏩ []int{0, 1, 2, 3, 4}

💡 Hint: This function has O(n) time complexity and ALWAYS returns a newly allocated slice.

💡 HINT: Use Remove if you want to remove elements by value

💡 AKA: DeleteIndex

func Repeat ¶

func Repeat[T any](v T, n int) []T

Repeat returns a slice with value v repeating exactly n times. The result is an empty slice if n is 0.

⚠️ WARNING: The function panics if n is negative.

🚀 EXAMPLE:

Repeat(123, -1) ⏩ ❌PANIC❌
Repeat(123, 0)  ⏩ []int{}
Repeat(123, 3)  ⏩ []int{123, 123, 123}

💡 HINT: The result slice contains shallow copy of element v. Use RepeatBy with a copier if deep copy is necessary.

func RepeatBy ¶

func RepeatBy[T any](fn func() T, n int) []T

RepeatBy returns a slice with elements generated by calling fn exactly n times. The result is an empty slice if n is 0.

⚠️ WARNING:

• The function panics if n is negative.

🚀 EXAMPLE:

fn := func() *int { v := 123; return &v }
RepeatBy(fn, -1) ⏩ ❌PANIC❌
RepeatBy(fn, 0)  ⏩ []*int{}
RepeatBy(fn, 3)  ⏩ []*int{ &int(123), &int(123), &int(123) } // different addresses!

func Reverse ¶

func Reverse[T any](s []T)

Reverse reverses the elements of slices.

💡 HINT: If you want to reverse in a newly allocated slice, use ReverseClone.

func ReverseClone ¶

func ReverseClone[S ~[]T, T any](s S) S

ReverseClone is variant of Reverse. It clones the original slice before reversing it.

func Shuffle ¶

func Shuffle[T any](s []T)

Shuffle pseudo-randomizes the order of elements.

Shuffle is 2x ~ 40x(parallel) faster than math/rand.Shuffle.

💡 HINT: If you want to shuffle in a newly allocated slice, use ShuffleClone .

func ShuffleClone ¶

func ShuffleClone[S ~[]T, T any](s S) S

ShuffleClone is variant of Shuffle. It clones the original slice before shuffling it.

func Slice ¶

func Slice[S ~[]T, I constraints.Integer, T any](s S, start, end I) S

Slice returns a sub-slice of the slice S that contains the elements starting from the start-th element up to but not including the end-th element "[start:end)". In other words, it is safer replacement of [Slice Expression].

• Slice(s, 0, 3) 🟰 s[:3]
• Slice(s, 1, 3) 🟰 s[1:3]

[Negative index] is supported:

• Slice(s, -3, -1) 🟰 s[len(s)-3:len(s)-1]
• Slice(s, -3, 0) 🟰 s[len(s)-3:] specially, the 0 at the end implies the end slice.

🚀 EXAMPLE:

s := []int{1, 2, 3, 4, 5}
Slice(s, 0, 3)     ⏩ []int{1, 2, 3}
Slice(s, 1, 3)     ⏩ []int{2, 3}
Slice(s, 0, 0)     ⏩ []int{}
Slice(s, 0, 100)   ⏩ []int{1, 2, 3, 4, 5}  // won't PANIC even out of range
Slice(s, 100, 99)  ⏩ []int{}               // won't PANIC even out of range
Slice(s, -3, -1)   ⏩ []int{3, 4}           // equal to Slice(s, 2, 4) and Slice(s, -3, 4)
Slice(s, -1, 0)    ⏩ []int{5}              // specially, the 0 at the end implies the end slice

💡 HINT: This function returns sub-slices of original slice, if you modify the sub-slices, the original slice is modified too. Use SliceClone to prevent this.

func SliceClone ¶

func SliceClone[S ~[]T, I constraints.Integer, T any](s S, start, end I) S

SliceClone is variant of Slice.

func Sort ¶

func Sort[T constraints.Ordered](s []T)

Sort sorts elements of slice in ascending order (from small to large).

🚀 EXAMPLE:

s := []int{1, 3, 2, 4}
Sort(s) ⏩ []int{1, 2, 3, 4}

💡 HINT:

• Sort in a newly allocated slice, use SortClone
• Sort by a custom comparison function, use SortBy
• Sort in descending order, use SortBy + github.com/bytedance/gg/gvalue.Greater

💡 AKA: Order

func SortBy ¶

func SortBy[T any](s []T, less func(T, T) bool)

SortBy sorts elements of slices i with function less.

💡 AKA: OrderBy

func SortClone ¶

func SortClone[S ~[]T, T constraints.Ordered](s S) S

SortClone is variant of Sort. It clones the original slice before sorting it.

func SortCloneBy ¶

func SortCloneBy[S ~[]T, T any](s S, less func(T, T) bool) S

SortCloneBy is variant of function SortBy. It clones the original slice before sorting it.

func StableSortBy ¶

func StableSortBy[T any](s []T, less func(T, T) bool)

StableSortBy is variant of SortBy, it keeps the original order of equal elements when sorting.

func Sum ¶

func Sum[T constraints.Number](s []T) T

Sum returns the arithmetic sum of the elements of slice s.

🚀 EXAMPLE:

Sum([]int{1, 2, 3, 4, 5})     ⏩ 15
Sum([]float64{1, 2, 3, 4, 5}) ⏩ 15.0

⚠️ WARNING: The returned type is still T, it may overflow for smaller types (such as int8, uint8).

func SumBy ¶

func SumBy[T any, N constraints.Number](s []T, f func(T) N) N

SumBy applies function f to each element of slice s, returns the arithmetic sum of function result.

func Take ¶

func Take[S ~[]T, I constraints.Integer, T any](s S, n I) S

Take returns the first n elements of slices s if 0 <= n <= len(s), or slice itself if n > len(s). If -len(s) <= n < 0, returns the last -n elements of slice s, or slice itself if n < -len(s).

🚀 EXAMPLE:

s := []int{1, 2, 3, 4, 5}
Take(s, 0)   ⏩ []int{}
Take(s, 3)   ⏩ []int{1, 2, 3}
Take(s, 10)  ⏩ []int{1, 2, 3, 4, 5}
Take(s, -1)  ⏩ []int{5}
Take(s, -3)  ⏩ []int{3, 4, 5}
Take(s, -10) ⏩ []int{1, 2, 3, 4, 5}

💡 HINT: This function returns sub-slices of original slice, if you modify the sub-slices, the original slice is modified too. Use TakeClone to prevent this.

func TakeClone ¶

func TakeClone[S ~[]T, I constraints.Integer, T any](s S, n I) S

TakeClone is variant of Take.

func ToMap ¶

func ToMap[T, V any, K comparable](s []T, f func(T) (K, V)) map[K]V

ToMap collects elements of slice to map, both map keys and values are produced by mapping function f.

🚀 EXAMPLE:

type Foo struct {
	ID   int
	Name string
}
mapper := func(f Foo) (int, string) { return f.ID, f.Name }
ToMap([]Foo{}, mapper) ⏩ map[int]string{}
s := []Foo{{1, "one"}, {2, "two"}, {3, "three"}}
ToMap(s, mapper)       ⏩ map[int]string{1: "one", 2: "two", 3: "three"}

func ToMapValues ¶

func ToMapValues[T any, K comparable](s []T, f func(T) K) map[K]T

ToMapValues collects elements of slice to values of map, the map keys are produced by mapping function f.

🚀 EXAMPLE:

type Foo struct {
    ID int
}
id := func(f Foo) int { return f.ID }
ToMapValues([]Foo{}, id)                    ⏩ map[int]Foo{}
ToMapValues([]Foo{ {1}, {2}, {1}, {3}}, id) ⏩ map[int]Foo{1: {1}, 2: {2}, 3: {3}}

💡 AKA: Kotlin's associateBy

func TryFilterMap ¶

func TryFilterMap[F, T any](s []F, f func(F) (T, error)) []T

TryFilterMap is a variant of FilterMap that allows function f to fail (return error).

🚀 EXAMPLE:

TryFilterMap([]string{"1", "2", "3"}, strconv.Atoi) ⏩ []int{1, 2, 3}
TryFilterMap([]string{"1", "2", "a"}, strconv.Atoi) ⏩ []int{1, 2}

func TryMap ¶

func TryMap[F, T any](s []F, f func(F) (T, error)) gresult.R[[]T]

TryMap is a variant of Map that allows function f to fail (return error).

🚀 EXAMPLE:

TryMap([]string{"1", "2", "3"}, strconv.Atoi) ⏩ gresult.OK([]int{1, 2, 3})
TryMap([]string{"1", "2", "a"}, strconv.Atoi) ⏩ gresult.Err("strconv.Atoi: parsing \"a\": invalid syntax")
TryMap([]string{}, strconv.Atoi)              ⏩ gresult.OK([]int{})

💡 HINT: Use TryFilterMap if you want to ignore error during mapping.

func TypeAssert ¶

func TypeAssert[To, From any](s []From) []To

TypeAssert converts a slice from type From to type To by type assertion.

🚀 EXAMPLE:

TypeAssert[int]([]any{1, 2, 3, 4})   ⏩ []int{1, 2, 3, 4}
TypeAssert[any]([]int{1, 2, 3, 4})   ⏩ []any{1, 2, 3, 4}
TypeAssert[int64]([]int{1, 2, 3, 4}) ⏩ ❌PANIC❌

⚠️ WARNING:

• This function may ❌PANIC❌. See github.com/bytedance/gg/gvalue.TypeAssert for more details

func Union ¶

func Union[S ~[]T, T comparable](ss ...S) S

Union returns the unions of slices as a newly allocated slices.

💡 NOTE: If the result is an empty set, always return an empty slice instead of nil

🚀 EXAMPLE:

Union([]int{1, 2, 3}, []int{3, 4, 5}) ⏩ []int{1, 2, 3, 4, 5}
Union([]int{1, 2, 3}, []int{})        ⏩ []int{1, 2, 3}
Union([]int{}, []int{3, 4, 5})        ⏩ []int{3, 4, 5}

💡 HINT: if you need a set data structure, use github.com/bytedance/gg/collection/set.

func Uniq ¶

func Uniq[S ~[]T, T comparable](s S) S

Uniq returns the distinct elements of slice. Elements are ordered by their first occurrence.

🚀 EXAMPLE:

Uniq([]int{0, 1, 4, 3, 1, 4}) ⏩ []int{0, 1, 4, 3}

💡 HINT:

• If type is not comparable, use UniqBy.
• If you need duplicate elements, use Dup.

💡 AKA: Distinct, Dedup, Unique

func UniqBy ¶

func UniqBy[S ~[]T, K comparable, T any](s S, f func(T) K) S

UniqBy returns the distinct elements of slice with key function f. The result is a newly allocated slice without duplicate elements.

🚀 EXAMPLE:

type Foo struct{ Value int }
s := []Foo{{0}, {1}, {4}, {3}, {1}, {4}}
UniqBy(s, func(v Foo) int { return v.Value }) ⏩ []Foo{{0}, {1}, {4}, {3}}

💡 AKA: DistinctBy, DedupBy.