iter

func (ChunkResult[T]) IsErr ¶ added in v1.10.0

func (r ChunkResult[T]) IsErr() bool

IsErr returns true if the result is an error.

func (ChunkResult[T]) IsOk ¶ added in v1.10.0

func (r ChunkResult[T]) IsOk() bool

IsOk returns true if the result is ok.

func (ChunkResult[T]) Unwrap ¶ added in v1.10.0

func (r ChunkResult[T]) Unwrap() T

Unwrap returns the contained T value.

func (ChunkResult[T]) UnwrapErr ¶ added in v1.10.0

func (r ChunkResult[T]) UnwrapErr() T

UnwrapErr returns the contained error T value.

func (DoubleEndedIterator[T]) AdvanceBackBy ¶ added in v1.7.0

func (de DoubleEndedIterator[T]) AdvanceBackBy(n uint) gust.VoidResult

AdvanceBackBy advances the iterator from the back by n elements.

AdvanceBackBy is the reverse version of AdvanceBy. This method will eagerly skip n elements starting from the back by calling NextBack up to n times until None is encountered.

AdvanceBackBy(n) will return Ok[Void](nil) if the iterator successfully advances by n elements, or Err[Void](k) with value k if None is encountered, where k is remaining number of steps that could not be advanced because the iterator ran out. If iter is empty and n is non-zero, then this returns Err[Void](n). Otherwise, k is always less than n.

Calling AdvanceBackBy(0) can do meaningful work.

Examples ¶

var a = []int{3, 4, 5, 6}
var deIter = FromSlice(a).MustToDoubleEnded()
assert.True(t, deIter.AdvanceBackBy(2).IsOk())
assert.Equal(t, gust.Some(4), deIter.NextBack())
assert.True(t, deIter.AdvanceBackBy(0).IsOk())
assert.True(t, deIter.AdvanceBackBy(100).IsErr())

func (DoubleEndedIterator[T]) NextBack ¶ added in v1.7.0

func (de DoubleEndedIterator[T]) NextBack() gust.Option[T]

NextBack removes and returns an element from the end of the iterator.

Returns None when there are no more elements.

Examples ¶

var numbers = []int{1, 2, 3, 4, 5, 6}
var deIter = FromSlice(numbers).MustToDoubleEnded()
assert.Equal(t, gust.Some(6), deIter.NextBack())
assert.Equal(t, gust.Some(5), deIter.NextBack())
assert.Equal(t, gust.Some(4), deIter.NextBack())
assert.Equal(t, gust.Some(3), deIter.NextBack())
assert.Equal(t, gust.Some(2), deIter.NextBack())
assert.Equal(t, gust.Some(1), deIter.NextBack())
assert.Equal(t, gust.None[int](), deIter.NextBack())

func (DoubleEndedIterator[T]) NthBack ¶ added in v1.7.0

func (de DoubleEndedIterator[T]) NthBack(n uint) gust.Option[T]

NthBack returns the nth element from the end of the iterator.

This is essentially the reversed version of Nth(). Although like most indexing operations, the count starts from zero, so NthBack(0) returns the first value from the end, NthBack(1) the second, and so on.

Note that all elements between the end and the returned element will be consumed, including the returned element. This also means that calling NthBack(0) multiple times on the same iterator will return different elements.

NthBack() will return None if n is greater than or equal to the length of the iterator.

Examples ¶

var a = []int{1, 2, 3}
var deIter = FromSlice(a).MustToDoubleEnded()
assert.Equal(t, gust.Some(1), deIter.NthBack(2))
assert.Equal(t, gust.Some(2), deIter.NthBack(1))
assert.Equal(t, gust.Some(3), deIter.NthBack(0))
assert.Equal(t, gust.None[int](), deIter.NthBack(10))

func (DoubleEndedIterator[T]) Remaining ¶ added in v1.8.0

func (de DoubleEndedIterator[T]) Remaining() uint

Remaining returns the number of elements remaining in the iterator.

Examples ¶

var numbers = []int{1, 2, 3, 4, 5, 6} var deIter = FromSlice(numbers).MustToDoubleEnded() assert.Equal(t, uint(6), deIter.Remaining()) deIter.Next() assert.Equal(t, uint(5), deIter.Remaining()) deIter.NextBack() assert.Equal(t, uint(4), deIter.Remaining()) deIter.NextBack() assert.Equal(t, uint(3), deIter.Remaining()) deIter.NextBack() assert.Equal(t, uint(2), deIter.Remaining()) deIter.NextBack() assert.Equal(t, uint(1), deIter.Remaining()) deIter.NextBack() assert.Equal(t, uint(0), deIter.Remaining()) deIter.NextBack() assert.Equal(t, uint(0), deIter.Remaining())

func (DoubleEndedIterator[T]) Rfind ¶ added in v1.7.0

func (de DoubleEndedIterator[T]) Rfind(predicate func(T) bool) gust.Option[T]

Rfind searches for an element of an iterator from the back that satisfies a predicate.

Rfind() takes a closure that returns true or false. It applies this closure to each element of the iterator, starting at the end, and if any of them return true, then Rfind() returns Some(element). If they all return false, it returns None.

Rfind() is short-circuiting; in other words, it will stop processing as soon as the closure returns true.

Examples ¶

var a = []int{1, 2, 3}
var deIter = FromSlice(a).MustToDoubleEnded()
assert.Equal(t, gust.Some(2), deIter.Rfind(func(x int) bool { return x == 2 }))

var b = []int{1, 2, 3}
var deIter2 = FromSlice(b).MustToDoubleEnded()
assert.Equal(t, gust.None[int](), deIter2.Rfind(func(x int) bool { return x == 5 }))

func (DoubleEndedIterator[T]) Rfold ¶ added in v1.7.0

func (de DoubleEndedIterator[T]) Rfold(init T, f func(T, T) T) T

Rfold folds every element into an accumulator by applying an operation, starting from the back.

This is the reverse version of Fold(): it takes elements starting from the back of the iterator.

Rfold() takes two arguments: an initial value, and a closure with two arguments: an 'accumulator', and an element. The closure returns the value that the accumulator should have for the next iteration.

The initial value is the value the accumulator will have on the first call.

After applying this closure to every element of the iterator, Rfold() returns the accumulator.

Note: Rfold() combines elements in a *right-associative* fashion. For associative operators like +, the order the elements are combined in is not important, but for non-associative operators like - the order will affect the final result.

Examples ¶

var a = []int{1, 2, 3}
var deIter = FromSlice(a).MustToDoubleEnded()
var sum = deIter.Rfold(0, func(acc int, x int) int { return acc + x })
assert.Equal(t, 6, sum)

func (DoubleEndedIterator[T]) TryRfold ¶ added in v1.7.0

func (de DoubleEndedIterator[T]) TryRfold(init T, f func(T, T) gust.Result[T]) gust.Result[T]

TryRfold is the reverse version of TryFold: it takes elements starting from the back of the iterator.

Examples ¶

var a = []string{"1", "2", "3"}
var deIter = FromSlice(a).MustToDoubleEnded()
var sum = deIter.TryRfold(0, func(acc int, s string) gust.Result[int] {
	if v, err := strconv.Atoi(s); err == nil {
		return gust.Ok(acc + v)
	}
	return gust.Err[int](err)
})
assert.True(t, sum.IsOk())
assert.Equal(t, 6, sum.Unwrap())

func (DoubleEndedIterator[T]) XRfold ¶ added in v1.7.0

func (de DoubleEndedIterator[T]) XRfold(init any, f func(any, T) any) any

XRfold folds every element into an accumulator by applying an operation, starting from the back (any version).

This is the reverse version of Fold(): it takes elements starting from the back of the iterator.

Examples ¶

var a = []int{1, 2, 3}
var deIter = FromSlice(a).MustToDoubleEnded()
var deIter = iter.MustToDoubleEnded()
var sum = deIter.XRfold(0, func(acc any, x int) any { return acc.(int) + x })
assert.Equal(t, 6, sum)

func (DoubleEndedIterator[T]) XTryRfold ¶ added in v1.7.0

func (de DoubleEndedIterator[T]) XTryRfold(init any, f func(any, T) gust.Result[any]) gust.Result[any]

XTryRfold is the reverse version of TryFold: it takes elements starting from the back of the iterator (any version).

Examples ¶

var a = []string{"1", "2", "3"}
var deIter = FromSlice(a).MustToDoubleEnded()
var sum = deIter.XTryRfold(0, func(acc any, s string) gust.Result[any] {
	if v, err := strconv.Atoi(s); err == nil {
		return gust.Ok(any(acc.(int) + v))
	}
	return gust.Err[any](err)
})
assert.True(t, sum.IsOk())
assert.Equal(t, 6, sum.Unwrap().(int))

func (Iterator[T]) AdvanceBy ¶

func (it Iterator[T]) AdvanceBy(n uint) gust.VoidResult

AdvanceBy advances the iterator by n elements.

Examples ¶

var iter = FromSlice([]int{1, 2, 3, 4})
assert.True(t, iter.AdvanceBy(2).IsOk())

func (Iterator[T]) All ¶

func (it Iterator[T]) All(predicate func(T) bool) bool

All tests if all elements satisfy a predicate.

Examples ¶

var iter = FromSlice([]int{2, 4, 6})
assert.True(t, iter.All(func(x int) bool { return x%2 == 0 }))

func (Iterator[T]) Any ¶

func (it Iterator[T]) Any(predicate func(T) bool) bool

Any tests if any element satisfies a predicate.

Examples ¶

var iter = FromSlice([]int{1, 2, 3})
assert.True(t, iter.Any(func(x int) bool { return x > 2 }))

func (Iterator[T]) Chain ¶

func (it Iterator[T]) Chain(other Iterator[T]) Iterator[T]

Chain takes two iterators and creates a new iterator over both in sequence.

Examples ¶

var iter1 = FromSlice([]int{1, 2, 3})
var iter2 = FromSlice([]int{4, 5, 6})
var chained = iter1.Chain(iter2)
assert.Equal(t, gust.Some(1), chained.Next())

func (Iterator[T]) Collect ¶

func (it Iterator[T]) Collect() []T

Collect collects all items into a slice.

Examples ¶

var iter = FromSlice([]int{1, 2, 3})
var result = iter.Collect()
assert.Equal(t, []int{1, 2, 3}, result)

func (Iterator[T]) Count ¶

func (it Iterator[T]) Count() uint

Count consumes the iterator, counting the number of iterations.

Examples ¶

var iter = FromSlice([]int{1, 2, 3, 4, 5})
assert.Equal(t, uint(5), iter.Count())

func (Iterator[T]) Cycle ¶ added in v1.7.0

func (it Iterator[T]) Cycle() Iterator[T]

Cycle repeats an iterator endlessly.

Examples ¶

var iter = FromSlice([]int{1, 2, 3})
var cycled = iter.Cycle()
assert.Equal(t, gust.Some(1), cycled.Next())
assert.Equal(t, gust.Some(2), cycled.Next())
assert.Equal(t, gust.Some(3), cycled.Next())
assert.Equal(t, gust.Some(1), cycled.Next()) // starts over

func (Iterator[T]) Filter ¶

func (it Iterator[T]) Filter(predicate func(T) bool) Iterator[T]

Filter creates an iterator which uses a closure to determine if an element should be yielded.

Examples ¶

var iter = FromSlice([]int{0, 1, 2})
var filtered = iter.Filter(func(x int) bool { return x > 0 })
assert.Equal(t, gust.Some(1), filtered.Next())

func (Iterator[T]) FilterMap ¶

func (it Iterator[T]) FilterMap(f func(T) gust.Option[T]) Iterator[T]

FilterMap creates an iterator that both filters and maps.

Examples ¶

var iter = FromSlice([]string{"1", "two", "NaN", "four", "5"})
var filtered = iter.FilterMap(func(s string) gust.Option[string] {
	if s == "1" || s == "5" {
		return gust.Some(s)
	}
	return gust.None[string]()
})
// Can chain: filtered.Filter(...).Collect()

func (Iterator[T]) Find ¶

func (it Iterator[T]) Find(predicate func(T) bool) gust.Option[T]

Find searches for an element that satisfies a predicate.

Examples ¶

var iter = FromSlice([]int{1, 2, 3})
assert.Equal(t, gust.Some(2), iter.Find(func(x int) bool { return x > 1 }))

func (Iterator[T]) FindMap ¶

func (it Iterator[T]) FindMap(f func(T) gust.Option[T]) gust.Option[T]

FindMap searches for an element and maps it.

Examples ¶

var iter = FromSlice([]string{"lol", "NaN", "2", "5"})
var firstNumber = iter.FindMap(func(s string) gust.Option[int] {
	if v, err := strconv.Atoi(s); err == nil {
		return gust.Some(v)
	}
	return gust.None[int]()
})
assert.Equal(t, gust.Some(2), firstNumber)

func (Iterator[T]) FlatMap ¶ added in v1.7.0

func (it Iterator[T]) FlatMap(f func(T) Iterator[T]) Iterator[T]

FlatMap creates an iterator that maps and flattens nested iterators.

Examples ¶

var iter = FromSlice([]int{1, 2, 3})
var flatMapped = iter.FlatMap(func(x int) Iterator[int] {
	return FromSlice([]int{x, x * 2})
})
// Can chain: flatMapped.Filter(...).Collect()

func (Iterator[T]) Fold ¶

func (it Iterator[T]) Fold(init T, f func(T, T) T) T

Fold folds every element into an accumulator. This wrapper method allows Fold to be called as a method.

Examples ¶

var iter = FromSlice([]int{1, 2, 3})
var sum = iter.Fold(0, func(acc int, x int) int { return acc + x })
assert.Equal(t, 6, sum)

func (Iterator[T]) ForEach ¶

func (it Iterator[T]) ForEach(f func(T))

ForEach calls a closure on each element.

Examples ¶

var iter = FromSlice([]int{1, 2, 3})
iter.ForEach(func(x int) { fmt.Println(x) })

func (Iterator[T]) Fuse ¶

func (it Iterator[T]) Fuse() Iterator[T]

Fuse creates an iterator that ends after the first None.

Examples ¶

var iter = FromSlice([]int{1, 2, 3})
var fused = iter.Fuse()
// After None, it will always return None

func (Iterator[T]) Inspect ¶

func (it Iterator[T]) Inspect(f func(T)) Iterator[T]

Inspect creates an iterator that calls a closure on each element for side effects.

Examples ¶

var iter = FromSlice([]int{1, 2, 3})
var inspected = iter.Inspect(func(x int) { fmt.Println(x) })
// Prints 1, 2, 3 when iterated

func (Iterator[T]) Intersperse ¶

func (it Iterator[T]) Intersperse(separator T) Iterator[T]

Intersperse creates an iterator that places a separator between adjacent items.

Examples ¶

var iter = FromSlice([]int{0, 1, 2})
var interspersed = iter.Intersperse(100)
assert.Equal(t, gust.Some(0), interspersed.Next())
assert.Equal(t, gust.Some(100), interspersed.Next())

func (Iterator[T]) IntersperseWith ¶

func (it Iterator[T]) IntersperseWith(separator func() T) Iterator[T]

IntersperseWith creates an iterator that places an item generated by separator between adjacent items.

Examples ¶

var iter = FromSlice([]int{0, 1, 2})
var interspersed = iter.IntersperseWith(func() int { return 99 })
assert.Equal(t, gust.Some(0), interspersed.Next())
assert.Equal(t, gust.Some(99), interspersed.Next())

func (Iterator[T]) Last ¶

func (it Iterator[T]) Last() gust.Option[T]

Last returns the last element of the iterator.

Examples ¶

var iter = FromSlice([]int{1, 2, 3})
assert.Equal(t, gust.Some(3), iter.Last())

func (Iterator[T]) Map ¶

func (it Iterator[T]) Map(f func(T) T) Iterator[T]

Map creates an iterator which calls a closure on each element.

Examples ¶

var iter = FromSlice([]int{1, 2, 3})
var doubled = iter.Map(func(x int) int { return x * 2 })
assert.Equal(t, gust.Some(2), doubled.Next())
// Can chain: doubled.Filter(...).Collect()

func (Iterator[T]) MapWhile ¶

func (it Iterator[T]) MapWhile(predicate func(T) gust.Option[T]) Iterator[T]

MapWhile creates an iterator that both yields elements based on a predicate and maps.

func (Iterator[T]) MapWindows ¶ added in v1.7.0

func (it Iterator[T]) MapWindows(windowSize uint, f func([]T) T) Iterator[T]

MapWindows creates an iterator that applies a function to overlapping windows.

Examples ¶

var iter = FromSlice([]int{1, 2, 3, 4, 5})
var windows = iter.MapWindows(3, func(window []int) int {
	return window[0] + window[1] + window[2]
})
// Can chain: windows.Filter(...).Collect()

func (Iterator[T]) MaxBy ¶ added in v1.7.0

func (it Iterator[T]) MaxBy(compare func(T, T) int) gust.Option[T]

MaxBy returns the element that gives the maximum value with respect to the specified comparison function.

Examples ¶

var iter = FromSlice([]int{-3, 0, 1, 5, -10})
var max = iter.MaxBy(func(x, y int) int {
	if x < y {
		return -1
	}
	if x > y {
		return 1
	}
	return 0
})
assert.Equal(t, gust.Some(5), max)

func (Iterator[T]) MinBy ¶ added in v1.7.0

func (it Iterator[T]) MinBy(compare func(T, T) int) gust.Option[T]

MinBy returns the element that gives the minimum value with respect to the specified comparison function.

Examples ¶

var iter = FromSlice([]int{-3, 0, 1, 5, -10})
var min = iter.MinBy(func(x, y int) int {
	if x < y {
		return -1
	}
	if x > y {
		return 1
	}
	return 0
})
assert.Equal(t, gust.Some(-10), min)

func (Iterator[T]) MustToDoubleEnded ¶ added in v1.7.0

func (it Iterator[T]) MustToDoubleEnded() DoubleEndedIterator[T]

MustToDoubleEnded converts to a DoubleEndedIterator[T] if the underlying iterator supports double-ended iteration. Otherwise, it panics.

Examples ¶

var iter = FromSlice([]int{1, 2, 3})
var deIter = iter.MustToDoubleEnded()
assert.Equal(t, gust.Some(3), deIter.NextBack())
// Can use Iterator methods:
var doubled = deIter.Map(func(x int) any { return x * 2 })

func (Iterator[T]) Next ¶

func (it Iterator[T]) Next() gust.Option[T]

Next advances the iterator and returns the next value. This implements gust.Iterable[T] interface.

func (Iterator[T]) NextChunk ¶

func (it Iterator[T]) NextChunk(n uint) ChunkResult[[]T]

NextChunk advances the iterator and returns an array containing the next N values.

Examples ¶

var iter = FromSlice([]int{1, 2, 3, 4, 5})
chunk := iter.NextChunk(2)
assert.True(t, chunk.IsOk())

func (Iterator[T]) Nth ¶

func (it Iterator[T]) Nth(n uint) gust.Option[T]

Nth returns the nth element of the iterator.

Examples ¶

var iter = FromSlice([]int{1, 2, 3})
assert.Equal(t, gust.Some(2), iter.Nth(1))

func (Iterator[T]) Partition ¶ added in v1.0.0

func (it Iterator[T]) Partition(f func(T) bool) (truePart []T, falsePart []T)

Partition partitions the iterator into two slices.

Examples ¶

var iter = FromSlice([]int{1, 2, 3, 4, 5})
evens, odds := iter.Partition(func(x int) bool { return x%2 == 0 })
assert.Equal(t, []int{2, 4}, evens)
assert.Equal(t, []int{1, 3, 5}, odds)

func (Iterator[T]) Peekable ¶

func (it Iterator[T]) Peekable() PeekableIterator[T]

Peekable creates a peekable iterator.

Examples ¶

var iter = FromSlice([]int{1, 2, 3})
var peekable = iter.Peekable()
assert.Equal(t, gust.Some(1), peekable.Peek())
assert.Equal(t, gust.Some(1), peekable.Next())

// Can use all Iterator methods:
var filtered = peekable.Filter(func(x int) bool { return x > 1 })
assert.Equal(t, gust.Some(2), filtered.Next())

func (Iterator[T]) Position ¶

func (it Iterator[T]) Position(predicate func(T) bool) gust.Option[uint]

Position searches for an element in an iterator, returning its index.

Examples ¶

var iter = FromSlice([]int{1, 2, 3})
assert.Equal(t, gust.Some(uint(1)), iter.Position(func(x int) bool { return x == 2 }))

func (Iterator[T]) Pull ¶ added in v1.9.0

func (it Iterator[T]) Pull() (next func() (T, bool), stop func())

Pull converts the Iterator[T] to a pull-style iterator using Go's standard iter.Pull. This returns two functions: next (to pull values) and stop (to stop iteration). The caller should defer stop() to ensure proper cleanup.

Examples ¶

iter := FromSlice([]int{1, 2, 3, 4, 5})
next, stop := iter.Pull()
defer stop()

// Pull values manually
for {
	v, ok := next()
	if !ok {
		break
	}
	fmt.Println(v)
	if v == 3 {
		break // Early termination
	}
}

func (Iterator[T]) Pull2 ¶ added in v1.9.1

func (it Iterator[T]) Pull2() (next func() (uint, T, bool), stop func())

Pull2 converts the Iterator[T] to a pull-style iterator using Go's standard iter.Pull2. This returns two functions: next (to pull key-value pairs) and stop (to stop iteration). The caller should defer stop() to ensure proper cleanup.

Examples ¶

iter := FromSlice([]int{1, 2, 3, 4, 5})
next, stop := iter.Pull2()
defer stop()

// Pull key-value pairs manually
for {
	k, v, ok := next()
	if !ok {
		break
	}
	fmt.Println(k, v)
	if v == 3 {
		break // Early termination
	}
}

func (Iterator[T]) Reduce ¶

func (it Iterator[T]) Reduce(f func(T, T) T) gust.Option[T]

Reduce reduces the iterator to a single value.

Examples ¶

var iter = FromSlice([]int{1, 2, 3})
var sum = iter.Reduce(func(acc int, x int) int { return acc + x })
assert.Equal(t, gust.Some(6), sum)

func (Iterator[T]) Scan ¶ added in v0.8.0

func (it Iterator[T]) Scan(initialState T, f func(*T, T) gust.Option[T]) Iterator[T]

Scan creates an iterator that scans over the iterator with a state.

Examples ¶

var iter = FromSlice([]int{1, 2, 3})
var scanned = iter.Scan(0, func(state *int, x int) gust.Option[int] {
	*state = *state + x
	return gust.Some(*state)
})
// Can chain: scanned.Filter(...).Collect()

func (Iterator[T]) Seq ¶ added in v1.9.0

func (it Iterator[T]) Seq() stditer.Seq[T]

Seq converts the Iterator[T] to Go's standard iter.Seq[T]. This allows using gust iterators with Go's built-in iteration support (for loops).

Examples ¶

iter := FromSlice([]int{1, 2, 3})
for v := range iter.Seq() {
	fmt.Println(v) // prints 1, 2, 3
}

func (Iterator[T]) Seq2 ¶ added in v1.9.1

func (it Iterator[T]) Seq2() stditer.Seq2[uint, T]

Seq2 converts the Iterator[T] to Go's standard iter.Seq2[T]. This allows using gust iterators with Go's built-in iteration support (for loops).

Examples ¶

iter := FromSlice([]int{1, 2, 3})

for k, v := range iter.Seq2() {
	fmt.Println(k, v) // prints 0 1, 1 2, 2 3
}

func (Iterator[T]) SizeHint ¶

func (it Iterator[T]) SizeHint() (uint, gust.Option[uint])

SizeHint returns the bounds on the remaining length of the iterator. This implements gust.IterableSizeHint interface.

func (Iterator[T]) Skip ¶ added in v0.8.0

func (it Iterator[T]) Skip(n uint) Iterator[T]

Skip creates an iterator that skips the first n elements.

Examples ¶

var iter = FromSlice([]int{1, 2, 3, 4, 5})
var skipped = iter.Skip(2)
assert.Equal(t, gust.Some(3), skipped.Next())

func (Iterator[T]) SkipWhile ¶

func (it Iterator[T]) SkipWhile(predicate func(T) bool) Iterator[T]

SkipWhile creates an iterator that skips elements while a predicate is true.

Examples ¶

var iter = FromSlice([]int{1, 2, 3, 4, 5})
var skipped = iter.SkipWhile(func(x int) bool { return x < 3 })
assert.Equal(t, gust.Some(3), skipped.Next())

func (Iterator[T]) StepBy ¶

func (it Iterator[T]) StepBy(step uint) Iterator[T]

StepBy creates an iterator that steps by n elements at a time.

Examples ¶

var iter = FromSlice([]int{0, 1, 2, 3, 4, 5})
var stepped = iter.StepBy(2)
assert.Equal(t, gust.Some(0), stepped.Next())
assert.Equal(t, gust.Some(2), stepped.Next())
assert.Equal(t, gust.Some(4), stepped.Next())

func (Iterator[T]) Take ¶ added in v0.8.0

func (it Iterator[T]) Take(n uint) Iterator[T]

Take creates an iterator that yields the first n elements.

Examples ¶

var iter = FromSlice([]int{1, 2, 3, 4, 5})
var taken = iter.Take(2)
assert.Equal(t, gust.Some(1), taken.Next())
assert.Equal(t, gust.Some(2), taken.Next())
assert.Equal(t, gust.None[int](), taken.Next())

func (Iterator[T]) TakeWhile ¶

func (it Iterator[T]) TakeWhile(predicate func(T) bool) Iterator[T]

TakeWhile creates an iterator that yields elements while a predicate is true.

Examples ¶

var iter = FromSlice([]int{1, 2, 3, 4, 5})
var taken = iter.TakeWhile(func(x int) bool { return x < 3 })
assert.Equal(t, gust.Some(1), taken.Next())
assert.Equal(t, gust.Some(2), taken.Next())
assert.Equal(t, gust.None[int](), taken.Next())

func (Iterator[T]) TryFind ¶

func (it Iterator[T]) TryFind(f func(T) gust.Result[bool]) gust.Result[gust.Option[T]]

TryFind applies function to the elements of iterator and returns the first true result or the first error.

Examples ¶

var a = []string{"1", "2", "lol", "NaN", "5"}
var result = iter.TryFind(func(s string) gust.Result[bool] {
	if s == "lol" {
		return gust.Err[bool](errors.New("invalid"))
	}
	if v, err := strconv.Atoi(s); err == nil {
		return gust.Ok(v == 2)
	}
	return gust.Ok(false)
})
assert.True(t, result.IsOk())

func (Iterator[T]) TryFold ¶

func (it Iterator[T]) TryFold(init T, f func(T, T) gust.Result[T]) gust.Result[T]

TryFold applies a function as long as it returns successfully, producing a single, final value.

Examples ¶

var iter = FromSlice([]int{1, 2, 3})
var sum = iter.TryFold(0, func(acc int, x int) gust.Result[int] {
	return gust.Ok(acc + x)
})
assert.True(t, sum.IsOk())
assert.Equal(t, 6, sum.Unwrap())

func (Iterator[T]) TryForEach ¶ added in v1.0.0

func (it Iterator[T]) TryForEach(f func(T) gust.Result[T]) gust.Result[T]

TryForEach applies a fallible function to each item in the iterator, stopping at the first error and returning that error.

Examples ¶

var data = []string{"no_tea.txt", "stale_bread.json", "torrential_rain.png"}
var res = iter.TryForEach(func(x string) gust.Result[string] {
	fmt.Println(x)
	return gust.Ok[string](x+"_processed")
})
assert.True(t, res.IsOk())
assert.Equal(t, "no_tea.txt_processed", res.Unwrap())

func (Iterator[T]) TryReduce ¶ added in v1.0.0

func (it Iterator[T]) TryReduce(f func(T, T) gust.Result[T]) gust.Result[gust.Option[T]]

TryReduce reduces the elements to a single one by repeatedly applying a reducing operation.

Examples ¶

var numbers = []int{10, 20, 5, 23, 0}
var sum = iter.TryReduce(func(x, y int) gust.Result[int] {
	if x+y > 100 {
		return gust.Err[int](errors.New("overflow"))
	}
	return gust.Ok(x + y)
})
assert.True(t, sum.IsOk())

func (Iterator[T]) TryToDoubleEnded ¶ added in v1.7.0

func (it Iterator[T]) TryToDoubleEnded() gust.Option[DoubleEndedIterator[T]]

TryToDoubleEnded converts to a DoubleEndedIterator[T] if the underlying iterator supports double-ended iteration. Otherwise, it returns None.

Examples ¶

var iter = FromSlice([]int{1, 2, 3})
var deIter = iter.TryToDoubleEnded()
assert.Equal(t, gust.Some(3), deIter.NextBack())
// Can use Iterator methods:
var doubled = deIter.Map(func(x int) any { return x * 2 })

func (Iterator[T]) XFilterMap ¶

func (it Iterator[T]) XFilterMap(f func(T) gust.Option[any]) Iterator[any]

XFilterMap creates an iterator that both filters and maps (any version).

Examples ¶

var iter = FromSlice([]string{"1", "two", "NaN", "four", "5"})
var filtered = iter.XFilterMap(func(s string) gust.Option[any] {
	if s == "1" {
		return gust.Some(any(1))
	}
	if s == "5" {
		return gust.Some(any(5))
	}
	return gust.None[any]()
})
// Can chain: filtered.Filter(...).Collect()

func (Iterator[T]) XFindMap ¶

func (it Iterator[T]) XFindMap(f func(T) gust.Option[any]) gust.Option[any]

XFindMap searches for an element and maps it (any version).

Examples ¶

var iter = FromSlice([]string{"lol", "NaN", "2", "5"})
var firstNumber = iter.XFindMap(func(s string) gust.Option[any] {
	if v, err := strconv.Atoi(s); err == nil {
		return gust.Some(any(v))
	}
	return gust.None[any]()
})
assert.True(t, firstNumber.IsSome())
assert.Equal(t, 2, firstNumber.Unwrap().(int))

func (Iterator[T]) XFlatMap ¶ added in v1.7.0

func (it Iterator[T]) XFlatMap(f func(T) Iterator[any]) Iterator[any]

XFlatMap creates an iterator that maps and flattens nested iterators (any version).

Examples ¶

var iter = FromSlice([]int{1, 2, 3})
var flatMapped = iter.XFlatMap(func(x int) Iterator[any] {
	return FromSlice([]any{x, x * 2})
})
// Can chain: flatMapped.Filter(...).Collect()

func (Iterator[T]) XFold ¶ added in v1.7.0

func (it Iterator[T]) XFold(init any, f func(any, T) any) any

XFold folds every element into an accumulator. This wrapper method allows XFold to be called as a method.

Examples ¶

var iter = FromSlice([]int{1, 2, 3})
var sum = iter.XFold(0, func(acc any, x int) any { return acc.(int) + x })
assert.Equal(t, 6, sum)

func (Iterator[T]) XMap ¶

func (it Iterator[T]) XMap(f func(T) any) Iterator[any]

XMap creates an iterator which calls a closure on each element (any version).

Examples ¶

var iter = FromSlice([]int{1, 2, 3})
var doubled = iter.XMap(func(x int) any { return x * 2 })
assert.Equal(t, gust.Some(2), doubled.Next())
// Can chain: doubled.Filter(...).Collect()

func (Iterator[T]) XMapWhile ¶

func (it Iterator[T]) XMapWhile(predicate func(T) gust.Option[any]) Iterator[any]

XMapWhile creates an iterator that both yields elements based on a predicate and maps (any version).

func (Iterator[T]) XMapWindows ¶ added in v1.7.0

func (it Iterator[T]) XMapWindows(windowSize uint, f func([]T) any) Iterator[any]

XMapWindows creates an iterator that applies a function to overlapping windows (any version).

Examples ¶

var iter = FromSlice([]int{1, 2, 3, 4, 5})
var windows = iter.XMapWindows(3, func(window []int) any {
	return window[0] + window[1] + window[2]
})
// Can chain: windows.Filter(...).Collect()

func (Iterator[T]) XScan ¶ added in v1.7.0

func (it Iterator[T]) XScan(initialState any, f func(*any, T) gust.Option[any]) Iterator[any]

XScan creates an iterator that scans over the iterator with a state (any version).

Examples ¶

var iter = FromSlice([]int{1, 2, 3})
var scanned = iter.XScan(0, func(state *any, x int) gust.Option[any] {
	s := (*state).(int) + x
	*state = s
	return gust.Some(any(s))
})
// Can chain: scanned.Filter(...).Collect()

func (Iterator[T]) XTryFold ¶ added in v1.7.0

func (it Iterator[T]) XTryFold(init any, f func(any, T) gust.Result[any]) gust.Result[any]

XTryFold applies a function as long as it returns successfully, producing a single, final value (any version).

Examples ¶

var iter = FromSlice([]int{1, 2, 3})
var sum = iter.XTryFold(0, func(acc any, x int) gust.Result[any] {
	return gust.Ok(any(acc.(int) + x))
})
assert.True(t, sum.IsOk())
assert.Equal(t, 6, sum.Unwrap().(int))

func (Iterator[T]) XTryForEach ¶ added in v1.7.0

func (it Iterator[T]) XTryForEach(f func(T) gust.Result[any]) gust.Result[any]

XTryForEach applies a fallible function to each item in the iterator, stopping at the first error and returning that error.

Examples ¶

var data = []string{"no_tea.txt", "stale_bread.json", "torrential_rain.png"}
var res = iter.TryForEach(func(x string) gust.Result[any] {
	fmt.Println(x)
	return gust.Ok[any](nil)
})
assert.True(t, res.IsOk())

func (*PeekableIterator[T]) Next ¶ added in v1.7.0

func (p *PeekableIterator[T]) Next() gust.Option[T]

Next advances the iterator and returns the next value. This overrides Iterator[T].Next() to handle peeked values.

func (*PeekableIterator[T]) Peek ¶ added in v1.7.0

func (p *PeekableIterator[T]) Peek() gust.Option[T]

Peek returns the next element without consuming it.

Examples ¶

var xs = []int{1, 2, 3}
var iter = Peekable(FromSlice(xs))

assert.Equal(t, gust.Some(1), iter.Peek())
assert.Equal(t, gust.Some(1), iter.Peek()) // Can peek multiple times
assert.Equal(t, gust.Some(1), iter.Next())

func (*PeekableIterator[T]) SizeHint ¶ added in v1.7.0

func (p *PeekableIterator[T]) SizeHint() (uint, gust.Option[uint])

SizeHint returns the bounds on the remaining length of the iterator. This overrides Iterator[T].SizeHint() to account for peeked values.