add examples

comparer_test.go

@@ -3,10 +3,24 @@ package compare_test
 import (
 	"fmt"
 	"testing"
+	"time"
 
 	"github.com/hiroebe/go-compare"
 )
 
+func ExampleComparable() {
+	diff := compare.Diff("A", "B", func(v string) compare.C {
+		return compare.C{
+			compare.Comparable("v", v),
+		}
+	})
+
+	fmt.Println(diff)
+
+	// Output:
+	// v: "A" != "B"
+}
+
 func TestComparable(t *testing.T) {
 	t.Parallel()
 
@@ -68,6 +82,20 @@ func TestComparable(t *testing.T) {
 	}
 }
 
+func ExampleComparableSlice() {
+	diff := compare.Diff([]int{1, 2}, []int{3, 4}, func(v []int) compare.C {
+		return compare.C{
+			compare.ComparableSlice("v", v),
+		}
+	})
+
+	fmt.Println(diff)
+
+	// Output:
+	// v[0]: 1 != 3
+	// v[1]: 2 != 4
+}
+
 func TestComparableSlice(t *testing.T) {
 	t.Parallel()
 
@@ -101,6 +129,23 @@ v[1]: 2 != 4`,
 	}
 }
 
+func ExampleComparablePointer() {
+	type S struct {
+		I int
+	}
+
+	diff := compare.Diff(&S{1}, &S{2}, func(v *S) compare.C {
+		return compare.C{
+			compare.ComparablePointer("v", v),
+		}
+	})
+
+	fmt.Println(diff)
+
+	// Output:
+	// v: compare_test.S{I:1} != compare_test.S{I:2}
+}
+
 func TestComparablePointer(t *testing.T) {
 	t.Parallel()
 
@@ -149,6 +194,30 @@ func TestComparablePointer(t *testing.T) {
 	}
 }
 
+func ExampleFunc() {
+	t1 := time.Now()
+	t2 := t1.Add(100 * time.Millisecond)
+
+	diff := compare.Diff(t1, t2, func(t time.Time) compare.C {
+		return compare.C{
+			// Custom comparer to allow maximum 1s diff.
+			compare.Func("t", t, func(t1, t2 time.Time) error {
+				if t2.Sub(t1).Abs() > time.Second {
+					return fmt.Errorf("t1 != t2")
+				}
+				return nil
+			}),
+		}
+	})
+
+	if diff == "" {
+		fmt.Println("t1 approximately equals t2")
+	}
+
+	// Output:
+	// t1 approximately equals t2
+}
+
 func TestFunc(t *testing.T) {
 	t.Parallel()
 
@@ -185,6 +254,33 @@ func TestFunc(t *testing.T) {
 	}
 }
 
+func ExampleNest() {
+	type Child struct {
+		F1 int
+		F2 string
+	}
+	type Parent struct {
+		Child Child
+	}
+
+	diff := compare.Diff(Parent{Child{1, "child1"}}, Parent{Child{2, "child2"}}, func(parent Parent) compare.C {
+		return compare.C{
+			compare.Nest("Child", parent.Child, func(child Child) compare.C {
+				return compare.C{
+					compare.Comparable("F1", child.F1),
+					compare.Comparable("F2", child.F2),
+				}
+			}),
+		}
+	})
+
+	fmt.Println(diff)
+
+	// Output:
+	// Child.F1: 1 != 2
+	// Child.F2: "child1" != "child2"
+}
+
 func TestNest(t *testing.T) {
 	t.Parallel()
 
@@ -240,6 +336,28 @@ S.F2: "s1" != "s2"`,
 	}
 }
 
+func ExampleSlice() {
+	type S struct {
+		F int
+	}
+
+	diff := compare.Diff([]S{{1}, {2}}, []S{{3}, {4}}, func(vs []S) compare.C {
+		return compare.C{
+			compare.Slice("vs", vs, func(v S) compare.C {
+				return compare.C{
+					compare.Comparable("F", v.F),
+				}
+			}),
+		}
+	})
+
+	fmt.Println(diff)
+
+	// Output:
+	// vs[0].F: 1 != 3
+	// vs[1].F: 2 != 4
+}
+
 func TestSlice(t *testing.T) {
 	t.Parallel()
 

example_test.go

@@ -0,0 +1,54 @@
+package compare_test
+
+import (
+	"fmt"
+
+	"github.com/hiroebe/go-compare"
+)
+
+func Example() {
+	type Item struct {
+		Key   string
+		Value string
+	}
+	type Object struct {
+		ID    int
+		Items []*Item
+	}
+
+	obj1 := Object{
+		ID: 1,
+		Items: []*Item{
+			{Key: "item1", Value: "value1"},
+			{Key: "item2", Value: "value2"},
+		},
+	}
+	obj2 := Object{
+		ID: 2,
+		Items: []*Item{
+			{Key: "item1", Value: "value1"},
+			{Key: "item3", Value: "value3"},
+		},
+	}
+	diff := compare.Diff(obj1, obj2, func(obj Object) compare.C {
+		return compare.C{
+			// compare `ID` by `==`.
+			compare.Comparable("ID", obj.ID),
+			// compare `Items` as slice.
+			compare.Slice("Items", obj.Items, func(item *Item) compare.C {
+				// define nested `compare.C` to compare each `Item`.
+				return compare.C{
+					compare.Comparable("Key", item.Key),
+					compare.Comparable("Value", item.Value),
+				}
+			}),
+		}
+	})
+
+	fmt.Println(diff)
+
+	// Output:
+	// ID: 1 != 2
+	// Items[1].Key: "item2" != "item3"
+	// Items[1].Value: "value2" != "value3"
+}