lancet/docs/stream.md

# Stream

Package stream implements a sequence of elements supporting sequential and operations. This package is an experiment to explore if stream in go can work as the way java does. it's feature is very limited.

<div STYLE="page-break-after: always;"></div>

## Source:

-   [https://github.com/duke-git/lancet/blob/main/stream/stream.go](https://github.com/duke-git/lancet/blob/main/stream/stream.go)

<div STYLE="page-break-after: always;"></div>

## Usage:

```go
import (
    "github.com/duke-git/lancet/v2/stream"
)
```

<div STYLE="page-break-after: always;"></div>

## Index

-   [Of](#Of)
-   [FromSlice](#FromSlice)
-   [FromChannel](#FromChannel)
-   [FromRange](#FromRange)
-   [Generate](#Generate)
-   [Concat](#Concat)
-   [Distinct](#Distinct)
-   [Filter](#Filter)
-   [Map](#Map)
-   [Peek](#Peek)
-   [Skip](#Skip)
-   [Limit](#Limit)
-   [Reverse](#Reverse)
-   [Range](#Range)
-   [Sorted](#Sorted)
-   [ForEach](#ForEach)
-   [Reduce](#Reduce)
-   [FindFirst](#FindFirst)
-   [FindLast](#FindLast)
-   [Max](#Max)
-   [Min](#Min)
-   [AllMatch](#AllMatch)
-   [AnyMatch](#AnyMatch)
-   [NoneMatch](#NoneMatch)
-   [Count](#Count)
-   [ToSlice](#ToSlice)

<div STYLE="page-break-after: always;"></div>

## Documentation

### <span id="Of">Of</span>

<p>Creates a stream whose elements are the specified values.</p>

<b>Signature:</b>

```go
func Of[T any](elems ...T) stream[T]
```

<b>Example:</b>

```go
import (
    "fmt"
    "github.com/duke-git/lancet/v2/stream"
)

func main() {
    s := stream.Of(1, 2, 3)

    data := s.ToSlice()

    fmt.Println(data)

    // Output:
    // [1 2 3]
}
```

### <span id="FromSlice">FromSlice</span>

<p>Creates a stream from slice.</p>

<b>Signature:</b>

```go
func FromSlice[T any](source []T) stream[T]
```

<b>Example:</b>

```go
import (
    "fmt"
    "github.com/duke-git/lancet/v2/stream"
)

func main() {
    s := stream.FromSlice([]int{1, 2, 3})

    data := s.ToSlice()

    fmt.Println(data)

    // Output:
    // [1 2 3]
}
```

### <span id="FromChannel">FromChannel</span>

<p>Creates a stream from channel.</p>

<b>Signature:</b>

```go
func FromChannel[T any](source <-chan T) stream[T]
```

<b>Example:</b>

```go
import (
    "fmt"
    "github.com/duke-git/lancet/v2/stream"
)

func main() {
    ch := make(chan int)
    go func() {
        for i := 1; i < 4; i++ {
            ch <- i
        }
        close(ch)
    }()

    s := stream.FromChannel(ch)

    data := s.ToSlice()

    fmt.Println(data)

    // Output:
    // [1 2 3]
}
```

### <span id="FromRange">FromRange</span>

<p>Creates a number stream from start to end. both start and end are included. [start, end]</p>

<b>Signature:</b>

```go
func FromRange[T constraints.Integer | constraints.Float](start, end, step T) stream[T]
```

<b>Example:</b>

```go
import (
    "fmt"
    "github.com/duke-git/lancet/v2/stream"
)

func main() {
    s := stream.FromRange(1, 5, 1)

    data := s.ToSlice()
    fmt.Println(data)

    // Output:
    // [1 2 3 4 5]
}
```

### <span id="Generate">Generate</span>

<p>Creates a stream where each element is generated by the provided generater function.</p>

<b>Signature:</b>

```go
func Generate[T any](generator func() func() (item T, ok bool)) stream[T]
```

<b>Example:</b>

```go
import (
    "fmt"
    "github.com/duke-git/lancet/v2/stream"
)

func main() {
    n := 0
    max := 4

    generator := func() func() (int, bool) {
        return func() (int, bool) {
            n++
            return n, n < max
        }
    }

    s := stream.Generate(generator)

    data := s.ToSlice()

    fmt.Println(data)

    // Output:
    // [1 2 3]
}
```

### <span id="Concat">Concat</span>

<p>Creates a lazily concatenated stream whose elements are all the elements of the first stream followed by all the elements of the second stream.</p>

<b>Signature:</b>

```go
func Concat[T any](a, b stream[T]) stream[T]
```

<b>Example:</b>

```go
import (
    "fmt"
    "github.com/duke-git/lancet/v2/stream"
)

func main() {
    s1 := stream.FromSlice([]int{1, 2, 3})
    s2 := stream.FromSlice([]int{4, 5, 6})

    s := Concat(s1, s2)

    data := s.ToSlice()

    fmt.Println(data)

    // Output:
    // [1 2 3 4 5 6]
}
```

### <span id="Distinct">Distinct</span>

<p>Creates returns a stream that removes the duplicated items. <b>Support chainable operation</b></p>

<b>Signature:</b>

```go
func (s stream[T]) Distinct() stream[T]
```

<b>Example:</b>

```go
import (
    "fmt"
    "github.com/duke-git/lancet/v2/stream"
)

func main() {
    original := stream.FromSlice([]int{1, 2, 2, 3, 3, 3})
    distinct := original.Distinct()

    data1 := original.ToSlice()
    data2 := distinct.ToSlice()

    fmt.Println(data1)
    fmt.Println(data2)

    // Output:
    // [1 2 2 3 3 3]
    // [1 2 3]
}
```

### <span id="Filter">Filter</span>

<p>Returns a stream consisting of the elements of this stream that match the given predicate. <b>Support chainable operation</b></p>

<b>Signature:</b>

```go
func (s stream[T]) Filter(predicate func(item T) bool) stream[T]
```

<b>Example:</b>

```go
import (
    "fmt"
    "github.com/duke-git/lancet/v2/stream"
)

func main() {
    original := stream.FromSlice([]int{1, 2, 3, 4, 5})

    isEven := func(n int) bool {
        return n%2 == 0
    }

    even := original.Filter(isEven)

    fmt.Println(even.ToSlice())

    // Output:
    // [2 4]
}
```

### <span id="Map">Map</span>

<p>Returns a stream consisting of the elements of this stream that apply the given function to elements of stream. <b>Support chainable operation</b></p>

<b>Signature:</b>

```go
func (s stream[T]) Map(mapper func(item T) T) stream[T]
```

<b>Example:</b>

```go
import (
    "fmt"
    "github.com/duke-git/lancet/v2/stream"
)

func main() {
    original := stream.FromSlice([]int{1, 2, 3})

    addOne := func(n int) int {
        return n + 1
    }

    increament := original.Map(addOne)

    fmt.Println(increament.ToSlice())

    // Output:
    // [2 3 4]
}
```

### <span id="Peek">Peek</span>

<p>Returns a stream consisting of the elements of this stream, additionally performing the provided action on each element as elements are consumed from the resulting stream. <b>Support chainable operation</b></p>

<b>Signature:</b>

```go
func (s stream[T]) Peek(consumer func(item T)) stream[T]
```

<b>Example:</b>

```go
import (
    "fmt"
    "github.com/duke-git/lancet/v2/stream"
)

func main() {
    original := stream.FromSlice([]int{1, 2, 3})

    data := []string{}
    peekStream := original.Peek(func(n int) {
        data = append(data, fmt.Sprint("value", n))
    })

    fmt.Println(original.ToSlice())
    fmt.Println(peekStream.ToSlice())
    fmt.Println(data)

    // Output:
    // [1 2 3]
    // [1 2 3]
    // [value1 value2 value3]
}
```

### <span id="Skip">Skip</span>

<p>Returns a stream consisting of the remaining elements of this stream after discarding the first n elements of the stream. If this stream contains fewer than n elements then an empty stream will be returned. <b>Support chainable operation</b></p>

<b>Signature:</b>

```go
func (s stream[T]) Skip(n int) stream[T]
```

<b>Example:</b>

```go
import (
    "fmt"
    "github.com/duke-git/lancet/v2/stream"
)

func main() {
    original := stream.FromSlice([]int{1, 2, 3, 4})

    s1 := original.Skip(-1)
    s2 := original.Skip(0)
    s3 := original.Skip(1)
    s4 := original.Skip(5)

    fmt.Println(s1.ToSlice())
    fmt.Println(s2.ToSlice())
    fmt.Println(s3.ToSlice())
    fmt.Println(s4.ToSlice())

    // Output:
    // [1 2 3 4]
    // [1 2 3 4]
    // [2 3 4]
    // []
}
```

### <span id="Limit">Limit</span>

<p>Returns a stream consisting of the elements of this stream, truncated to be no longer than maxSize in length. <b>Support chainable operation</b></p>

<b>Signature:</b>

```go
func (s stream[T]) Limit(maxSize int) stream[T]
```

<b>Example:</b>

```go
import (
    "fmt"
    "github.com/duke-git/lancet/v2/stream"
)

func main() {
    original := stream.FromSlice([]int{1, 2, 3, 4})

    s1 := original.Limit(-1)
    s2 := original.Limit(0)
    s3 := original.Limit(1)
    s4 := original.Limit(5)

    fmt.Println(s1.ToSlice())
    fmt.Println(s2.ToSlice())
    fmt.Println(s3.ToSlice())
    fmt.Println(s4.ToSlice())

    // Output:
    // []
    // []
    // [1]
    // [1 2 3 4]
}
```

### <span id="Reverse">Reverse</span>

<p>Returns a stream whose elements are reverse order of given stream. <b>Support chainable operation</b></p>

<b>Signature:</b>

```go
func (s stream[T]) Reverse() stream[T]
```

<b>Example:</b>

```go
import (
    "fmt"
    "github.com/duke-git/lancet/v2/stream"
)

func main() {
    original := stream.FromSlice([]int{1, 2, 3})

    reverse := original.Reverse()

    fmt.Println(reverse.ToSlice())

    // Output:
    // [3 2 1]
}
```

### <span id="Range">Range</span>

<p>Returns a stream whose elements are in the range from start(included) to end(excluded) original stream.<b>Support chainable operation</b></p>

<b>Signature:</b>

```go
func (s stream[T]) Range(start, end int) stream[T]
```

<b>Example:</b>

```go
import (
    "fmt"
    "github.com/duke-git/lancet/v2/stream"
)

func main() {
    original := stream.FromSlice([]int{1, 2, 3})

    s1 := original.Range(0, 0)
    s2 := original.Range(0, 1)
    s3 := original.Range(0, 3)
    s4 := original.Range(1, 2)

    fmt.Println(s1.ToSlice())
    fmt.Println(s2.ToSlice())
    fmt.Println(s3.ToSlice())
    fmt.Println(s4.ToSlice())

    // Output:
    // []
    // [1]
    // [1 2 3]
    // [2]
}
```

### <span id="Sorted">Sorted</span>

<p>Returns a stream consisting of the elements of this stream, sorted according to the provided less function.<b>Support chainable operation</b></p>

<b>Signature:</b>

```go
func (s stream[T]) Sorted(less func(a, b T) bool) stream[T]
```

<b>Example:</b>

```go
import (
    "fmt"
    "github.com/duke-git/lancet/v2/stream"
)

func main() {
    original := stream.FromSlice([]int{4, 2, 1, 3})

    sorted := original.Sorted(func(a, b int) bool { return a < b })

    fmt.Println(original.ToSlice())
    fmt.Println(sorted.ToSlice())

    // Output:
    // [4 2 1 3]
    // [1 2 3 4]
}
```

### <span id="ForEach">ForEach</span>

<p>Performs an action for each element of this stream.</p>

<b>Signature:</b>

```go
func (s stream[T]) ForEach(action func(item T))
```

<b>Example:</b>

```go
import (
    "fmt"
    "github.com/duke-git/lancet/v2/stream"
)

func main() {
    original := stream.FromSlice([]int{1, 2, 3})

    result := 0
    original.ForEach(func(item int) {
        result += item
    })

    fmt.Println(result)

    // Output:
    // 6
}
```

### <span id="Reduce">Reduce</span>

<p>Performs a reduction on the elements of this stream, using an associative accumulation function, and returns an Optional describing the reduced value, if any.</p>

<b>Signature:</b>

```go
func (s stream[T]) Reduce(initial T, accumulator func(a, b T) T) T
```

<b>Example:</b>

```go
import (
    "fmt"
    "github.com/duke-git/lancet/v2/stream"
)

func main() {
    original := stream.FromSlice([]int{1, 2, 3})

    result := original.Reduce(0, func(a, b int) int {
        return a + b
    })

    fmt.Println(result)

    // Output:
    // 6
}
```

### <span id="FindFirst">FindFirst</span>

<p>Returns the first element of this stream and true, or zero value and false if the stream is empty.</p>

<b>Signature:</b>

```go
func (s stream[T]) FindFirst() (T, bool)
```

<b>Example:</b>

```go
import (
    "fmt"
    "github.com/duke-git/lancet/v2/stream"
)

func main() {
    original := stream.FromSlice([]int{1, 2, 3})

    result, ok := original.FindFirst()

    fmt.Println(result)
    fmt.Println(ok)

    // Output:
    // 1
    // true
}
```

### <span id="FindLast">FindLast</span>

<p>Returns the last element of this stream and true, or zero value and false if the stream is empty.</p>

<b>Signature:</b>

```go
func (s stream[T]) FindLast() (T, bool)
```

<b>Example:</b>

```go
import (
    "fmt"
    "github.com/duke-git/lancet/v2/stream"
)

func main() {
    original := stream.FromSlice([]int{3, 2, 1})

    result, ok := original.FindLast()

    fmt.Println(result)
    fmt.Println(ok)

    // Output:
    // 1
    // true
}
```

### <span id="Max">Max</span>

<p>Returns the maximum element of this stream according to the provided less function. less fuction: a > b</p>

<b>Signature:</b>

```go
func (s stream[T]) Max(less func(a, b T) bool) (T, bool)
```

<b>Example:</b>

```go
import (
    "fmt"
    "github.com/duke-git/lancet/v2/stream"
)

func main() {
    original := stream.FromSlice([]int{4, 2, 1, 3})

    max, ok := original.Max(func(a, b int) bool { return a > b })

    fmt.Println(max)
    fmt.Println(ok)

    // Output:
    // 4
    // true
}
```

### <span id="Min">Min</span>

<p>Returns the minimum element of this stream according to the provided less function. less fuction: a < b</p>

<b>Signature:</b>

```go
func (s stream[T]) Min(less func(a, b T) bool) (T, bool)
```

<b>Example:</b>

```go
import (
    "fmt"
    "github.com/duke-git/lancet/v2/stream"
)

func main() {
    original := stream.FromSlice([]int{4, 2, 1, 3})

    min, ok := original.Min(func(a, b int) bool { return a < b })

    fmt.Println(min)
    fmt.Println(ok)

    // Output:
    // 1
    // true
}
```

### <span id="AllMatch">AllMatch</span>

<p>Returns whether all elements of this stream match the provided predicate.</p>

<b>Signature:</b>

```go
func (s stream[T]) AllMatch(predicate func(item T) bool) bool
```

<b>Example:</b>

```go
import (
    "fmt"
    "github.com/duke-git/lancet/v2/stream"
)

func main() {
    original := stream.FromSlice([]int{1, 2, 3})

    result1 := original.AllMatch(func(item int) bool {
        return item > 0
    })

    result2 := original.AllMatch(func(item int) bool {
        return item > 1
    })

    fmt.Println(result1)
    fmt.Println(result2)

    // Output:
    // true
    // false
}
```

### <span id="AnyMatch">AnyMatch</span>

<p>Returns whether any elements of this stream match the provided predicate.</p>

<b>Signature:</b>

```go
func (s stream[T]) AnyMatch(predicate func(item T) bool) bool
```

<b>Example:</b>

```go
import (
    "fmt"
    "github.com/duke-git/lancet/v2/stream"
)

func main() {
    original := stream.FromSlice([]int{1, 2, 3})

    result1 := original.AnyMatch(func(item int) bool {
        return item > 1
    })

    result2 := original.AnyMatch(func(item int) bool {
        return item > 3
    })

    fmt.Println(result1)
    fmt.Println(result2)

    // Output:
    // true
    // false
}
```

### <span id="NoneMatch">NoneMatch</span>

<p>Returns whether no elements of this stream match the provided predicate.</p>

<b>Signature:</b>

```go
func (s stream[T]) NoneMatch(predicate func(item T) bool) bool
```

<b>Example:</b>

```go
import (
    "fmt"
    "github.com/duke-git/lancet/v2/stream"
)

func main() {
    original := stream.FromSlice([]int{1, 2, 3})

    result1 := original.NoneMatch(func(item int) bool {
        return item > 3
    })

    result2 := original.NoneMatch(func(item int) bool {
        return item > 1
    })

    fmt.Println(result1)
    fmt.Println(result2)

    // Output:
    // true
    // false
}
```

### <span id="Count">Count</span>

<p>Returns the count of elements in the stream.</p>

<b>Signature:</b>

```go
func (s stream[T]) Count() int
```

<b>Example:</b>

```go
import (
    "fmt"
    "github.com/duke-git/lancet/v2/stream"
)

func main() {
    s1 := stream.FromSlice([]int{1, 2, 3})
    s2 := stream.FromSlice([]int{})

    fmt.Println(s1.Count())
    fmt.Println(s2.Count())

    // Output:
    // 3
    // 0
}
```

### <span id="ToSlice">ToSlice</span>

<p>Returns the elements in the stream.</p>

<b>Signature:</b>

```go
func (s stream[T]) ToSlice() []T
```

<b>Example:</b>

```go
import (
    "fmt"
    "github.com/duke-git/lancet/v2/stream"
)

func main() {
    s := stream.Of(1, 2, 3)

    data := s.ToSlice()

    fmt.Println(data)

    // Output:
    // [1 2 3]
}
```