% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hex_distance.R
\name{hex_distance}
\alias{hex_distance}
\title{Grid Distance Between Cells}
\usage{
hex_distance(cell_a, cell_b, grid)
}
\arguments{
\item{cell_a, cell_b}{Cell IDs. Must be the same length (pairs) or one
of them length 1 (broadcast). For H3 grids, character vectors.
For ISEA grids, numeric vectors.}

\item{grid}{A HexGridInfo or HexData object specifying the grid.}
}
\value{
An integer vector of grid distances. \code{NA} where the distance
cannot be computed (e.g., pentagon path issues in H3).
}
\description{
Computes the grid distance (minimum number of hops) between pairs
of hexagonal cells. This is a discrete distance measured in cell steps,
not a geodesic distance.
}
\details{
\strong{H3 backend:} Uses the vendored H3 \code{gridDistance} function.
Returns the exact shortest path length in cell hops.

\strong{ISEA backend:} For cells on the same quad, computes the cube-coordinate
distance: \verb{max(|di|, |dj|, |di + dj|)}. Cross-quad distances use BFS
expansion and may return \code{NA} for very distant cells.

For geodesic (geographic) distances between cell centers, convert to
lon/lat with \code{\link[=cell_to_lonlat]{cell_to_lonlat()}} and use \code{sf::st_distance()}.
}
\examples{
\donttest{
# H3 grid distance
g <- hex_grid(resolution = 5, type = "h3")
a <- lonlat_to_cell(10, 50, g)
b <- lonlat_to_cell(10.1, 50.1, g)
hex_distance(a, b, g)
}
}
\seealso{
\code{\link[=get_neighbors]{get_neighbors()}} for finding cells within a given distance,
\code{\link[=cell_to_lonlat]{cell_to_lonlat()}} for geographic coordinates
}
