goterators

README

Goterators

• Goterators is util library that support aggregate & transforms functions list in Go.

• Iterate:

  • for-each
  • find
  • reduce
  • reduce right
  • filter
  • map
  • flat

• Condition:

  • every
  • some
  • group
  • exist
  • include
  • include some

• Aggregate:

  • count
  • count list
  • mode
  • sum
  • average
  • max
  • min
  • median
  • range
  • mid range

• Support generic functions that fit with all your types.

• The API and functions are inspired by Rust and Javascript.

Requirement

• Go 1.18

Installation

This assumes you already have a working Go environment.

Use Go get to pull goterators for using

go get -u github.com/ledongthuc/goterators

Usage

Import the package goterators into your project before using.

import "github.com/ledongthuc/goterators"

Functions

For-each

• For-each function does the same for in Go. Just another option to loop through items in a list.

goterators.ForEach(list1, func(item int) {
  // handle each item in the list
})

goterators.ForEach(list2, func(item string) {
  // handle each item in the list
})

goterators.ForEach(list3, func(item MyStruct) {
  // handle each item in the list
})

Find

• Find function returns the first element and its index in the list that meets the functional condition. If no element meet the condition function, return the error "Not Found".

matchedInt, index, err := goterators.Find(list, func(item int) bool {
  return item == 1
})

matchedString, index, err := goterators.Find(list, func(item string) bool {
  return item == "searching text"
})

matchedStruct, index, err := goterators.Find(list, func(item MyStruct) bool {
  return item == searchingStruct
})

Reduce

• Similar to Fold Left, Reduce function runs the reducer function on each element of the array. In order, the reduce function passes in the return value from the calculation on the preceding element. The final result of running the reducer across all elements of the array is the return value of the final reducer on the last element.
• Reduce function has 3 parameters:
  • list: source list we want to process.
  • initial value: the previous value that's used in the reducer call of the first element. At this time, previous = initial value, current = first element of the list.
  • reducer function: the function will run on all elements of the source list.
• Can use Reduce() or ReduceLeft() or FoldLeft()

// Sum
total := goterators.Reduce(list, 0, func(previous int, current int, index int, list []int) int {
	return previous + current
})

// Mapping ints to floats
items := goterators.Reduce(testSource, []float64{}, func(previous []float64, current int, index int, list []int) []float64 {
	return append(previous, float64(current))
})

Reduce right

• Similar to Fold Right, Reduce right function run the reducer function on each element of the array, from last to the first element. In order, the reduce function passes in the return value from the calculation on the preceding element. The final result of running the reducer across all elements of the array is the return value of the final reducer on the first element.
• Reduce function has 3 parameters:
  • list: source list we want to process.
  • initial value: the previous value that's used in the reducer call of the last element. At this time, previous = initial value, current = last element of list.
  • reducer function: the function will run on all elements of the source list.
• Can use ReduceRight() or FoldRight()

// Reverse
reversedList := goterators.Reduce(list, []string{}, func(previous []string, current string, index int, list []string) []string {
  return append(list, current)
})

Filter

• Filter function return items that pass the filter function.

filteredItems, err := goterators.Filter(list, func(item int) bool {
  return item % 2 == 0
})

filteredItems, err := goterators.Filter(list, func(item string) bool {
  return item.Contains("ValidWord")
})

filteredItems, err := goterators.Filter(list, func(item MyStruct) bool {
  return item.Valid()
})

Map

• Map function converts items in the list to the output list.

mappedItems := goterators.Map(testSource, func(item int64) float64 {
  return float64(item)
})

prices := goterators.Map(testSource, func(item Order) Price {
  return item.GetPrice()
})

Every

• Every function checks all elements in the list with condition function. If it's yes return true; otherwise, return false.

valid := goterators.Every(list, func(item int) bool { item % 2 == 0 }) 

valid := goterators.Every(list, func(item string) bool { len(item) < 20 }) 

Some

• Some function check at least one element in the list meet the condition; return true, or return false if all elements don't meet the condition.

valid := goterators.Some(list, func(item int) bool { item % 2 == 0 }) 

valid := goterators.Some(list, func(item string) bool { len(item) < 20 }) 

Group

• Group groups elements into the nested level. Use a build-group function to define group type.

groups := goterators.Group(list, func(item Product) groupKey {
   return item.ComposeGroupKey()
}) // Group contains [ [ Product1, Product2, Product3 ], [ Product4, Product5 ] ]

Flat

• Flat returns a new array with all sub-array elements concatenated with 1 level depth.

output := goterators.Flat([][]int{{1,2}, {3}}) // output = {1,2,3}

Exist

• Exist function checks the existence of an element in the list.

matchedInt, err := goterators.Exist(list, 1)

matchedString, err := goterators.Exist(list, "searching string")

matchedStruct, err := goterators.Exist(list, SearchingStruct)

Include

• Include check if source list contains all items from the sub-list item.

list := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20}
subList := []int{8, 15, 19}
result := goterators.Include(list, subList)
fmt.Println("Include: ", result)

Include some

• IncludeSome check if source list contains any items from the sub-list item.

list := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20}
subList := []int{8, 15, 19}
result := goterators.IncludeSome(list, subList)
fmt.Println("IncludeSome: ", result)

Count

• Count returns number of checking item exists in source list

testSource := []int{1, 1, 1, 2, 2, 3, 3, 3, 3, 4}
fmt.Println("Count: ", goterators.Count(testSource, 3))

Count list

• CountList returns sub-list counter of input sub-list that want to count from source list.

testSource := []int{1, 1, 1, 2, 2, 3, 3, 3, 3, 4}
fmt.Println("CountList: ", goterators.CountList(testSource, []int{1, 1, 2, 3, 5}))

Mode

• Mode return a value that appears most often in the source list.

testSource := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20}
mostOftenValue, counter := goterators.Mode(testSource)
fmt.Println("Mode: ", mostOftenValue, counter)

Sum

• Sum plus all item from source list

testSource := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20}
fmt.Println("Sum: ", goterators.Sum(testSource))

Average

• Average sum of all the source list divided by the total number of source list
• We can use Average() or Mean()

testSource := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20}
fmt.Println("Average: ", goterators.Average(testSource))
fmt.Println("Mean: ", goterators.Mean(testSource))

Max

• Max find largest value from source list

testSource := []int{20, 17, 9, 21, 18, 3, 11, 5}
result, err := goterators.Max(testSource)
fmt.Println("Max: ", result)

Min

• Min find smallest value from source list

testSource := []int{20, 17, 9, 21, 18, 3, 11, 5}
result, _ := goterators.Min(testSource)
fmt.Println("Min: ", result)

Median

• Median return a value in the middle of an ordered source list. If number of item in source is even, return right item. Make sure source list are sorted

testSource := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20}
median, index, _ := goterators.Median(testSource)
fmt.Println("Median: ", median, ", with index: ", index)

Range

• Range return max - min

testSource := []int{20, 17, 9, 21, 18, 3, 11, 5}
fmt.Println("Range: ", goterators.Range(testSource))

Mid range

• MidRange return (max + min) / 2

testSource := []int{20, 17, 9, 21, 18, 3, 11, 5}
fmt.Println("Range: ", goterators.Range(testSource))

License

MIT

Contribution

All your contributions to project and make it better, they are welcome. Feel free to reach me https://thuc.space or create an issue to start it.

Thanks! 🙌

• Viet Nam We Build group https://webuild.community for discussion

Documentation

Overview

Package goterators provides utility functions that support aggregate & transforms list in Go.

Index

• Variables
• func Average[T Number](source []T) float64
• func Count[T constraints.Ordered](source []T, checkedItem T) (result int)
• func CountList[T constraints.Ordered](source []T, checkedItems []T) []int
• func Every[T comparable](source []T, conditionFunc func(item T) bool) bool
• func Exist[T comparable](source []T, checkingItem T) bool
• func Filter[T any](source []T, filteredFunc func(item T) bool) (output []T)
• func Find[T any](source []T, matchedItemFunc func(item T) bool) (t T, index int, err error)
• func Flat[T any](source [][]T) []T
• func FoldLeft[T1 any, T2 any](source []T1, initialValue T2, ...) T2
• func FoldRight[T1 any, T2 any](source []T1, initialValue T2, ...) T2
• func ForEach[T any](source []T, handler func(item T))
• func Group[T any, G comparable](source []T, buildGroup func(item T) G) [][]T
• func Include[T comparable](source, subList []T) bool
• func IncludeSome[T comparable](source, subList []T) bool
• func Map[T1 any, T2 any](source []T1, mappingFunc func(item T1) T2) (output []T2)
• func Max[T constraints.Ordered](source []T) (result T, err error)
• func Mean[T Number](source []T) float64
• func Median[T any](source []T) (T, int, error)
• func MidRange[T Number](source []T) float64
• func Min[T constraints.Ordered](source []T) (result T, err error)
• func Mode[T constraints.Ordered](source []T) (T, int)
• func Range[T Number](source []T) T
• func Reduce[T1 any, T2 any](source []T1, initialValue T2, ...) T2
• func ReduceLeft[T1 any, T2 any](source []T1, initialValue T2, ...) T2
• func ReduceRight[T1 any, T2 any](source []T1, initialValue T2, ...) T2
• func Some[T comparable](source []T, conditionFunc func(item T) bool) bool
• func Sum[T Number](source []T) (result T)
• type Number

Examples

• Average
• Count
• CountList
• Every
• Exist
• Filter
• Find
• Flat
• ForEach
• Group
• Include
• IncludeSome
• Map
• Max
• Median
• MidRange
• Min
• Mode
• Range
• Reduce
• ReduceRight
• Some
• Sum

Variables

var (
	// ErrNotFound is used in functions that need to find any items in the list but are not found.
	ErrNotFound = fmt.Errorf("not found")
)

Functions

func Average

func Average[T Number](source []T) float64

Average sum of all the source list divided by the total number of source list

Example

testSource := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20}
fmt.Println("Average: ", Average(testSource))
fmt.Println("Mean: ", Mean(testSource))

func Count

func Count[T constraints.Ordered](source []T, checkedItem T) (result int)

Count returns number of checking item exists in source list

Example

testSource := []int{1, 1, 1, 2, 2, 3, 3, 3, 3, 4}
fmt.Println("Count: ", Count(testSource, 3))

func CountList

func CountList[T constraints.Ordered](source []T, checkedItems []T) []int

CountList returns sub-list counter of input sub-list that want to count from source list.

Example

testSource := []int{1, 1, 1, 2, 2, 3, 3, 3, 3, 4}
fmt.Println("CountList: ", CountList(testSource, []int{1, 1, 2, 3, 5}))

func Every

func Every[T comparable](source []T, conditionFunc func(item T) bool) bool

Every checks all elements in the list with condition function. If it's yes return true; otherwise, return false.

Example

testSource := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20}
everyValid := Every(testSource, func(item int) bool { return item <= 20 })
fmt.Println("Every: ", everyValid)

func Exist

func Exist[T comparable](source []T, checkingItem T) bool

Exist checks the existence of an element in the list.

Example

testSource := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20}
fmt.Println("Exist: ", Exist(testSource, 15))

func Filter

func Filter[T any](source []T, filteredFunc func(item T) bool) (output []T)

Filter return items that pass the filter function.

Example

testSource := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20}
filteredItems := Filter(testSource, func(item int) bool {
	return item%2 == 0
})
fmt.Println("Filtered: ", filteredItems)

func Find

func Find[T any](source []T, matchedItemFunc func(item T) bool) (t T, index int, err error)

Find returns the first element and its index in the list that meets the functional condition. If no element meet the condition function, return the error "Not Found".

Example

testSource := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20}
firstFoundItem, index, _ := Find(testSource, func(item int) bool {
	return item%10 == 0
})
fmt.Println("Find: ", firstFoundItem, index)

func Flat

func Flat[T any](source [][]T) []T

Flat returns a new array with all sub-array elements concatenated with 1 level depth.

Example

testSource := [][]int{{1, 2, 3, 4}, {5, 6, 7, 8, 9, 10, 11}, {12, 13, 14, 15, 16, 17, 18, 19}, {20}, {}}
items := Flat(testSource)
fmt.Println("Flat: ", items)

func FoldLeft

func FoldLeft[T1 any, T2 any](source []T1, initialValue T2, reducer func(previousValue T2, currentValue T1, currentIndex int, list []T1) T2) T2

FoldLeft is same with Reduce()

func FoldRight

func FoldRight[T1 any, T2 any](source []T1, initialValue T2, reducer func(previousValue T2, currentValue T1, currentIndex int, list []T1) T2) T2

FoldRight is same with Reduce()

func ForEach

func ForEach[T any](source []T, handler func(item T))

ForEach does the same `for` in Go. Just another option to loop through items in a list.

Example

testSource := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20}
ForEach(testSource, func(item int) {
	fmt.Println("ForEach: ", item)
})

func Group

func Group[T any, G comparable](source []T, buildGroup func(item T) G) [][]T

Group groups elements into the nested level. Use a build-group function to define group type.

Example

testSource := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20}
groups := Group(testSource, func(item int) int {
	return item % 2
})
fmt.Println("Group: ", groups)

func Include

func Include[T comparable](source, subList []T) bool

Include check if source list contains all items from the sub-list item.

Example

testSource := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20}
subList := []int{8, 15, 19}
result := Include(testSource, subList)
fmt.Println("Include: ", result)

func IncludeSome

func IncludeSome[T comparable](source, subList []T) bool

IncludeSome check if source list contains any items from the sub-list item.

Example

testSource := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20}
subList := []int{8, 15, 19}
result := IncludeSome(testSource, subList)
fmt.Println("IncludeSome: ", result)

func Map

func Map[T1 any, T2 any](source []T1, mappingFunc func(item T1) T2) (output []T2)

Map function converts items in the list to the output list.

Example

testSource := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20}
mappedItems := Map(testSource, func(item int) string {
	return fmt.Sprintf("Item-%d", item)
})
fmt.Println("Map: ", mappedItems)

func Max

func Max[T constraints.Ordered](source []T) (result T, err error)

Max find largest value from source list

Example

testSource := []int{20, 17, 9, 21, 18, 3, 11, 5}
result, _ := Max(testSource)
fmt.Println("Max: ", result)

func Mean

func Mean[T Number](source []T) float64

func Median

func Median[T any](source []T) (T, int, error)

Median return a value in the middle of an ordered source list. If number of item in source is even, return right item. Make sure source list are sorted

Example

testSource := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20}
median, index, _ := Median(testSource)
fmt.Println("Median: ", median, ", with index: ", index)

func MidRange

func MidRange[T Number](source []T) float64

MidRange return (max + min) / 2

Example

testSource := []int{20, 17, 9, 21, 18, 3, 11, 5}
fmt.Println("MidRange: ", MidRange(testSource))

func Min

func Min[T constraints.Ordered](source []T) (result T, err error)

Min find smallest value from source list

Example

testSource := []int{20, 17, 9, 21, 18, 3, 11, 5}
result, _ := Min(testSource)
fmt.Println("Min: ", result)

func Mode

func Mode[T constraints.Ordered](source []T) (T, int)

Mode return a value that appears most often in the source list.

Example

testSource := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20}
mostOftenValue, counter := Mode(testSource)
fmt.Println("Mode: ", mostOftenValue, counter)

func Range

func Range[T Number](source []T) T

Range return max - min

Example

testSource := []int{20, 17, 9, 21, 18, 3, 11, 5}
fmt.Println("Range: ", Range(testSource))

func Reduce

func Reduce[T1 any, T2 any](source []T1, initialValue T2, reducer func(previousValue T2, currentValue T1, currentIndex int, list []T1) T2) T2

Reduce runs the reducer function on each element of the array. In order, the reduce function passes in the return value from the calculation on the preceding element. The final result of running the reducer across all elements of the array is the return value of the final reducer on the last element. - list paramerter: source list we want to process. - initial value paramerter: the previous value that's used in the reducer call of the first element. At this time, previous = initial value, current = first element of the list. - reducer function paramerter: the function will run on all elements of the source list.

Example

testSource := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20}
result := Reduce(testSource, 0, func(previous int, current int, index int, list []int) int {
	return previous + current
})
fmt.Println("Reduce: ", result)

func ReduceLeft

func ReduceLeft[T1 any, T2 any](source []T1, initialValue T2, reducer func(previousValue T2, currentValue T1, currentIndex int, list []T1) T2) T2

ReduceLeft is same with Reduce()

func ReduceRight

func ReduceRight[T1 any, T2 any](source []T1, initialValue T2, reducer func(previousValue T2, currentValue T1, currentIndex int, list []T1) T2) T2

ReduceRight runs the reducer function on each element of the array, from last to the first element. In order, the reduce function passes in the return value from the calculation on the preceding element. The final result of running the reducer across all elements of the array is the return value of the final reducer on the first element.

- list parameter: source list we want to process. - initial value parameter: the previous value that's used in the reducer call of the last element. At this time, previous = initial value, current = last element of list. - reducer function parameter: the function will run on all elements of the source list.

Example

testSource := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20}
result := ReduceRight(testSource, []int{}, func(previous []int, current int, index int, list []int) []int {
	return append(previous, current)
})
fmt.Println("ReduceRight: ", result)

func Some

func Some[T comparable](source []T, conditionFunc func(item T) bool) bool

Some checks at least one element in the list meet the condition; return true, or return false if all elements don't meet the condition.

Example

testSource := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20}
result := Some(testSource, func(item int) bool {
	return item%2 == 0
})
fmt.Println("Some: ", result)

func Sum

func Sum[T Number](source []T) (result T)

Sum plus all item from source list

Example

testSource := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20}
fmt.Println("Sum: ", Sum(testSource))

Types

type Number

type Number interface {
	constraints.Integer | constraints.Float
}