wesovilabs / koazee

A StreamLike, Immutable, Lazy Loading and smart Golang Library to deal with slices.

Koazee

Lazy like a koala, smart like a chimpanzee

What is Koazee?

Koazee is a StreamLike, Immutable, Lazy Loading and smart Golang Library to deal with slices.

Visit the Koazee wiki to find out what Koazee can do.

Koazee Highlights

• Immutable: Koazee won't modify your inputs. 
• StreamLike: We can combine operations up our convenience. 
• Lazy loading: Operations are not performed until they're required
• Generic: Koazee provides a generic interface able to deal with slice of any type without creating custom functions.
• Focusing on performance: First rule for implementing a new operation is providing the best possible performance.

Getting started

Installing

Add Koazee to your project

Go modules

module github.com/me/project
require ( 
  github.com/wesovilabs/koazee vX.Y.Z
)

Glide

glide get github.com/wesovilabs/koazee

Go dep

go get github.com/wesovilabs/koazee

Usage

Stream creation

Let's first obtain a stream from an existing array.

package main

import (
	"fmt"
	"github.com/wesovilabs/koazee"
)

var numbers = []int{1, 5, 4, 3, 2, 7, 1, 8, 2, 3}

func main() {
	fmt.Printf("slice: %v\n", numbers)
	stream := koazee.StreamOf(numbers)
	fmt.Printf("stream: %v\n", stream.Out().Val())
}

/**
go run main.go

slice: [1 5 4 3 2 7 1 8 2 3]
stream: [1 5 4 3 2 7 1 8 2 3]
*/

Stream operations

Current release v0.0.3 (Gibbon) brings us 20 generic operations that are showed below

stream.At / stream.First / stream.Last

These operations return an element from the stream

package main

import (
	"fmt"
	"github.com/wesovilabs/koazee"
)

var numbers = []int{1, 5, 4, 3, 2, 7, 1, 8, 2, 3}

func main() {
	stream := koazee.StreamOf(numbers)
	fmt.Printf("stream.At(4): %d\n", stream.At(4).Int())
	fmt.Printf("stream.First: %d\n", stream.First().Int())
	fmt.Printf("stream.Last: %d\n", stream.Last().Int())
}

/**
go run main.go

stream.At(4): 2
stream.First: 1
stream.Last: 3
*/

stream.Add / stream.Drop / stream.DropWhile / stream.DeleteAt / stream.Pop / stream.Set

These operations add or delete elements from the stream.

package main

import (
	"fmt"
	"github.com/wesovilabs/koazee"
)

var numbers = []int{1, 5, 4, 3, 2, 7, 1, 8, 2, 3}

func main() {
	fmt.Printf("input: %v\n", numbers)

	stream := koazee.StreamOf(numbers)
	fmt.Print("stream.Add(10): ")
	fmt.Println(stream.Add(10).Do().Out().Val())

	fmt.Print("stream.Drop(5): ")
	fmt.Println(stream.Drop(5).Do().Out().Val())
	
	fmt.Print("stream.DropWhile(val<=5): ")
	fmt.Println(stream.DropWhile(func(element int)bool{return element<=5}).Do().Out().Val())

	fmt.Print("stream.DeleteAt(4): ")
	fmt.Println(stream.DeleteAt(4).Do().Out().Val())

	fmt.Print("stream.Set(0,5): ")
	fmt.Println(stream.Set(0, 5).Do().Out().Val())

	fmt.Print("stream.Pop(): ")
	val, newStream := stream.Pop()
	fmt.Printf("%d ... ", val.Int())
	fmt.Println(newStream.Out().Val())

}

/**
go run main.go

input: [1 5 4 3 2 7 1 8 2 3]
stream.Add(10): [1 5 4 3 2 7 1 8 2 3 10]
stream.Drop(5): [1 4 3 2 7 1 8 2 3]
stream.DropWhile(val<=5): [7 8]
stream.DeleteAt(4): [1 5 4 3 7 1 8 2 3]
stream.Set(0,5): [5 5 4 3 2 7 1 8 2 3]
stream.Pop(): 1 ... [5 4 3 2 7 1 8 2 3]
*/

tream.Count / stream.IndexOf / stream.IndexesOf / stream.LastIndexOf / stream.Contains

These operations return info from the elements in the stream

package main

import (
	"fmt"
	"github.com/wesovilabs/koazee"
)

var numbers = []int{1, 5, 4, 3, 2, 7, 1, 8, 2, 3}

func main() {
	fmt.Printf("input: %v\n", numbers)
	stream := koazee.StreamOf(numbers)
	count, _ := stream.Count()
	fmt.Printf("stream.Count(): %d\n", count)
	index, _ := stream.IndexOf(2)
	fmt.Printf("stream.IndexOf(2): %d\n", index)
	indexes, _ := stream.IndexesOf(2)
    fmt.Printf("stream.IndexesOf(2): %d\n", indexes)
	index, _ = stream.LastIndexOf(2)
	fmt.Printf("stream.LastIndexOf(2): %d\n", index)
	contains, _ := stream.Contains(7)
	fmt.Printf("stream.Contains(7): %v\n", contains)
}

/**
go run main.go

input: [1 5 4 3 2 7 1 8 2 3]
stream.Count(): 10
stream.IndexOf(2): 4
stream.IndexesOf(2): [4 8]
stream.LastIndexOf(2): 8
stream.Contains(7): true
*/

stream.Sort / stream.Reverse

These operations organize the elements in the stream.

package main

import (
	"fmt"
	"github.com/wesovilabs/koazee"
	"strings"
)

var animals = []string{"lynx", "dog", "cat", "monkey", "fox", "tiger", "lion"}

func main() {
	fmt.Print("input: ")
	fmt.Println(animals)
	stream := koazee.StreamOf(animals)

	fmt.Print("stream.Reverse(): ")
	fmt.Println(stream.Reverse().Out().Val())

	fmt.Print("stream.Sort(strings.Compare): ")
	fmt.Println(stream.Sort(strings.Compare).Out().Val())

}

/**
go run main.go

input: [lynx dog cat monkey fox tiger lion]
stream.Reverse(): [lion tiger fox monkey cat dog lynx]
stream.Sort(strings.Compare): [cat dog fox lion lynx monkey tiger]
*/

stream.Take / stream.Filter / stream.RemoveDuplicates

These operations return a filtered stream.

package main

import (
	"fmt"
	"github.com/wesovilabs/koazee"
)

var animals = []string{"lynx", "dog", "cat", "monkey", "dog", "fox", "tiger", "lion"}

func main() {
	fmt.Print("input: ")
	fmt.Println(animals)
	stream := koazee.StreamOf(animals)

	fmt.Print("stream.Take(1,4): ")
	fmt.Println(stream.Take(1, 4).Out().Val())

	fmt.Print("stream.Filter(len==4): ")
	fmt.Println(stream.
		Filter(
			func(val string) bool {
				return len(val) == 4
			}).
		Out().Val(),
	)
	fmt.Print("stream.RemoveDuplicates(): ")
	fmt.Println(stream.RemoveDuplicates().Out().Val())
}

/**
go run main.go

input: [lynx dog cat monkey dog fox tiger lion]
stream.Take(1,4): [dog cat monkey dog]
stream.Filter(len==4): [lynx lion]
stream.RemoveDuplicates(): [lynx dog cat monkey fox tiger lion]
*/

stream.GroupBy

This operation creates groups depending on the returned function value

You can now optionally return an error as the second parameter to stop processing of the stream. The error will be available in stream.Out().Err().UserError().

package main

import (
	"fmt"
	"github.com/wesovilabs/koazee"
	"strings"
)

var animals = []string{"lynx", "dog", "cat", "monkey", "dog", "fox", "tiger", "lion"}

func main() {
	fmt.Printf("input: %v\n", animals)
	stream := koazee.StreamOf(animals)
	fmt.Print("stream.GroupBy(strings.Len): ")
	out, _ := stream.GroupBy(func(val string)int{return len(val)})
	fmt.Println(out)
}

/**
go run main.go

input: [lynx dog cat monkey dog fox tiger lion]
stream.GroupBy(strings.Len): map[5:[tiger] 4:[lynx lion] 3:[dog cat dog fox] 6:[monkey]]
*/

stream.Map

This operation performs a modification over all the elements in the stream.

You can now optionally return an error as the second parameter to stop processing of the stream. The error will be available in stream.Out().Err().UserError().

package main

import (
	"fmt"
	"github.com/wesovilabs/koazee"
	"strings"
)

var animals = []string{"lynx", "dog", "cat", "monkey", "dog", "fox", "tiger", "lion"}

func main() {
	fmt.Printf("input: %v\n", animals)
	stream := koazee.StreamOf(animals)
	fmt.Print("stream.Map(strings.Title): ")
	fmt.Println(stream.Map(strings.Title).Do().Out().Val())
}

/**
go run main.go

input: [lynx dog cat monkey dog fox tiger lion]
stream.Map(strings.Title): [Lynx Dog Cat Monkey Dog Fox Tiger Lion]
*/

stream.Reduce

This operation give us a single output after iterating over the elements in the stream.

You can now optionally return an error as the second parameter to stop processing of the stream. The error will be available in stream.Out().Err().UserError().

package main

import (
	"fmt"
	"github.com/wesovilabs/koazee"
)

var numbers = []int{1, 5, 4, 3, 2, 7, 1, 8, 2, 3}

func main() {
	fmt.Printf("input: %v\n", numbers)
	stream := koazee.StreamOf(numbers)
	fmt.Print("stream.Reduce(sum): ")
	fmt.Println(stream.Reduce(func(acc, val int) int {
		return acc + val
	}).Int())
}

/**
go run main.go

input: [1 5 4 3 2 7 1 8 2 3]
stream.Reduce(sum): 36
*/

stream.ForEach

This operation iterates over the element in the stream.

You can now optionally return an error as the second parameter to stop processing of the stream. The error will be available in stream.Out().Err().UserError().

package main

import (
	"fmt"
	"github.com/wesovilabs/koazee"
)

type message struct {
	user    string
	message string
}

var messages = []*message{
	{user: "John", message: "Hello Jane"},
	{user: "Jane", message: "Hey John, how are you?"},
	{user: "John", message: "I'm fine! and you?"},
	{user: "Jane", message: "Me too"},
}

func main() {

	stream := koazee.StreamOf(messages)
	stream.ForEach(func(m *message) {
		fmt.Printf("%s: \"%s\"\n", m.user, m.message)
	}).Do()
}

/**
go run main.go

John: "Hello Jane"
Jane: "Hey John, how are you?"
John: "I'm fine! and you?"
Jane: "Me too"
*/

Combine operations and evaluate them lazily

The main goal of Koazee is providing a set of operations that can be combined and being evaluated lazily.

package main

import (
	"fmt"
	"github.com/wesovilabs/koazee"
	"strings"
)

type Person struct {
	Name string
	Male bool
	Age  int
}

var people = []*Person{
	{"John Smith", true, 32},
	{"Peter Pan", true, 17},
	{"Jane Doe", false, 20},
	{"Anna Wallace", false, 35},
	{"Tim O'Brian", true, 13},
	{"Celia Hills", false, 15},
}

func main() {
	stream := koazee.
		StreamOf(people).
		Filter(func(person *Person) bool {
			return !person.Male
		}).
		Sort(func(person, otherPerson *Person) int {
			return strings.Compare(person.Name, otherPerson.Name)
		}).
		ForEach(func(person *Person) {
			fmt.Printf("%s is %d years old\n", person.Name, person.Age)
		})

	fmt.Println("Operations are not evaluated until we perform stream.Do()\n")
	stream.Do()
}

/**
go run main.go

Operations are not evaluated until we perform stream.Do()

Anna Wallace is 35 years old
Celia Hills is 15 years old
Jane Doe is 20 years old
 */

Available Operations

Operation	Description	Since
Add	It adds a new element in the last position	v0.0.1
At	It returns the element in the given position	v0.0.1
Contains	It checks if the given element is found in the stream.	v0.0.1
Count	It returns the number of elements in a stream	v0.0.1
DeleteAt	It remove the elements in the given position	v0.0.3
Drop	It removes an element from the stream	v0.0.1
DropWhile	It removes the elements in the stream that match with the given input function	v0.0.4
Filter	It discards those elements that doesn't match with the provided filter	v0.0.1
First	It returns the element in the first position	v0.0.1
ForEach	It does something over all the elements in the stream.	v0.0.1
GroupBy	It creates groups depending on the returned function value	v0.0.4
IndexOf	It returns the first index of the element in the stream.	v0.0.3
IndexesOf	It returns the index for all the occurrences of the element in the stream.	v0.0.4
Last	It returns the element in the last position	v0.0.1
LastIndexOf	It returns the last occurrence for the element in the stream.	v0.0.3
Map	It converts the element in the stream	v0.0.1
Pop	It extracts the first element in the stream and return this and the new stream	v0.0.3
Reduce	It reduceshe stream to a single value by executing a provided function for each value of the stream	v0.0.1
RemoveDuplicates	It removes duplicated elements.	v0.0.1
Reverse	It reverses the sequence of elements in the stream.	v0.0.3
Set	It replaces the element in the given index by the provided value	v0.0.3
Sort	It sorts the elements in the stream	v0.0.1
Take	It returns a stream with the elements between the given indexes	v0.0.3

Samples

A rich and growing set of examples can be found on koazee-samples

Benchmark

You can check the Benchmark for the Koazee operations here

A benchmark comparison with other frameworks can be found in Koazee vs Go-Funk vs Go-Linq

Guides & Tutorials

Shopping cart with Koazee

Roadmap

This is only the beginning! By the way, If you missed any operation in Koazee v0.0.3, or you found a bug, please create a new issue on Github or vote the existing ones!

Contributors

• @ivancorrales
• @xuyz
• @u5surf
• @flowonyx