Iterator implementation for bson/array

GODRIVER-293

Change-Id: I60ead2ab754fed4a3dc2999dc21e9efe23247721

Author: Divjot Arora

bson/array.go

@@ -328,3 +328,9 @@ func (a *Array) MarshalBSON() ([]byte, error) {
 	}
 	return b, nil
 }
+
+// Iterator returns a ArrayIterator that can be used to iterate through the
+// elements of this Array.
+func (a *Array) Iterator() (*ArrayIterator, error) {
+	return NewArrayIterator(a)
+}

bson/array_iterator.go

@@ -0,0 +1,51 @@
+package bson
+
+// ArrayIterator facilitates iterating over a bson.Array.
+type ArrayIterator struct {
+	array *Array
+	pos   uint
+	val   *Value
+	err   error
+}
+
+// NewArrayIterator constructs a new ArrayIterator over a given Array
+func NewArrayIterator(array *Array) (*ArrayIterator, error) {
+	iter := &ArrayIterator{}
+	iter.array = array
+
+	return iter, nil
+}
+
+// Next fetches the next value in the Array, returning whether or not it could be fetched successfully. If true is
+// returned, call Value to get the value. If false is returned, call Err to check if an error occurred.
+func (iter *ArrayIterator) Next() bool {
+	v, err := iter.array.Lookup(iter.pos)
+
+	if err != nil {
+		// error if out of bounds
+		// don't assign iter.err
+		return false
+	}
+
+	_, err = v.validate(false)
+	if err != nil {
+		iter.err = err
+		return false
+	}
+
+	iter.val = v
+	iter.pos++
+
+	return true
+}
+
+// Value returns the current value of the ArrayIterator. The pointer returned will _always_ be the same for a given
+// ArrayIterator. The returned value will be nil if this function is called before the first successful call to Next().
+func (iter *ArrayIterator) Value() *Value {
+	return iter.val
+}
+
+// Err returns the error that occurred while iterating, or nil if none occurred.
+func (iter *ArrayIterator) Err() error {
+	return iter.err
+}

bson/array_test.go

@@ -222,6 +222,54 @@ func TestArray(t *testing.T) {
 			})
 		}
 	})
+	t.Run("Iterator", func(t *testing.T) {
+		iteratorTests := []struct {
+			name   string
+			values [][]*Value
+		}{
+			{"one-one", tapag.oneOne()},
+			{"two-one", tapag.twoOne()},
+		}
+
+		for _, tc := range iteratorTests {
+			t.Run(tc.name, func(t *testing.T) {
+				a := NewArray()
+				for _, elems := range tc.values {
+					a.Prepend(elems...)
+				}
+
+				iter, err := a.Iterator()
+				if err != nil {
+					t.Errorf("Got error creating array iterator: %s", err)
+				}
+
+				for _, elem := range tc.values {
+					if !iter.Next() {
+						t.Errorf("ArrayIterator.Next() returned false")
+					}
+
+					if err = iter.Err(); err != nil {
+						t.Errorf("ArrayIterator.Err() returned non-nil error: %s", err)
+					}
+
+					for _, val := range elem {
+						got := iter.Value()
+						if !valueEqual(got, val) {
+							t.Errorf("Returned element does not match expected element. got %#v; want %#v", got, val)
+						}
+					}
+				}
+
+				if iter.Next() {
+					t.Errorf("ArrayIterator.Next() returned true. expected false")
+				}
+
+				if err = iter.Err(); err != nil {
+					t.Errorf("ArrayIterator.Err() returned non-nil error: %s", err)
+				}
+			})
+		}
+	})
 }
 
 type testArrayPrependAppendGenerator struct{}