cellToChildPos gives the position of the child in an ordered list of all the children of the cell's parent at a given resolution. The "ordered list" here is the same order as returned by cellToChildren, which I believe is numerically sorted by index. Essentially, this function allows you to determine the numeric index of the cell among its siblings, given a parent resolution that defines the sibling list.
childPosToCell offers the reverse functionality, returning a child cell given a parent, a child resolution, and a child index.
This pair of functions opens up several new use cases:
Easy iteration through all children of some parent, with no need to allocate memory for cellToChildren. I think we can do this internally in the library using iterators, but this offers an ergonomic API for external consumers (simply iterate for (int i = 0; i < cellToChildrenSize(parent, res); i++) and take childPosToCell(i, parent, res)).
Compact representations for sets of common-ancestor cells, including arrays of small bit-width integers (e.g. uint16 if the parent/child res difference is <= 5) and bit arrays (e.g. 16807 bits / 2101 bytes to indicate yes/no whether each child 5 steps down is included in the set). This is likely more effective than compact if there's no particular likelihood that the cells are contiguous.
Association between data arrays and H3 indexes without the need to store the H3 indexes themselves (e.g. a list of 16807 values corresponding by position to each child 5 steps down from some parent)
Notes
I'm open to suggestions on the name. childPosition might be clearer (but longer), childIndex makes sense but risked confusion with H3 indexes.
I included exhaustive tests for 0-3 resolution steps for all cells up to res 2. Let me know if you think any further tests are needed here.
Coverage increased (+0.04%) to 98.64% when pulling 11722512c89b7a883515f5f752f1d9d120bf2b05 on nrabinowitz:child-pos-functions into 139e5bff48ec16e5af745136d514a5b104869427 on uber:master.
Adds two new functions:
cellToChildPos
gives the position of the child in an ordered list of all the children of the cell's parent at a given resolution. The "ordered list" here is the same order as returned bycellToChildren
, which I believe is numerically sorted by index. Essentially, this function allows you to determine the numeric index of the cell among its siblings, given a parent resolution that defines the sibling list.childPosToCell
offers the reverse functionality, returning a child cell given a parent, a child resolution, and a child index.This pair of functions opens up several new use cases:
cellToChildren
. I think we can do this internally in the library using iterators, but this offers an ergonomic API for external consumers (simply iteratefor (int i = 0; i < cellToChildrenSize(parent, res); i++)
and takechildPosToCell(i, parent, res)
).uint16
if the parent/child res difference is <= 5) and bit arrays (e.g. 16807 bits / 2101 bytes to indicate yes/no whether each child 5 steps down is included in the set). This is likely more effective thancompact
if there's no particular likelihood that the cells are contiguous.Notes
childPosition
might be clearer (but longer),childIndex
makes sense but risked confusion with H3 indexes.