feat: Accum, ReduceOK (#29)

feat(slice,loop): Accum, ReduceOK methods.

Author: m4gshm

README.md

@@ -258,6 +258,18 @@ var sum = slice.Reduce([]int{1, 2, 3, 4, 5, 6}, func(i1, i2 int) int { return i1
 //21
 ```
 
+##### slice.Accum
+
+``` go
+import (
+    "github.com/m4gshm/gollections/op"
+    "github.com/m4gshm/gollections/slice"
+)
+
+var sum = slice.Accum(100, slice.Of(1, 2, 3, 4, 5, 6), op.Sum)
+//121
+```
+
 ##### slice.First
 
 ``` go
@@ -455,9 +467,10 @@ type (
 )
 ```
 
-The `Loop` function retrieves a next element from a dataset and returns
-`ok==true` if successful.  
-The `KVLoop` behaves similar but returns a key/value pair.  
+The `Loop` function returns a next element from a dataset and returns
+`ok==true` on success. `ok==false` means there are no more elements in
+the dataset.  
+The `KVLoop` behaves similar but returns key/value pairs.  
 
 ``` go
 even := func(i int) bool { return i%2 == 0 }
@@ -553,7 +566,10 @@ ageGroupedSortedNames = loop.ToMapResolv(loop.Of(users...), func(u User) string
 ##### sum.Of
 
 ``` go
-import "github.com/m4gshm/gollections/op/sum"
+import (
+    "github.com/m4gshm/gollections/loop"
+    "github.com/m4gshm/gollections/loop/sum"
+)
 
 var sum = sum.Of(loop.Of(1, 2, 3, 4, 5, 6)) //21
 ```
@@ -565,6 +581,31 @@ var sum = loop.Reduce(loop.Of(1, 2, 3, 4, 5, 6), func(i1, i2 int) int { return i
 //21
 ```
 
+##### loop.ReduceOK
+
+``` go
+adder := func(i1, i2 int) int { return i1 + i2 }
+
+sum, ok := loop.ReduceOK(loop.Of(1, 2, 3, 4, 5, 6), adder)
+//21, true
+
+emptyLoop := loop.Of[int]()
+sum, ok = loop.ReduceOK(emptyLoop, adder)
+//0, false
+```
+
+##### loop.Accum
+
+``` go
+import (
+    "github.com/m4gshm/gollections/loop"
+    "github.com/m4gshm/gollections/op"
+)
+
+var sum = loop.Accum(100, loop.Of(1, 2, 3, 4, 5, 6), op.Sum)
+//121
+```
+
 ##### loop.First
 
 ``` go

break/kv/loop/api.go

@@ -23,6 +23,9 @@ func New[S, K, V any](source S, hasNext func(S) bool, getNext func(S) (K, V, err
 
 // From wrap the next loop to a breakable loop
 func From[K, V any](next func() (K, V, bool)) func() (K, V, bool, error) {
+	if next == nil {
+		return nil
+	}
 	return func() (K, V, bool, error) {
 		k, v, ok := next()
 		return k, v, ok, nil
@@ -32,6 +35,9 @@ func From[K, V any](next func() (K, V, bool)) func() (K, V, bool, error) {
 // To transforms a breakable loop to a simple loop.
 // The errConsumer is a function that is called when an error occurs.
 func To[K, V any](next func() (K, V, bool, error), errConsumer func(error)) func() (K, V, bool) {
+	if next == nil {
+		return nil
+	}
 	return func() (K, V, bool) {
 		k, v, ok, err := next()
 		if err != nil {
@@ -47,40 +53,56 @@ func Group[K comparable, V any](next func() (K, V, bool, error)) (map[K][]V, err
 	return ToMapResolv(next, resolv.Slice[K, V])
 }
 
-// Reduce reduces the key/value pairs retrieved by the 'next' function into an one pair using the 'merge' function
-func Reduce[K, V any](next func() (K, V, bool, error), merge func(K, K, V, V) (K, V)) (rk K, rv V, err error) {
+// Reduce reduces the key/value pairs retrieved by the 'next' function into an one pair using the 'merge' function.
+// If the 'next' function returns ok=false at the first call, the zero values of 'K', 'V' types are returned.
+func Reduce[K, V any](next func() (K, V, bool, error), merge func(K, K, V, V) (K, V)) (K, V, error) {
+	rk, rv, _, err := ReduceOK(next, merge)
+	return rk, rv, err
+}
+
+// ReduceOK reduces the key/value pairs retrieved by the 'next' function into an one pair using the 'merge' function.
+// Returns ok==false if the 'next' function returns ok=false at the first call (no more elements).
+func ReduceOK[K, V any](next func() (K, V, bool, error), merge func(K, K, V, V) (K, V)) (rk K, rv V, ok bool, err error) {
 	if next == nil {
-		return rk, rv, nil
+		return rk, rv, false, nil
 	}
 	k, v, ok, err := next()
 	if err != nil || !ok {
-		return rk, rv, err
+		return k, v, ok, err
 	}
 	rk, rv = k, v
 	for {
 		k, v, ok, err := next()
 		if err != nil || !ok {
-			return rk, rv, err
+			return rk, rv, true, err
 		}
 		rk, rv = merge(rk, k, rv, v)
 	}
 }
 
-// Reducee reduces the key/value pairs retrieved by the 'next' function into an one pair using the 'merge' function
-func Reducee[K, V any](next func() (K, V, bool, error), merge func(K, K, V, V) (K, V, error)) (rk K, rv V, err error) {
+// Reducee reduces the key/value pairs retrieved by the 'next' function into an one pair using the 'merge' function.
+// If the 'next' function returns ok=false at the first call, the zero values of 'K', 'V' types are returned.
+func Reducee[K, V any](next func() (K, V, bool, error), merge func(K, K, V, V) (K, V, error)) (K, V, error) {
+	rk, rv, _, err := ReduceeOK(next, merge)
+	return rk, rv, err
+}
+
+// ReduceeOK reduces the key/value pairs retrieved by the 'next' function into an one pair using the 'merge' function.
+// Returns ok==false if the 'next' function returns ok=false at the first call (no more elements).
+func ReduceeOK[K, V any](next func() (K, V, bool, error), merge func(K, K, V, V) (K, V, error)) (rk K, rv V, ok bool, err error) {
 	if next == nil {
-		return rk, rv, nil
+		return rk, rv, false, nil
 	}
 	k, v, ok, err := next()
 	if err != nil || !ok {
-		return rk, rv, err
+		return rk, rv, ok, err
 	}
 	rk, rv = k, v
 	for {
 		if k, v, ok, err := next(); err != nil || !ok {
-			return rk, rv, err
+			return rk, rv, true, err
 		} else if rk, rv, err = merge(rk, k, rv, v); err != nil {
-			return rk, rv, err
+			return rk, rv, true, err
 		}
 	}
 }
@@ -145,7 +167,7 @@ func Conv[K, V any, KOUT, VOUT any](next func() (K, V, bool, error), converter f
 			return k2, v2, false, err
 		}
 		k2, v2, err = converter(k, v)
-		return k2, v2, err == nil, err
+		return k2, v2, true, err
 	}
 }
 

break/kv/loop/loop.go

@@ -13,16 +13,30 @@ func (next Loop[K, V]) First(predicate func(K, V) bool) (K, V, bool, error) {
 	return First(next, predicate)
 }
 
-// Reduce reduces the elements retrieved by the 'next' function into an one using the 'merge' function.
+// Reduce reduces the key/value pairs retrieved by the 'next' function into an one pair using the 'merge' function.
+// If the 'next' function returns ok=false at the first call, the zero values of 'K', 'V' types are returned.
 func (next Loop[K, V]) Reduce(merge func(K, K, V, V) (K, V)) (K, V, error) {
 	return Reduce(next, merge)
 }
 
-// Reducee reduces the elements retrieved by the 'next' function into an one using the 'merge' function.
+// ReduceOK reduces the key/value pairs retrieved by the 'next' function into an one pair using the 'merge' function.
+// Returns ok==false if the 'next' function returns ok=false at the first call (no more elements).
+func (next Loop[K, V]) ReduceOK(merge func(K, K, V, V) (K, V)) (K, V, bool, error) {
+	return ReduceOK(next, merge)
+}
+
+// Reducee reduces the key/value pairs retrieved by the 'next' function into an one pair using the 'merge' function.
+// If the 'next' function returns ok=false at the first call, the zero values of 'K', 'V' types are returned.
 func (next Loop[K, V]) Reducee(merge func(K, K, V, V) (K, V, error)) (K, V, error) {
 	return Reducee(next, merge)
 }
 
+// ReduceeOK reduces the key/value pairs retrieved by the 'next' function into an one pair using the 'merge' function.
+// Returns ok==false if the 'next' function returns ok=false at the first call (no more elements).
+func (next Loop[K, V]) ReduceeOK(merge func(K, K, V, V) (K, V, error)) (K, V, bool, error) {
+	return ReduceeOK(next, merge)
+}
+
 // HasAny finds the first element that satisfies the 'predicate' function condition and returns true if successful
 func (next Loop[K, V]) HasAny(predicate func(K, V) bool) (bool, error) {
 	return HasAny(next, predicate)

break/kv/loop/test/api_test.go

@@ -44,21 +44,57 @@ func Test_Firstt(t *testing.T) {
 func Test_Reduce(t *testing.T) {
 	kvl := breakkvloop.From(loop.KeyValue(loop.Of(k.V(1, "one"), k.V(2, "two"), k.V(3, "three")), c.KV[int, string].Key, c.KV[int, string].Value))
 
-	k, v, _ := breakkvloop.Reduce(kvl, func(kl, kr int, vl, vr string) (int, string) { return kl + kr, vl + vr })
+	k, v, ok, _ := breakkvloop.ReduceOK(kvl, func(kl, kr int, vl, vr string) (int, string) { return kl + kr, vl + vr })
 
+	assert.True(t, ok)
 	assert.Equal(t, 1+2+3, k)
 	assert.Equal(t, "one"+"two"+"three", v)
 }
 
+func Test_Reduce_Empty(t *testing.T) {
+	kvl := breakkvloop.From(loop.KeyValue(loop.Of[c.KV[int, string]](), c.KV[int, string].Key, c.KV[int, string].Value))
+
+	_, _, ok, _ := breakkvloop.ReduceOK(kvl, func(kl, kr int, vl, vr string) (int, string) { return kl + kr, vl + vr })
+
+	assert.False(t, ok)
+}
+
+func Test_Reduce_Nil(t *testing.T) {
+	var l loop.Loop[c.KV[int, string]]
+	kvl := breakkvloop.From(loop.KeyValue(l, c.KV[int, string].Key, c.KV[int, string].Value))
+
+	_, _, ok, _ := breakkvloop.ReduceOK(kvl, func(kl, kr int, vl, vr string) (int, string) { return kl + kr, vl + vr })
+
+	assert.False(t, ok)
+}
+
 func Test_Reducee(t *testing.T) {
 	kvl := breakkvloop.From(loop.KeyValue(loop.Of(k.V(1, "one"), k.V(2, "two"), k.V(3, "three")), c.KV[int, string].Key, c.KV[int, string].Value))
 
-	k, v, _ := breakkvloop.Reducee(kvl, func(kl, kr int, vl, vr string) (int, string, error) { return kl + kr, vl + vr, nil })
+	k, v, ok, _ := breakkvloop.ReduceeOK(kvl, func(kl, kr int, vl, vr string) (int, string, error) { return kl + kr, vl + vr, nil })
 
+	assert.True(t, ok)
 	assert.Equal(t, 1+2+3, k)
 	assert.Equal(t, "one"+"two"+"three", v)
 }
 
+func Test_Reducee_Empty(t *testing.T) {
+	kvl := breakkvloop.From(loop.KeyValue(loop.Of[c.KV[int, string]](), c.KV[int, string].Key, c.KV[int, string].Value))
+
+	_, _, ok, _ := breakkvloop.ReduceeOK(kvl, func(kl, kr int, vl, vr string) (int, string, error) { return kl + kr, vl + vr, nil })
+
+	assert.False(t, ok)
+}
+
+func Test_Reducee_Nil(t *testing.T) {
+	var l loop.Loop[c.KV[int, string]]
+	kvl := breakkvloop.From(loop.KeyValue(l, c.KV[int, string].Key, c.KV[int, string].Value))
+
+	_, _, ok, _ := breakkvloop.ReduceeOK(kvl, func(kl, kr int, vl, vr string) (int, string, error) { return kl + kr, vl + vr, nil })
+
+	assert.False(t, ok)
+}
+
 func Test_Convert(t *testing.T) {
 	kvl := breakkvloop.From(loop.KeyValue(loop.Of(k.V(1, "1"), k.V(2, "2"), k.V(3, "3")), c.KV[int, string].Key, c.KV[int, string].Value))
 

break/loop/api.go

@@ -200,40 +200,76 @@ func Append[T any, TS ~[]T](next func() (T, bool, error), out TS) (TS, error) {
 	return out, nil
 }
 
-// Reduce reduces the elements retrieved by the 'next' function into an one using the 'merge' function.
-func Reduce[T any](next func() (T, bool, error), merger func(T, T) T) (out T, e error) {
+// ReduceOK reduces the elements retrieved by the 'next' function into an one using the 'merge' function.
+// If the 'next' function returns ok=false at the first call, the zero value of 'T' type is returned.
+func Reduce[T any](next func() (T, bool, error), merge func(T, T) T) (T, error) {
+	result, _, err := ReduceOK(next, merge)
+	return result, err
+}
+
+// ReduceOK reduces the elements retrieved by the 'next' function into an one using the 'merge' function.
+// Returns ok==false if the 'next' function returns ok=false at the first call (no more elements).
+func ReduceOK[T any](next func() (T, bool, error), merge func(T, T) T) (result T, ok bool, err error) {
 	if next == nil {
-		return out, nil
+		return result, false, nil
+	}
+	if result, ok, err = next(); err != nil || !ok {
+		return result, ok, err
+	}
+	result, err = Accum(result, next, merge)
+	return result, true, err
+}
+
+// Reducee reduces the elements retrieved by the 'next' function into an one using the 'merge' function.
+// If the 'next' function returns ok=false at the first call, the zero value of 'T' type is returned.
+func Reducee[T any](next func() (T, bool, error), merge func(T, T) (T, error)) (T, error) {
+	result, _, err := ReduceeOK(next, merge)
+	return result, err
+}
+
+// ReduceeOK reduces the elements retrieved by the 'next' function into an one using the 'merge' function.
+// Returns ok==false if the 'next' function returns ok=false at the first call (no more elements).
+func ReduceeOK[T any](next func() (T, bool, error), merge func(T, T) (T, error)) (result T, ok bool, err error) {
+	if next == nil {
+		return result, false, nil
+	}
+	if result, ok, err = next(); err != nil || !ok {
+		return result, ok, err
 	}
-	v, ok, err := next()
-	if err != nil || !ok {
-		return out, err
+	result, err = Accumm(result, next, merge)
+	return result, true, err
+}
+
+// Accum accumulates a value by using the 'first' argument to initialize the accumulator and sequentially applying the 'merge' functon to the accumulator and each element retrieved by the 'next' function.
+func Accum[T any](first T, next func() (T, bool, error), merge func(T, T) T) (accumulator T, err error) {
+	accumulator = first
+	if next == nil {
+		return accumulator, nil
 	}
-	out = v
 	for {
 		v, ok, err := next()
-		if err != nil || !ok {
-			return out, err
+		if err != nil {
+			return accumulator, err
+		} else if !ok {
+			return accumulator, nil
 		}
-		out = merger(out, v)
+		accumulator = merge(accumulator, v)
 	}
 }
 
-// Reducee reduces the elements retrieved by the 'next' function into an one using the 'merge' function
-func Reducee[T any](next func() (T, bool, error), merger func(T, T) (T, error)) (out T, e error) {
+// Accumm accumulates a value by using the 'first' argument to initialize the accumulator and sequentially applying the 'merge' functon to the accumulator and each element retrieved by the 'next' function.
+func Accumm[T any](first T, next func() (T, bool, error), merge func(T, T) (T, error)) (accumulator T, err error) {
+	accumulator = first
 	if next == nil {
-		return out, nil
-	}
-	v, ok, err := next()
-	if err != nil || !ok {
-		return out, err
+		return accumulator, nil
 	}
-	out = v
 	for {
 		if v, ok, err := next(); err != nil || !ok {
-			return out, err
-		} else if out, err = merger(out, v); err != nil {
-			return out, err
+			return accumulator, err
+		} else if v, err = merge(accumulator, v); err != nil {
+			return accumulator, err
+		} else {
+			accumulator = v
 		}
 	}
 }
@@ -608,7 +644,7 @@ func KeyValuee[T any, K, V any](next func() (T, bool, error), keyExtractor func(
 			return key, value, false, err
 		} else if key, err = keyExtractor(elem); err == nil {
 			value, err = valExtractor(elem)
-			return key, value, err == nil, err
+			return key, value, true, err
 		}
 		return key, value, false, nil
 	}
@@ -850,13 +886,13 @@ func ToMapResolvv[T any, K comparable, V, VR any](
 }
 
 // ConvertAndReduce converts each elements and merges them into one
-func ConvertAndReduce[From, To any](next func() (From, bool, error), converter func(From) To, merger func(To, To) To) (out To, err error) {
-	return Reduce(Convert(next, converter), merger)
+func ConvertAndReduce[From, To any](next func() (From, bool, error), converter func(From) To, merge func(To, To) To) (out To, err error) {
+	return Reduce(Convert(next, converter), merge)
 }
 
 // ConvAndReduce converts each elements and merges them into one
-func ConvAndReduce[From, To any](next func() (From, bool, error), converter func(From) (To, error), merger func(To, To) To) (out To, err error) {
-	return Reduce(Conv(next, converter), merger)
+func ConvAndReduce[From, To any](next func() (From, bool, error), converter func(From) (To, error), merge func(To, To) To) (out To, err error) {
+	return Reduce(Conv(next, converter), merge)
 }
 
 // Crank rertieves a next element from the 'next' function, returns the function, element, successfully flag.