### Install PGXN Client on Ubuntu

Source: https://github.com/zachasme/h3-pg/blob/main/docs/pgxnclient.md

Installs the PGXN Client using the apt package manager on Ubuntu systems. This command fetches and installs the necessary packages for the PGXN client tool.

```bash
apt-get install pgxnclient
```

--------------------------------

### Install PGXN Client on macOS

Source: https://github.com/zachasme/h3-pg/blob/main/docs/pgxnclient.md

Installs the PGXN Client using the Homebrew package manager on macOS systems. This command downloads and sets up the PGXN client for use on your Mac.

```bash
brew install pgxnclient
```

--------------------------------

### Generate Documentation

Source: https://github.com/zachasme/h3-pg/blob/main/docs/development.md

Uses the `scripts/documentaion` script to generate documentation from SQL files. This process requires Poetry to be installed.

```shell
scripts/documentaion
```

--------------------------------

### Install and Load h3 Extension with PGXN Client

Source: https://github.com/zachasme/h3-pg/blob/main/README.md

Installs and loads the h3 extension using the PGXN Client. This is a quick method if prerequisites are met.

```Shell
$ pgxn install h3
$ pgxn load h3
```

--------------------------------

### Build h3-pg Extension

Source: https://github.com/zachasme/h3-pg/blob/main/README.md

Commands to build the h3-pg extension using CMake. This involves generating the build system, compiling, and installing.

```Shell
# Generate native build system
cmake -B build -DCMAKE_BUILD_TYPE=Release

# Build extension(s)
cmake --build build

# Install extensions (might require sudo)
cmake --install build --component h3-pg
```

--------------------------------

### Install h3-pg on Debian/Ubuntu

Source: https://github.com/zachasme/h3-pg/blob/main/README.md

Installs the h3-pg PostgreSQL extension on Debian/Ubuntu systems using apt. Replace '16' with your PostgreSQL version.

```Shell
sudo apt install postgresql-16-h3
```

--------------------------------

### H3 Raster Data Summarization Example

Source: https://github.com/zachasme/h3-pg/blob/main/docs/api.md

Example SQL query demonstrating how to use H3 raster functions to calculate summary statistics (count, sum, mean, stddev, min, max) for continuous raster data within H3 cells.

```SQL
SELECT
    (summary).h3 AS h3,
    (h3_raster_summary_stats_agg((summary).stats)).*
FROM (
    SELECT h3_raster_summary(rast, 8) AS summary
    FROM rasters
) t
GROUP BY 1;
```

--------------------------------

### Install h3-pg on Redhat Derivatives

Source: https://github.com/zachasme/h3-pg/blob/main/README.md

Installs the h3-pg PostgreSQL extension on Redhat derivatives (Rocky/EL 8+, Fedora 37+) using yum. Replace '16' with your PostgreSQL version.

```Shell
sudo yum install h3-pg_16
```

--------------------------------

### Define PostgreSQL Extension

Source: https://github.com/zachasme/h3-pg/blob/main/h3/CMakeLists.txt

Defines the PostgreSQL extension 'h3' using a build script command. It specifies properties like relocatability, name, comment, version, component, source files, installation scripts, and update scripts.

```build script
PostgreSQL_add_extension(
  postgresql_h3
  RELOCATABLE
  NAME h3
  COMMENT "H3 bindings for PostgreSQL"
  VERSION ${INSTALL_VERSION}
  COMPONENT ${PROJECT_NAME}
  SOURCES
    src/binding/edge.c
    src/binding/hierarchy.c
    src/binding/indexing.c
    src/binding/inspection.c
    src/binding/miscellaneous.c
    src/binding/regions.c
    src/binding/traversal.c
    src/binding/vertex.c
    src/deprecated.c
    src/extension.c
    src/guc.c
    src/init.c
    src/opclass_btree.c
    src/opclass_hash.c
    src/opclass_spgist.c
    src/operators.c
    src/srf.c
    src/type.c
  INSTALLS
    sql/install/00-type.sql
    sql/install/01-indexing.sql
    sql/install/02-inspection.sql
    sql/install/03-traversal.sql
    sql/install/04-hierarchy.sql
    sql/install/05-regions.sql
    sql/install/06-edge.sql
    sql/install/07-vertex.sql
    sql/install/08-miscellaneous.sql
    sql/install/10-operators.sql
    sql/install/11-opclass_btree.sql
    sql/install/12-opclass_hash.sql
    sql/install/13-opclass_brin.sql
    sql/install/14-opclass_spgist.sql
    sql/install/20-casts.sql
    sql/install/30-extension.sql
    sql/install/99-deprecated.sql
  UPDATES
    sql/updates/h3--0.1.0.sql
    sql/updates/h3--0.1.0--0.2.0.sql
    sql/updates/h3--0.2.0--0.3.0.sql
    sql/updates/h3--0.3.0--0.3.1.sql
    sql/updates/h3--0.3.1--0.3.2.sql
    sql/updates/h3--0.3.2--0.4.0.sql
    sql/updates/h3--0.4.0--1.0.0.sql
    sql/updates/h3--1.0.0--1.0.1.sql
    sql/updates/h3--1.0.1--1.0.2.sql
    sql/updates/h3--1.0.2--1.0.3.sql
    sql/updates/h3--1.0.3--1.0.4.sql
    sql/updates/h3--1.0.4--1.0.5.sql
    sql/updates/h3--1.0.5--1.0.6.sql
    sql/updates/h3--1.0.6--3.4.0.sql
    sql/updates/h3--3.4.0--3.4.1.sql
    sql/updates/h3--3.4.1--3.5.0.sql
    sql/updates/h3--3.5.0--3.6.0.sql
    sql/updates/h3--3.6.0--3.6.1.sql
    sql/updates/h3--3.6.1--3.6.2.sql
    sql/updates/h3--3.6.2--3.6.3.sql
    sql/updates/h3--3.6.3--3.6.4.sql
    sql/updates/h3--3.6.4--3.6.5.sql
    sql/updates/h3--3.6.5--3.7.0.sql
    sql/updates/h3--3.7.0--3.7.1.sql
    sql/updates/h3--3.7.1--3.7.2.sql
    sql/updates/h3--3.7.2--4.0.0.sql
    sql/updates/h3--4.0.0--4.0.1.sql
    sql/updates/h3--4.0.1--4.0.2.sql
    sql/updates/h3--4.0.2--4.0.3.sql
    sql/updates/h3--4.0.3--4.1.0.sql
    sql/updates/h3--4.1.0--4.1.1.sql
    sql/updates/h3--4.1.1--4.1.2.sql
    sql/updates/h3--4.1.2--4.1.3.sql
    sql/updates/h3--4.1.3--4.1.4.sql
    sql/updates/h3--4.1.4--4.2.0.sql
    sql/updates/h3--4.2.0--4.2.1.sql
    sql/updates/h3--4.2.1--4.2.2.sql
    sql/updates/h3--4.2.2--4.2.3.sql
    sql/updates/h3--4.2.3--unreleased.sql
)
```

--------------------------------

### Shell: Validate h3-postgis Extension Upgrade

Source: https://github.com/zachasme/h3-pg/blob/main/h3_postgis/test/CMakeLists.txt

Sets up a CMake test to validate the upgrade path for the h3_postgis extension using the pg_validate_extupgrade utility. It specifies the extension name, the source version, and the target installation version.

```shell
if(PostgreSQL_VALIDATE_EXTUPGRADE)
  add_test(
    NAME "h3_postgis_validate_extupgrade"
    COMMAND pg_validate_extupgrade
        --extname h3_postgis
        --from 4.0.0
        --to ${INSTALL_VERSION}
  )
endif()
```

--------------------------------

### PostgreSQL H3 PostGIS Extension Definition

Source: https://github.com/zachasme/h3-pg/blob/main/h3_postgis/CMakeLists.txt

Defines the PostgreSQL extension 'h3_postgis', specifying its components, dependencies on H3 and PostGIS, source files, and installation scripts. This block outlines the structure and contents of the extension for PostgreSQL.

```APIDOC
PostgreSQL_add_extension(postgresql_h3_postgis
  RELOCATABLE
  NAME h3_postgis
  COMMENT "H3 PostGIS integration"
  VERSION ${INSTALL_VERSION}
  COMPONENT ${PROJECT_NAME}
  REQUIRES
    h3
    postgis
    postgis_raster
  SOURCES
    src/init.c
    src/wkb_bbox3.c
    src/wkb_indexing.c
    src/wkb_linked_geo.c
    src/wkb_regions.c
    src/wkb_split.c
    src/wkb_vect3.c
    src/wkb.c
  INSTALLS
    sql/install/01-indexing.sql
    sql/install/03-traversal.sql
    sql/install/05-regions.sql
    sql/install/10-operators.sql
    sql/install/20-casts.sql
    sql/install/30-wkb.sql
    sql/install/40-rasters.sql
    sql/install/99-deprecated.sql
  UPDATES
    sql/updates/h3_postgis--4.0.0.sql
    sql/updates/h3_postgis--4.0.0--4.0.1.sql
    sql/updates/h3_postgis--4.0.1--4.0.2.sql
    sql/updates/h3_postgis--4.0.2--4.0.3.sql
    sql/updates/h3_postgis--4.0.3--4.1.0.sql
    sql/updates/h3_postgis--4.1.0--4.1.1.sql
    sql/updates/h3_postgis--4.1.1--4.1.2.sql
    sql/updates/h3_postgis--4.1.2--4.1.3.sql
    sql/updates/h3_postgis--4.1.3--4.1.4.sql
    sql/updates/h3_postgis--4.1.4--4.2.0.sql
    sql/updates/h3_postgis--4.2.0--4.2.1.sql
    sql/updates/h3_postgis--4.2.1--4.2.2.sql
    sql/updates/h3_postgis--4.2.2--4.2.3.sql
    sql/updates/h3_postgis--4.2.3--unreleased.sql
)
```

--------------------------------

### Fetch and Configure h3 Dependency

Source: https://github.com/zachasme/h3-pg/blob/main/cmake/h3/CMakeLists.txt

Demonstrates fetching the h3 C library using CMake's FetchContent module, disabling optional tooling, and setting target properties and include directories for the library.

```cmake
include(FetchContent)

# Skip core tooling we won't need for extension
set(ENABLE_COVERAGE   OFF)
set(BUILD_BENCHMARKS  OFF)
set(BUILD_FUZZERS     OFF)
set(BUILD_FILTERS     OFF)
set(BUILD_GENERATORS  OFF)
set(ENABLE_FORMAT     OFF)
set(ENABLE_LINTING    OFF)
set(ENABLE_DOCS       OFF)

FetchContent_Declare(
  h3
  URL      https://github.com/uber/h3/archive/refs/tags/v${H3_CORE_VERSION}.tar.gz
  URL_HASH SHA256=${H3_CORE_SHA256}
)
FetchContent_MakeAvailable(h3)

set_target_properties(h3 PROPERTIES
  INTERPROCEDURAL_OPTIMIZATION TRUE
  C_VISIBILITY_PRESET          hidden
)

set(H3_INCLUDE_DIR ${h3_BINARY_DIR}/src/h3lib/include)
```

--------------------------------

### SP-GiST Indexing (Experimental)

Source: https://github.com/zachasme/h3-pg/blob/main/docs/api.md

Instructions for creating an SP-GiST index using the experimental h3index_ops_experimental operator class.

```APIDOC
Add an SP-GiST index using the `h3index_ops_experimental` operator class:
```sql
-- CREATE INDEX [indexname] ON [tablename] USING spgist([column] h3index_ops_experimental);
CREATE INDEX spgist_idx ON h3_data USING spgist(hex h3index_ops_experimental);
```
*This is still an experimental feature and may change in future versions.*
```

--------------------------------

### Prepare for Development (Post-Release)

Source: https://github.com/zachasme/h3-pg/blob/main/docs/development.md

Resets the `INSTALL_VERSION` in the root `CMakeLists.txt` to 'unreleased' after a release. It also involves creating new update files with the `--unreleased` suffix and adding them to relevant CMakeLists.txt files.

```cmake
set(INSTALL_VERSION "unreleased")
```

--------------------------------

### Run Development Script

Source: https://github.com/zachasme/h3-pg/blob/main/docs/development.md

Executes the `./scripts/develop` script to build and test changes in the project. This is the primary command for local development.

```shell
./scripts/develop
```

--------------------------------

### Build Configuration and Dependencies

Source: https://github.com/zachasme/h3-pg/blob/main/h3/CMakeLists.txt

Configures build settings, including generating configuration headers, setting include directories, and linking necessary libraries. It also includes conditional compilation for testing.

```build script
# configure
configure_file(src/config.h.in src/config.h)

# include
target_include_directories(postgresql_h3 PRIVATE
  ${CMAKE_CURRENT_BINARY_DIR}/src
  src
)

# link
target_link_libraries(postgresql_h3 PRIVATE
  postgresql_h3_shared
  h3
)

# test
if(BUILD_TESTING)
  add_subdirectory(test)
endif()
```

--------------------------------

### h3-pg CMake Build Configuration

Source: https://github.com/zachasme/h3-pg/blob/main/CMakeLists.txt

This entry details the CMake build configuration for the h3-pg project. It covers setting the minimum CMake version, project definition, module paths, package finding (PostgreSQL, PostGIS), including subdirectories for core H3 and extensions, and defining a custom target for packaging.

```APIDOC
Project: h3-pg

# Copyright 2022 Zacharias Knudsen
# 
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
# 
#     http://www.apache.org/licenses/LICENSE-2.0
# 
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# CMake Minimum Version Requirement
# Specifies the minimum and maximum tested versions of CMake.
# Ensures compatibility with a range of CMake versions.
cmake_minimum_required(VERSION 3.20..3.24)

# Policy CMP0135
# Sets the timestamps of all extracted contents to the time of extraction.
if(POLICY CMP0135)
  cmake_policy(SET CMP0135 NEW)
endif()

# Project Definition
# Defines the project name, version, and primary language.
# Sets useful variables like PROJECT_NAME and PROJECT_VERSION.
project(
  h3-pg
  VERSION 4.2.3
  LANGUAGES C
)

# Installation Version Variable
# Sets the version used for installation, defaults to 'unreleased' if not a release.
set(INSTALL_VERSION "unreleased")

# H3 Core Library Version and SHA256
# Defines the version and checksum for the H3 core library.
set(H3_CORE_VERSION 4.2.0)
set(H3_CORE_SHA256 438db46fc2b388785d2a0d8e26aa5509739240a7b50b2510c416778d871a4e11)

# Module Path Configuration
# Appends the 'cmake' directory to the module path, allowing CMake to find custom modules.
list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")

# PostgreSQL Version Configuration
# Allows forcing a specific PostgreSQL version via an environment variable.
# CACHE STRING makes it a user-configurable variable.
set(POSTGRESQL_VERSION $ENV{POSTGRESQL_VERSION} CACHE STRING "PostgreSQL version major")

# Package Finding
# Finds the PostgreSQL package, optionally including PostGIS components.
# Requires PostgreSQL to be installed and discoverable.
find_package(PostgreSQL ${POSTGRESQL_VERSION} REQUIRED
  OPTIONAL_COMPONENTS PostGIS
)

# Include PostgreSQL Extension Module
# Imports CMake functions for adding PostgreSQL extensions.
include(AddPostgreSQLExtension)

# Define PostgreSQL Version Macro
# Adds a preprocessor definition for the PostgreSQL major version.
add_definitions(-DPOSTGRESQL_VERSION_MAJOR=${PostgreSQL_VERSION_MAJOR})

# CTest Configuration
# Includes CTest support if the project name matches the CMake project name.
# Used for running tests.
if(CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
  include(CTest)
endif()

# Subdirectory Inclusion
# Includes subdirectories for the core H3 library, include files, and the H3 PostgreSQL extension.
# This structures the build process by incorporating different parts of the project.
add_subdirectory(cmake/h3)
add_subdirectory(include)
add_subdirectory(h3)
add_subdirectory(h3_postgis)

# PGXN Packaging Target
# Configures a META.json file and creates a custom target 'pgxn' to build a zip archive for PGXN.
# The archive includes the project files and is prefixed with the project version.
configure_file(META.json.in META.json)
add_custom_target(pgxn
  COMMAND git archive --format zip
                      --prefix="h3-${INSTALL_VERSION}/"
                      --add-file ${CMAKE_BINARY_DIR}/META.json
                      -o h3-${INSTALL_VERSION}.zip HEAD
  WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
)

```

--------------------------------

### Bundle Release

Source: https://github.com/zachasme/h3-pg/blob/main/docs/development.md

Executes the `scripts/bundle` script to package the release artifacts. This is a crucial step in preparing the extension for distribution.

```shell
scripts/bundle
```

--------------------------------

### CMake Build Configuration

Source: https://github.com/zachasme/h3-pg/blob/main/h3_postgis/CMakeLists.txt

Configures the build process using CMake, linking the 'h3_postgis' target to necessary libraries like 'postgresql_h3_shared' and 'h3'. It also conditionally includes the test subdirectory based on 'BUILD_TESTING' and 'PostgreSQL_PostGIS_FOUND' flags.

```cmake
# link
target_link_libraries(postgresql_h3_postgis PRIVATE postgresql_h3_shared h3)

# test
if(BUILD_TESTING AND PostgreSQL_PostGIS_FOUND)
  add_subdirectory(test)
endif()
```

--------------------------------

### Configure PostgreSQL Regression Test for h3

Source: https://github.com/zachasme/h3-pg/blob/main/h3/test/CMakeLists.txt

Defines a CMake test named 'h3_regress' to run the PostgreSQL regression test suite. It configures the test instance, binary directory, input/output directories, and loads the 'h3' extension. This test ensures the h3 extension functions correctly within the PostgreSQL environment.

```cmake
if(PostgreSQL_REGRESS)
  add_test(
    NAME h3_regress
    COMMAND ${PostgreSQL_REGRESS}
      --temp-instance=${CMAKE_BINARY_DIR}/tmp
      --bindir=${PostgreSQL_BIN_DIR}
      --inputdir=${CMAKE_CURRENT_SOURCE_DIR}
      --outputdir=${CMAKE_CURRENT_BINARY_DIR}
      --load-extension h3
      ${TESTS}
  )
endif()
```

--------------------------------

### Configure PostgreSQL Extension Upgrade Validation

Source: https://github.com/zachasme/h3-pg/blob/main/h3/test/CMakeLists.txt

Sets up a CMake test named 'h3_validate_extupgrade' to validate the extension upgrade process for the h3 extension. It uses the 'pg_validate_extupgrade' tool to check compatibility from version '0.1.0' to the current 'INSTALL_VERSION'. This is crucial for ensuring smooth upgrades between h3-pg releases.

```cmake
if(PostgreSQL_VALIDATE_EXTUPGRADE)
  add_test(
    NAME h3_validate_extupgrade
    COMMAND pg_validate_extupgrade
      --extname h3
      --from 0.1.0
      --to ${INSTALL_VERSION}
  )
endif()
```

--------------------------------

### Configure PostgreSQL H3 Shared Library

Source: https://github.com/zachasme/h3-pg/blob/main/include/CMakeLists.txt

Defines and configures the shared library for PostgreSQL H3 integration. It specifies the source files, links against the PostgreSQL library, sets interface include directories, and enables position-independent code.

```cmake
add_library(postgresql_h3_shared
  OBJECT error.c
)
target_link_libraries(postgresql_h3_shared
  PRIVATE PostgreSQL::PostgreSQL
)
target_include_directories(postgresql_h3_shared
  INTERFACE ./
)
set_target_properties(postgresql_h3_shared PROPERTIES POSITION_INDEPENDENT_CODE True)
```

--------------------------------

### CMake: Add PostgreSQL Regression Test for h3-postgis

Source: https://github.com/zachasme/h3-pg/blob/main/h3_postgis/test/CMakeLists.txt

Configures a CMake test to run PostgreSQL regression tests. It specifies the PostgreSQL regression testing utility, input/output directories, and loads necessary extensions like h3, postgis, postgis_raster, and h3_postgis.

```cmake
set(
  deprecations
  postgis
  rasters
)

if(PostgreSQL_REGRESS)
  add_test(
    NAME "h3_postgis_regress"
    COMMAND ${PostgreSQL_REGRESS}
      --temp-instance=${CMAKE_BINARY_DIR}/tmp
      --bindir=${PostgreSQL_BIN_DIR}
      --inputdir=${CMAKE_CURRENT_SOURCE_DIR}
      --outputdir=${CMAKE_CURRENT_BINARY_DIR}
      --load-extension h3
      --load-extension postgis
      --load-extension postgis_raster
      --load-extension h3_postgis
      ${TESTS}
  )
endif()
```

--------------------------------

### Extension Specific Functions

Source: https://github.com/zachasme/h3-pg/blob/main/docs/api.md

Functions related to the h3-pg extension itself, such as version retrieval and migration.

```APIDOC
h3_get_extension_version() ⇒ text
  *Since v1.0.0*
  Get the currently installed version of the extension.
```

```APIDOC
h3_pg_migrate_pass_by_reference(h3index) ⇒ h3index
  *Since v4.1.0*
  Migrate h3index from pass-by-reference to pass-by-value.
```

--------------------------------

### Miscellaneous H3 Functions

Source: https://github.com/zachasme/h3-pg/blob/main/docs/api.md

Utility functions for H3 grid system properties, distances, and cell information.

```APIDOC
h3_great_circle_distance(a point, b point, [unit text = km]) ⇒ double precision
  *Since v4.0.0*
  The great circle distance in radians between two spherical coordinates.
```

```APIDOC
h3_get_hexagon_area_avg(resolution integer, [unit text = km]) ⇒ double precision
  *Since v4.0.0*
  Average hexagon area in square (kilo)meters at the given resolution.
```

```APIDOC
h3_cell_area(cell h3index, [unit text = km^2]) ⇒ double precision
  *Since v4.0.0*
  Exact area for a specific cell (hexagon or pentagon).
```

```APIDOC
h3_get_hexagon_edge_length_avg(resolution integer, [unit text = km]) ⇒ double precision
  *Since v4.0.0*
  Average hexagon edge length in (kilo)meters at the given resolution.
```

```APIDOC
h3_edge_length(edge h3index, [unit text = km]) ⇒ double precision
  *Since v4.0.0*
  Exact length for a specific unidirectional edge.
```

```APIDOC
h3_get_num_cells(resolution integer) ⇒ bigint
  *Since v4.0.0*
  Number of unique H3 indexes at the given resolution.
```

```APIDOC
h3_get_res_0_cells() ⇒ SETOF h3index
  *Since v4.0.0*
  Returns all 122 resolution 0 indexes.
```

```APIDOC
h3_get_pentagons(resolution integer) ⇒ SETOF h3index
  *Since v4.0.0*
  All the pentagon H3 indexes at the specified resolution.
```

--------------------------------

### PostGIS Integration Notes

Source: https://github.com/zachasme/h3-pg/blob/main/docs/api.md

Guidelines for using PostGIS GEOMETRY types with h3-pg functions, emphasizing SRID 4326.

```APIDOC
The `GEOMETRY` data passed to `h3-pg` PostGIS functions should be in SRID 4326. This is an expectation of the core H3 library. Using other SRIDs, such as 3857, can result in either errors or invalid data depending on the function. For example, the `h3_polygon_to_cells()` function will fail with an error in this scenario while the `h3_latlng_to_cell()` function will return an invalid geometry.
```

--------------------------------

### H3 Grid Traversal Functions

Source: https://github.com/zachasme/h3-pg/blob/main/docs/api.md

Functions for navigating the H3 grid system. These allow finding neighboring cells, calculating distances, and determining paths between H3 indexes.

```APIDOC
h3_grid_disk(origin h3index, [k integer = 1]) ⇒ SETOF h3index
  Produces indices within "k" distance of the origin index.
```

```APIDOC
h3_grid_disk_distances(origin h3index, [k integer = 1], OUT index h3index, OUT distance int) ⇒ SETOF record
  Produces indices within "k" distance of the origin index paired with their distance to the origin.
```

```APIDOC
h3_grid_ring_unsafe(origin h3index, [k integer = 1]) ⇒ SETOF h3index
  Returns the hollow hexagonal ring centered at origin with distance "k".
```

```APIDOC
h3_grid_path_cells(origin h3index, destination h3index) ⇒ SETOF h3index
  Given two H3 indexes, return the line of indexes between them (inclusive).
  This function may fail to find the line between two indexes, for example if they are very far apart.
  It may also fail when finding distances for indexes on opposite sides of a pentagon.
  See also: h3_grid_path_cells_recursive(h3index, h3index)
```

```APIDOC
h3_grid_distance(origin h3index, destination h3index) ⇒ bigint
  Returns the distance in grid cells between the two indices.
```

```APIDOC
h3_cell_to_local_ij(origin h3index, index h3index) ⇒ point
  Produces local IJ coordinates for an H3 index anchored by an origin.
```

```APIDOC
h3_local_ij_to_cell(origin h3index, coord point) ⇒ h3index
  Produces an H3 index from local IJ coordinates anchored by an origin.
```

--------------------------------

### H3 Cellular Hierarchy Functions

Source: https://github.com/zachasme/h3-pg/blob/main/docs/api.md

Functions for navigating the H3 hierarchical grid system, including parent/child relationships, compaction, and uncompaction.

```APIDOC
h3_cell_to_center_child(cell h3index, resolution integer) ⇒ h3index
  *Since v4.0.0*
  Returns the center child (finer) index contained by input index at the given resolution.

h3_compact_cells(cells h3index[]) ⇒ SETOF h3index
  *Since v4.0.0*
  Compacts the given array of H3 indexes as best as possible.

h3_cell_to_child_pos(child h3index, parentRes integer) ⇒ int8
  *Since v4.1.0*
  Returns the position of a child cell within an ordered list of all children of its parent at the specified parent resolution. This is the complement of childPosToCell.

h3_child_pos_to_cell(childPos int8, parent h3index, childRes integer) ⇒ h3index
  *Since v4.1.0*
  Returns the child cell at a given position within an ordered list of all children of the parent at the specified child resolution. This is the complement of cellToChildPos.

h3_uncompact_cells(cells h3index[], resolution integer) ⇒ SETOF h3index
  *Since v4.0.0*
  Uncompacts the given array of H3 indexes at the specified resolution.

h3_uncompact_cells(cells h3index[]) ⇒ SETOF h3index
  *Since v4.0.0*
  Uncompacts the given array of H3 indexes at the resolution one higher than the highest resolution present in the set.

h3_cell_to_parent(cell h3index) ⇒ h3index
  *Since v4.0.0*
  Returns the parent index of the given H3 index.

h3_cell_to_children(cell h3index) ⇒ SETOF h3index
  *Since v4.0.0*
  Returns the set of direct children indexes for the given H3 index.

h3_cell_to_children_slow(index h3index, resolution integer) ⇒ SETOF h3index
  *Since v4.0.0*
  Slower version of H3ToChildren but allocates less memory, returning children at a specific resolution.

h3_cell_to_children_slow(index h3index) ⇒ SETOF h3index
  *Since v4.0.0*
  Slower version of H3ToChildren but allocates less memory, returning children at the next resolution.
```

--------------------------------

### H3 Raster Class Summary API Functions

Source: https://github.com/zachasme/h3-pg/blob/main/docs/api.md

Provides API documentation for functions related to summarizing raster data by H3 cells for discrete values. These functions allow conversion to JSONB, aggregation, and different methods of sampling or clipping raster data to H3 cells.

```APIDOC
h3_raster_class_summary_item_to_jsonb(item h3_raster_class_summary_item) ⇒ jsonb
  Converts a raster summary item (containing count, value, area) into a JSONB object.
  Example: {"count": 10, "value": 2, "area": 16490.3423}
  Since v4.1.1

h3_raster_class_summary_item_agg(setof h3_raster_class_summary_item)
  Aggregates a set of raster summary items. Used internally for grouping.
  Since v4.1.1

h3_raster_class_summary_clip(rast raster, resolution integer, [nband integer = 1]) ⇒ TABLE (h3 h3index, val integer, summary h3_raster_class_summary_item)
  Returns summary items for each H3 cell and value by clipping the raster to H3 cell geometries.
  Processes each clipped part separately.
  Since v4.1.1

h3_raster_class_summary_centroids(rast raster, resolution integer, [nband integer = 1]) ⇒ TABLE (h3 h3index, val integer, summary h3_raster_class_summary_item)
  Returns summary items for each H3 cell and value by finding the H3 cell for each pixel.
  Groups results by H3 index and value.
  Since v4.1.1

h3_raster_class_summary_subpixel(rast raster, resolution integer, [nband integer = 1]) ⇒ TABLE (h3 h3index, val integer, summary h3_raster_class_summary_item)
  Returns summary items for each H3 cell and value, assuming H3 cells are smaller than pixels.
  Finds the corresponding pixel for each H3 cell.
  Since v4.1.1

h3_raster_class_summary(rast raster, resolution integer, [nband integer = 1]) ⇒ TABLE (h3 h3index, val integer, summary h3_raster_class_summary_item)
  Returns summary items for each H3 cell and value. Attempts to select an appropriate method based on pixel density per H3 cell.
  Since v4.1.1
```

--------------------------------

### PostGIS Indexing Functions

Source: https://github.com/zachasme/h3-pg/blob/main/docs/api.md

Functions for indexing geographic locations (lat/lng) into H3 cells and converting H3 cells to PostGIS geometries.

```APIDOC
h3_latlng_to_cell(geometry, resolution integer) ⇒ h3index
  *Since v4.2.3*
  Indexes the location at the specified resolution.
```

```APIDOC
h3_latlng_to_cell(geography, resolution integer) ⇒ h3index
  *Since v4.2.3*
  Indexes the location at the specified resolution.
```

```APIDOC
h3_cell_to_geometry(h3index) ⇒ geometry
  *Since v4.0.0*
  Finds the centroid of the index.
```

```APIDOC
h3_cell_to_geography(h3index) ⇒ geography
  *Since v4.0.0*
  Finds the centroid of the index.
```

```APIDOC
h3_cell_to_boundary_geometry(h3index) ⇒ geometry
  *Since v4.0.0*
  Finds the boundary of the index.
  Splits polygons when crossing 180th meridian.
```

--------------------------------

### H3 Vertex Functions

Source: https://github.com/zachasme/h3-pg/blob/main/docs/api.md

Functions for working with H3 cell vertices, including retrieval and validation.

```APIDOC
h3_cell_to_vertex(cell h3index, vertexNum integer) ⇒ h3index
  *Since v4.0.0*
  Returns a single vertex for a given cell, as an H3 index.
```

```APIDOC
h3_cell_to_vertexes(cell h3index) ⇒ SETOF h3index
  *Since v4.0.0*
  Returns all vertexes for a given cell, as H3 indexes.
```

```APIDOC
h3_vertex_to_latlng(vertex h3index) ⇒ point
  *Since v4.2.3*
  Get the geocoordinates of an H3 vertex.
```

```APIDOC
h3_is_valid_vertex(vertex h3index) ⇒ boolean
  *Since v4.0.0*
  Whether the input is a valid H3 vertex.
```

--------------------------------

### Check for Inlined Function (Non-macOS)

Source: https://github.com/zachasme/h3-pg/blob/main/h3/test/CMakeLists.txt

Defines a CMake test named 'h3_inlined' that runs only on non-macOS systems in the Release configuration. It uses 'objdump' to check if the 'radsToDegs' function is inlined within the 'h3.so' library. This test is marked with a TODO for potential macOS implementation.

```cmake
# @TODO: Figure out how to inline on MacOS
if(NOT APPLE)
  add_test(
    NAME h3_inlined
    COMMAND sh -c "! objdump -D ${PostgreSQL_PKG_LIBRARY_DIR}/h3.so | grep radsToDegs"
    CONFIGURATIONS Release
  )
endif()
```

--------------------------------

### Deprecated H3 Functions

Source: https://github.com/zachasme/h3-pg/blob/main/docs/api.md

List of H3 functions that are deprecated and their recommended alternatives.

```APIDOC
h3_cell_to_boundary(cell h3index, extend_antimeridian boolean) ⇒ polygon
  DEPRECATED: Use `SET h3.extend_antimeridian TO true` instead.
  DEPRECATED: Use `h3_vertex_to_latlng` instead.
  DEPRECATED: Use `h3_cell_to_latlng` instead.
  DEPRECATED: Use `h3_latlng_to_cell` instead.
```

--------------------------------

### H3 Index Inspection Functions

Source: https://github.com/zachasme/h3-pg/blob/main/docs/api.md

Functions to retrieve metadata about H3 indexes, such as resolution, base cell, validity, orientation, and pentagon status. These utilities help in understanding and validating H3 indexes.

```APIDOC
h3_get_resolution(h3index) ⇒ integer
  Returns the resolution of the index.
```

```APIDOC
h3_get_base_cell_number(h3index) ⇒ integer
  Returns the base cell number of the index.
```

```APIDOC
h3_is_valid_cell(h3index) ⇒ boolean
  Returns true if the given H3Index is valid.
```

```APIDOC
h3_is_res_class_iii(h3index) ⇒ boolean
  Returns true if this index has a resolution with Class III orientation.
```

```APIDOC
h3_is_pentagon(h3index) ⇒ boolean
  Returns true if this index represents a pentagonal cell.
```

```APIDOC
h3_get_icosahedron_faces(h3index) ⇒ integer[]
  Find all icosahedron faces intersected by a given H3 index.
```

--------------------------------

### H3 Operators

Source: https://github.com/zachasme/h3-pg/blob/main/docs/api.md

Operators for comparing and intersecting H3 indexes, including distance and spatial relationships.

```APIDOC
Operator: h3index <-> h3index
  *Since v3.7.0*
  Returns the distance in grid cells between the two indices (at the lowest resolution of the two).
```

```APIDOC
Operator: h3index = h3index
  *Since v0.1.0*
  Returns true if two indexes are the same.
```

```APIDOC
Operator: h3index <> h3index
  *Since v0.1.0*
  (No description provided for inequality operator)
```

```APIDOC
Operator: h3index && h3index
  *Since v3.6.1*
  Returns true if the two H3 indexes intersect.
```

```APIDOC
Operator: h3index @> h3index
  *Since v3.6.1*
  Returns true if A contains B.
```

```APIDOC
Operator: h3index <@ h3index
  *Since v3.6.1*
  Returns true if A is contained by B.
```

--------------------------------

### H3 Directed Edge Functions

Source: https://github.com/zachasme/h3-pg/blob/main/docs/api.md

Functions for retrieving boundary coordinates of unidirectional H3 edges.

```APIDOC
h3_directed_edge_to_boundary(edge h3index) ⇒ polygon
  *Since v4.0.0*
  Provides the coordinates defining the unidirectional edge.
```

--------------------------------

### Update Version in CMakeLists.txt

Source: https://github.com/zachasme/h3-pg/blob/main/docs/development.md

Modifies the root `CMakeLists.txt` file to update the project's version number. This involves setting `INSTALL_VERSION` and ensuring it aligns with H3 core's major and minor versions, incrementing the patch number.

```cmake
set(INSTALL_VERSION "${PROJECT_VERSION}")
```

--------------------------------

### H3 Type Casts

Source: https://github.com/zachasme/h3-pg/blob/main/docs/api.md

Functions for converting H3 indexes to and from other data types like bigint and point.

```APIDOC
h3index :: bigint
  Convert H3 index to bigint, which is useful when you need a decimal representation.
```

```APIDOC
bigint :: h3index
  Convert bigint to H3 index.
```

```APIDOC
h3index :: point
  Convert H3 index to point.
```

--------------------------------

### h3_polygon_to_cells_experimental Experimental Polygon to H3

Source: https://github.com/zachasme/h3-pg/blob/main/docs/api.md

An experimental function to convert polygons to H3 cells, offering a containment mode for handling how points within cells are treated. Supports geometry and geography inputs.

```APIDOC
h3_polygon_to_cells_experimental(multi geometry, resolution integer, [containment_mode text = center]) ⇒ SETOF h3index
```

```APIDOC
h3_polygon_to_cells_experimental(multi geography, resolution integer, [containment_mode text = center]) ⇒ SETOF h3index
```