% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hexify_neighbors.R
\name{get_neighbors}
\alias{get_neighbors}
\title{Get Neighboring Cells}
\usage{
get_neighbors(cell_id, grid, k = 1L, include_self = FALSE, distances = FALSE)
}
\arguments{
\item{cell_id}{Cell IDs to find neighbors for. Numeric vector for ISEA
grids, character vector for H3 grids.}

\item{grid}{A HexGridInfo or HexData object specifying the grid.}

\item{k}{Integer. Ring distance (default 1). \code{k = 1} returns immediate
neighbors, \code{k = 2} includes neighbors-of-neighbors, etc.}

\item{include_self}{Logical. If \code{TRUE}, include the input cell in the
result (default \code{FALSE}).}

\item{distances}{Logical. If \code{TRUE}, return a data.frame with cell IDs
and their ring distance from the origin (default \code{FALSE}).}
}
\value{
If \code{distances = FALSE} (default): a list of cell ID vectors, one
per input cell. If \code{distances = TRUE}: a list of data.frames with columns
\code{cell_id} and \code{ring_distance}.
}
\description{
Returns the k-ring (disk) of cells neighboring the input cells.
For \code{k = 1}, returns the immediate 6 neighbors (5 for pentagons).
For \code{k > 1}, returns all cells within \code{k} grid hops.
}
\details{
For \strong{ISEA grids}, neighbors are computed using axial coordinate offsets
in the quad IJ space. Cells at quad boundaries are handled by reprojection
through lon/lat coordinates.

For \strong{H3 grids}, neighbors use the vendored H3 \code{gridDisk} /
\code{gridDiskDistances} functions.

Pentagon cells (the 12 icosahedron vertices) have only 5 neighbors instead
of the usual 6.
}
\examples{
\donttest{
# ISEA grid neighbors
g <- hex_grid(area_km2 = 1000)
cell <- lonlat_to_cell(10, 50, g)
nbrs <- get_neighbors(cell, g)
nbrs[[1]]

# H3 grid neighbors
g_h3 <- hex_grid(resolution = 5, type = "h3")
cell_h3 <- lonlat_to_cell(10, 50, g_h3)
get_neighbors(cell_h3, g_h3, k = 2)

# With distances
get_neighbors(cell, g, k = 2, distances = TRUE)
}
}
\seealso{
\code{\link[=hexify]{hexify()}} for creating HexData objects,
\code{\link[=hex_distance]{hex_distance()}} for grid distances between cells
}
