Add godoc

Author: jpbetz

fieldpath/fromvalue.go

@@ -57,9 +57,9 @@ func (w *objectWalker) walk() {
 	case w.value.IsList():
 		// If the list were atomic, we'd break here, but we don't have
 		// a schema, so we can't tell.
-		l := w.value.AsListInto(w.allocator)
+		l := w.value.AsListUsing(w.allocator)
 		defer w.allocator.Free(l)
-		iter := l.RangeInto(w.allocator)
+		iter := l.RangeUsing(w.allocator)
 		defer w.allocator.Free(iter)
 		for iter.Next() {
 			i, value := iter.Item()
@@ -73,9 +73,9 @@ func (w *objectWalker) walk() {
 		// If the map/struct were atomic, we'd break here, but we don't
 		// have a schema, so we can't tell.
 
-		m := w.value.AsMapInto(w.allocator)
+		m := w.value.AsMapUsing(w.allocator)
 		defer w.allocator.Free(m)
-		m.IterateInto(w.allocator, func(k string, val value.Value) bool {
+		m.IterateUsing(w.allocator, func(k string, val value.Value) bool {
 			w2 := *w
 			w2.path = append(w.path, PathElement{FieldName: &k})
 			w2.value = val
@@ -112,7 +112,7 @@ func (w *objectWalker) GuessBestListPathElement(index int, item value.Value) Pat
 		return PathElement{Index: &index}
 	}
 
-	m := item.AsMapInto(w.allocator)
+	m := item.AsMapUsing(w.allocator)
 	defer w.allocator.Free(m)
 	var keys value.FieldList
 	for _, name := range AssociativeListCandidateFieldNames {

typed/helpers.go

@@ -162,7 +162,7 @@ func listValue(a value.Allocator, val value.Value) (value.List, error) {
 	if !val.IsList() {
 		return nil, fmt.Errorf("expected list, got %v", val)
 	}
-	return val.AsListInto(a), nil
+	return val.AsListUsing(a), nil
 }
 
 // Returns the map, or an error. Reminder: nil is a valid map and might be returned.
@@ -177,7 +177,7 @@ func mapValue(a value.Allocator, val value.Value) (value.Map, error) {
 	if !val.IsMap() {
 		return nil, fmt.Errorf("expected map, got %v", val)
 	}
-	return val.AsMapInto(a), nil
+	return val.AsMapUsing(a), nil
 }
 
 func keyedAssociativeListItemToPathElement(a value.Allocator, list *schema.List, index int, child value.Value) (fieldpath.PathElement, error) {
@@ -191,7 +191,7 @@ func keyedAssociativeListItemToPathElement(a value.Allocator, list *schema.List,
 		return pe, errors.New("associative list with keys may not have non-map elements")
 	}
 	keyMap := value.FieldList{}
-	m := child.AsMapInto(a)
+	m := child.AsMapUsing(a)
 	defer a.Free(m)
 	for _, fieldName := range list.Keys {
 		if val, ok := m.Get(fieldName); ok {

typed/merge.go

@@ -312,7 +312,7 @@ func (w *mergingWalker) visitMapItem(t *schema.Map, out map[string]interface{},
 func (w *mergingWalker) visitMapItems(t *schema.Map, lhs, rhs value.Map) (errs ValidationErrors) {
 	out := map[string]interface{}{}
 
-	value.MapZipInto(w.allocator, lhs, rhs, value.Unordered, func(key string, lhsValue, rhsValue value.Value) bool {
+	value.MapZipUsing(w.allocator, lhs, rhs, value.Unordered, func(key string, lhsValue, rhsValue value.Value) bool {
 		errs = append(errs, w.visitMapItem(t, out, key, lhsValue, rhsValue)...)
 		return true
 	})

typed/remove.go

@@ -20,18 +20,18 @@ import (
 )
 
 type removingWalker struct {
-	value    value.Value
-	out      interface{}
-	schema   *schema.Schema
-	toRemove *fieldpath.Set
+	value     value.Value
+	out       interface{}
+	schema    *schema.Schema
+	toRemove  *fieldpath.Set
 	allocator value.Allocator
 }
 
 func removeItemsWithSchema(val value.Value, toRemove *fieldpath.Set, schema *schema.Schema, typeRef schema.TypeRef) value.Value {
 	w := &removingWalker{
-		value:    val,
-		schema:   schema,
-		toRemove: toRemove,
+		value:     val,
+		schema:    schema,
+		toRemove:  toRemove,
 		allocator: value.NewFreelistAllocator(),
 	}
 	resolveSchema(schema, typeRef, val, w)
@@ -44,15 +44,15 @@ func (w *removingWalker) doScalar(t *schema.Scalar) ValidationErrors {
 }
 
 func (w *removingWalker) doList(t *schema.List) (errs ValidationErrors) {
-	l := w.value.AsListInto(w.allocator)
+	l := w.value.AsListUsing(w.allocator)
 	defer w.allocator.Free(l)
 	// If list is null, empty, or atomic just return
 	if l == nil || l.Length() == 0 || t.ElementRelationship == schema.Atomic {
 		return nil
 	}
 
 	var newItems []interface{}
-	iter := l.RangeInto(w.allocator)
+	iter := l.RangeUsing(w.allocator)
 	defer w.allocator.Free(iter)
 	for iter.Next() {
 		i, item := iter.Item()
@@ -74,7 +74,7 @@ func (w *removingWalker) doList(t *schema.List) (errs ValidationErrors) {
 }
 
 func (w *removingWalker) doMap(t *schema.Map) ValidationErrors {
-	m := w.value.AsMapInto(w.allocator)
+	m := w.value.AsMapUsing(w.allocator)
 	if m != nil {
 		defer w.allocator.Free(m)
 	}

typed/tofieldset.go

@@ -56,7 +56,7 @@ type toFieldSetWalker struct {
 
 	// Allocate only as many walkers as needed for the depth by storing them here.
 	spareWalkers *[]*toFieldSetWalker
-	allocator value.Allocator
+	allocator    value.Allocator
 }
 
 func (v *toFieldSetWalker) prepareDescent(pe fieldpath.PathElement, tr schema.TypeRef) *toFieldSetWalker {

typed/validate.go

@@ -116,7 +116,7 @@ func (v *validatingObjectWalker) doScalar(t *schema.Scalar) ValidationErrors {
 func (v *validatingObjectWalker) visitListItems(t *schema.List, list value.List) (errs ValidationErrors) {
 	observedKeys := fieldpath.MakePathElementSet(list.Length())
 	for i := 0; i < list.Length(); i++ {
-		child := list.AtInto(v.allocator, i)
+		child := list.AtUsing(v.allocator, i)
 		defer v.allocator.Free(child)
 		var pe fieldpath.PathElement
 		if t.ElementRelationship != schema.Associative {
@@ -161,7 +161,7 @@ func (v *validatingObjectWalker) doList(t *schema.List) (errs ValidationErrors)
 }
 
 func (v *validatingObjectWalker) visitMapItems(t *schema.Map, m value.Map) (errs ValidationErrors) {
-	m.IterateInto(v.allocator, func(key string, val value.Value) bool {
+	m.IterateUsing(v.allocator, func(key string, val value.Value) bool {
 		pe := fieldpath.PathElement{FieldName: &key}
 		tr := t.ElementType
 		if sf, ok := t.FindField(key); ok {

value/list.go

@@ -23,15 +23,25 @@ type List interface {
 	// At returns the item at the given position in the map. It will
 	// panic if the index is out of range.
 	At(int) Value
-	AtInto(Allocator, int) Value
+	// AtUsing uses the provided allocator and returns the item at the given
+	// position in the map. It will panic if the index is out of range.
+	// The returned Value should be given back to the Allocator when no longer needed
+	// by calling Allocator.Free(Value).
+	AtUsing(Allocator, int) Value
 	// Range returns a ListRange for iterating over the items in the list.
 	Range() ListRange
-	RangeInto(Allocator) ListRange
-
-	// Equals compares the two list, and return true if they are the same, false otherwise.
+	// RangeUsing uses the provided allocator and returns a ListRange for
+	// iterating over the items in the list.
+	// The returned Range should be given back to the Allocator when no longer needed
+	// by calling Allocator.Free(Value).
+	RangeUsing(Allocator) ListRange
+	// Equals compares the two lists, and return true if they are the same, false otherwise.
 	// Implementations can use ListEquals as a general implementation for this methods.
 	Equals(List) bool
-	EqualsInto(Allocator, List) bool
+	// EqualsUsing uses the provided allocator and compares the two lists, and return true if
+	// they are the same, false otherwise. Implementations can use ListEqualsUsing as a general
+	// implementation for this methods.
+	EqualsUsing(Allocator, List) bool
 }
 
 // ListRange represents a single iteration across the items of a list.
@@ -60,23 +70,25 @@ func (_ *emptyRange) Item() (index int, value Value) {
 // ListEquals compares two lists lexically.
 // WARN: This is a naive implementation, calling lhs.Equals(rhs) is typically the most efficient.
 func ListEquals(lhs, rhs List) bool {
-	return ListEqualsInto(defaultAllocator, lhs, rhs)
+	return ListEqualsUsing(HeapAllocator, lhs, rhs)
 }
 
-func ListEqualsInto(a Allocator, lhs, rhs List) bool {
+// ListEqualsUsing uses the provided allocator and compares two lists lexically.
+// WARN: This is a naive implementation, calling lhs.EqualsUsing(allocator, rhs) is typically the most efficient.
+func ListEqualsUsing(a Allocator, lhs, rhs List) bool {
 	if lhs.Length() != rhs.Length() {
 		return false
 	}
 
-	lhsRange := lhs.RangeInto(a)
+	lhsRange := lhs.RangeUsing(a)
 	defer a.Free(lhsRange)
-	rhsRange := rhs.RangeInto(a)
+	rhsRange := rhs.RangeUsing(a)
 	defer a.Free(rhsRange)
 
 	for lhsRange.Next() && rhsRange.Next() {
 		_, lv := lhsRange.Item()
 		_, rv := rhsRange.Item()
-		if !EqualsInto(a, lv, rv) {
+		if !EqualsUsing(a, lv, rv) {
 			return false
 		}
 	}
@@ -91,12 +103,15 @@ func ListLess(lhs, rhs List) bool {
 // ListCompare compares two lists lexically. The result will be 0 if l==rhs, -1
 // if l < rhs, and +1 if l > rhs.
 func ListCompare(lhs, rhs List) int {
-	return ListCompareInto(defaultAllocator, lhs, rhs)
+	return ListCompareUsing(HeapAllocator, lhs, rhs)
 }
-func ListCompareInto(a Allocator, lhs, rhs List) int {
-	lhsRange := lhs.RangeInto(a)
+
+// ListCompareUsing uses the provided allocator and compares two lists lexically. The result will be 0 if l==rhs, -1
+// if l < rhs, and +1 if l > rhs.
+func ListCompareUsing(a Allocator, lhs, rhs List) int {
+	lhsRange := lhs.RangeUsing(a)
 	defer a.Free(lhsRange)
-	rhsRange := rhs.RangeInto(a)
+	rhsRange := rhs.RangeUsing(a)
 	defer a.Free(rhsRange)
 
 	for {
@@ -116,7 +131,7 @@ func ListCompareInto(a Allocator, lhs, rhs List) int {
 		}
 		_, lv := lhsRange.Item()
 		_, rv := rhsRange.Item()
-		if c := CompareInto(a, lv, rv); c != 0 {
+		if c := CompareUsing(a, lv, rv); c != 0 {
 			return c
 		}
 		// The items are equal; continue.

value/listreflect.go

@@ -34,7 +34,7 @@ func (r listReflect) At(i int) Value {
 	return mustWrapValueReflect(val.Index(i), nil, nil)
 }
 
-func (r listReflect) AtInto(a Allocator, i int) Value {
+func (r listReflect) AtUsing(a Allocator, i int) Value {
 	val := r.Value
 	return a.allocValueReflect().mustReuse(val.Index(i), nil, nil, nil)
 }
@@ -49,10 +49,10 @@ func (r listReflect) Unstructured() interface{} {
 }
 
 func (r listReflect) Range() ListRange {
-	return r.RangeInto(defaultAllocator)
+	return r.RangeUsing(HeapAllocator)
 }
 
-func (r listReflect) RangeInto(a Allocator) ListRange {
+func (r listReflect) RangeUsing(a Allocator) ListRange {
 	length := r.Value.Len()
 	if length == 0 {
 		return EmptyRange
@@ -65,13 +65,13 @@ func (r listReflect) RangeInto(a Allocator) ListRange {
 }
 
 func (r listReflect) Equals(other List) bool {
-	return r.EqualsInto(defaultAllocator, other)
+	return r.EqualsUsing(HeapAllocator, other)
 }
-func (r listReflect) EqualsInto(a Allocator, other List) bool {
+func (r listReflect) EqualsUsing(a Allocator, other List) bool {
 	if otherReflectList, ok := other.(*listReflect); ok {
 		return reflect.DeepEqual(r.Value.Interface(), otherReflectList.Value.Interface())
 	}
-	return ListEqualsInto(a, &r, other)
+	return ListEqualsUsing(a, &r, other)
 }
 
 type listReflectRange struct {

value/listunstructured.go

@@ -26,23 +26,23 @@ func (l listUnstructured) At(i int) Value {
 	return NewValueInterface(l[i])
 }
 
-func (l listUnstructured) AtInto(a Allocator, i int) Value {
+func (l listUnstructured) AtUsing(a Allocator, i int) Value {
 	return a.allocValueUnstructured().reuse(l[i])
 }
 
 func (l listUnstructured) Equals(other List) bool {
-	return l.EqualsInto(defaultAllocator, other)
+	return l.EqualsUsing(HeapAllocator, other)
 }
 
-func (l listUnstructured) EqualsInto(a Allocator, other List) bool {
-	return ListEqualsInto(a, &l, other)
+func (l listUnstructured) EqualsUsing(a Allocator, other List) bool {
+	return ListEqualsUsing(a, &l, other)
 }
 
 func (l listUnstructured) Range() ListRange {
-	return l.RangeInto(defaultAllocator)
+	return l.RangeUsing(HeapAllocator)
 }
 
-func (l listUnstructured) RangeInto(a Allocator) ListRange {
+func (l listUnstructured) RangeUsing(a Allocator) ListRange {
 	if len(l) == 0 {
 		return EmptyRange
 	}