h3o

https://docs.rs/h3o
Admin
h3o is a Rust library that implements the H3 geospatial indexing system using hierarchical hexagonal...
Tokens:117,194
Snippets:727
Trust Score:9.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### FaceSet::iter Example

Source: https://docs.rs/h3o/latest/src/h3o/face.rs.html

Demonstrates how to iterate over the faces contained in the set.

```rust
let index = h3o::CellIndex::try_from(0x089283470803ffff)?;
let faces = index.icosahedron_faces().iter().collect::<Vec<_>>();
assert_eq!(faces, vec![h3o::Face::try_from(7)?]);
# Ok::<(), Box<dyn std::error::Error>>(())
```

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

### FaceSet::len Example

Source: https://docs.rs/h3o/latest/src/h3o/face.rs.html

Demonstrates how to retrieve the number of faces in a set.

```rust
let index = h3o::CellIndex::try_from(0x089283470803ffff)?;
let faces = index.icosahedron_faces();
assert_eq!(faces.len(), 1);
# Ok::<(), h3o::error::InvalidCellIndex>(())
```

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

### FaceSet::contains Example

Source: https://docs.rs/h3o/latest/src/h3o/face.rs.html

Demonstrates how to check if a specific face is present in the set.

```rust
let index = h3o::CellIndex::try_from(0x089283470803ffff)?;
let faces = index.icosahedron_faces();
assert!(faces.contains(h3o::Face::try_from(7)?));
# Ok::<(), Box<dyn std::error::Error>>(())
```

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

### Iterate Over Directions

Source: https://docs.rs/h3o/latest/h3o/enum.Direction.html

Example showing how to collect all valid directions into a vector using the iter method.

```rust
use h3o::Direction;

let directions = Direction::iter().collect::<Vec<_>>();
```

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

### Check slice prefix

Source: https://docs.rs/h3o/latest/h3o/struct.Boundary.html

Determines if a slice starts with a specific sequence.

```rust
let v = [10, 40, 30];
assert!(v.starts_with(&[10]));
assert!(v.starts_with(&[10, 40]));
assert!(v.starts_with(&v));
assert!(!v.starts_with(&[50]));
assert!(!v.starts_with(&[10, 50]));
```

```rust
let v = &[10, 40, 30];
assert!(v.starts_with(&[]));
let v: &[u8] = &[];
assert!(v.starts_with(&[]));
```

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

### Get first element

Source: https://docs.rs/h3o/latest/h3o/struct.Boundary.html

Returns the first element of the slice, or None if it is empty.

```rust
let v = [10, 40, 30];
assert_eq!(Some(&10), v.first());

let w: &[i32] = &[];
assert_eq!(None, w.first());
```

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

### Retrieve Vertex and Owner

Source: https://docs.rs/h3o/latest/src/h3o/index/vertex.rs.html

Examples demonstrating how to extract the vertex and the owner hexagon from a VertexIndex instance.

```rust
let index = h3o::VertexIndex::try_from(0x2222597fffffffff)?;
assert_eq!(index.vertex(), h3o::Vertex::try_from(2)?);
# Ok::<(), Box<dyn std::error::Error>>(())
```

```rust
let index = h3o::VertexIndex::try_from(0x2222597fffffffff)?;
assert_eq!(index.owner(), h3o::CellIndex::try_from(0x822597fffffffff)?);
# Ok::<(), Box<dyn std::error::Error>>(())
```

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

### grid_disk_distances

Source: https://docs.rs/h3o/latest/src/h3o/index/cell.rs.html

Convenience method to get cells and their distances from the current cell.

```APIDOC
## fn grid_disk_distances<T>(self, k: u32) -> T

### Description
Returns a collection of tuples containing the cell index and its distance from the origin cell, up to distance `k`. It attempts the fast algorithm first, falling back to the safe one if needed.

### Parameters
- **k** (u32) - The grid distance.
```

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

### Get the first cell index at a resolution

Source: https://docs.rs/h3o/latest/src/h3o/index/cell.rs.html

Retrieves the first valid cell index for a given H3 resolution.

```rust
use h3o::{CellIndex, Resolution};

let first = CellIndex::first(Resolution::Nine);
```

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

### Get slice length

Source: https://docs.rs/h3o/latest/h3o/struct.Boundary.html

Returns the number of elements in the slice.

```rust
let a = [1, 2, 3];
assert_eq!(a.len(), 3);
```

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

### Get cell vertex

Source: https://docs.rs/h3o/latest/h3o/struct.CellIndex.html

Retrieves a specific vertex of the cell.

```rust
use h3o::{CellIndex, Vertex, VertexIndex};

let index = CellIndex::try_from(0x8a1fb46622dffff)?;
assert_eq!(
    index.vertex(Vertex::try_from(3)?),
    VertexIndex::try_from(0x25a1fb464492ffff).ok()
);
```

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

### Get the last cell index at a resolution

Source: https://docs.rs/h3o/latest/src/h3o/index/cell.rs.html

Retrieves the last valid cell index for a given H3 resolution.

```rust
use h3o::{CellIndex, Resolution};

let last = CellIndex::last(Resolution::Nine);
```

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

### grid_disk_fast

Source: https://docs.rs/h3o/latest/src/h3o/index/cell.rs.html

A fast, fallible implementation for calculating grid disks.

```APIDOC
## fn grid_disk_fast(self, k: u32) -> impl Iterator<Item = Option<Self>>

### Description
Calculates cells within grid distance `k`. This method may return `None` if a pentagon distortion is encountered, indicating that the results should be discarded.

### Parameters
- **k** (u32) - The grid distance.
```

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

### Get FaceSet length

Source: https://docs.rs/h3o/latest/h3o/struct.FaceSet.html

Returns the number of faces in the set.

```rust
let index = h3o::CellIndex::try_from(0x089283470803ffff)?;
let faces = index.icosahedron_faces();
assert_eq!(faces.len(), 1);
```

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

### Get parent cell

Source: https://docs.rs/h3o/latest/h3o/struct.CellIndex.html

Returns the parent of the cell at a specified resolution.

```rust
use h3o::{CellIndex, Resolution};

let index = CellIndex::try_from(0x8a1fb46622dffff)?;
assert_eq!(
    index.parent(Resolution::Five),
    CellIndex::try_from(0x851fb467fffffff).ok()
);
```

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

### TilerBuilder::new

Source: https://docs.rs/h3o/latest/h3o/geom/struct.TilerBuilder.html

Initializes a new tiler builder with the specified resolution.

```APIDOC
## pub const fn new(resolution: Resolution) -> Self

### Description
Initializes a new tiler builder with default settings and the provided resolution.
```

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

### Get Successor Cell Index

Source: https://docs.rs/h3o/latest/src/h3o/index/cell.rs.html

Retrieves the next cell index in the H3 ordering. Returns None if the current cell is the last one at its resolution.

```rust
use h3o::CellIndex;

let start = CellIndex::try_from(0x823147fffffffff)?;
let after = start.succ().expect("next cell index");
# Ok::<(), h3o::error::InvalidCellIndex>(())
```

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

### RingHierarchy Implementation Methods

Source: https://docs.rs/h3o/latest/src/h3o/geom/solvent/ring_hierarchy.rs.html

Methods for initializing the hierarchy, iterating over polygons, and peeling outer rings.

```rust
51impl RingHierarchy {
52    /// Builds a new hierarchy of rings.
53    pub fn new(rings: Vec<LineString<f64>>) -> Self {
54        let is_assigned = vec![false; rings.len()];
55        let is_transmeridian = rings
56            .iter()
57            .map(|ring| {
58                ring.lines()
59                    .any(|line| (line.start.x - line.end.x).abs() > 180.)
60            })
61            .collect::<Vec<_>>();
62
63        // Compute the hierarchy matrix.
64        let mut matrix = vec![false; rings.len() * rings.len()];
65        for (i, r1) in rings.iter().enumerate() {
66            for (j, r2) in rings.iter().enumerate() {
67                // One cannot contains itself.
68                if i == j {
69                    continue;
70                }
71
72                let (r1, r2) = if is_transmeridian[i] {
73                    (
74                        LineString::new(
75                            r1.coords().map(adjust_coordinate).collect(),
76                        ),
77                        adjust_coordinate(&r2.0[0]),
78                    )
79                } else {
80                    (r1.clone(), r2.0[0])
81                };
82                // We are guaranteed not to overlap, so just test the first
83                // point.
84                // Need to convert to Polygon to have the right `contains`
85                // algorithm.
86                if Polygon::new(r1, vec![]).contains(&r2) {
87                    matrix[j * rings.len() + i] = true;
88                }
89            }
90        }
91
92        Self {
93            rings,
94            is_assigned,
95            matrix,
96        }
97    }
98
99    /// Consumes the hierarchy into a stream of Polygon.
100    pub fn into_iter(mut self) -> impl Iterator<Item = Polygon<f64>> {
101        type OuterRingIterator =
102            Peekable<vec::IntoIter<(usize, LineString<f64>)>>;
103
104        // Outers ring at the current nesting level.
105        let mut outers: Option<OuterRingIterator> = None;
106
107        std::iter::from_fn(move || {
108            // If the current layer is exhausted, peel the next one.
109            if outers.as_mut().is_none_or(|rings| rings.peek().is_none()) {
110                outers = self
111                    .peel_outers()
112                    .map(|rings| rings.into_iter().peekable());
113            }
114
115            outers.as_mut().map(|outers| {
116                let (id, outer) = outers.next().expect("peeked above");
117                let inners = self.inners(id);
118
119                // Mark the outer as assigned.
120                self.is_assigned[id] = true;
121
122                Polygon::new(outer, inners)
123            })
124        })
125    }
126
127    /// Peels one layer of outer rings and return them.
128    ///
129    /// An outer ring is a ring that is not contained by any other ring.
130    ///
131    /// Note that in case of nested polygons, you may need to call this function
132    /// several time to extract outer rings at every nesting level.
133    fn peel_outers(&mut self) -> Option<Vec<(usize, LineString<f64>)>> {
134        #[expect(
135            clippy::filter_map_bool_then,
136            reason = "borrow issue if filter+map"
137        )]
138        let outers = (0..self.rings.len())
139            .filter_map(|i| {
140                // Skip assigned rings and non-outer ones.
141                (!self.is_assigned[i] && self.is_outer(i)).then(|| {
142                    // Extract the ring in place to preserve `rings` size and
143                    // ordering.
```

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

### Get direction at resolution

Source: https://docs.rs/h3o/latest/h3o/struct.CellIndex.html

Returns the cell direction at a specific resolution.

```rust
use h3o::{CellIndex, Direction, Resolution};

let index = CellIndex::try_from(0x8a1fb46622dffff)?;
assert_eq!(index.direction_at(Resolution::Five), Some(Direction::K));
```

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

### Calculate grid disk quickly

Source: https://docs.rs/h3o/latest/src/h3o/index/cell.rs.html

Uses the fast algorithm which may return None if a pentagon distortion is encountered.

```rust
let index = h3o::CellIndex::try_from(0x8a1fb46622dffff)?;
let cells = index.grid_disk_fast(2).collect::<Option<Vec<_>>>()
    .unwrap_or_default();
# Ok::<(), h3o::error::InvalidCellIndex>(())
```

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

### Implement TryFrom and Display for LocalIJ

Source: https://docs.rs/h3o/latest/src/h3o/coord/localij.rs.html

Conversions and string formatting implementations for the LocalIJ type.

```rust
impl TryFrom<LocalIJ> for CellIndex {
    type Error = LocalIjError;

    fn try_from(value: LocalIJ) -> Result<Self, Self::Error> {
        let local_ijk = LocalIJK {
            anchor: value.anchor,
            coord: CoordIJK::try_from(value.coord)?,
        };
        Self::try_from(local_ijk)
    }
}

impl fmt::Display for LocalIJ {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{} {}", self.anchor, self.coord)
    }
}
```

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

### PlotterBuilder

Source: https://docs.rs/h3o/latest/src/h3o/geom/plotter.rs.html

The entry point for configuring and creating a Plotter instance.

```APIDOC
## PlotterBuilder

### Description
Used to configure and instantiate a `Plotter` object. The builder allows setting the target H3 resolution and toggling coordinate conversion.

### Methods
- **new(resolution: Resolution)**: Initializes a new builder with the specified resolution.
- **disable_radians_conversion()**: Disables automatic degrees-to-radians conversion.
- **build()**: Consumes the builder and returns a configured `Plotter` instance.
```

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

### PlotterBuilder::new

Source: https://docs.rs/h3o/latest/h3o/geom/struct.PlotterBuilder.html

Initializes a new instance of the PlotterBuilder with a specified resolution.

```APIDOC
### pub const fn new(resolution: Resolution) -> Self

Initializes a new plotter builder with default settings.
```

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

### Get last element

Source: https://docs.rs/h3o/latest/h3o/struct.Boundary.html

Returns the last element of the slice, or None if it is empty.

```rust
let v = [10, 40, 30];
assert_eq!(Some(&30), v.last());

let w: &[i32] = &[];
assert_eq!(None, w.last());
```

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

### VertexGraph Structure and Initialization

Source: https://docs.rs/h3o/latest/src/h3o/geom/solvent/vertex_graph.rs.html

Defines the Node and VertexGraph structures, including the from_heterogeneous method for building the graph from cell iterators.

```rust
use super::RingHierarchy;
use crate::{
    CellIndex, LatLng, Resolution, VertexIndex, error::DissolutionError,
    geom::neighbors,
};
use ahash::{HashMap, HashMapExt, HashSet, HashSetExt};
use either::Either;
use geo::{LineString, MultiPolygon, Polygon};
use std::collections::hash_map::Entry;

/// A single node in a vertex graph.
#[derive(Debug, Eq, PartialEq, Hash)]
pub struct Node {
    from: VertexIndex,
    to: VertexIndex,
}

/// A data structure to store a graph of vertices.
#[derive(Default)]
pub struct VertexGraph {
    nodes: HashMap<VertexIndex, Vec<VertexIndex>>,
    distortions: HashMap<Node, LatLng>,
    is_class3: bool,
}

impl VertexGraph {
    /// Initializes a new `VertexGraph` from a set of heterogeneous cells.
    ///
    /// # Notes
    ///
    /// If `check_duplicate` is set to true, a duplicates detection is
    /// performed, which implies an eager consumption of the iterator upfront,
    /// incurring memory overhead and losing the lazyness of the iterator-based
    /// approach.
    pub fn from_heterogeneous(
        cells: impl IntoIterator<Item = CellIndex>,
        resolution: Resolution,
        check_duplicate: bool,
    ) -> Result<Self, DissolutionError> {
        let cells = if check_duplicate {
            let cells = cells.into_iter().collect::<Vec<_>>();
            if cells.iter().any(|cell| cell.resolution() > resolution) {
                return Err(DissolutionError::UnsupportedResolution);
            }
            check_duplicates(
                cells.iter().flat_map(|cell| cell.children(resolution)),
            )?;
            Either::Left(cells.into_iter())
        } else {
            Either::Right(cells.into_iter())
        };

        let mut graph = Self {
            nodes: HashMap::new(),
            distortions: HashMap::new(),
            is_class3: resolution.is_class3(),
        };

        // Scratchpad to reuse memory allocations.
        let mut scratchpad = Scratchpad::new();
        for cell in cells {
            match cell.resolution().cmp(&resolution) {
                std::cmp::Ordering::Less => {
                    graph.insert_large_cell(cell, resolution, &mut scratchpad);
                }
                std::cmp::Ordering::Equal => {
                    scratchpad.compute_vertexes(cell);
                    for pair in scratchpad.vertexes.windows(2) {
                        graph.insert(&Node {
                            from: pair[0],
                            to: pair[1],
                        });
                    }

                    // Keep track of distortions vertices when necessary.
                    if graph.is_class3 && cell.icosahedron_faces().len() > 1 {
                        graph.index_distortions(cell, &scratchpad.vertexes);
                    }
                }
                std::cmp::Ordering::Greater => {
                    return Err(DissolutionError::UnsupportedResolution);
                }
            }
        }

        Ok(graph)
    }

    /// Adds an edge to the graph.
    pub fn insert(&mut self, node: &Node) {
        // First lookup the reversed edge.
        // If we've seen this edge already, it will be reversed.
        if let Entry::Occupied(mut entry) = self.nodes.entry(node.to) {
            // Edge share by two cells: not part of the outline!
            if let Some(pos) =
                entry.get().iter().position(|&vertex| vertex == node.from)
            {
                entry.get_mut().swap_remove(pos);
                if entry.get().is_empty() {
                    entry.remove_entry();
                }
                self.distortions.remove(&Node {
                    from: node.to,
                    to: node.from,
                });
                return;
            }
        }

        // New edge, insert it.
        let nodes = self
            .nodes
            .entry(node.from)
            // A vertex is shared by at most 3 edges.
            .or_insert_with(|| Vec::with_capacity(3));
        nodes.push(node.to);
    }

    /// Removes a node from the graph.
    pub fn remove(&mut self, node: &Node) {
        if let Entry::Occupied(mut entry) = self.nodes.entry(node.from)
            && let Some(pos) =
                entry.get().iter().position(|&vertex| vertex == node.to)
        {
            entry.get_mut().swap_remove(pos);
            if entry.get().is_empty() {
                entry.remove_entry();
            }
            // XXX: distortions deletion is handled when injected.
        }
    }
```

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

### Get center child

Source: https://docs.rs/h3o/latest/h3o/struct.CellIndex.html

Returns the center child index at a specified resolution.

```rust
use h3o::{CellIndex, Resolution};

let index = CellIndex::try_from(0x8a1fb46622dffff)?;
assert_eq!(
    index.center_child(Resolution::Fifteen),
    CellIndex::try_from(0x8f1fb46622d8000).ok()
);
```

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

### Initialize LatLng from degrees

Source: https://docs.rs/h3o/latest/h3o/struct.LatLng.html

Creates a new LatLng instance from latitude and longitude in degrees. Returns an error if inputs are not finite.

```rust
let ll = h3o::LatLng::new(48.864716, 2.349014)?;

assert!(h3o::LatLng::new(f64::NAN, 10.).is_err());
```

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

### Initialize LatLng from radians

Source: https://docs.rs/h3o/latest/h3o/struct.LatLng.html

Creates a new LatLng instance from latitude and longitude in radians.

```rust
let ll = h3o::LatLng::from_radians(0.852850182, 0.0409980285)?;
```

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

### Get pentagon count

Source: https://docs.rs/h3o/latest/src/h3o/resolution.rs.html

Returns the constant number of pentagons present in the H3 grid.

```rust
assert_eq!(h3o::Resolution::pentagon_count(), 12);
```

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

### Scratchpad Structure and Initialization

Source: https://docs.rs/h3o/latest/src/h3o/geom/solvent/vertex_graph.rs.html

Defines a Scratchpad for vertex and neighbor tracking, including a constructor for pre-allocating memory.

```rust
271    vertexes: Vec<VertexIndex>,
272    blacklist: HashSet<Node>,
273}
274
275impl Scratchpad {
276    fn new() -> Self {
277        Self {
278            // 6 neighbors + self.
279            neighbors: [0; 7],
280            // 6 vertexes + 1 to close the loop.
281            vertexes: Vec::with_capacity(7),
282            // 5 neighbors * 6 vertexes.
283            blacklist: HashSet::with_capacity(30),
284        }
285    }
286
287    fn compute_vertexes(&mut self, cell: CellIndex) {
288        self.vertexes.clear();
289        self.vertexes.extend(cell.vertexes());
290        // Close the loop.
291        // This simplify the iteration over edges by using `windows(2)`.
292        self.vertexes.push(self.vertexes[0]);
293    }
294}
```

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

### Get cell count

Source: https://docs.rs/h3o/latest/src/h3o/resolution.rs.html

Retrieves the total number of unique H3 indexes at a given resolution.

```rust
let nb_cells = h3o::Resolution::Three.cell_count();
```

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

### Initialize GridPathCells

Source: https://docs.rs/h3o/latest/src/h3o/index/iterator.rs.html

The new constructor calculates the distance and step offsets between two H3 cell indices to prepare for iteration.

```rust
pub fn new(start: CellIndex, end: CellIndex) -> Result<Self, LocalIjError> {
    let anchor = start;

    // Get IJK coords for the start and end.
    let src = start.to_local_ijk(start)?;
    let dst = end.to_local_ijk(start)?;
    let distance = src.coord().distance(dst.coord());

    // Convert IJK to cube coordinates suitable for linear interpolation
    let start = CoordCube::from(*src.coord());
    let end = CoordCube::from(*dst.coord());

    let (i_step, j_step, k_step) = if distance == 0 {
        (0., 0., 0.)
    } else {
        let inv_distance = 1.0 / f64::from(distance);
        (
            f64::from(end.i - start.i) * inv_distance,
            f64::from(end.j - start.j) * inv_distance,
            f64::from(end.k - start.k) * inv_distance,
        )
    };

    Ok(Self {
        anchor,
        start,
        distance,
        n: 0,
        i_step,
        j_step,
        k_step,
    })
}
```

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

### Get boundary cell indexes

Source: https://docs.rs/h3o/latest/h3o/struct.CellIndex.html

Retrieves the first or last cell index at a specific resolution.

```rust
use h3o::{CellIndex, Resolution};

let first = CellIndex::first(Resolution::Nine);
```

```rust
use h3o::{CellIndex, Resolution};

let last = CellIndex::last(Resolution::Nine);
```

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

### Get all directed edges

Source: https://docs.rs/h3o/latest/h3o/struct.CellIndex.html

Returns all directed edges originating from the current cell in counter-clockwise order.

```rust
let index = h3o::CellIndex::try_from(0x8a1fb46622dffff)?;
let edges = index.edges().collect::<Vec<_>>();
```

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

### Enable no_std support

Source: https://docs.rs/h3o/latest/src/h3o/lib.rs.html

Configure the crate to operate without the standard library.

```rust
1#![cfg_attr(not(feature = "std"), no_std)]
```

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

### FaceIJK::new

Source: https://docs.rs/h3o/latest/src/h3o/coord/faceijk.rs.html

Creates a new FaceIJK instance with the specified face and IJK coordinates.

```APIDOC
## FaceIJK::new

### Description
Constructs a new FaceIJK object representing a specific face and coordinate set.

### Signature
`pub const fn new(face: Face, coord: CoordIJK) -> Self`
```

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

### H3 Index Resolution

Source: https://docs.rs/h3o-bit/latest/src/h3o_bit/lib.rs.html

Functions to get, clear, and set the resolution bits of an H3 index.

```APIDOC
## H3 Index Resolution

### Description
Provides functions to interact with the resolution component of an H3 index.

### Functions

#### `get_resolution(bits: u64) -> u8`
Returns the H3 index resolution.

#### `clr_resolution(bits: u64) -> u64`
Clears the H3 index resolution bits.

#### `set_resolution(bits: u64, resolution: u8) -> u64`
Sets the H3 index resolution bits.
```

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

### Standard mathematical function wrappers

Source: https://docs.rs/h3o/latest/src/h3o/math/functions-std.rs.html

Inline wrappers for f64 mathematical functions provided by the standard library.

```rust
1#[inline]
2pub const fn abs(x: f64) -> f64 {
3    x.abs()
4}
5
6#[inline]
7pub fn sin(x: f64) -> f64 {
8    x.sin()
9}
10
11#[inline]
12pub fn cos(x: f64) -> f64 {
13    x.cos()
14}
15
16#[inline]
17pub fn tan(x: f64) -> f64 {
18    x.tan()
19}
20
21#[inline]
22pub fn asin(x: f64) -> f64 {
23    x.asin()
24}
25
26#[inline]
27pub fn acos(x: f64) -> f64 {
28    x.acos()
29}
30
31#[inline]
32pub fn atan(x: f64) -> f64 {
33    x.atan()
34}
35
36#[inline]
37pub fn atan2(y: f64, x: f64) -> f64 {
38    y.atan2(x)
39}
40
41#[inline]
42pub fn hypot(x: f64, y: f64) -> f64 {
43    x.hypot(y)
44}
45
46#[inline]
47pub fn sqrt(x: f64) -> f64 {
48    x.sqrt()
49}
50
51#[inline]
52pub const fn round(x: f64) -> f64 {
53    x.round()
54}
55
56#[inline]
57pub const fn mul_add(a: f64, b: f64, c: f64) -> f64 {
58    a.mul_add(b, c)
59}
```

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

### Implement Kahan summation with FloatAdder

Source: https://docs.rs/h3o/latest/src/h3o/math/fp_adder.rs.html

Defines the FloatAdder structure and implements AddAssign for accurate floating-point accumulation.

```rust
//! Implement an accurate floating-point adder.
//!
//! Current implementation is based on the Kahan summation algorithm, but this
//! is subject to change in the future.
//!
//! # References
//! - <https://en.wikipedia.org/wiki/Kahan_summation_algorithm> for the
//!   algorithm description.

use core::ops::AddAssign;

#[derive(Clone, Copy, Default)]
pub struct FloatAdder {
    sum: f64,
    correction: f64,
}

impl From<FloatAdder> for f64 {
    #[inline]
    fn from(value: FloatAdder) -> Self {
        value.sum + value.correction
    }
}

impl AddAssign<f64> for FloatAdder {
    #[inline]
    fn add_assign(&mut self, value: f64) {
        let y = value - self.correction;
        let t = self.sum + y;
        self.correction = (t - self.sum) - y;
        self.sum = t;
    }
}

#[cfg(test)]
#[path = "./fp_adder_tests.rs"]
mod tests;
```

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

### Tiler Builder Implementation

Source: https://docs.rs/h3o/latest/src/h3o/geom/tiler.rs.html

The build method constructs a Tiler instance using the configured resolution, containment mode, and geometry settings.

```rust
    /// Builds the tiler.
    #[must_use]
    pub fn build(self) -> Tiler {
        Tiler {
            resolution: self.resolution,
            containment_mode: self.containment_mode,
            convert_to_rads: self.convert_to_rads,
            transmeridian_heuristic_enabled: self
                .transmeridian_heuristic_enabled,
            geom: MultiPolygon::new(Vec::new()),
        }
    }
}
```

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

### Get element or subslice by index

Source: https://docs.rs/h3o/latest/h3o/struct.Boundary.html

Returns a reference to an element or subslice depending on the type of index provided.

```rust
let v = [10, 40, 30];
assert_eq!(Some(&40), v.get(1));
assert_eq!(Some(&[10, 40][..]), v.get(0..2));
assert_eq!(None, v.get(3));
assert_eq!(None, v.get(0..4));
```

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

### Get average edge length

Source: https://docs.rs/h3o/latest/src/h3o/resolution.rs.html

Retrieves the average hexagon edge length in meters for a specific resolution.

```rust
let avg_edge_len = h3o::Resolution::Three.edge_length_m();
```

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

### Calculate grid disk distances quickly

Source: https://docs.rs/h3o/latest/src/h3o/index/cell.rs.html

Retrieves cells and their distances using the fast algorithm, which may return None on pentagon distortions.

```rust
let index = h3o::CellIndex::try_from(0x8a1fb46622dffff)?;
let cells_and_dists = index.grid_disk_distances_fast(2)
    .collect::<Option<Vec<_>>>()
    .unwrap_or_default();
# Ok::<(), h3o::error::InvalidCellIndex>(())
```

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

### TilerBuilder Configuration

Source: https://docs.rs/h3o/latest/src/h3o/geom/tiler.rs.html

Builder pattern implementation for configuring the Tiler, including settings for resolution, containment modes, and heuristics.

```rust
pub struct TilerBuilder {
    resolution: Resolution,
    containment_mode: ContainmentMode,
    convert_to_rads: bool,
    transmeridian_heuristic_enabled: bool,
}
```

```rust
impl TilerBuilder {
    /// Initializes a new tiler builder with default settings.
    #[must_use]
    pub const fn new(resolution: Resolution) -> Self {
        Self {
            resolution,
            containment_mode: ContainmentMode::ContainsCentroid,
            convert_to_rads: true,
            transmeridian_heuristic_enabled: true,
        }
    }

    /// Disable the degrees-to-radians conversion pre-processing.
    #[must_use]
    pub const fn disable_radians_conversion(mut self) -> Self {
        self.convert_to_rads = false;
        self
    }

    /// Set the containment mode defining if a cell is in a polygon or not.
    #[must_use]
    pub const fn containment_mode(mut self, mode: ContainmentMode) -> Self {
        self.containment_mode = mode;
        self
    }

    /// Disable the transmeridian heuristic.
    ///
    /// It's safe to do if you are sure that none of the input polygon are
    /// spread over the 180th meridian.
    /// It's necessary to disable if you have a non-transmeridian polygon with
    /// an arc greater than 180° (which would trip the heuristic).
    #[must_use]
    pub const fn disable_transmeridian_heuristic(mut self) -> Self {
```

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

### H3 Index Base Cell

Source: https://docs.rs/h3o-bit/latest/src/h3o_bit/lib.rs.html

Functions to get and set the base cell bits of an H3 index.

```APIDOC
## H3 Index Base Cell

### Description
Provides functions to interact with the base cell component of an H3 index.

### Functions

#### `get_base_cell(bits: u64) -> u8`
Returns the H3 index base cell bits.

#### `set_base_cell(bits: u64, cell: u8) -> u64`
Sets the H3 index base cell bits.
```

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

### Strip Prefix from Slice

Source: https://docs.rs/h3o/latest/h3o/struct.Boundary.html

Removes a specified prefix from the start of a slice, returning None if the prefix is not found.

```rust
let v = &[10, 40, 30];
assert_eq!(v.strip_prefix(&[10]), Some(&[40, 30][..]));
assert_eq!(v.strip_prefix(&[10, 40]), Some(&[30][..]));
assert_eq!(v.strip_prefix(&[10, 40, 30]), Some(&[][..]));
assert_eq!(v.strip_prefix(&[50]), None);
assert_eq!(v.strip_prefix(&[10, 50]), None);

let prefix : &str = "he";
assert_eq!(b"hello".strip_prefix(prefix.as_bytes()),
           Some(b"llo".as_ref()));
```

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

### Module structure and implementation

Source: https://docs.rs/h3o/latest/src/h3o/geom/solvent/mod.rs.html

Internal module structure and core implementation of the Solvent and SolventBuilder types.

```rust
mod arc_set;
mod ring_hierarchy;
mod vertex_graph;

use arc_set::ArcSet;
use ring_hierarchy::RingHierarchy;
use vertex_graph::VertexGraph;

/// A solvent that dissolves a set of H3 cell indexes into a `MultiPolygon`
/// representing the outlines of the set.
#[derive(Debug, Clone, Copy)]
pub struct Solvent {
    input_mode: InputMode,
    check_duplicate: bool,
}

impl Solvent {
    /// Creates a [`MultiPolygon`][geo::MultiPolygon] describing the outline(s)
    /// of a set of cells.
    ///
    /// # Errors
    ///
    /// All cell indexes must be unique and have the expected resolution,
    /// otherwise [`DissolutionError`][crate::error::DissolutionError] is returned.
    ///
    /// # Example
    ///
    /// ```
    /// use h3o::{geom::SolventBuilder, CellIndex, Resolution};
    ///
    /// let index = CellIndex::try_from(0x089283470803ffff)?;
    /// let cells = index.children(Resolution::Twelve).collect::<Vec<_>>();
    /// let solvent = SolventBuilder::new().build();
    /// let geom = solvent.dissolve(cells)?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn dissolve(
        &self,
        cells: impl IntoIterator<Item = crate::CellIndex>,
    ) -> Result<geo::MultiPolygon, crate::error::DissolutionError> {
        Ok(match self.input_mode {
            InputMode::Homogeneous => {
                ArcSet::new(cells, self.check_duplicate)?.into()
            }
            InputMode::Heterogeneous(resolution) => {
                VertexGraph::from_heterogeneous(
                    cells,
                    resolution,
                    self.check_duplicate,
                )?
                .into()
            }
        })
    }
}

// -----------------------------------------------------------------------------

/// A builder to configure a solvent.
#[derive(Debug, Clone, Copy)]
pub struct SolventBuilder {
    input_mode: InputMode,
    check_duplicate: bool,
}

impl Default for SolventBuilder {
    fn default() -> Self {
        Self::new()
    }
}

impl SolventBuilder {
    /// Initializes a new plotter builder with default settings.
    #[must_use]
    pub const fn new() -> Self {
        Self {
            input_mode: InputMode::Homogeneous,
            check_duplicate: true,
        }
    }

    /// Disable duplicate detection.
    ///
    /// If the input set contains duplicate cells, the resulting geometry will
    /// be incorrect.
    ///
    /// By default the solvent will ensure that the input set doesn't contains
    /// any duplicate but this may be costly (especially for heterogeneous
    /// input) and implies a memory overhead.
    ///
    /// Thus, in case where unicity is already guaranteed (e.g. coming from a
    /// hashset, already checked beforehand, ...) it is possible to disable this
    /// check.
    #[must_use]
    pub const fn disable_duplicate_detection(mut self) -> Self {
        self.check_duplicate = false;
        self
    }

    /// Enable support for heterogeneous (e.g. compacted) cell set.
    ///
    /// This mode is way faster and use less memory for large & dense set of
    /// cells. It may be slower for small or very sparse sets.
    ///
    /// When enabling this mode you must specify the finest resolution you want
    /// to support. Coarser cells will be converted on-the-fly and finer cells
    /// will trigger an error.
    #[must_use]
    pub const fn enable_heterogeneous_support(
        mut self,
        resolution: crate::Resolution,
    ) -> Self {
        self.input_mode = InputMode::Heterogeneous(resolution);
        self
    }

    /// Builds the plotter.
    #[must_use]
    pub const fn build(self) -> Solvent {
        Solvent {
            input_mode: self.input_mode,
            check_duplicate: self.check_duplicate,
        }
    }
}

#[derive(Debug, Clone, Copy)]
enum InputMode {
    /// An homogeneous set of cells.
    Homogeneous,
    /// An heterogeneous set of cells (e.g. compacted) with a max resolution.
    Heterogeneous(crate::Resolution),
}
```

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

### Initialize and convert Vec2d

Source: https://docs.rs/h3o/latest/src/h3o/coord/vec2d.rs.html

Provides a constructor for Vec2d and a method to encode an n-vector into icosahedral 2D hex coordinates.

```rust
impl Vec2d {
    /// Initializes a new 2D vector with the specified component values.
    pub const fn new(x: f64, y: f64) -> Self {
        Self { x, y }
    }

    /// Encodes n-vector to the corresponding icosahedral 2D hex coordinates
    /// relative to the given face center.
    ///
    ///
    /// # Preconditions
    ///
    /// `value` is expected to be on the unit sphere.
    ///
    /// # Arguments
    ///
    /// * `value` - The n-vector to encode.
    /// * `resolution` -  The desired H3 resolution for the encoding.
    /// * `face` -  The icosahedral face of the coordinate.
    /// * `distance` - The squared euclidean distance from the face center.
    pub fn from_vec3d(
        value: Vec3d,
        resolution: Resolution,
        face: Face,
        distance: f64,
    ) -> Self {
        float_eq::debug_assert_float_eq!(value.norm(), 1., abs <= f64::EPSILON);

        let face = usize::from(face);

        let r = {
            // cos(r) = 1 - 2 * sin^2(r/2) = 1 - 2 * (sqd / 4) = 1 - sqd/2
            let r = acos(mul_add(distance, -0.5, 1.));

            if r < EPSILON {
                return Self::new(0., 0.);
            }

            // Perform gnomonic scaling of `r` (`tan(r)`) and scale for current
            // resolution length `u`.
            (tan(r) * INV_RES0_U_GNOMONIC)
                * SQRT7_POWERS[usize::from(resolution)]
        };

        let theta = {
            // Compute counter-clockwise `theta` from Class II i-axis.
            let mut theta = face::AXES_AZ_RADS_CII[face]
                - face::CENTER_POINT[face].azimuth(&value);

            // Adjust `theta` for Class III.
            if resolution.is_class3() {
                theta -= AP7_ROT_RADS;
            }
            theta
        };

        // Convert to local x, y.
        Self::new(r * cos(theta), r * sin(theta))
    }
```

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

### Get last chunk

Source: https://docs.rs/h3o/latest/h3o/struct.Boundary.html

Returns an array reference to the last N items in the slice, or None if the slice is too short.

```rust
let u = [10, 40, 30];
assert_eq!(Some(&[40, 30]), u.last_chunk::<2>());

let v: &[i32] = &[10];
assert_eq!(None, v.last_chunk::<2>());

let w: &[i32] = &[];
assert_eq!(Some(&[]), w.last_chunk::<0>());
```

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

### Get first chunk

Source: https://docs.rs/h3o/latest/h3o/struct.Boundary.html

Returns an array reference to the first N items in the slice, or None if the slice is too short.

```rust
let u = [10, 40, 30];
assert_eq!(Some(&[10, 40]), u.first_chunk::<2>());

let v: &[i32] = &[10];
assert_eq!(None, v.first_chunk::<2>());

let w: &[i32] = &[];
assert_eq!(Some(&[]), w.first_chunk::<0>());
```

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

### PlotterBuilder::build

Source: https://docs.rs/h3o/latest/h3o/geom/struct.PlotterBuilder.html

Consumes the builder and returns a configured Plotter instance.

```APIDOC
### pub const fn build(self) -> Plotter

Builds the plotter.
```

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

### Get Edge Cells for LineString

Source: https://docs.rs/h3o/latest/src/h3o/geom/tiler.rs.html

Generates an iterator of cell indexes that approximate the path of a LineString at a given resolution.

```rust
fn get_edge_cells(
    ring: &LineString,
    resolution: Resolution,
) -> impl Iterator<Item = CellIndex> + '_ {
    ring.lines().flat_map(move |line @ Line { start, end }| {
        let count = line_hex_estimate(&line, resolution);

        assert!(count <= 1 << f64::MANTISSA_DIGITS);
        #[expect(
            clippy::cast_precision_loss,
            reason = "cannot happen thanks to assert above"
        )]
        (0..count).map(move |i| {
            let i = i as f64;
            let count = count as f64;
            let inv_count = 1. / count;

            let lat = mul_add(
                start.y * (count - i),
                inv_count,
                end.y * i * inv_count,
            );
            let lng = mul_add(
                start.x * (count - i),
                inv_count,
                end.x * i * inv_count,
            );

            LatLng::from_radians(lat, lng)
                .expect("finite line coordinate")
                .to_cell(resolution)
        })
    })
}
```

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

### Plotting H3 cells along lines

Source: https://docs.rs/h3o/latest/h3o/geom/struct.Plotter.html

Demonstrates initializing a Plotter with a specific resolution, adding a batch of lines, and collecting the resulting H3 cell indexes.

```rust
use geo::line_string;
use h3o::{geom::PlotterBuilder, Resolution};

let mut plotter = PlotterBuilder::new(Resolution::Ten).build();
plotter.add_batch(line_string![
    (x: 2.363503198417334,  y: 48.8203086545891),
    (x: 2.3730684893043588, y: 48.85398407690437),
    (x: 2.334964762310932,  y: 48.870861968772914),
].lines())?;

let cells = plotter.plot().collect::<Result<Vec<_>, _>>()?;
```

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

### Initialize Vec3d

Source: https://docs.rs/h3o/latest/src/h3o/coord/vec3d.rs.html

Create a new 3D vector with specified component values.

```rust
impl Vec3d {
    /// Initializes a new 3D vector with the specified component values.
    pub const fn new(x: f64, y: f64, z: f64) -> Self {
        Self { x, y, z }
    }
```

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

### Get maximum face intersection count

Source: https://docs.rs/h3o/latest/h3o/struct.CellIndex.html

Returns the maximum number of icosahedron faces the cell may intersect.

```rust
let index = h3o::CellIndex::try_from(0x8a1fb46622dffff)?;
assert_eq!(index.max_face_count(), 2);
```

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

### LatLng::new

Source: https://docs.rs/h3o/latest/src/h3o/coord/latlng.rs.html

Initializes a new coordinate from degrees. Returns an error if the provided values are not finite.

```APIDOC
## LatLng::new(lat: f64, lng: f64) -> Result<Self, InvalidLatLng>

### Description
Creates a new LatLng instance from latitude and longitude values provided in degrees.

### Parameters
- **lat** (f64) - Latitude in degrees.
- **lng** (f64) - Longitude in degrees.

### Returns
- **Result<Self, InvalidLatLng>** - Returns the new LatLng instance or an error if inputs are non-finite.
```

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

### Get coverage size hint for Tiler in Rust

Source: https://docs.rs/h3o/latest/h3o/geom/struct.Tiler.html

Returns an upper bound to the number of cells returned by into_coverage.

```rust
use geo::{LineString, Polygon};
use h3o::{geom::{ContainmentMode, TilerBuilder}, Resolution};

let polygon = Polygon::new(
    LineString::from(vec![(0., 0.), (1., 1.), (1., 0.), (0., 0.)]),
    vec![],
);
let mut tiler = TilerBuilder::new(Resolution::Six)
    .containment_mode(ContainmentMode::Covers)
    .build();
tiler.add(polygon)?;

let size_hint = tiler.coverage_size_hint();
```

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

### Retrieve Cell and Pentagon Counts

Source: https://docs.rs/h3o/latest/h3o/enum.Resolution.html

Get the total number of unique H3 indexes or the constant number of pentagons.

```rust
let nb_cells = h3o::Resolution::Three.cell_count();
```

```rust
assert_eq!(h3o::Resolution::pentagon_count(), 12);
```

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

### Implement Iterator for GridPathCells

Source: https://docs.rs/h3o/latest/src/h3o/index/iterator.rs.html

The next method performs linear interpolation to find the next cell index in the path, while size_hint provides the remaining count.

```rust
impl Iterator for GridPathCells {
    type Item = Result<CellIndex, LocalIjError>;

    fn next(&mut self) -> Option<Self::Item> {
        (self.n <= self.distance).then(|| {
            let coord = self.start.translate((
                self.i_step * f64::from(self.n),
                self.j_step * f64::from(self.n),
                self.k_step * f64::from(self.n),
            ));
            self.n += 1;

            // Convert cube -> ijk -> h3 index
            let local_ijk = LocalIJK {
                anchor: self.anchor,
                coord: CoordIJK::from(coord),
            };
            CellIndex::try_from(local_ijk)
        })
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        let count = usize::try_from(max(self.distance - self.n, 0))
            .unwrap_or(usize::MAX);
        (count, Some(count))
    }
}
```

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

### LocalIJ::new

Source: https://docs.rs/h3o/latest/h3o/struct.LocalIJ.html

Initializes a new LocalIJ instance from a given anchor cell index and IJ coordinates.

```APIDOC
## pub const fn new(anchor: CellIndex, coord: CoordIJ) -> Self

### Description
Initializes a new `LocalIJ` from its components. This constructor creates a `LocalIJ` structure anchored by an origin.

### Parameters
- **anchor** (CellIndex) - The anchor cell index.
- **coord** (CoordIJ) - The IJ coordinates relative to the anchor.

### Returns
- **Self** - A new `LocalIJ` instance.
```

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

### H3 Index Direction

Source: https://docs.rs/h3o-bit/latest/src/h3o_bit/lib.rs.html

Functions to get, clear, and set the direction bits of an H3 index at a specific resolution.

```APIDOC
## H3 Index Direction

### Description
Provides functions to interact with the direction component of an H3 index at a given resolution.

### Functions

#### `get_direction(bits: u64, resolution: u8) -> u8`
Returns the H3 index direction bits at the given resolution.

#### `clr_direction(bits: u64, resolution: u8) -> u64`
Clears the H3 index direction at the given resolution.

#### `set_direction(bits: u64, resolution: u8, direction: u8) -> u64`
Sets the H3 index direction bits at the given resolution.
```

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

### Creating contiguous windows

Source: https://docs.rs/h3o/latest/h3o/struct.Boundary.html

Use windows to iterate over overlapping sub-slices of a fixed size. Panics if the size is zero.

```rust
let slice = ['l', 'o', 'r', 'e', 'm'];
let mut iter = slice.windows(3);
assert_eq!(iter.next().unwrap(), &['l', 'o', 'r']);
assert_eq!(iter.next().unwrap(), &['o', 'r', 'e']);
assert_eq!(iter.next().unwrap(), &['r', 'e', 'm']);
assert!(iter.next().is_none());
```

```rust
let slice = ['f', 'o', 'o'];
let mut iter = slice.windows(4);
assert!(iter.next().is_none());
```

```rust
use std::cell::Cell;

let mut array = ['R', 'u', 's', 't', ' ', '2', '0', '1', '5'];
let slice = &mut array[..];
let slice_of_cells: &[Cell<char>] = Cell::from_mut(slice).as_slice_of_cells();
for w in slice_of_cells.windows(3) {
    Cell::swap(&w[0], &w[2]);
}
assert_eq!(array, ['s', 't', ' ', '2', '0', '1', '5', 'u', 'R']);
```

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

### grid_disk_safe

Source: https://docs.rs/h3o/latest/src/h3o/index/cell.rs.html

A safe, albeit slower, implementation for calculating grid disks.

```APIDOC
## fn grid_disk_safe(self, k: u32) -> impl Iterator<Item = Self>

### Description
Calculates all cells within grid distance `k` using a safe algorithm that handles pentagon distortions correctly.

### Parameters
- **k** (u32) - The grid distance.
```
Tokens:
Raw