Merge pull request #10 from thecasualcoder/documentation-and-examples

Add documentation and examples

README.md

@@ -20,9 +20,8 @@ This library heavily makes use of `reflect` package and hence will have an **imp
 
 ### Map
 
-Map applies a mapper function on each element of an input and sets it in output. 
-
-_Primitive types_
+Map applies a mapper function on each element of an input and sets it in output.
+For more [docs](https://godoc.org/github.com/thecasualcoder/godash#Map).
 
 ```go
 func main() {
@@ -37,8 +36,6 @@ func main() {
 }
 ```
 
-_Struct type_
-
 ```go
 type Person struct {
 	Name string
@@ -62,7 +59,8 @@ func main() {
 
 ### Filter
 
-Filter out elements that fail the predicate
+Filter out elements that fail the predicate.
+For more [docs](https://godoc.org/github.com/thecasualcoder/godash#Filter).
 
 ```go
 func main() {
@@ -95,31 +93,38 @@ func main() {
 
 ### Reduce
 
-Reduce reduces the given collection using given reduce function 
-
-_Primitive types_
+Reduce can accept a reducer and apply the reducer on each element of the input slice while providing an accumulator to save the reduce output
+For more [docs](https://godoc.org/github.com/thecasualcoder/godash#Reduce).
 
 ```go
 func main() {
-	input := []int{1, 2, 3, 4, 5}
-	var output int
-
-	godash.Reduce(input, &output, func(sum, element int) int {
-		return sum + element
+    input := []string{"count", "words", "and", "print", "words", "count"}
+	accumulator := map[string]int{}
+
+	_ = godash.Reduce(input, &accumulator, func(acc map[string]int, element string) map[string]int {
+		if _, present := acc[element]; present {
+			acc[element] = acc[element] + 1
+		} else {
+			acc[element] = 1
+		}
+		return acc
 	})
 
-	fmt.Println(output) // prints 15
-}
-```
+	bytes, _ := json.MarshalIndent(accumulator, "", "  ")
+	fmt.Println(string(bytes))
 
-_Struct type_
+	// Output:
+	//{
+	//   "and": 1,
+	//   "count": 2,
+	//   "print": 1,
+	//   "words": 2
+	//}
 
-```go
-type Person struct {
-	Name string
-	Age Int
 }
+```
 
+```go
 func main() {
 	input := []Person{
 		{Name: "John", Age: 22},

filter.go

@@ -5,6 +5,20 @@ import (
 	"reflect"
 )
 
+// Filter out elements that fail the predicate.
+//
+// Input of type slice is supported as of now.
+// Output is a slice in which filtered-in elements are stored.
+// PredicateFn function is applied on each element of input to determine to filter or not
+//
+// Validations:
+//
+//	1. Input and Output's slice should be of same type
+//	2. Predicate function can take one argment and return one argument
+//	3. Predicate's return argument is always boolean.
+//	4. Predicate's input argument should be input/output slice's element type.
+//
+// Validation errors are returned to the caller.
 func Filter(in, out, predicateFn interface{}) error {
 	input := reflect.ValueOf(in)
 

filter_test.go

@@ -1,6 +1,7 @@
 package godash_test
 
 import (
+	"fmt"
 	"github.com/stretchr/testify/assert"
 	"github.com/thecasualcoder/godash"
 	"testing"
@@ -101,3 +102,21 @@ func TestFilter(t *testing.T) {
 		}
 	})
 }
+
+func ExampleFilter() {
+	input := []string{
+		"rhythm",
+		"of",
+		"life",
+	}
+	var output []string
+
+	_ = godash.Filter(input, &output, func(in string) bool {
+		return len(in) > 3
+	})
+
+	fmt.Println(output)
+
+	// Output:
+	// [rhythm life]
+}

reduce.go

@@ -5,7 +5,23 @@ import (
 	"reflect"
 )
 
-// Reduce reduces the given collection using given reduce function
+// Reduce can accept a reducer and apply the reducer on each element
+// of the input slice while providing an accumulator to save the reduce output.
+//
+// Input of type slice is supported as of now.
+// Output is the accumulator.
+// ReduceFn is the reducer function.
+//
+// Whatever ReduceFn returns is fed as accumulator for the next iteration.
+// Reduction happens from left-to-right.
+//
+// Reduce does the following validations:
+//
+//	1. Reducer function should accept exactly 2 arguments and return 1 argument
+//  2. Reducer function's second argument should be the same type as input slice's element type
+// 	3. Reducer function's return type should be the same as that of the accumulator
+//
+// Validation errors are returned to the caller.
 func Reduce(in, out, reduceFn interface{}) error {
 	input := reflect.ValueOf(in)
 	output := reflect.ValueOf(out)

reduce_test.go

@@ -1,6 +1,8 @@
 package godash_test
 
 import (
+	"encoding/json"
+	"fmt"
 	"github.com/stretchr/testify/assert"
 	"github.com/thecasualcoder/godash"
 	"strconv"
@@ -178,3 +180,28 @@ func TestReduce(t *testing.T) {
 		}
 	})
 }
+
+func ExampleReduce() {
+	input := []string{"count", "words", "and", "print", "words", "count"}
+	accumulator := map[string]int{}
+
+	_ = godash.Reduce(input, &accumulator, func(acc map[string]int, element string) map[string]int {
+		if _, present := acc[element]; present {
+			acc[element] = acc[element] + 1
+		} else {
+			acc[element] = 1
+		}
+		return acc
+	})
+
+	bytes, _ := json.MarshalIndent(accumulator, "", "  ")
+	fmt.Println(string(bytes))
+
+	// Output:
+	//{
+	//   "and": 1,
+	//   "count": 2,
+	//   "print": 1,
+	//   "words": 2
+	//}
+}