refactor: export Differ type to allow reuse of resources

The Differ type is now exported, and provide a Reset method, which
allows to reset the underlying storage to reduce allocations on reuse.

Author: wI2L

bench_test.go

@@ -6,16 +6,16 @@ import (
 	"testing"
 )
 
-func BenchmarkCompare(b *testing.B) {
-	beforeBytes, err := ioutil.ReadFile("testdata/benchs/before.json")
+func BenchmarkMedium(b *testing.B) {
+	beforeBytes, err := ioutil.ReadFile("testdata/benchs/medium/before.json")
 	if err != nil {
 		b.Fatal(err)
 	}
-	afterBytesOrdered, err := ioutil.ReadFile("testdata/benchs/after-ordered.json")
+	afterBytesOrdered, err := ioutil.ReadFile("testdata/benchs/medium/after-ordered.json")
 	if err != nil {
 		b.Fatal(err)
 	}
-	afterBytesUnordered, err := ioutil.ReadFile("testdata/benchs/after-unordered.json")
+	afterBytesUnordered, err := ioutil.ReadFile("testdata/benchs/medium/after-unordered.json")
 	if err != nil {
 		b.Fatal(err)
 	}
@@ -64,15 +64,16 @@ func BenchmarkCompare(b *testing.B) {
 				_ = patch
 			}
 		})
-		b.Run("differ_diff/"+bb.name, func(b *testing.B) {
+		b.Run("DifferCompare/"+bb.name, func(b *testing.B) {
+			d := Differ{
+				targetBytes: bb.afterBytes,
+			}
+			for _, opt := range bb.opts {
+				opt(&d)
+			}
 			for i := 0; i < b.N; i++ {
-				d := differ{
-					targetBytes: bb.afterBytes,
-				}
-				for _, opt := range bb.opts {
-					opt(&d)
-				}
-				d.diff(before, after)
+				d.Compare(before, after)
+				d.Reset()
 			}
 		})
 	}

compare.go

@@ -2,22 +2,18 @@ package jsondiff
 
 import "encoding/json"
 
-// An Option overrides the default diff behavior of
-// the CompareOpts and CompareJSONOpts function.
-type Option func(*differ)
-
 // Compare compares the JSON representations of the
 // given values and returns the differences relative
 // to the former as a list of JSON Patch operations.
 func Compare(source, target interface{}) (Patch, error) {
-	var d differ
+	var d Differ
 	return compare(&d, source, target)
 }
 
 // CompareOpts is similar to Compare, but also accepts
-// a list of options to configure the diff behavior.
+// a list of options to configure the behavior.
 func CompareOpts(source, target interface{}, opts ...Option) (Patch, error) {
-	var d differ
+	var d Differ
 	d.applyOpts(opts...)
 
 	return compare(&d, source, target)
@@ -27,47 +23,20 @@ func CompareOpts(source, target interface{}, opts ...Option) (Patch, error) {
 // returns the differences relative to the former as
 // a list of JSON Patch operations.
 func CompareJSON(source, target []byte) (Patch, error) {
-	var d differ
+	var d Differ
 	return compareJSON(&d, source, target)
 }
 
 // CompareJSONOpts is similar to CompareJSON, but also
-// accepts a list of options to configure the diff behavior.
+// accepts a list of options to configure the behavior.
 func CompareJSONOpts(source, target []byte, opts ...Option) (Patch, error) {
-	var d differ
+	var d Differ
 	d.applyOpts(opts...)
 
 	return compareJSON(&d, source, target)
 }
 
-// Factorize enables factorization of operations.
-func Factorize() Option {
-	return func(o *differ) { o.opts.factorize = true }
-}
-
-// Rationalize enables rationalization of operations.
-func Rationalize() Option {
-	return func(o *differ) { o.opts.rationalize = true }
-}
-
-// Equivalent disables the generation of operations for
-// arrays of equal length and content that are not ordered.
-func Equivalent() Option {
-	return func(o *differ) { o.opts.equivalent = true }
-}
-
-// Invertible enables the generation of an invertible
-// patch, by preceding each remove and replace operation
-// by a test operation that verifies the value at the
-// path that is being removed/replaced.
-// Note that copy operations are not invertible, and as
-// such, using this option disable the usage of copy
-// operation in favor of add operations.
-func Invertible() Option {
-	return func(o *differ) { o.opts.invertible = true }
-}
-
-func compare(d *differ, src, tgt interface{}) (Patch, error) {
+func compare(d *Differ, src, tgt interface{}) (Patch, error) {
 	si, _, err := marshalUnmarshal(src)
 	if err != nil {
 		return nil, err
@@ -77,12 +46,12 @@ func compare(d *differ, src, tgt interface{}) (Patch, error) {
 		return nil, err
 	}
 	d.targetBytes = tb
-	d.diff(si, ti)
+	d.Compare(si, ti)
 
 	return d.patch, nil
 }
 
-func compareJSON(d *differ, src, tgt []byte) (Patch, error) {
+func compareJSON(d *Differ, src, tgt []byte) (Patch, error) {
 	var si, ti interface{}
 	if err := json.Unmarshal(src, &si); err != nil {
 		return nil, err
@@ -91,13 +60,13 @@ func compareJSON(d *differ, src, tgt []byte) (Patch, error) {
 		return nil, err
 	}
 	d.targetBytes = tgt
-	d.diff(si, ti)
+	d.Compare(si, ti)
 
 	return d.patch, nil
 }
 
 // marshalUnmarshal returns the result of unmarshaling
-// the JSON representation of the given value.
+// the JSON representation of the given interface value.
 func marshalUnmarshal(i interface{}) (interface{}, []byte, error) {
 	b, err := json.Marshal(i)
 	if err != nil {

differ.go

@@ -5,7 +5,9 @@ import (
 	"strings"
 )
 
-type differ struct {
+// A Differ is a JSON Patch generator.
+// The zero value is an empty generator ready to use.
+type Differ struct {
 	patch       Patch
 	hasher      hasher
 	hashmap     map[uint64]jsonNode
@@ -20,14 +22,43 @@ type options struct {
 	equivalent  bool
 }
 
-func (d *differ) diff(src, tgt interface{}) {
+// Patch returns the list of JSON patch operations
+// generated by the Differ. The patch is valid for usage
+// until the next comparison or reset.
+func (d *Differ) Patch() Patch {
+	return d.patch
+}
+
+// WithOpts applies the given options to the Differ
+// and returns it to allow chained calls.
+func (d *Differ) WithOpts(opts ...Option) *Differ {
+	for _, o := range opts {
+		o(d)
+	}
+	return d
+}
+
+// Reset resets the Differ to be empty, but it retains the
+// underlying storage for use by future comparisons.
+func (d *Differ) Reset() {
+	d.patch = d.patch[:0]
+
+	// Optimized map clear.
+	for k := range d.hashmap {
+		delete(d.hashmap, k)
+	}
+}
+
+// Compare computes the differences between src and tgt as
+// a series of JSON Patch operations.
+func (d *Differ) Compare(src, tgt interface{}) {
 	if d.opts.factorize {
 		d.prepare(emptyPtr, src, tgt)
 	}
-	d.compare(emptyPtr, src, tgt)
+	d.diff(emptyPtr, src, tgt)
 }
 
-func (d *differ) compare(ptr pointer, src, tgt interface{}) {
+func (d *Differ) diff(ptr pointer, src, tgt interface{}) {
 	if src == nil && tgt == nil {
 		return
 	}
@@ -70,7 +101,7 @@ func (d *differ) compare(ptr pointer, src, tgt interface{}) {
 	}
 }
 
-func (d *differ) prepare(ptr pointer, src, tgt interface{}) {
+func (d *Differ) prepare(ptr pointer, src, tgt interface{}) {
 	if src == nil && tgt == nil {
 		return
 	}
@@ -110,7 +141,7 @@ func (d *differ) prepare(ptr pointer, src, tgt interface{}) {
 	}
 }
 
-func (d *differ) rationalizeLastOps(ptr pointer, src, tgt interface{}, lastOpIdx int) {
+func (d *Differ) rationalizeLastOps(ptr pointer, src, tgt interface{}, lastOpIdx int) {
 	newOps := make(Patch, 0, 2)
 
 	if d.opts.invertible {
@@ -140,23 +171,30 @@ func (d *differ) rationalizeLastOps(ptr pointer, src, tgt interface{}, lastOpIdx
 
 // compareObjects generates the patch operations that
 // represents the differences between two JSON objects.
-func (d *differ) compareObjects(ptr pointer, src, tgt map[string]interface{}) {
-	cmpSet := make(map[string]uint8)
+func (d *Differ) compareObjects(ptr pointer, src, tgt map[string]interface{}) {
+	cmpSet := map[string]uint8{}
 
 	for k := range src {
 		cmpSet[k] |= 1 << 0
 	}
 	for k := range tgt {
 		cmpSet[k] |= 1 << 1
 	}
-	for _, k := range sortedObjectKeys(cmpSet) {
+	keys := make([]string, 0, len(cmpSet))
+
+	for k := range cmpSet {
+		keys = append(keys, k)
+	}
+	sortStrings(keys)
+
+	for _, k := range keys {
 		v := cmpSet[k]
 		inOld := v&(1<<0) != 0
 		inNew := v&(1<<1) != 0
 
 		switch {
 		case inOld && inNew:
-			d.compare(ptr.appendKey(k), src[k], tgt[k])
+			d.diff(ptr.appendKey(k), src[k], tgt[k])
 		case inOld && !inNew:
 			d.remove(ptr.appendKey(k), src[k])
 		case !inOld && inNew:
@@ -167,7 +205,7 @@ func (d *differ) compareObjects(ptr pointer, src, tgt map[string]interface{}) {
 
 // compareArrays generates the patch operations that
 // represents the differences between two JSON arrays.
-func (d *differ) compareArrays(ptr pointer, src, tgt []interface{}) {
+func (d *Differ) compareArrays(ptr pointer, src, tgt []interface{}) {
 	size := min(len(src), len(tgt))
 
 	// When the source array contains more elements
@@ -183,7 +221,7 @@ func (d *differ) compareArrays(ptr pointer, src, tgt []interface{}) {
 	// Compare the elements at each index present in
 	// both the source and destination arrays.
 	for i := 0; i < size; i++ {
-		d.compare(ptr.appendIndex(i), src[i], tgt[i])
+		d.diff(ptr.appendIndex(i), src[i], tgt[i])
 	}
 next:
 	// When the target array contains more elements
@@ -194,7 +232,7 @@ next:
 	}
 }
 
-func (d *differ) unorderedDeepEqualSlice(src, tgt []interface{}) bool {
+func (d *Differ) unorderedDeepEqualSlice(src, tgt []interface{}) bool {
 	if len(src) != len(tgt) {
 		return false
 	}
@@ -206,7 +244,7 @@ func (d *differ) unorderedDeepEqualSlice(src, tgt []interface{}) bool {
 	}
 	for _, v := range tgt {
 		k := d.hasher.digest(v)
-		// If the digest hash if not in the diff,
+		// If the digest hash if not in the Compare,
 		// return early.
 		if _, ok := diff[k]; !ok {
 			return false
@@ -219,7 +257,7 @@ func (d *differ) unorderedDeepEqualSlice(src, tgt []interface{}) bool {
 	return len(diff) == 0
 }
 
-func (d *differ) add(ptr pointer, v interface{}) {
+func (d *Differ) add(ptr pointer, v interface{}) {
 	if !d.opts.factorize {
 		d.patch = d.patch.append(OperationAdd, emptyPtr, ptr, nil, v)
 		return
@@ -246,21 +284,21 @@ func (d *differ) add(ptr pointer, v interface{}) {
 	}
 }
 
-func (d *differ) replace(ptr pointer, src, tgt interface{}) {
+func (d *Differ) replace(ptr pointer, src, tgt interface{}) {
 	if d.opts.invertible {
 		d.patch = d.patch.append(OperationTest, emptyPtr, ptr, nil, src)
 	}
 	d.patch = d.patch.append(OperationReplace, emptyPtr, ptr, src, tgt)
 }
 
-func (d *differ) remove(ptr pointer, v interface{}) {
+func (d *Differ) remove(ptr pointer, v interface{}) {
 	if d.opts.invertible {
 		d.patch = d.patch.append(OperationTest, emptyPtr, ptr, nil, v)
 	}
 	d.patch = d.patch.append(OperationRemove, emptyPtr, ptr, v, nil)
 }
 
-func (d *differ) findUnchanged(v interface{}) pointer {
+func (d *Differ) findUnchanged(v interface{}) pointer {
 	if d.hashmap != nil {
 		k := d.hasher.digest(v)
 		node, ok := d.hashmap[k]
@@ -271,7 +309,7 @@ func (d *differ) findUnchanged(v interface{}) pointer {
 	return emptyPtr
 }
 
-func (d *differ) findRemoved(v interface{}) int {
+func (d *Differ) findRemoved(v interface{}) int {
 	for i := 0; i < len(d.patch); i++ {
 		op := d.patch[i]
 		if op.Type == OperationRemove && deepEqual(op.OldValue, v) {
@@ -281,21 +319,34 @@ func (d *differ) findRemoved(v interface{}) int {
 	return -1
 }
 
-func (d *differ) applyOpts(opts ...Option) {
+func (d *Differ) applyOpts(opts ...Option) {
 	for _, opt := range opts {
 		if opt != nil {
 			opt(d)
 		}
 	}
 }
 
-func sortedObjectKeys(m map[string]uint8) []string {
-	keys := make([]string, 0, len(m))
-	for k := range m {
-		keys = append(keys, k)
+func sortStrings(v []string) {
+	if len(v) < 20 {
+		insertionSort(v)
+	} else {
+		sort.Strings(v)
+	}
+}
+
+func insertionSort(v []string) {
+	for j := 1; j < len(v); j++ {
+		// Invariant: v[:j] contains the same elements as
+		// the original slice v[:j], but in sorted order.
+		key := v[j]
+		i := j - 1
+		for i >= 0 && v[i] > key {
+			v[i+1] = v[i]
+			i--
+		}
+		v[i+1] = key
 	}
-	sort.Strings(keys)
-	return keys
 }
 
 func min(i, j int) int {

differ_test.go

@@ -67,11 +67,11 @@ func runTestCases(t *testing.T, cases []testcase, opts ...Option) {
 			if err != nil {
 				t.Error(err)
 			}
-			d := differ{
+			d := Differ{
 				targetBytes: beforeBytes,
 			}
 			d.applyOpts(opts...)
-			d.diff(tc.Before, tc.After)
+			d.Compare(tc.Before, tc.After)
 
 			if d.patch != nil {
 				t.Logf("\n%s", d.patch)

hash.go

@@ -4,7 +4,6 @@ import (
 	"encoding/binary"
 	"hash/maphash"
 	"math"
-	"sort"
 	"strconv"
 )
 
@@ -15,6 +14,7 @@ type hasher struct {
 func (h *hasher) digest(val interface{}) uint64 {
 	h.mh.Reset()
 	h.hash(val)
+
 	return h.mh.Sum64()
 }
 
@@ -36,13 +36,14 @@ func (h *hasher) hash(i interface{}) {
 			h.hash(e)
 		}
 	case map[string]interface{}:
+		keys := make([]string, 0, len(v))
+
 		// Extract keys first, and sort them
 		// in lexicographical order.
-		keys := make([]string, 0, len(v))
 		for k := range v {
 			keys = append(keys, k)
 		}
-		sort.Strings(keys)
+		sortStrings(keys)
 
 		for _, k := range keys {
 			_, _ = h.mh.WriteString(k)

option.go

@@ -0,0 +1,31 @@
+package jsondiff
+
+// An Option changes the default behavior of a Differ.
+type Option func(*Differ)
+
+// Factorize enables factorization of operations.
+func Factorize() Option {
+	return func(o *Differ) { o.opts.factorize = true }
+}
+
+// Rationalize enables rationalization of operations.
+func Rationalize() Option {
+	return func(o *Differ) { o.opts.rationalize = true }
+}
+
+// Equivalent disables the generation of operations for
+// arrays of equal length and content that are not ordered.
+func Equivalent() Option {
+	return func(o *Differ) { o.opts.equivalent = true }
+}
+
+// Invertible enables the generation of an invertible
+// patch, by preceding each remove and replace operation
+// by a test operation that verifies the value at the
+// path that is being removed/replaced.
+// Note that copy operations are not invertible, and as
+// such, using this option disable the usage of copy
+// operation in favor of add operations.
+func Invertible() Option {
+	return func(o *Differ) { o.opts.invertible = true }
+}