kol

README

kol

kol is a collection package based on Go 1.18+ Generics. It provides List, Set and Sequence like Kotlin collections package. You can operate collections with method-chaining 🔗.

• kotlin.collections
• kotlin.sequences

Out of scope

kol is not a complete reimplementation of the kotlin.collections and kotlin.sequences packages. It is implemented by utilizing Go language features.

🚀 Installation

go get github.com/ichizero/kol

🧐 Example

package main

import (
	"fmt"

	"github.com/ichizero/kol"
)

func main() {
	seq := kol.NewSequence(1, 2, 3, 4, 5).
		Filter(func(e int) bool {
			return e < 3
		}).
		Map(func(e int) int {
			return e * 2
		}).
		Distinct().
		Drop(1).
		Take(2)
	fmt.Println(seq.ToSlice())
}

✨ Features

GoDoc:

List & Set

List backend is a slice of Go.

Set backend is a map of Go. It seems like Kotlin & Java's HashMap, but it cannot be iterated in a sorted order.

	List	Set
All	✅	✅
Any	✅	✅
Contains	✅	✅
Count	✅	✅
Distinct	✅	✅
Filter	✅	✅
FilterIndexed	✅	🚫
Find	✅	✅
ForEach	✅	✅
ForEachIndexed	✅	🚫
Intersect	✅	✅
Iterator	✅	✅
Map	✅	✅
MapIndexed	✅	🚫
Minus	✅	✅
None	✅	✅
Plus	✅	✅
Single	✅	✅
Subtract	✅	✅
Union	✅	✅

Sequence

Sequence enables us to lazy evaluation of a collection. In some cases, the process is faster than list operations.

For more details, please refer to the following documents.

• Kotlin docs: Sequence processing example

	Sequence
Distinct	✅
Filter	✅
Map	✅
Take	✅
Drop	✅

⚠️ Limitation

Map

Because of the Go Generics specification, Map methods in each interface cannot convert an element type. You can use MapList, MapSet and MapSequence instead.

MapList(
    NewList(1, 2, 3).
        Map(func(e int) int {
            return e * 2
        }),
    func(e int) string {
        return strconv.Itoa(e)
    })

Documentation

Index

• type Collection
• type Iterable
• type Iterator
• type List
  • func MapList[E1 comparable, E2 comparable](collection Collection[E1], transform func(E1) E2) List[E2]
  • func NewList[E comparable](elements ...E) List[E]
• type Sequence
  • func MapSequence[E1 comparable, E2 comparable](seq Sequence[E1], predicate func(E1) E2) Sequence[E2]
  • func NewSequence[E comparable](elements ...E) Sequence[E]
• type Set
  • func MapSet[E1 comparable, E2 comparable](collection Collection[E1], transform func(E1) E2) Set[E2]
  • func NewSet[E comparable](elements ...E) Set[E]

Examples

• List
• Sequence
• Set

Types

type Collection

type Collection[E comparable] interface {
	Iterable[E]

	// Add adds specified elements.
	Add(elements ...E)
	// Clear removes all elements.
	Clear()
	// IsEmpty returns `true` if the collection is empty, `false` otherwise.
	IsEmpty() bool
	// Remove removes specified elements.
	Remove(elements ...E)
	// Retain retains only elements in this collection that are contained in specified elements.
	Retain(elements ...E)
	// Size is size of this collection.
	Size() int
}

Collection is a generic collection of elements.

type Iterable

type Iterable[E comparable] interface {
	// All returns `true` if all elements match the given predicate.
	All(predicate func(element E) bool) bool
	// Any returns `true` if collection has at least one element matched the given predicate.
	Any(predicate func(element E) bool) bool
	// Contains returns `true` if the given element is found in the collection.
	Contains(element E) bool
	// Count returns the number of elements that matches the given predicate.
	Count(predicate func(element E) bool) int
	// Distinct returns a collection containing only distinct elements.
	Distinct() Collection[E]
	// Filter returns a collection only elements matching the given predicate.
	Filter(predicate func(element E) bool) Collection[E]
	// Find returns the first element matching the given predicate.
	// If there is no such element, it returns `false` as a second return value.
	Find(predicate func(element E) bool) (E, bool)
	// ForEach performs the given action on each element.
	ForEach(action func(element E))
	// Intersect returns a set containing all elements that are contained
	// by both this collection and the specified collection.
	Intersect(other Iterable[E]) Set[E]
	// Map returns a collection containing the result of applying the given transform function to each element.
	Map(transform func(element E) E) Collection[E]
	// Minus returns a collection containing all elements of the original collection except given elements.
	Minus(element ...E) Collection[E]
	// None returns `true` if no elements match the given predicate.
	None(predicate func(element E) bool) bool
	// Plus returns a list containing all elements of the original collection and given elements.
	Plus(element ...E) Collection[E]
	// Single returns the single element matching the given predicate.
	// If there is no such element, it returns `false` as a second return value.
	Single(predicate func(element E) bool) (E, bool)
	// Subtract returns a set containing all elements that are contained by this collection
	// and not contained by the specified collection.
	Subtract(other Iterable[E]) Set[E]
	// ToList converts this collection into List.
	ToList() List[E]
	// ToSet converts this collection into Set.
	ToSet() Set[E]
	// ToSlice converts this collection into slice.
	ToSlice() []E
	// Union returns a set containing all distinct elements from both collections.
	Union(other Iterable[E]) Set[E]
}

type Iterator

type Iterator[E comparable] interface {
	HasNext() bool
	Next() (E, bool)
}

type List

type List[E comparable] interface {
	Collection[E]

	// Drop returns a list containing all elements except first n elements.
	Drop(n uint) Collection[E]
	// DropWhile returns a list containing all elements except first elements that satisfy the given predicate.
	DropWhile(predicate func(element E) bool) Collection[E]
	// ElementAt returns an element at the given index.
	// If the given index is out of range of this collection, it returns `false` as a second return value.
	ElementAt(index int) (E, bool)
	// ElementAtOrElse returns an element at the given index or the result calling of the defaultValue function
	// if the index is out of range of this collection.
	ElementAtOrElse(index int, defaultValue func() E) E
	// FilterIndexed returns a list containing only elements matching the given predicate.
	FilterIndexed(predicate func(idx int, element E) bool) Collection[E]
	// FindLast returns the last element matching the given predicate.
	// If there is no such element, it returns `false` as a second return value.
	FindLast(predicate func(element E) bool) (E, bool)
	// ForEachIndexed performs the given action on each element.
	ForEachIndexed(action func(index int, element E))
	// IndexOf returns an index of the first element matching the given element, or -1 if not preset.
	IndexOf(element E) int
	// IndexOfFirst returns an index of the first element matching the given predicate, or -1 if not present.
	IndexOfFirst(predicate func(element E) bool) int
	// IndexOfLast returns an index of the last element matching the given predicate, or -1 if not present.
	IndexOfLast(predicate func(element E) bool) int
	// MapIndexed returns a list containing the results of applying the given transform function
	// to each element and its index.
	MapIndexed(transform func(idx int, element E) E) Collection[E]
	// Partition splits the original collection in to two lists.
	// If any element returns `true` from the given predicate,
	// it is included in the first list, otherwise it is included in the second list.
	Partition(predicate func(element E) bool) (List[E], List[E])
	// Reversed returns a list with elements in reversed order.
	Reversed() List[E]
	// Shuffled returns a list with elements in shuffled order.
	Shuffled() List[E]
	// Take returns a list containing first n elements.
	Take(n uint) Collection[E]
	// TakeWhile returns a list containing first elements satisfying the given predicate.
	TakeWhile(predicate func(element E) bool) Collection[E]
}

List is an ordered collection of elements.

Example

l1 := NewList(1, 2, 3)
l2 := NewList(2, 3, 4).
	MapIndexed(func(idx int, e int) int {
		return idx + e
	})
fmt.Println(l1.Subtract(l2).ToSlice())

func MapList

func MapList[E1 comparable, E2 comparable](collection Collection[E1], transform func(E1) E2) List[E2]

func NewList

func NewList[E comparable](elements ...E) List[E]

type Sequence

type Sequence[E comparable] interface {
	// Distinct returns a sequence containing only distinct elements.
	Distinct() Sequence[E]
	// Filter returns a sequence containing only elements matching the given predicate.
	Filter(predicate func(element E) bool) Sequence[E]
	// Map returns a sequence containing the results of applying the given transform function to each element.
	Map(predicate func(element E) E) Sequence[E]
	// Take returns a sequence containing first n elements.
	Take(n int) Sequence[E]
	// Drop returns a sequence containing all elements except first n elements.
	Drop(n int) Sequence[E]
	// ToList evaluate each element and returns it as a List.
	ToList() List[E]
	// ToSlice evaluate each element and returns it as a slice.
	ToSlice() []E
}

Sequence returns lazily evaluated values.

Example

seq := NewSequence(1, 2, 3, 4, 5).
	Filter(func(e int) bool {
		return e < 3
	}).
	Map(func(e int) int {
		return e * 2
	}).
	Distinct().
	Drop(1).
	Take(2)
fmt.Println(seq.ToSlice())

func MapSequence

func MapSequence[E1 comparable, E2 comparable](seq Sequence[E1], predicate func(E1) E2) Sequence[E2]

func NewSequence

func NewSequence[E comparable](elements ...E) Sequence[E]

type Set

type Set[E comparable] interface {
	Collection[E]
}

Set is an un-ordered collection of elements without duplicate elements.

Example

s1 := NewSet(1, 2, 3, 3, 3)
s2 := NewSet(2, 3, 4).
	Map(func(e int) int {
		return e + 1
	})
fmt.Println(s1.Union(s2).ToSlice())

func MapSet

func MapSet[E1 comparable, E2 comparable](collection Collection[E1], transform func(E1) E2) Set[E2]

func NewSet

func NewSet[E comparable](elements ...E) Set[E]