docs

functions.go

@@ -46,22 +46,35 @@ func OrderAsc[T Ordered](a, b T) bool {
 	return a > b
 }
 
+// Println prints the value of the provided argument v to the standard output.
+// It can accept any type of value due to the use of a type parameter T.
 func Println[T any](v T) {
 	fmt.Println(v)
 }
 
+// Min returns true if the first argument a is greater than the second argument b.
+// It is intended to be used with types that implement the Ordered interface,
+// which allows for comparison operations.
 func Min[T Ordered](a, b T) bool {
 	return a > b
 }
 
+// Max returns true if the first argument a is less than the second argument b.
+// It is intended to be used with types that implement the Ordered interface,
+// which allows for comparison operations.
 func Max[T Ordered](a, b T) bool {
 	return a < b
 }
 
+// Sum returns the sum of two numbers a and b.
+// It is intended to be used with types that implement the Number interface,
+// which allows for addition operations.
 func Sum[T Number](a, b T) T {
 	return a + b
 }
 
+// FindPosition returns a function that checks if a given value x is equal to the specified position p.
+// The returned function takes a single argument of type T and returns true if it matches p.
 func FindPosition[T Number](p T) func(T) bool {
 	return func(x T) bool {
 		return x == p

integration.go

@@ -1,5 +1,7 @@
 package steams
 
+// Distinct returns a new Steam containing only the unique elements from the input Steam.
+// It uses a map to track seen elements and filters out duplicates.
 func Distinct[T comparable](s Steam[T]) Steam[T] {
 	m := make(map[T]bool)
 	slice := s.Collect()
@@ -13,6 +15,9 @@ func Distinct[T comparable](s Steam[T]) Steam[T] {
 	return results
 }
 
+// CollectSteamToSteam2 transforms a Steam of type T into a Steam2 of key-value pairs,
+// where keys and values are derived from the provided keyFunc and valueFunc.
+// It collects elements from the input Steam and maps them to a new Steam2 instance.
 func CollectSteamToSteam2[K comparable, V, T any](s Steam[T], keyFunc func(T) K, valueFunc func(T) V) Steam2[K, V] {
 	m := make(map[K]V)
 	for _, v := range s.Collect() {
@@ -21,6 +26,8 @@ func CollectSteamToSteam2[K comparable, V, T any](s Steam[T], keyFunc func(T) K,
 	return Map[K, V](m)
 }
 
+// CollectSteam2ToSteam transforms a Steam2 of key-value pairs into a Steam of type R,
+// using the provided mapper function to convert each key-value pair into a single value of type R.
 func CollectSteam2ToSteam[K comparable, V, R any](s Steam2[K, V], mapper func(K, V) R) Steam[R] {
 	m := s.Collect()
 	results := make([]R, len(m))
@@ -32,11 +39,13 @@ func CollectSteam2ToSteam[K comparable, V, R any](s Steam2[K, V], mapper func(K,
 	return List[R](results)
 }
 
+// GroupBy groups elements of a Steam by a classifier function that maps each element to a key.
+// It returns a Steam2 where each key corresponds to a Steam of elements that share that key.
 func GroupBy[K comparable, V any](s Steam[V], classifier func(V) K) Steam2[K, Steam[V]] {
 	m := make(Map[K, Steam[V]])
 	for _, v := range s.Collect() {
 		c := classifier(v)
-        if _, ok := m[c]; ok {
+		if _, ok := m[c]; ok {
 			m[c] = append(m[c].(List[V]), v)
 		} else {
 			m[c] = append(List[V]{}, v)
@@ -45,19 +54,23 @@ func GroupBy[K comparable, V any](s Steam[V], classifier func(V) K) Steam2[K, St
 	return m
 }
 
+// GroupByCounting groups elements of a Steam by a classifier function and counts the occurrences of each key.
+// It returns a Steam2 where each key corresponds to the count of elements that share that key.
 func GroupByCounting[K comparable, V any](s Steam[V], classifier func(V) K) Steam2[K, int] {
 	m := make(Map[K, int])
 	for _, v := range s.Collect() {
 		c := classifier(v)
-        if _, ok := m[c]; ok {
-			m[c] = m[c]+1
+		if _, ok := m[c]; ok {
+			m[c] = m[c] + 1
 		} else {
 			m[c] = 1
 		}
 	}
 	return m
 }
 
+// Zip combines two Steams into a single Steam of structs, where each struct contains one element from each input Steam.
+// It panics if the two Steams do not have the same length.
 func Zip[T, R any](s1 Steam[T], s2 Steam[R]) Steam[struct {
 	first  T
 	second R
@@ -81,14 +94,18 @@ func Zip[T, R any](s1 Steam[T], s2 Steam[R]) Steam[struct {
 	return result
 }
 
+// Of creates a Steam from a variadic list of elements of type T.
 func Of[T any](args ...T) Steam[T] {
 	return List[T](args)
 }
 
+// OfSlice creates a Steam from a slice of elements of type T.
 func OfSlice[T any](slice []T) Steam[T] {
 	return Of(slice...)
 }
 
+// OfMap creates a Steam2 from a map of key-value pairs.
+// The keys and values are derived from the provided map.
 func OfMap[K comparable, V any](m map[K]V) Steam2[K, V] {
 	return Map[K, V](m)
 }

list.go

@@ -7,12 +7,16 @@ import (
 	"github.com/javiorfo/steams/opt"
 )
 
+// List is a generic type that represents a slice of elements of type T.
+// It provides methods to perform various operations on the list, following a functional programming style.
 type List[T any] []T
 
+// ListOf creates a List from a variadic list of elements of type T and returns it as a Steam.
 func ListOf[T any](args ...T) Steam[T] {
 	return List[T](args)
 }
 
+// Filter returns a new List containing only the elements that match the provided predicate function.
 func (list List[T]) Filter(predicate func(T) bool) Steam[T] {
 	results := make(List[T], 0)
 	for _, v := range list {
@@ -23,6 +27,7 @@ func (list List[T]) Filter(predicate func(T) bool) Steam[T] {
 	return results
 }
 
+// MapToAny applies the provided mapper function to each element in the List and returns a new List of type any.
 func (list List[T]) MapToAny(mapper func(T) any) Steam[any] {
 	results := make(List[any], len(list))
 	for i, v := range list {
@@ -31,6 +36,7 @@ func (list List[T]) MapToAny(mapper func(T) any) Steam[any] {
 	return results
 }
 
+// MapToString applies the provided mapper function to each element in the List and returns a new List of strings.
 func (list List[T]) MapToString(mapper func(T) string) Steam[string] {
 	results := make(List[string], len(list))
 	for i, v := range list {
@@ -39,6 +45,7 @@ func (list List[T]) MapToString(mapper func(T) string) Steam[string] {
 	return results
 }
 
+// MapToInt applies the provided mapper function to each element in the List and returns a new List of integers.
 func (list List[T]) MapToInt(mapper func(T) int) Steam[int] {
 	results := make(List[int], len(list))
 	for i, v := range list {
@@ -47,6 +54,8 @@ func (list List[T]) MapToInt(mapper func(T) int) Steam[int] {
 	return results
 }
 
+// FilterMapToAny filters the elements based on the provided predicate and then maps the remaining elements
+// using the provided mapper function, returning a new List of type any.
 func (list List[T]) FilterMapToAny(predicate func(T) bool, mapper func(T) any) Steam[any] {
 	results := make(List[any], 0)
 	for _, v := range list {
@@ -57,6 +66,8 @@ func (list List[T]) FilterMapToAny(predicate func(T) bool, mapper func(T) any) S
 	return results
 }
 
+// FlatMapToAny applies the provided mapper function to each element in the List, which returns a Steam,
+// and concatenates the results into a single List of type any.
 func (list List[T]) FlatMapToAny(mapper func(T) Steam[any]) Steam[any] {
 	results := make(List[any], 0, list.Count())
 	for _, v := range list {
@@ -65,6 +76,7 @@ func (list List[T]) FlatMapToAny(mapper func(T) Steam[any]) Steam[any] {
 	return results
 }
 
+// Limit restricts the number of elements in the List to the specified limit and returns a new List.
 func (list List[T]) Limit(limit int) Steam[T] {
 	results := make(List[T], 0)
 	for i := 0; i < len(list) && i < limit; i++ {
@@ -73,23 +85,29 @@ func (list List[T]) Limit(limit int) Steam[T] {
 	return results
 }
 
+// Count returns the number of elements in the List.
 func (list List[T]) Count() int {
 	return len(list)
 }
 
+// ForEach applies the provided consumer function to each element in the List.
 func (list List[T]) ForEach(consumer func(T)) {
 	for _, v := range list {
 		consumer(v)
 	}
 }
 
+// Peek applies the provided consumer function to each element in the List without modifying it,
+// and returns the original List.
 func (list List[T]) Peek(consumer func(T)) Steam[T] {
 	for _, v := range list {
 		consumer(v)
 	}
 	return list
 }
 
+// AllMatch checks if all elements in the List match the provided predicate function.
+// It returns true if all elements match, false otherwise.
 func (list List[T]) AllMatch(predicate func(T) bool) bool {
 	for _, v := range list {
 		if !predicate(v) {
@@ -99,6 +117,8 @@ func (list List[T]) AllMatch(predicate func(T) bool) bool {
 	return true
 }
 
+// AnyMatch checks if any element in the List matches the provided predicate function.
+// It returns true if at least one element matches, false otherwise.
 func (list List[T]) AnyMatch(predicate func(T) bool) bool {
 	for _, v := range list {
 		if predicate(v) {
@@ -108,6 +128,8 @@ func (list List[T]) AnyMatch(predicate func(T) bool) bool {
 	return false
 }
 
+// NoneMatch checks if no elements in the List match the provided predicate function.
+// It returns true if no elements match, false otherwise.
 func (list List[T]) NoneMatch(predicate func(T) bool) bool {
 	for _, v := range list {
 		if predicate(v) {
@@ -117,13 +139,18 @@ func (list List[T]) NoneMatch(predicate func(T) bool) bool {
 	return true
 }
 
+// FindFirst returns an Optional containing the first element of the List if it is present;
+// otherwise, it returns an empty Optional.
 func (list List[T]) FindFirst() opt.Optional[T] {
 	if len(list) > 0 {
 		return opt.Of(list[0])
 	}
 	return opt.Empty[T]()
 }
 
+// TakeWhile returns a new List containing elements from the start of the List
+// as long as they match the provided predicate function.
+// It stops including elements as soon as an element does not match.
 func (list List[T]) TakeWhile(predicate func(T) bool) Steam[T] {
 	results := make(List[T], 0)
 	for _, v := range list {
@@ -136,6 +163,9 @@ func (list List[T]) TakeWhile(predicate func(T) bool) Steam[T] {
 	return results
 }
 
+// DropWhile returns a new List that skips elements from the start of the List
+// as long as they match the provided predicate function.
+// It includes all subsequent elements after the first non-matching element.
 func (list List[T]) DropWhile(predicate func(T) bool) Steam[T] {
 	results := make(List[T], 0)
 	for _, v := range list {
@@ -146,6 +176,8 @@ func (list List[T]) DropWhile(predicate func(T) bool) Steam[T] {
 	return results
 }
 
+// Reduce applies an accumulator function to the elements of the List,
+// starting with the provided initial value. It returns the final accumulated value.
 func (list List[T]) Reduce(initValue T, acc func(T, T) T) T {
 	result := initValue
 	for _, v := range list {
@@ -154,6 +186,7 @@ func (list List[T]) Reduce(initValue T, acc func(T, T) T) T {
 	return result
 }
 
+// Reverse returns a new List containing the elements of the original List in reverse order.
 func (list List[T]) Reverse() Steam[T] {
 	length := len(list)
 	results := make(List[T], length)
@@ -165,6 +198,8 @@ func (list List[T]) Reverse() Steam[T] {
 	return results
 }
 
+// Position returns an Optional containing the index of the first element that matches the provided predicate function;
+// otherwise, it returns an empty Optional.
 func (list List[T]) Position(predicate func(T) bool) opt.Optional[int] {
 	for i, v := range list {
 		if predicate(v) {
@@ -174,6 +209,8 @@ func (list List[T]) Position(predicate func(T) bool) opt.Optional[int] {
 	return opt.Empty[int]()
 }
 
+// Last returns an Optional containing the last element of the List if it is present;
+// otherwise, it returns an empty Optional.
 func (list List[T]) Last() opt.Optional[T] {
 	length := list.Count()
 	if length > 0 {
@@ -182,6 +219,8 @@ func (list List[T]) Last() opt.Optional[T] {
 	return opt.Empty[T]()
 }
 
+// Skip returns a new List that skips the first n elements of the original List.
+// If n is greater than or equal to the length of the List, it returns an empty List.
 func (list List[T]) Skip(n int) Steam[T] {
 	length := len(list)
 	if length > n {
@@ -197,6 +236,8 @@ func (list List[T]) Skip(n int) Steam[T] {
 	return results
 }
 
+// Sorted returns a new List containing the elements of the original List sorted
+// according to the provided comparison function.
 func (list List[T]) Sorted(cmp func(T, T) bool) Steam[T] {
 	slice := list.Collect()
 	results := make(List[T], len(slice))
@@ -207,6 +248,8 @@ func (list List[T]) Sorted(cmp func(T, T) bool) Steam[T] {
 	return results
 }
 
+// GetCompared returns an Optional containing the element that is compared
+// according to the provided comparison function. If the List is empty, it returns an empty Optional.
 func (list List[T]) GetCompared(cmp func(T, T) bool) opt.Optional[T] {
 	if len(list) == 0 {
 		return opt.Empty[T]()
@@ -220,6 +263,7 @@ func (list List[T]) GetCompared(cmp func(T, T) bool) opt.Optional[T] {
 	return opt.Of(item)
 }
 
+// Collect returns the underlying slice of the List.
 func (list List[T]) Collect() []T {
 	return list
 }