Move to FrogPilot API

frogpilot/third_party/h3/api/basic_str/__init__.py

@@ -1,5 +1,6 @@
 # This file is **symlinked** across the APIs to ensure they are exactly the same.
 from typing import Literal
+from array import array
 
 from ... import _cy
 from ..._h3shape import (
@@ -128,6 +129,20 @@ def average_hexagon_edge_length(res, unit='km'):
     return _cy.average_hexagon_edge_length(res, unit)
 
 
+def is_valid_index(h):
+    """Validates *any* H3 index (cell, vertex, or directed edge).
+
+    Returns
+    -------
+    bool
+    """
+    try:
+        h = _in_scalar(h)
+        return _cy.is_valid_index(h)
+    except (ValueError, TypeError):
+        return False
+
+
 def is_valid_cell(h):
     """
     Validates an H3 cell (hexagon or pentagon).
@@ -736,10 +751,124 @@ def get_base_cell_number(h):
     Returns
     -------
     int
+
+    Examples
+    --------
+    >>> h = construct_cell(57, 2, 1, 4)
+    >>> h
+    '83728cfffffffff'
+    >> get_base_cell_number(h)
+    57
     """
     return _cy.get_base_cell_number(_in_scalar(h))
 
 
+def get_index_digit(h, res):
+    """
+    Get the index digit of a cell at the given resolution.
+
+    Parameters
+    ----------
+    h : H3Cell
+        Cell whose index digit will be returned.
+    res : int
+        Resolution (``>= 1``) at which to read the digit.
+
+    Returns
+    -------
+    int
+        The index digit at the requested resolution.
+
+    Examples
+    --------
+    >>> h = construct_cell(7, 2, 1, 4)
+    >>> h
+    '830e8cfffffffff'
+    >>> get_index_digit(h, 1)
+    2
+    >>> get_index_digit(h, 2)
+    1
+    >>> get_index_digit(h, 3)
+    4
+    """
+    return _cy.get_index_digit(_in_scalar(h), res)
+
+
+def construct_cell(base_cell_number, *digits, res=None):
+    """
+    Construct cell from base cell and digits.
+
+    Parameters
+    ----------
+    base_cell_number : int
+        Base cell *number* (``0`` to ``121``).
+    *digits : int
+        Sequence of index digits (``0`` to ``6``).
+        Length of digits will be the resulting resolution of the output cell.
+    res : int, optional
+        Resolution of the constructed cell. If provided, it must equal
+        ``len(digits)``; otherwise it is inferred from the number of digits.
+
+    Returns
+    -------
+    H3Cell
+        The constructed cell.
+
+    Examples
+    --------
+    >>> construct_cell(7, 2, 1, 4)  # resolution 3 cell
+    '830e8cfffffffff'
+
+    >>> construct_cell(15, 0, 0, 5, 3)  # resolution 4 cell
+    '841e057ffffffff'
+
+    >>> construct_cell(15, 0, 0, 5, 3, res=4)
+    '841e057ffffffff'
+    """
+    if (res is not None) and (len(digits) != res):
+        raise ValueError('Resolution must match number of digits.')
+
+    digits = array('i', digits)
+    o = _cy.construct_cell(base_cell_number, digits)
+    return _out_scalar(o)
+
+
+def deconstruct_cell(h):
+    """
+    Deconstruct cell into base cell and digits.
+
+    Parameters
+    ----------
+    h : H3Cell
+        Cell to deconstruct.
+
+    Returns
+    -------
+    list of int
+        [base_cell_number, digit1, digit2, ..., digitN]
+
+    Examples
+    --------
+    >>> h = construct_cell(7, 2, 1, 4)  # resolution 3 cell
+    >>> h
+    '830e8cfffffffff'
+    >>> deconstruct_cell(h)
+    (7, 2, 1, 4)
+
+    >>> h = construct_cell(15, 0, 0, 5, 3)  # resolution 4 cell
+    >>> h
+    '841e057ffffffff'
+    >>> deconstruct_cell(h)
+    (15, 0, 0, 5, 3)
+    >>> construct_cell(*deconstruct_cell(h), 0) == cell_to_center_child(h)
+    """
+    res = get_resolution(h)
+    bc = get_base_cell_number(h)
+    digits = [get_index_digit(h, r + 1) for r in range(res)]
+
+    return [bc, *digits]
+
+
 def are_neighbor_cells(h1, h2):
     """
     Returns ``True`` if ``h1`` and ``h2`` are neighboring cells.