CellID.AllNeighbors: Return nil for invalid level (golang#146)

Return nil if level is too low (cells are too large and might not be
neighbors) or higher than MaxLevel (no such cells exist). Weakens
precondition of function.

golang#104 complained that AllNeighbors
was returning the wrong results, but the level precondition was being
violated. Make this more obvious and less confusing.

Author: jmr

s2/cellid.go

@@ -268,8 +268,13 @@ func (ci CellID) VertexNeighbors(level int) []CellID {
 // same neighbor may be returned more than once. There could be up to eight
 // neighbors including the diagonal ones that share the vertex.
 //
-// This requires level >= ci.Level().
+// Returns nil if level < ci.Level() (cells would not be neighboring) or
+// level > MaxLevel (no such cells exist).
 func (ci CellID) AllNeighbors(level int) []CellID {
+	if level < ci.Level() || level > MaxLevel {
+		return nil
+	}
+
 	var neighbors []CellID
 
 	face, i, j, _ := ci.faceIJOrientation()

s2/cellid_test.go

@@ -323,6 +323,19 @@ func TestCellIDAllNeighbors(t *testing.T) {
 	}
 }
 
+func TestCellIDAllNeighborsBadLevels(t *testing.T) {
+	ci := CellIDFromLatLng(LatLngFromDegrees(47.38, 8.54)).Parent(29)
+	if got := ci.AllNeighbors(-1); got != nil {
+		t.Errorf("AllNeighbors(%v) = %v, want nil", -1, got)
+	}
+	if got := ci.AllNeighbors(28); got != nil {
+		t.Errorf("AllNeighbors(%v) = %v, want nil", 28, got)
+	}
+	if got := ci.AllNeighbors(31); got != nil {
+		t.Errorf("AllNeighbors(%v) = %v, want nil", 31, got)
+	}
+}
+
 func TestCellIDTokensNominal(t *testing.T) {
 	tests := []struct {
 		token string