feat: add IterateInOrder function

document/document.go

@@ -75,6 +75,34 @@ func Fields(d Document) ([]string, error) {
 	return fields, nil
 }
 
+func IterateInOrder(d Document, fn func(string, Value) error) error {
+	type pair struct {
+		field string
+		value Value
+	}
+	var pairs []pair
+
+	err := d.Iterate(func(field string, value Value) error {
+		pairs = append(pairs, pair{field, value})
+		return nil
+	})
+	if err != nil {
+		return err
+	}
+
+	sort.Slice(pairs, func(i, j int) bool {
+		return strings.Compare(pairs[i].field, pairs[j].field) == -1
+	})
+
+	for _, p := range pairs {
+		err := fn(p.field, p.value)
+		if err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
 // FieldBuffer stores a group of fields in memory. It implements the Document interface.
 type FieldBuffer struct {
 	fields []fieldValue

document/document_test.go

@@ -665,3 +665,19 @@ func BenchmarkDocumentIterate(b *testing.B) {
 		}
 	})
 }
+
+func TestIterateInOrder(t *testing.T) {
+	fb := new(document.FieldBuffer)
+
+	fb.Add("zyx", document.NewIntegerValue(3))
+	fb.Add("abc", document.NewIntegerValue(1))
+	fb.Add("cba", document.NewIntegerValue(2))
+
+	i := int64(0)
+	err := document.IterateInOrder(fb, func(_ string, value document.Value) error {
+		i++
+		require.Equal(t, i, value.V.(int64))
+		return nil
+	})
+	require.NoError(t, err)
+}