README
¶
go-iter
Package iter provides tools for creating iterators, for the Go programming language.
These iterators are intentionally made to resemble *sql.Rows from the "database/sql" package.
Including having the same Close, Err, Next, and Scan methods.
(Note that to turn something into an actual *sql.Rows from the "database/sql" package,
instead of just resembling it, use https://github.com/reiver/go-shunt instead.)
Documention
Online documentation, which includes examples, can be found at: http://godoc.org/github.com/reiver/go-iter
Example
var slice []string = []string {
"apple",
"banana",
"cherry",
}
iterator := iterstring.Slice{
Slice: slice,
}
defer iterator.Close()
for iterator.Next() {
var datum string // Could have also used: var datum interface{}
if err := iterator.Decode(&datum); nil != err {
return err
}
fmt.Printf("Next datum: %v \n", datum)
}
if err := iterator.Err(); nil != err {
return err
}
Import
To import package iter use import code like the follownig:
import "github.com/reiver/go-iter"
Installation
To install package iter do the following:
GOPROXY=direct go get github.com/reiver/go-iter
Author
Package iter was written by Charles Iliya Krempeaux
Documentation
¶
Overview ¶
Package iter (including its sub-packages) provides tools for creating iterators.
These iterators are intentionally made to resemble *sql.Rows from the "database/sql" package. Including having the same Close, Err, Next, and Scan methods.
(Note that to turn something into an actual *sql.Rows from the "database/sql" package, instead of just resembling it, use https://github.com/reiver/go-shunt instead.)
For example, we can turn a slice into an iterator, with code like the following:
var slice []string = []string {
"apple",
"banana",
"cherry",
}
iterator := iterstring.Slice{
Slice: slice,
}
defer iterator.Close()
for iterator.Next() {
var datum string // Could have also used: var datum interface{}
if err := iterator.Decode(&datum); nil != err {
return err
}
fmt.Printf("Next datum: %v \n", datum)
}
if err := iterator.Err(); nil != err {
return err
}
This can help to enable us to write more (run-time oriented) generic code.
To be able to distinguish one iterator type from another, in a (run-time oriented) generic way, that is not so specific to this package, we can use the Type method.
For example:
switch reflect.Zero( iterator.Type() ).Interface().(type) {
case bool:
//@TODO
case float64:
//@TODO
case [2]float64:
//@TODO
case string:
//@TODO
default:
//@TODO
}
Index ¶
- type EmptyIteratorComplainer
- type Filter
- type First
- type FlattenedIterator
- type For
- type Iterator
- type Iterators
- type Slice
- func (receiver *Slice[T]) Close() error
- func (receiver *Slice[T]) Decode(x any) error
- func (receiver *Slice[T]) Err() error
- func (receiver *Slice[T]) Next() bool
- func (receiver *Slice[T]) Scan(dest ...interface{}) error
- func (receiver *Slice[T]) Type() reflect.Type
- func (receiver *Slice[T]) WriteTo(w io.Writer) (int64, error)
- type Slices
- type SplitIterators
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type EmptyIteratorComplainer ¶
type EmptyIteratorComplainer interface {
error
EmptyIteratorComplainer()
}
EmptyIteratorComplainer is a type of error will be returned in situations where an empty iterator is not expected.
Example:
err := iter.First{Iterator: iterator}.Decode(&datum)
if nil != err {
switch {
case iter.EmptyIteratorComplainer:
//@TODO
default:
return err
}
}
type Filter ¶
type First ¶
type First struct {
Iterator Iterator
}
First is useful when you only expect one (1) item in the iterator.
Note that it will return an error if there is more than one (1) item in the iterator. (It checks for this.)
Example Usage
iterator := ...
err := iter.First{Iterator: iterator}.Decode(v)
if nil != err {
switch {
case iter.EmptyIteratorComplainer:
//@TODO
default:
return err
}
}
type FlattenedIterator ¶
type FlattenedIterator struct {
Iterators Iterators
// contains filtered or unexported fields
}
FlattenedIterator flattens Iterators into a "normal" Iterator.
func (*FlattenedIterator) Close ¶
func (receiver *FlattenedIterator) Close() error
func (*FlattenedIterator) Decode ¶
func (receiver *FlattenedIterator) Decode(dst any) error
func (*FlattenedIterator) Err ¶
func (receiver *FlattenedIterator) Err() error
func (*FlattenedIterator) Next ¶
func (receiver *FlattenedIterator) Next() bool
type For ¶
type For struct {
Iterator Iterator
}
For is useful for iterating through an iterator in a terse way.
Example Usage
iterator := ...
err := iter.For{iterator}.Each(func(datum string){
//@TODO
})
Or:
type MyStruct {
GiveName string `iter:"given_name"`
FamilyName string `iter:"family_name"`
Age int64 `iter:"age"`
}
iterator := ...
err := iter.For{iterator}.Each(func(datum MyStruct){
//@TODO
})
Etc.
type Iterator ¶
Iterator represents a "normal" iterator.
Many of the sub-packages that are part of this export types that fit this interface.
Some of those exported type have more methods than just these.
But these can be relied on to exist.
Example Usage
iterator := //...
defer iterator.Close()
for iterator.Next() {
datum := struct{
GivenName string `iter:"given_name"`
FamilyName string `iter:"family_name"`
Age int64 `iter:"age"`
}{}
if err := iterator.Decode(&datum); nil != err {
return err
}
//@TODO: do something with `datum`.
}
if err := iterator.Err(); nil != err {
return err
}
var ( // Empty is an empty iterator. // // It is useful in cases where you want to quickly and cheaply return an empty iterator. // // Usage: // // func fn() (iter.Iterator, error) { // // // ... // // return iter.Empty, nil Empty Iterator )
type Iterators ¶
Iterators represents something that has a series of iterators.
There are no more iterators when NextIterator() return nil (for Iterator).
Iterators is used by FlattenedIterator.
type Slice ¶
type Slice[T any] struct { Slice []T // contains filtered or unexported fields }
func (*Slice[T]) Decode ¶
Decode stores the next datum in the data represented by the empty interface value `x`. If `x` is nil, the value will be discarded. Otherwise, the value underlying `x` must be a pointer to the correct type for the next datum.
func (*Slice[T]) Err ¶
Err returns the error, if an error was encountered during an iteration. If no error was encountered during an iteration, then Err returns nil.
func (*Slice[T]) Next ¶
Next prepares the next datum for reading via the Decode method.
If there is indeed a next datum, Next returns true.
And a call to the Decode method will obtain that next datum.
If there is no next datum, Next returns false.
If an error was encountered while calling Next, Next will also return false.
And a call to the Err method will obtain that error.
Err should be called to distinguish between the two cases where the Next method can return false: 'no next datum' and 'an error was encountered'.
type SplitIterators ¶
type SplitIterators[T any] struct { Iterator Iterator Func func(T) (Iterator, error) // contains filtered or unexported fields }
func (*SplitIterators[T]) Close ¶
func (receiver *SplitIterators[T]) Close() error
func (*SplitIterators[T]) NextIterator ¶
func (receiver *SplitIterators[T]) NextIterator() (Iterator, error)
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
Package itersqlrows provides tools for creating iterators for *sql.Rows from the standard Go package "database/sql".
|
Package itersqlrows provides tools for creating iterators for *sql.Rows from the standard Go package "database/sql". |
|
Package iterutf8 provides tools for creating iterators for the []byte type, where the data in the []byte is encoded as UTF-8; note that values decoded from this are of the rune type (and not the byte type).
|
Package iterutf8 provides tools for creating iterators for the []byte type, where the data in the []byte is encoded as UTF-8; note that values decoded from this are of the rune type (and not the byte type). |