docs(package): add simple README.md and package descriptions

.woodpecker/.test.yml

@@ -5,7 +5,6 @@ when:
 
 steps:
   test:
-    group: test
     image: golang:1.22-alpine
     commands:
       - go test -v ./...

README.md

@@ -0,0 +1,5 @@
+# `collections`
+
+[![Go Report Card](https://goreportcard.com/badge/pkg.icikowski.pl/collections)](https://goreportcard.com/report/pkg.icikowski.pl/collections)
+
+Collections and stream-like operations for Go.

collection.go

@@ -9,7 +9,7 @@ import (
 	"pkg.icikowski.pl/collections/functions"
 )
 
-// Collection represents the collection of data
+// Collection represents the collection of data.
 //
 // By default, the collection uses parallel implementation of operators.
 type Collection[T any] struct {
@@ -17,23 +17,23 @@ type Collection[T any] struct {
 	parallel bool
 }
 
-// Count counts values in the collection
+// Count counts values in the collection.
 func (s *Collection[T]) Count() int {
 	return len(s.data)
 }
 
-// Epty determines whether the collection is empty
+// Epty determines whether the collection is empty.
 func (s *Collection[T]) Empty() bool {
 	return len(s.data) == 0
 }
 
-// Parallel sets the collection to use parallel implementation of operators
+// Parallel sets the collection to use parallel implementation of operators.
 func (s *Collection[T]) Parallel() *Collection[T] {
 	s.parallel = true
 	return s
 }
 
-// Sequential sets the collection to use sequential implementation of operators
+// Sequential sets the collection to use sequential implementation of operators.
 func (s *Collection[T]) Sequential() *Collection[T] {
 	s.parallel = false
 	return s
@@ -73,7 +73,7 @@ func (s *Collection[T]) filterSequential(p functions.Predicate[T]) *Collection[T
 	return s
 }
 
-// Filter filters the collection using given [functions.Predicate]
+// Filter filters the collection using given [functions.Predicate].
 func (s *Collection[T]) Filter(p functions.Predicate[T]) *Collection[T] {
 	if s.parallel {
 		return s.filterParallel(p)
@@ -113,7 +113,7 @@ func (s *Collection[T]) allMatchSequential(p functions.Predicate[T]) bool {
 	return true
 }
 
-// AllMatch checks whether all elements in collection match given [functions.Predicate]
+// AllMatch checks whether all elements in collection match given [functions.Predicate].
 func (s *Collection[T]) AllMatch(p functions.Predicate[T]) bool {
 	if s.parallel {
 		return s.allMatchParallel(p)
@@ -153,7 +153,7 @@ func (s *Collection[T]) anyMatchSequential(p functions.Predicate[T]) bool {
 	return false
 }
 
-// AnyMatch checks whether any elements in collection match given [functions.Predicate]
+// AnyMatch checks whether any elements in collection match given [functions.Predicate].
 func (s *Collection[T]) AnyMatch(p functions.Predicate[T]) bool {
 	if s.parallel {
 		return s.anyMatchParallel(p)
@@ -193,7 +193,7 @@ func (s *Collection[T]) noneMatchSequential(p functions.Predicate[T]) bool {
 	return true
 }
 
-// NoneMatch checks whether no elements in collection match given [functions.Predicate]
+// NoneMatch checks whether no elements in collection match given [functions.Predicate].
 func (s *Collection[T]) NoneMatch(p functions.Predicate[T]) bool {
 	if s.parallel {
 		return s.noneMatchParallel(p)
@@ -201,7 +201,7 @@ func (s *Collection[T]) NoneMatch(p functions.Predicate[T]) bool {
 	return s.noneMatchSequential(p)
 }
 
-// Sorted sorts the collection using given [functions.Comparator]
+// Sorted sorts the collection using given [functions.Comparator].
 func (s *Collection[T]) Sorted(c functions.Comparator[T]) *Collection[T] {
 	sort.SliceStable(s.data, func(i, j int) bool {
 		return c(s.data[i], s.data[j])
@@ -232,7 +232,7 @@ func (s *Collection[T]) peekSequential(c functions.Consumer[T]) *Collection[T] {
 	return s
 }
 
-// Peek executes given [function.Consumer] on every value in collections
+// Peek executes given [function.Consumer] on every value in collections.
 func (s *Collection[T]) Peek(c functions.Consumer[T]) *Collection[T] {
 	if s.parallel {
 		return s.peekParallel(c)
@@ -267,7 +267,7 @@ func (s *Collection[T]) transformSequential(u functions.UnaryOperator[T]) *Colle
 	return s
 }
 
-// Transform transforms all values in collection using given [functions.UnaryOperator]
+// Transform transforms all values in collection using given [functions.UnaryOperator].
 func (s *Collection[T]) Transform(u functions.UnaryOperator[T]) *Collection[T] {
 	if s.parallel {
 		return s.transformParallel(u)
@@ -275,7 +275,7 @@ func (s *Collection[T]) Transform(u functions.UnaryOperator[T]) *Collection[T] {
 	return s.transformSequential(u)
 }
 
-// Reduce reduces values in given collection using given [functions.BinaryOperator]
+// Reduce reduces values in given collection using given [functions.BinaryOperator].
 func (s *Collection[T]) Reduce(b functions.BinaryOperator[T]) T {
 	processed := *new(T)
 	if len(s.data) == 0 {
@@ -288,7 +288,7 @@ func (s *Collection[T]) Reduce(b functions.BinaryOperator[T]) T {
 	return processed
 }
 
-// Limit limits the collection to given number of values
+// Limit limits the collection to given number of values.
 func (s *Collection[T]) Limit(n int) *Collection[T] {
 	if len(s.data) < n {
 		return s
@@ -302,7 +302,7 @@ func (s *Collection[T]) Limit(n int) *Collection[T] {
 	return s
 }
 
-// Skip skips given number of values in the collection
+// Skip skips given number of values in the collection.
 func (s *Collection[T]) Skip(n int) *Collection[T] {
 	if len(s.data) == 0 {
 		return s
@@ -316,7 +316,7 @@ func (s *Collection[T]) Skip(n int) *Collection[T] {
 	return s
 }
 
-// FindFirst returns [Optional] with first item of the collection
+// FindFirst returns [Optional] with first item of the collection.
 func (s *Collection[T]) FindFirst() *Optional[T] {
 	e, present := *new(T), false
 	if len(s.data) != 0 {
@@ -325,7 +325,7 @@ func (s *Collection[T]) FindFirst() *Optional[T] {
 	return &Optional[T]{e, present}
 }
 
-// FindFirst returns [Optional] with last item of the collection
+// FindFirst returns [Optional] with last item of the collection.
 func (s *Collection[T]) FindLast() *Optional[T] {
 	e, present := *new(T), false
 	if len(s.data) != 0 {
@@ -334,17 +334,17 @@ func (s *Collection[T]) FindLast() *Optional[T] {
 	return &Optional[T]{e, present}
 }
 
-// Min returns the lowest value from the collection using given [functions.Comparator]
+// Min returns the lowest value from the collection using given [functions.Comparator].
 func (s *Collection[T]) Min(c functions.Comparator[T]) *Optional[T] {
 	return s.Sorted(c).FindFirst()
 }
 
-// Max returns the highest value from the collection using given [functions.Comparator]
+// Max returns the highest value from the collection using given [functions.Comparator].
 func (s *Collection[T]) Max(c functions.Comparator[T]) *Optional[T] {
 	return s.Sorted(c).FindLast()
 }
 
-// Distinct ensures that all elements in the collecion are unique
+// Distinct ensures that all elements in the collecion are unique.
 func (s *Collection[T]) Distinct() *Collection[T] {
 	processed := []T{}
 	for i := 0; i < len(s.data); i++ {
@@ -363,7 +363,7 @@ func (s *Collection[T]) Distinct() *Collection[T] {
 	return s
 }
 
-// MapCollection maps collection of values of type T to collection of values of type U using given [functions.Function]
+// MapCollection maps collection of values of type T to collection of values of type U using given [functions.Function].
 func MapCollection[T, U any](src *Collection[T], mapper functions.Function[T, U]) *Collection[U] {
 	data := []U{}
 	for _, e := range src.data {
@@ -372,7 +372,7 @@ func MapCollection[T, U any](src *Collection[T], mapper functions.Function[T, U]
 	return &Collection[U]{data, src.parallel}
 }
 
-// Collect returns all items from collection as a slice
+// Collect returns all items from collection as a slice.
 func (s *Collection[T]) Collect() []T {
 	return s.data
 }

collection_test.go

@@ -13,14 +13,14 @@ import (
 //go:embed collection_test.csv
 var testData []byte
 
-type person struct {
+func TestCollection(t *testing.T) {
+	type person struct {
 		ID        int
 		LastName  string
 		FirstName string
 		Email     string
-}
+	}
 
-func TestCollection(t *testing.T) {
 	data := strings.Split(string(testData), "\n")
 
 	lines := OfSlice(data).Skip(1).Filter(func(s string) bool {

comparators/numeric.go

@@ -2,7 +2,7 @@ package comparators
 
 import "pkg.icikowski.pl/collections/functions"
 
-// CompareNumeric returns comparator for numeric values
+// CompareNumeric returns comparator for numeric values.
 func CompareNumeric[T ~int | ~int8 | ~int16 | ~int32 | ~int64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr | ~float32 | ~float64]() functions.Comparator[T] {
 	return func(a, b T) bool {
 		return a < b

comparators/package.go

@@ -1,4 +1,4 @@
 /*
-Handy comparators
+Handy comparators.
 */
 package comparators

comparators/string.go

@@ -6,7 +6,7 @@ import (
 	"pkg.icikowski.pl/collections/functions"
 )
 
-// CompareString returns [functions.Comparator] for string values in given language
+// CompareString returns [functions.Comparator] for string values in given language.
 func CompareString(lang language.Tag) functions.Comparator[string] {
 	c := collate.New(lang)
 	return func(a, b string) bool {

functions.go

@@ -2,17 +2,17 @@ package collections
 
 import "pkg.icikowski.pl/collections/functions"
 
-// Of creates [Collection] of given items
+// Of creates [Collection] of given items.
 func Of[T any](data ...T) *Collection[T] {
 	return &Collection[T]{data, true}
 }
 
-// OfSlice creates [Collection] of given slice elements
+// OfSlice creates [Collection] of given slice elements.
 func OfSlice[T any](data []T) *Collection[T] {
 	return &Collection[T]{data, true}
 }
 
-// Iterate creates [Collection] of given number of items generated from given seed and [functions.UnaryOperator]
+// Iterate creates [Collection] of given number of items generated from given seed and [functions.UnaryOperator].
 func Iterate[T any](seed T, u functions.UnaryOperator[T], limit int) *Collection[T] {
 	if limit <= 0 {
 		limit = 1
@@ -25,7 +25,7 @@ func Iterate[T any](seed T, u functions.UnaryOperator[T], limit int) *Collection
 	return &Collection[T]{data, true}
 }
 
-// Generate creates [Collection] of given number of items generated from given [functions.Supplier]
+// Generate creates [Collection] of given number of items generated from given [functions.Supplier].
 func Generate[T any](p functions.Supplier[T], limit int) *Collection[T] {
 	if limit < 0 {
 		limit = 0

functions/package.go

@@ -1,4 +1,4 @@
 /*
-Function types
+Function types.
 */
 package functions

functions/types.go

@@ -1,24 +1,24 @@
 package functions
 
 type (
-	// Consumer takes an argument of type T and returns nothing
+	// Consumer takes an argument of type T and returns nothing.
 	Consumer[T any] func(T)
 
-	// Function takes an argument of type T and returns a result of type U
+	// Function takes an argument of type T and returns a result of type U.
 	Function[T, U any] func(T) U
 
-	// Predicate takes an argument of type T and returns a boolean result
+	// Predicate takes an argument of type T and returns a boolean result.
 	Predicate[T any] func(T) bool
 
-	// Supplier takes no argument and returns a result of type T
+	// Supplier takes no argument and returns a result of type T.
 	Supplier[T any] func() T
 
-	// UnaryOperator takes an argument of type T and returns a result of type T
+	// UnaryOperator takes an argument of type T and returns a result of type T.
 	UnaryOperator[T any] func(T) T
 
-	// BinaryOperator takes two arguments of type T and returns a result of type T
+	// BinaryOperator takes two arguments of type T and returns a result of type T.
 	BinaryOperator[T any] func(T, T) T
 
-	// Comparator takes two arguments of type T and returns a boolean result
+	// Comparator takes two arguments of type T and returns a boolean result.
 	Comparator[T any] func(T, T) bool
 )

go.mod

@@ -3,8 +3,8 @@ module pkg.icikowski.pl/collections
 go 1.20
 
 require (
-	github.com/stretchr/testify v1.8.4
-	golang.org/x/text v0.11.0
+	github.com/stretchr/testify v1.9.0
+	golang.org/x/text v0.15.0
 )
 
 require (

go.sum

@@ -2,10 +2,10 @@ github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
-github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
-golang.org/x/text v0.11.0 h1:LAntKIrcmeSKERyiOh0XMV39LXS8IE9UL2yP7+f5ij4=
-golang.org/x/text v0.11.0/go.mod h1:TvPlkZtksWOMsz7fbANvkp4WM8x/WCo/om8BMLbz+aE=
+github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
+github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+golang.org/x/text v0.15.0 h1:h1V/4gjBv8v9cjcR6+AR5+/cIYK5N/WAgiv4xlsEtAk=
+golang.org/x/text v0.15.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

optional.go

@@ -2,23 +2,23 @@ package collections
 
 import "pkg.icikowski.pl/collections/functions"
 
-// Optional represents an optional value of type T
+// Optional represents an optional value of type T.
 type Optional[T any] struct {
 	e       T
 	present bool
 }
 
-// IsPresent determines whether the underlying value is present
+// IsPresent determines whether the underlying value is present.
 func (o *Optional[T]) IsPresent() bool {
 	return o.present
 }
 
-// Get returns the underlying value
+// Get returns the underlying value.
 func (o *Optional[T]) Get() T {
 	return o.e
 }
 
-// OrElse returns the underlying value or given value if underlying value is not present
+// OrElse returns the underlying value or given value if underlying value is not present.
 func (o *Optional[T]) OrElse(e T) T {
 	if !o.present {
 		return e
@@ -26,7 +26,7 @@ func (o *Optional[T]) OrElse(e T) T {
 	return o.e
 }
 
-// OrElseGet returns the underlying value or value from given supplier if underlying value is not present
+// OrElseGet returns the underlying value or value from given supplier if underlying value is not present.
 func (o *Optional[T]) OrElseGet(s functions.Supplier[T]) T {
 	if !o.present {
 		return s()
@@ -34,7 +34,7 @@ func (o *Optional[T]) OrElseGet(s functions.Supplier[T]) T {
 	return o.e
 }
 
-// Transform transforms the underlying value with given [functions.UnaryOperator] if the vale is present
+// Transform transforms the underlying value with given [functions.UnaryOperator] if the vale is present.
 func (o *Optional[T]) Transform(u functions.UnaryOperator[T]) *Optional[T] {
 	if o.present {
 		o.e = u(o.e)
@@ -42,7 +42,7 @@ func (o *Optional[T]) Transform(u functions.UnaryOperator[T]) *Optional[T] {
 	return o
 }
 
-// MapOptional maps optional of type T to optional of type U using given [functions.Function]
+// MapOptional maps optional of type T to optional of type U using given [functions.Function].
 func MapOptional[T, U any](src *Optional[T], mapper functions.Function[T, U]) *Optional[U] {
 	return &Optional[U]{mapper(src.e), src.present}
 }

package.go

@@ -1,4 +1,4 @@
 /*
-Collections-related types and functions
+Collections and stream-like operations for Go.
 */
 package collections