Merge pull request #3 from go-andiamo/docs

Docs

accumulator.go

@@ -1,11 +1,14 @@
 package streams
 
+// AccumulatorFunc is the function signature used to create a new Accumulator
 type AccumulatorFunc[T any, R any] func(t T, r R) R
 
+// Accumulator is the interface used Reducer
 type Accumulator[T any, R any] interface {
 	Apply(t T, r R) R
 }
 
+// NewAccumulator creates a new Accumulator from the function provided
 func NewAccumulator[T any, R any](f AccumulatorFunc[T, R]) Accumulator[T, R] {
 	return accumulator[T, R]{
 		f: f,

comparator.go

@@ -1,19 +1,52 @@
 package streams
 
+// Comparator is the interface used to compare elements of a Stream
+//
+// This interface is ued when sorting, when finding min/max of a stream
+// and is also used to determine equality during set operations
+// (Stream.Difference, Stream.Intersection, Stream.SymmetricDifference and Stream.Union)
 type Comparator[T any] interface {
+	// Compare compares the two values lexicographically, i.e.:
+	//
+	// * the result should be 0 if v1 == v2
+	//
+	// * the result should be -1 if v1 < v2
+	//
+	// * the result should be 1 if v1 > v2
 	Compare(v1, v2 T) int
+	// Less returns true if v1 < v2, otherwise false
 	Less(v1, v2 T) bool
+	// LessOrEqual returns true if v1 <= v2, otherwise false
 	LessOrEqual(v1, v2 T) bool
+	// Greater returns true if v1 > v2, otherwise false
 	Greater(v1, v2 T) bool
+	// GreaterOrEqual returns true if v1 >= v2, otherwise false
 	GreaterOrEqual(v1, v2 T) bool
+	// Equal returns true if v1 == v2, otherwise false
 	Equal(v1, v2 T) bool
+	// NotEqual returns true if v1 != v2, otherwise false
 	NotEqual(v1, v2 T) bool
+	// Reversed creates a new comparator that imposes the reverse ordering to this comparator
+	//
+	// the reversal is against less/greater as well as against equality/non-equality
 	Reversed() Comparator[T]
+	// Then creates a new comparator from this comparator, with a following then comparator
+	// that is used when the initial comparison yields equal
 	Then(other Comparator[T]) Comparator[T]
 }
 
+// ComparatorFunc is the function signature used to create a new Comparator
+//
+// the function should compare the two values provided lexicographically, i.e.:
+//
+// * the result should be 0 if v1 == v2
+//
+// * the result should be -1 if v1 < v2
+//
+// * the result should be 1 if v1 > v2
 type ComparatorFunc[T any] func(v1, v2 T) int
 
+// NewComparator creates a new Comparator from the function provided
 func NewComparator[T any](f ComparatorFunc[T]) Comparator[T] {
 	return comparator[T]{
 		f: f,
@@ -27,6 +60,13 @@ type comparator[T any] struct {
 	reversed bool
 }
 
+// Compare compares the two values lexicographically, i.e.:
+//
+// * the result should be 0 if v1 == v2
+//
+// * the result should be -1 if v1 < v2
+//
+// * the result should be 1 if v1 > v2
 func (c comparator[T]) Compare(v1, v2 T) int {
 	result := 0
 	if c.f != nil {
@@ -43,22 +83,27 @@ func (c comparator[T]) Compare(v1, v2 T) int {
 	return result
 }
 
+// Less returns true if v1 < v2, otherwise false
 func (c comparator[T]) Less(v1, v2 T) bool {
 	return c.Compare(v1, v2) < 0
 }
 
+// LessOrEqual returns true if v1 <= v2, otherwise false
 func (c comparator[T]) LessOrEqual(v1, v2 T) bool {
 	return c.Compare(v1, v2) <= 0
 }
 
+// Greater returns true if v1 > v2, otherwise false
 func (c comparator[T]) Greater(v1, v2 T) bool {
 	return c.Compare(v1, v2) > 0
 }
 
+// GreaterOrEqual returns true if v1 >= v2, otherwise false
 func (c comparator[T]) GreaterOrEqual(v1, v2 T) bool {
 	return c.Compare(v1, v2) >= 0
 }
 
+// Equal returns true if v1 == v2, otherwise false
 func (c comparator[T]) Equal(v1, v2 T) bool {
 	if r := c.Compare(v1, v2); c.reversed {
 		return r != 0
@@ -67,6 +112,7 @@ func (c comparator[T]) Equal(v1, v2 T) bool {
 	}
 }
 
+// NotEqual returns true if v1 != v2, otherwise false
 func (c comparator[T]) NotEqual(v1, v2 T) bool {
 	if r := c.Compare(v1, v2); c.reversed {
 		return r == 0
@@ -75,13 +121,18 @@ func (c comparator[T]) NotEqual(v1, v2 T) bool {
 	}
 }
 
+// Reversed creates a new comparator that imposes the reverse ordering to this comparator
+//
+// the reversal is against less/greater as well as against equality/non-equality
 func (c comparator[T]) Reversed() Comparator[T] {
 	return comparator[T]{
 		f:        c.f,
 		reversed: !c.reversed,
 	}
 }
 
+// Then creates a new comparator from this comparator, with a following then comparator
+// that is used when the initial comparison yields equal
 func (c comparator[T]) Then(other Comparator[T]) Comparator[T] {
 	return comparator[T]{
 		inner: c,

consumer.go

@@ -1,12 +1,19 @@
 package streams
 
+// Consumer is the interface used by Stream.ForEach
 type Consumer[T any] interface {
+	// Accept is called by the user of teh consumer to supply a value
 	Accept(v T)
+	// AndThen creates a new consumer from the current with a subsequent action to be performed
+	//
+	// multiple consumers can be chained together as one using this method
 	AndThen(after Consumer[T]) Consumer[T]
 }
 
+// ConsumerFunc is the function signature used to create a new Consumer
 type ConsumerFunc[T any] func(v T)
 
+// NewConsumer creates a new consumer from the function provided
 func NewConsumer[T any](f ConsumerFunc[T]) Consumer[T] {
 	return consumer[T]{
 		f: f,
@@ -19,6 +26,7 @@ type consumer[T any] struct {
 	andThen Consumer[T]
 }
 
+// Accept is called by the user of teh consumer to supply a value
 func (c consumer[T]) Accept(v T) {
 	if c.f != nil {
 		c.f(v)
@@ -30,6 +38,9 @@ func (c consumer[T]) Accept(v T) {
 	}
 }
 
+// AndThen creates a new consumer from the current with a subsequent action to be performed
+//
+// multiple consumers can be chained together as one using this method
 func (c consumer[T]) AndThen(after Consumer[T]) Consumer[T] {
 	return consumer[T]{
 		inner:   c,

converter.go

@@ -1,11 +1,15 @@
 package streams
 
-type ConverterFunc[T any, R any] func(v T) R
-
+// Converter is the interface used by Mapper to convert one value type to another
 type Converter[T any, R any] interface {
+	// Convert converts a value of type T and returns a value of type R
 	Convert(v T) R
 }
 
+// ConverterFunc is the function signature used to create a new Converter
+type ConverterFunc[T any, R any] func(v T) R
+
+// NewConverter creates a new Converter from the function provided
 func NewConverter[T any, R any](f ConverterFunc[T, R]) Converter[T, R] {
 	return converter[T, R]{
 		f: f,
@@ -16,6 +20,7 @@ type converter[T any, R any] struct {
 	f ConverterFunc[T, R]
 }
 
+// Convert converts a value of type T and returns a value of type R
 func (c converter[T, R]) Convert(v T) R {
 	return c.f(v)
 }

mapper.go

@@ -1,9 +1,12 @@
 package streams
 
+// Mapper is an interface for mapping (converting) one element type to another
 type Mapper[T any, R any] interface {
+	// Map converts the values in the input Stream and produces a Stream of output types
 	Map(in Stream[T]) Stream[R]
 }
 
+// NewMapper creates a new Mapper that will use the provided Converter
 func NewMapper[T any, R any](c Converter[T, R]) Mapper[T, R] {
 	return mapper[T, R]{
 		c: c,
@@ -14,6 +17,7 @@ type mapper[T any, R any] struct {
 	c Converter[T, R]
 }
 
+// Map converts the values in the input stream and produces a stream of output types
 func (m mapper[T, R]) Map(in Stream[T]) Stream[R] {
 	r := make([]R, 0, in.Len())
 	in.ForEach(NewConsumer[T](func(v T) {

predicate.go

@@ -1,14 +1,24 @@
 package streams
 
+// Predicate is the interface used by filtering and matching operations
+//
+// i.e. is used by: Stream.AllMatch, Stream.AnyMatch, Stream.Count, Stream.Filter, Stream.FirstMatch,
+// Stream.LastMatch, Stream.NoneMatch and Stream.NthMatch
 type Predicate[T any] interface {
+	// Test evaluates this predicate against the supplied value
 	Test(v T) bool
+	// And creates a composed predicate that represents a short-circuiting logical AND of this predicate and another
 	And(other Predicate[T]) Predicate[T]
+	// Or creates a composed predicate that represents a short-circuiting logical OR of this predicate and another
 	Or(other Predicate[T]) Predicate[T]
+	// Negate creates a composed predicate that represents a logical NOT of this predicate
 	Negate() Predicate[T]
 }
 
+// PredicateFunc is the function signature used to create a new Predicate
 type PredicateFunc[T any] func(v T) bool
 
+// NewPredicate creates a new Predicate from the function provided
 func NewPredicate[T any](f PredicateFunc[T]) Predicate[T] {
 	return predicate[T]{
 		f: f,
@@ -23,6 +33,7 @@ type predicate[T any] struct {
 	and     Predicate[T]
 }
 
+// Test evaluates this predicate against the supplied value
 func (p predicate[T]) Test(v T) bool {
 	var r bool
 	if p.f != nil {
@@ -42,20 +53,23 @@ func (p predicate[T]) Test(v T) bool {
 	return r
 }
 
+// And creates a composed predicate that represents a short-circuiting logical AND of this predicate and another
 func (p predicate[T]) And(other Predicate[T]) Predicate[T] {
 	return predicate[T]{
 		inner: p,
 		and:   other,
 	}
 }
 
+// Or creates a composed predicate that represents a short-circuiting logical OR of this predicate and another
 func (p predicate[T]) Or(other Predicate[T]) Predicate[T] {
 	return predicate[T]{
 		inner: p,
 		or:    other,
 	}
 }
 
+// Negate creates a composed predicate that represents a logical NOT of this predicate
 func (p predicate[T]) Negate() Predicate[T] {
 	return predicate[T]{
 		inner:   p,

reducer.go

@@ -1,9 +1,12 @@
 package streams
 
+// Reducer is the interface used to perform reductions (folds/accumulations)
 type Reducer[T any, R any] interface {
+	// Reduce performs a reduction of the supplied Stream
 	Reduce(s Stream[T]) R
 }
 
+// NewReducer creates a new Reducer that will use the supplied Accumulator
 func NewReducer[T any, R any](accumulator Accumulator[T, R]) Reducer[T, R] {
 	return &reducer[T, R]{
 		accumulator: accumulator,
@@ -14,6 +17,7 @@ type reducer[T any, R any] struct {
 	accumulator Accumulator[T, R]
 }
 
+// Reduce performs a reduction of the supplied Stream
 func (r reducer[T, R]) Reduce(s Stream[T]) R {
 	var result R
 	s.ForEach(NewConsumer[T](func(v T) {