Core Cell Operations

def latlng_to_cell(lat: float, lng: float, res: int) -> str:
    """
    Convert latitude/longitude to H3 cell at specified resolution.
    
    Args:
        lat: Latitude in degrees (-90 to 90)
        lng: Longitude in degrees (-180 to 180)
        res: H3 resolution (0-15, where 0 is coarsest, 15 is finest)
        
    Returns:
        H3 cell identifier as hexadecimal string
        
    Raises:
        H3LatLngDomainError: If lat/lng outside valid ranges
        H3ResDomainError: If resolution outside 0-15 range
    """

def is_valid_cell(h: str) -> bool:
    """
    Check if an H3 cell identifier is valid.
    
    Args:
        h: H3 cell identifier (string or int)
        
    Returns:
        True if valid H3 cell, False otherwise
        
    Note:
        Returns False for any input that cannot be parsed as H3 cell,
        including H3 edges or vertices.
    """

def get_resolution(h: str) -> int:
    """
    Get the resolution of an H3 cell.
    
    Args:
        h: H3 cell identifier
        
    Returns:
        Resolution level (0-15)
        
    Raises:
        H3CellInvalidError: If h is not a valid H3 cell
    """

def is_pentagon(h: str) -> bool:
    """
    Check if an H3 cell is a pentagon.
    
    Args:
        h: H3 cell identifier
        
    Returns:
        True if cell is a pentagon, False if hexagon
        
    Note:
        There are exactly 12 pentagons at each resolution level.
        All other cells are hexagons.
    """

def get_base_cell_number(h: str) -> int:
    """
    Get the base cell number (0-121) of an H3 cell.
    
    Args:
        h: H3 cell identifier
        
    Returns:
        Base cell number (0 to 121)
        
    Note:
        The base cell is the resolution-0 cell containing this cell.
    """

def is_res_class_III(h: str) -> bool:
    """
    Determine if cell has Class II or Class III orientation.
    
    Args:
        h: H3 cell identifier
        
    Returns:
        True if Class III orientation, False if Class II
        
    Note:
        Class III resolutions: 1,3,5,7,9,11,13,15
        Class II resolutions: 0,2,4,6,8,10,12,14
    """

def cell_to_latlng(h: str) -> tuple[float, float]:
    """
    Get the center coordinates of an H3 cell.
    
    Args:
        h: H3 cell identifier
        
    Returns:
        Tuple of (latitude, longitude) in degrees
        
    Raises:
        H3CellInvalidError: If h is not a valid H3 cell
    """

def cell_to_boundary(h: str) -> tuple[tuple[float, float], ...]:
    """
    Get the boundary vertices of an H3 cell.
    
    Args:
        h: H3 cell identifier
        
    Returns:
        Tuple of (lat, lng) coordinate pairs defining cell boundary.
        Hexagons return 6 points, pentagons return 5 points.
        
    Raises:
        H3CellInvalidError: If h is not a valid H3 cell
        
    Note:
        Points are ordered counterclockwise around the cell boundary.
    """

def str_to_int(h: str) -> int:
    """
    Convert hexadecimal string H3 identifier to 64-bit integer.
    
    Args:
        h: H3 identifier as hexadecimal string (e.g., '89754e64993ffff')
        
    Returns:
        H3 identifier as unsigned 64-bit integer
        
    Raises:
        ValueError: If h is not valid hexadecimal format
    """

def int_to_str(x: int) -> str:
    """
    Convert 64-bit integer H3 identifier to hexadecimal string.
    
    Args:
        x: H3 identifier as unsigned 64-bit integer
        
    Returns:
        H3 identifier as hexadecimal string (e.g., '89754e64993ffff')
        
    Raises:
        ValueError: If x is not a valid H3 integer identifier
    """

def versions() -> dict[str, str]:
    """
    Get version information for H3 Python and C libraries.
    
    Returns:
        Dictionary with keys:
        - 'python': Python wrapper version (e.g., '4.3.1')  
        - 'c': C library version (e.g., '4.3.0')
        
    Note:
        Python and C versions match on major.minor but may differ on patch.
    """

def get_num_cells(res: int) -> int:
    """
    Get total number of H3 cells at a given resolution.
    
    Args:
        res: H3 resolution (0-15)
        
    Returns:
        Total number of cells (hexagons + pentagons) at resolution
        
    Raises:
        H3ResDomainError: If resolution outside 0-15 range
        
    Note:
        Cell counts grow exponentially: ~7x more cells per resolution level.
    """

import h3

# Create cell from coordinates
lat, lng = 37.7749, -122.4194  # San Francisco
cell = h3.latlng_to_cell(lat, lng, resolution=9)
print(f"Cell: {cell}")  # Cell: 89283082e6bffff

# Validate and get properties  
if h3.is_valid_cell(cell):
    print(f"Resolution: {h3.get_resolution(cell)}")  # Resolution: 9
    print(f"Is pentagon: {h3.is_pentagon(cell)}")    # Is pentagon: False
    print(f"Base cell: {h3.get_base_cell_number(cell)}")  # Base cell: 20

# Get center and boundary
center = h3.cell_to_latlng(cell)
print(f"Center: {center[0]:.6f}, {center[1]:.6f}")

boundary = h3.cell_to_boundary(cell)
print(f"Boundary has {len(boundary)} vertices")
for i, (lat, lng) in enumerate(boundary):
    print(f"  Vertex {i}: {lat:.6f}, {lng:.6f}")

import h3

# Convert between string and integer formats
hex_cell = '89283082e6bffff'
int_cell = h3.str_to_int(hex_cell)
print(f"Integer: {int_cell}")  # Integer: 621566949282324479

# Convert back to string
back_to_hex = h3.int_to_str(int_cell)
print(f"Hex: {back_to_hex}")   # Hex: 89283082e6bffff
assert hex_cell == back_to_hex

# Use integer API directly
import h3.api.basic_int as h3int
cell_int = h3int.latlng_to_cell(37.7749, -122.4194, 9)
print(f"Integer cell: {cell_int}")  # Integer cell: 621566949282324479

import h3

# Check library versions
versions = h3.versions()
print(f"Python h3: {versions['python']}")  # Python h3: 4.3.1
print(f"C library: {versions['c']}")       # C library: 4.3.0

# Get cell counts by resolution
for res in range(0, 6):
    count = h3.get_num_cells(res)
    print(f"Resolution {res}: {count:,} cells")
    
# Resolution 0: 122 cells
# Resolution 1: 842 cells  
# Resolution 2: 5,882 cells
# Resolution 3: 41,162 cells
# Resolution 4: 288,122 cells
# Resolution 5: 2,016,842 cells