uber · zachcoleman · Jun 4, 2025 · Jun 3, 2025
diff --git a/h3.go b/h3.go
@@ -263,6 +263,50 @@ func (c Cell) GridDiskDistances(k int) ([][]Cell, error) {
 	return GridDiskDistances(c, k)
 }
 
+// GridRing produces the "hollow" ring of cells at exactly grid distance k from the origin cell.
+//
+// k-ring 0 returns just the origin hexagon.
+//
+// Elements of the output array may be left zero, as can happen when crossing a pentagon.
+func GridRing(origin Cell, k int) ([]Cell, error) {
+	if cells, err := GridRingUnsafe(origin, k); err == nil {
+		return cells, nil
+	}
+	diskDistances, err := GridDiskDistances(origin, k)
+	if err != nil {
+		return nil, err
+	}
+	return diskDistances[k], nil
+}
+
+// GridRing produces the "hollow" ring of cells at exactly grid distance k from the origin cell.
+//
+// k-ring 0 returns just the origin hexagon.
+//
+// Elements of the output array may be left zero, as can happen when crossing a pentagon.
+func (c Cell) GridRing(k int) ([]Cell, error) {
+	return GridRing(c, k)
+}
+
+// GridRingUnsafe produces the "hollow" ring of cells at exactly grid distance k from the origin cell.
+//
+// k-ring 0 returns just the origin hexagon.
+func GridRingUnsafe(origin Cell, k int) ([]Cell, error) {
+	if k < 0 {
+		return nil, ErrDomain
+	}
+	out := make([]C.H3Index, ringSize(k))
+	errC := C.gridRingUnsafe(C.H3Index(origin), C.int(k), &out[0])
+	return cellsFromC(out, true, false), toErr(errC)
+}
+
+// GridRingUnsafe produces the "hollow" ring of cells at exactly grid distance k from the origin cell.
+//
+// k-ring 0 returns just the origin hexagon.
+func (c Cell) GridRingUnsafe(k int) ([]Cell, error) {
+	return GridRingUnsafe(c, k)
+}
+
 // PolygonToCells takes a given GeoJSON-like data structure fills it with the
 // hexagon cells that are contained by the GeoJSON-like data structure.
 //

diff --git a/h3_test.go b/h3_test.go
@@ -231,6 +231,77 @@ func TestGridDiskDistances(t *testing.T) {
 	})
 }
 
+func TestGridRing(t *testing.T) {
+	t.Parallel()
+
+	t.Run("success", func(t *testing.T) {
+		t.Parallel()
+
+		gr, err := validCell.GridRing(1)
+		assertEqualDisks(t,
+			validDiskDist3_1[1],
+			gr,
+		)
+		assertNoErr(t, err)
+	})
+
+	t.Run("success/pentagon", func(t *testing.T) {
+		t.Parallel()
+
+		gr, err := GridRing(pentagonCell, 1)
+		assertEqual(t, 5, len(gr))
+		assertNoErr(t, err)
+	})
+
+	t.Run("err/invalid_cell", func(t *testing.T) {
+		t.Parallel()
+
+		c := Cell(-1)
+		_, err := c.GridRing(1)
+		assertErr(t, err)
+		assertErrIs(t, err, ErrCellInvalid)
+	})
+
+	t.Run("err/invalid_kring", func(t *testing.T) {
+		rings, err := GridRing(pentagonCell, -1)
+		assertErr(t, err)
+		assertErrIs(t, err, ErrDomain)
+		assertNil(t, rings)
+	})
+}
+
+func TestGridRingUnsafe(t *testing.T) {
+	t.Parallel()
+
+	t.Run("success", func(t *testing.T) {
+		t.Parallel()
+
+		gr, err := validCell.GridRingUnsafe(1)
+		assertEqualDisks(t,
+			validDiskDist3_1[1],
+			gr,
+		)
+		assertNoErr(t, err)
+	})
+
+	t.Run("err/pentagon", func(t *testing.T) {
+		t.Parallel()
+
+		_, err := GridRingUnsafe(pentagonCell, 1)
+		assertErr(t, err)
+		assertErrIs(t, err, ErrPentagon)
+	})
+
+	t.Run("err/invalid_cell", func(t *testing.T) {
+		t.Parallel()
+
+		c := Cell(-1)
+		_, err := c.GridRingUnsafe(1)
+		assertErr(t, err)
+		assertErrIs(t, err, ErrCellInvalid)
+	})
+}
+
 func TestIsValid(t *testing.T) {
 	t.Parallel()
 	assertTrue(t, validCell.IsValid())
@@ -1401,7 +1472,7 @@ func flattenDisks(diskDist [][]Cell) []Cell {
 
 	flat := make([]Cell, 0, maxGridDiskSize(len(diskDist)-1))
 	for _, disk := range diskDist {
-		flat = append(flat, append([]Cell{}, disk...)...)
+		flat = append(flat, disk...)
 	}
 
 	return flat