Documentation
¶
Overview ¶
Package iterator provides the Iterator type which exposes an easily chainable, struct variant of the functional iterator API provided by the iter module.
Index ¶
- type Iterator
- func (i *Iterator[T]) AdvanceBy(n int) *Iterator[T]
- func (i *Iterator[T]) All(fn iter.Predicate[T]) bool
- func (i *Iterator[T]) Any(fn iter.Predicate[T]) bool
- func (i *Iterator[T]) Chain(other iter.Interface[T]) *Iterator[T]
- func (i *Iterator[T]) CollectChan(ctx context.Context, buffer int) <-chan T
- func (i *Iterator[T]) CollectSlice() []T
- func (i *Iterator[T]) Count() int
- func (i *Iterator[T]) Filter(fn iter.Predicate[T]) *Iterator[T]
- func (i *Iterator[T]) Find(fn iter.Predicate[T]) (T, bool)
- func (i *Iterator[T]) ForEach(fn func(*T))
- func (i *Iterator[T]) Inspect(fn iter.InspectFunc[T]) *Iterator[T]
- func (i *Iterator[T]) Interleave(other iter.Interface[T]) *Iterator[T]
- func (i *Iterator[T]) Intersperse(sep T) *Iterator[T]
- func (i *Iterator[T]) Last() (last T)
- func (i *Iterator[T]) Next() (T, bool)
- func (i *Iterator[T]) Nth(n int) (value T, ok bool)
- func (i *Iterator[T]) Partition(fn iter.Predicate[T]) ([]T, []T)
- func (i *Iterator[T]) Peekable() iter.Peekable[T]
- func (i *Iterator[T]) SizeHint() (int64, oxide.Option[int64])
- func (i *Iterator[T]) Skip(n int) *Iterator[T]
- func (i *Iterator[T]) SkipWhile(fn iter.Predicate[T]) *Iterator[T]
- func (i *Iterator[T]) Sorted(lessFunc func(i, j T) bool) *Iterator[T]
- func (i *Iterator[T]) StepBy(step int) *Iterator[T]
- func (i *Iterator[T]) Take(n int) *Iterator[T]
- func (i *Iterator[T]) TakeWhile(fn iter.Predicate[T]) *Iterator[T]
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Iterator ¶
type Iterator[T any] struct { // contains filtered or unexported fields }
An Iterator provides you a standard API for iterating over collections of data.
Example ¶
package main
import (
"fmt"
"github.com/moogar0880/oxide/iterator"
)
func main() {
{
// Generate an iterator from a pre-defined slice.
slice := iterator.FromSlice([]int{0, 1, 2, 3, 4, 5, 6, 7, 8, 9}).
// Use the Inspect method to debug values at any point in the
// iterators chain of operations.
Inspect(func(i *int) {
fmt.Printf("inspected: %d\n", *i)
}).
// Only consume every other value after the first value.
StepBy(3).
// Drop any values which are not even.
Filter(func(i *int) bool {
return *i%2 == 0
}).
// Inject a value of 100 between every pair of values yielded by
// the iterator.
Intersperse(100).
// Use the Inspect method one last time to debug the output values
// of our iteration.
Inspect(func(i *int) {
fmt.Printf("inspected: %d\n", *i)
}).
// Collect the results back into slice.
CollectSlice()
fmt.Println(slice)
}
}
Output: inspected: 0 inspected: 0 inspected: 1 inspected: 2 inspected: 3 inspected: 4 inspected: 5 inspected: 6 inspected: 100 inspected: 6 inspected: 7 inspected: 8 inspected: 9 [0 100 6]
func FromMap ¶
func FromMap[K comparable, V any](data map[K]V) *Iterator[iter.MapEntry[K, V]]
FromMap returns a new Iterator instance which wraps the provided maps and yields instances of the iter.MapEntry type.
func NewIterator ¶
NewIterator returns a new Iterator instance which wraps the provided iter.Interface.
func (*Iterator[T]) AdvanceBy ¶
AdvanceBy advances the iterator by n values.
Example ¶
package main
import (
"fmt"
"github.com/moogar0880/oxide/iterator"
)
func main() {
{
// Define an iterator over our pre-defined data.
iter := iterator.FromSlice([]int{0, 1, 2, 3, 4, 5, 6, 7, 8, 9})
// Use iter.AdvanceBy to advance the state of our iterator.
iter = iter.AdvanceBy(5)
// Use iter.CollectSlice to consume our iterator into a slice of the
// values yielded by the iterator.
slice := iter.CollectSlice()
fmt.Println(slice)
}
}
Output: [5 6 7 8 9]
func (*Iterator[T]) All ¶
All consumes the Iterator, returning a boolean value which indicates whether all the values yielded by the iterator satisfied the provided predicate.
Example ¶
package main
import (
"fmt"
"github.com/moogar0880/oxide/iterator"
)
func main() {
{
// Define an iterator over our pre-defined data.
iter := iterator.FromSlice([]int{-5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5})
isNegative := func(i *int) bool { return *i < 0 }
fmt.Println(iter.All(isNegative))
}
}
Output: false
func (*Iterator[T]) Any ¶
Any consumes the Iterator, returning a boolean value which indicates whether any of the values yielded by the iterator satisfied the provided predicate.
Example ¶
package main
import (
"fmt"
"github.com/moogar0880/oxide/iterator"
)
func main() {
{
// Define an iterator over our pre-defined data.
iter := iterator.FromSlice([]int{-5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5})
isNegative := func(i *int) bool { return *i < 0 }
fmt.Println(iter.Any(isNegative))
}
}
Output: true
func (*Iterator[T]) Chain ¶
Chain returns an Iterator which iterates over both of the provided iterators in the order in which they are provided.
Example ¶
package main
import (
"fmt"
"github.com/moogar0880/oxide/iterator"
)
func main() {
{
// Define an iterator over our pre-defined data.
i1 := iterator.FromSlice([]int{-5, -4, -3, -2, -1})
i2 := iterator.FromSlice([]int{0, 1, 2, 3, 4, 5})
slice := i1.Chain(i2).CollectSlice()
fmt.Println(slice)
}
}
Output: [-5 -4 -3 -2 -1 0 1 2 3 4 5]
func (*Iterator[T]) CollectChan ¶
CollectChan collects the Iterator into a channel of type T.
func (*Iterator[T]) CollectSlice ¶
func (i *Iterator[T]) CollectSlice() []T
CollectSlice collects the Iterator into a slice of type T.
func (*Iterator[T]) Count ¶
Count consumes the Iterator and returns the count of all items in the iterator.
Example ¶
package main
import (
"fmt"
"github.com/moogar0880/oxide/iterator"
)
func main() {
{
// Define an iterator over our pre-defined data.
iter := iterator.FromSlice([]int{0, 1, 2, 3, 4, 5, 6, 7, 8, 9})
fmt.Println(iter.Count())
}
}
Output: 10
func (*Iterator[T]) Filter ¶
Filter returns an Iterator which will only yield elements for which satisfies the provided Predicate.
func (*Iterator[T]) Find ¶
Find searches the Iterator for an element that satisfies the provided predicate.
Example ¶
package main
import (
"fmt"
"github.com/moogar0880/oxide/iterator"
)
func main() {
{
// Define an iterator over our pre-defined data.
iter := iterator.FromSlice([]int{0, 1, 2, 3, 4, 5, 6, 7, 8, 9})
value, found := iter.Find(func(i *int) bool {
return *i == 7
})
fmt.Println(value, found)
}
}
Output: 7 true
func (*Iterator[T]) ForEach ¶
func (i *Iterator[T]) ForEach(fn func(*T))
ForEach consumes the Iterator and calls the provided closure on each element.
Example ¶
package main
import (
"fmt"
"github.com/moogar0880/oxide/iterator"
)
func main() {
{
// Define an iterator over our pre-defined data.
iter := iterator.FromSlice([]int{0, 1, 2, 3, 4, 5, 6, 7, 8, 9})
fmt.Printf("[")
iter.ForEach(func(i *int) {
fmt.Printf("%d ", *i)
})
fmt.Printf("]\n")
}
}
Output: [0 1 2 3 4 5 6 7 8 9 ]
func (*Iterator[T]) Inspect ¶
func (i *Iterator[T]) Inspect(fn iter.InspectFunc[T]) *Iterator[T]
Inspect returns an Iterator which calls the specified closure on each element yielded by the iterator until the iterator is exhausted.
Example ¶
package main
import (
"fmt"
"github.com/moogar0880/oxide/iterator"
)
func main() {
{
// Define an iterator over our pre-defined data.
iter := iterator.FromSlice([]int{0, 1, 2, 3, 4, 5})
handler := func(i *int) { fmt.Println(*i) }
slice := iter.Inspect(handler).CollectSlice()
fmt.Println(slice)
}
}
Output: 0 1 2 3 4 5 [0 1 2 3 4 5]
func (*Iterator[T]) Interleave ¶
Interleave returns a new Iterator which alternates elements from two iterators until both Iterators are fully consumed.
func (*Iterator[T]) Intersperse ¶
Intersperse returns a new Iterator which injects a copy of the provided separator between items yielded by the Iterator.
Example ¶
package main
import (
"fmt"
"github.com/moogar0880/oxide/iterator"
)
func main() {
{
// Define an iterator over our pre-defined data.
iter := iterator.FromSlice([]int{0, 1, 2, 3, 4, 5})
slice := iter.Intersperse(100).CollectSlice()
fmt.Println(slice)
}
}
Output: [0 100 1 100 2 100 3 100 4 100 5]
func (*Iterator[T]) Last ¶
func (i *Iterator[T]) Last() (last T)
Last consumes the Iterator and returns the last element.
Example ¶
package main
import (
"fmt"
"github.com/moogar0880/oxide/iterator"
)
func main() {
{
// Define an iterator over our pre-defined data.
iter := iterator.FromSlice([]int{0, 1, 2, 3, 4, 5, 6, 7, 8, 9})
// Use iter.Last to get the last elemnt from the iterator.
fmt.Println(iter.Last())
}
}
Output: 9
func (*Iterator[T]) Next ¶
Next implements iter.Interface and allows Iterator[T] to be used as a bare iterator.
func (*Iterator[T]) Nth ¶
Nth returns the nth item in the Iterator.
Example ¶
package main
import (
"fmt"
"github.com/moogar0880/oxide/iterator"
)
func main() {
{
// Define an iterator over our pre-defined data.
iter := iterator.FromSlice([]int{0, 1, 2, 3, 4, 5, 6, 7, 8, 9})
value, ok := iter.Nth(5)
fmt.Println(value, ok)
}
}
Output: 5 true
func (*Iterator[T]) Partition ¶
Partition consumes the Iterator and produces two collections: 1: One collection contains all values yielded by the iterator for which the provided Predicate is satisfied (returned true) 2: The other collection contains all values yielded by the iterator for which the Predicate was not satisfied (returned false).
Example ¶
package main
import (
"fmt"
"github.com/moogar0880/oxide/iterator"
)
func main() {
{
// Define an iterator over our pre-defined data.
iter := iterator.FromSlice([]int{-5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5})
isNegative := func(i *int) bool { return *i < 0 }
neg, pos := iter.Partition(isNegative)
fmt.Println(neg, pos)
}
}
Output: [-5 -4 -3 -2 -1] [0 1 2 3 4 5]
func (*Iterator[T]) Peekable ¶
Peekable returns a new iter.Peekable iterator which, in addition to the standard Next() method, also implements Peek() which allows callers to view the next value that an iterator would yield, without consuming it.
Example ¶
package main
import (
"fmt"
"github.com/moogar0880/oxide/iterator"
)
func main() {
{
// Define an iterator over our pre-defined data.
iter := iterator.FromSlice([]int{-5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5})
peekable := iter.Peekable()
maybeValue := peekable.Peek()
fmt.Println(maybeValue.Unpack())
value, ok := peekable.Next()
fmt.Println(value, ok)
}
}
Output: -5 true -5 true
func (*Iterator[T]) SizeHint ¶
SizeHint implements the iter.SizeHinter interface and attempts to provide size hint information about the Iterator.
Note: not all Iterator implements or can implement SizeHint, so ensure that any logic which uses these values handles all possible variations of the returned lower and upper bounds.
func (*Iterator[T]) Skip ¶
Skip returns an Iterator which skips over the first n elements. The remaining elements are all yielded as normal.
Example ¶
package main
import (
"fmt"
"github.com/moogar0880/oxide/iterator"
)
func main() {
{
// Define an iterator over our pre-defined data.
iter := iterator.FromSlice([]int{0, 1, 2, 3, 4, 5})
slice := iter.Skip(3).CollectSlice()
fmt.Println(slice)
}
}
Output: [3 4 5]
func (*Iterator[T]) SkipWhile ¶
SkipWhile returns an Iterator which skips elements for as long as the provided predicate is satisfied. Once a false value is returned by the predicate all values will be yielded by the iterator as normal.
Example ¶
package main
import (
"fmt"
"github.com/moogar0880/oxide/iterator"
)
func main() {
{
// Define an iterator over our pre-defined data.
iter := iterator.FromSlice([]int{-5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5})
isNegative := func(i *int) bool { return *i < 0 }
slice := iter.SkipWhile(isNegative).CollectSlice()
fmt.Println(slice)
}
}
Output: [0 1 2 3 4 5]
func (*Iterator[T]) Sorted ¶
Sorted returns a new Iterator in which all elements are sorted according to the provided sorting function.
func (*Iterator[T]) StepBy ¶
StepBy returns a new Iterator which starts at this iterators next value, but which steps by the specified number of items on each subsequent iteration.
Example ¶
package main
import (
"fmt"
"github.com/moogar0880/oxide/iterator"
)
func main() {
{
// Define an iterator over our pre-defined data.
iter := iterator.FromSlice([]int{0, 1, 2, 3, 4, 5, 6, 7, 8, 9})
// Use iter.StepBy to ensure our iterator will have a configured step.
iter = iter.StepBy(3)
// Use iter.CollectSlice to consume our iterator into a slice of the
// values yielded by the iterator.
slice := iter.CollectSlice()
fmt.Println(slice)
}
}
Output: [0 3 6 9]
func (*Iterator[T]) Take ¶
Take returns an Iterator which yields the first n elements, or all elements if the iterator contains fewer than n elements, and then ceases to yield values.
Example ¶
package main
import (
"fmt"
"github.com/moogar0880/oxide/iterator"
)
func main() {
{
// Define an iterator over our pre-defined data.
iter := iterator.FromSlice([]int{0, 1, 2, 3, 4, 5})
slice := iter.Take(3).CollectSlice()
fmt.Println(slice)
}
}
Output: [0 1 2]
func (*Iterator[T]) TakeWhile ¶
TakeWhile returns an Iterator which yields elements for as long as the provided predicate is satisfied. Once a false value is returned by the predicate the iterator will cease to yield further values.
Example ¶
package main
import (
"fmt"
"github.com/moogar0880/oxide/iterator"
)
func main() {
{
// Define an iterator over our pre-defined data.
iter := iterator.FromSlice([]int{-5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5})
isNegative := func(i *int) bool { return *i < 0 }
slice := iter.TakeWhile(isNegative).CollectSlice()
fmt.Println(slice)
}
}
Output: [-5 -4 -3 -2 -1]
Source Files