### Polygon Coverage Example

Source: https://docs.rs/cdshealpix/latest/src/cdshealpix/nested/mod.rs.html

Demonstrates how to use `polygon_coverage` to find cells overlapped by a polygon. Requires importing `MainWind`, `get`, and `Layer` from `cdshealpix`.

```rust
use cdshealpix::compass_point::{MainWind};
use cdshealpix::nested::{get, Layer};

let depth = 3_u8;
let nested3 = get(depth);

let actual_res = nested3.polygon_coverage(&[(0.0, 0.0), (0.0, 0.5), (0.25, 0.25)], false);
let expected_res: [u64; 8] = [304, 305, 306, 307, 308, 310, 313, 316];
assert_eq!(actual_res.flat_iter().deep_size(), expected_res.len());
for (h1, h2) in actual_res.flat_iter().zip(expected_res.iter()) {
    assert_eq!(h1, *h2);
}

```

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

### Vec Capacity Example

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/map/mom/impls/ported_from_mom_builder/tree/type.Tree.html

Shows how to check the capacity of a Vec after initialization and adding elements.

```rust
let mut vec: Vec<i32> = Vec::with_capacity(10);
vec.push(42);
assert!(vec.capacity() >= 10);

```

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

### Vec Reserve Exact Example

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/map/mom/impls/ported_from_mom_builder/tree/type.Tree.html

Shows how to reserve the exact minimum additional capacity for a Vec.

```rust
let mut vec = vec![1];
vec.reserve_exact(10);
assert!(vec.capacity() >= 11);

```

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

### Vec Reserve Example

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/map/mom/impls/ported_from_mom_builder/tree/type.Tree.html

Demonstrates reserving additional capacity for a Vec and verifying the new capacity.

```rust
let mut vec = vec![1];
vec.reserve(10);
assert!(vec.capacity() >= 11);

```

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

### Get Info File Path

Source: https://docs.rs/cdshealpix/latest/src/cdshealpix/nested/sort/mod.rs.html

Constructs the path to the info file within the temporary directory.

```rust
fn create_info_file_path(&self) -> PathBuf {
    let mut path = self.tmp_dir.clone();
    path.push(Self::INFO_FILENAME);
    path
  }
```

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

### FitsCard Implementations

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/map/fits/keywords/trait.FitsCard.html

Examples of types implementing the FitsCard trait, showing their specific KEYWORD constants.

```APIDOC
## Implementors

### `impl FitsCard for CoordSys`

#### `const KEYWORD: &'static [u8; 8] = b"COORDSYS"`

### `impl FitsCard for IndexSchema`

#### `const KEYWORD: &'static [u8; 8] = b"INDXSCHM"`

### `impl FitsCard for Ordering`

#### `const KEYWORD: &'static [u8; 8] = b"ORDERING"`

### `impl FitsCard for PixType`

#### `const KEYWORD: &'static [u8; 8] = b"PIXTYPE "`

### `impl FitsCard for FirstPix`

#### `const KEYWORD: &'static [u8; 8] = b"FIRSTPIX"`

### `impl FitsCard for LastPix`

#### `const KEYWORD: &'static [u8; 8] = b"LASTPIX "`

### `impl FitsCard for Nside`

#### `const KEYWORD: &'static [u8; 8] = b"NSIDE "`

### `impl FitsCard for Order`

#### `const KEYWORD: &'static [u8; 8] = b"ORDER "`

### `impl FitsCard for TForm1`

#### `const KEYWORD: &'static [u8; 8] = b"TFORM1 "`

### `impl FitsCard for TForm2`

#### `const KEYWORD: &'static [u8; 8] = b"TFORM2 "`

### `impl FitsCard for TType1`

#### `const KEYWORD: &'static [u8; 8] = b"TTYPE1 "`
```

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

### Vec with System Allocator Example

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/map/mom/impls/ported_from_mom_builder/tree/type.Tree.html

Demonstrates creating a Vec with a specific allocator (System) and converting it back into parts.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let mut v: Vec<i32, System> = Vec::new_in(System);
v.push(-1);
v.push(0);
v.push(1);

let (ptr, len, cap, alloc) = v.into_parts_with_alloc();

let rebuilt = unsafe {
    // We can now make changes to the components, such as
    // transmuting the raw pointer to a compatible type.
    let ptr = ptr.cast::<u32>();

    Vec::from_parts_in(ptr, len, cap, alloc)
};
assert_eq!(rebuilt, [4294967295, 0, 1]);

```

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

### Get Cumulative Value by Hash

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/sort/cindex/struct.BorrowedCIndex.html

Retrieves the cumulative value associated with a given hash. The starting value is obtained by `get(i)` and the ending value by `get(i+1)`.

```rust
fn get(&self, hash: u64) -> T>
```

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

### Open 'all' File for Reading

Source: https://docs.rs/cdshealpix/latest/src/cdshealpix/nested/sort/mod.rs.html

Opens the 'all' file in the temporary directory for reading.

```rust
fn open_file_all(&self) -> Result<File, IoError> {
    let mut path = self.tmp_dir.clone();
    path.push(Self::ALL_FILENAME);
    File::open(path)
  }
```

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

### Get Ordered Files in Temporary Directory

Source: https://docs.rs/cdshealpix/latest/src/cdshealpix/nested/sort/mod.rs.html

Reads directory entries, filters for files, parses their names to get HEALPix depth and range, and returns a sorted list of file paths and their associated info. The list is sorted by the start of the range.

```rust
read_dir(&self.tmp_dir).map(|it| {
      let mut path_depth_range_vec: Vec<(PathBuf, u8, Range<u32>)> = it
        .filter_map(|res_dir_entry| {
          res_dir_entry.ok().and_then(|dir_entry| {
            let path = dir_entry.path();
            if path.is_file() {
              path
                .file_name()
                .and_then(|os_str| os_str.to_str())
                .and_then(SimpleExtSortParams::parse_tmp_file_name)
                .map(|(depth, range)| (path, depth, range))
            } else {
              None
            }
          })
        })
        .collect();
      // TODO: check that ranges are non-overlapping and depth is always the same?
      path_depth_range_vec.sort_by(|(_, _, rl), (_, _, rr)| rl.start.cmp(&rr.start));
      path_depth_range_vec.into_iter().collect()
    })
```

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

### Show Image with Default Application (Windows)

Source: https://docs.rs/cdshealpix/latest/src/cdshealpix/nested/map/img.rs.html

Opens an image file using the default application on Windows systems. Uses the `cmd /C start` command.

```rust
pub fn show_with_default_app(path: &str) -> Result<(), io::Error> {
  use std::process::Command;
  Command::new("cmd")
    .arg("/C")
    .arg(format!(r"start {}", path))
    .output()?;
  Ok(())
}
```

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

### Get Value Range by Hash at Index Depth

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/sort/cindex/struct.BorrowedCIndexExplicit.html

Returns the starting and ending cumulative values for a given hash at the index depth.

```rust
fn get_with_hash_at_index_depth(&self, hash: u64) -> Range<Self::V>
```

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

### Get Value Range by Range at Index Depth

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/sort/cindex/struct.BorrowedCIndexExplicit.html

Returns the starting and ending cumulative values for a given range of hashes at the index depth.

```rust
fn get_with_range_at_index_depth(&self, range: Range<u64>) -> Range<Self::V>
```

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

### Get Internal Edge Hashes

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/struct.Layer.html

Returns hashes of the internal bounds of a cell at a specified delta depth. The hashes are ordered anti-clockwise starting from the south-east border.

```rust
pub fn internal_edge(hash: u64, delta_depth: u8) -> Box<[u64]>
```

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

### Vec Try Reserve Exact Example

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/map/mom/impls/ported_from_mom_builder/tree/type.Tree.html

Demonstrates using `try_reserve_exact` for precise capacity reservation, with error handling.

```rust
use std::collections::TryReserveError;

fn process_data(data: &[u32]) -> Result<Vec<u32>, TryReserveError> {
    let mut output = Vec::new();

    // Pre-reserve the memory, exiting if we can't
    output.try_reserve_exact(data.len())?;

    // Now we know this can't OOM in the middle of our complex work
    output.extend(data.iter().map(|&val| {
        val * 2 + 5 // very complicated
    }));

    Ok(output)
}

```

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

### Index Convention Example

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/map/mom/impls/ported_from_mom_builder/build_tree/index.html

Illustrates the indexing scheme for a binary tree with n_children=2 and max_norder=2, showing parent-child index relationships.

```text
       __0__           __1__
      /     \         /     \
     0       1       2      3
    / \     / \     / \    / \
   0   1   2  3    4  5    6  7

(An example of a “tree” with `n_children=2`, `max_norder=2`, `n_root=2`)
```

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

### Handle CSV Comments and Header Lines

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/map/skymap/explicit/struct.ExplicitCountMap.html

Provides an example of how to preprocess an iterator of CSV rows to remove starting comment lines and a potential header line before processing.

```rust
    let mut it = it.peekable();
    // Handle starting comments
    while let Some(Ok(line)) = it.next_if(|res| {
      res
        .as_ref() 
        .map(|line| line.starts_with('#'))
        .unwrap_or(false)
    }) { }
    // Handle header line
    if has_header {
      it.next().transpose()?;
    }
```

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

### get Method for HCIndex

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/sort/cindex/struct.OwnedCIndexExplicit.html

Retrieves the cumulative value associated with a HEALPix index. Used to find the start of a cell's data and the end of the previous cell's data.

```rust
fn get(&self, hash: u64) -> Self::V>
```

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

### Calculate best starting depth for various distances

Source: https://docs.rs/cdshealpix/latest/cdshealpix/fn.best_starting_depth.html

Demonstrates the usage of best_starting_depth with different angular distances to find the corresponding optimal HEALPix depth. Assumes the cdshealpix crate and PI constant are available.

```rust
use cdshealpix::{best_starting_depth};
use std::f64::consts::PI;

assert_eq!(0, best_starting_depth(PI / 4f64)); // 45 deg
assert_eq!(5, best_starting_depth(0.0174533)); //  1 deg
assert_eq!(7, best_starting_depth(0.0043632)); // 15 arcmin
assert_eq!(9, best_starting_depth(0.0013));    // 4.469 arcmin
assert_eq!(15, best_starting_depth(1.454E-5)); // 3 arcsec
assert_eq!(20, best_starting_depth(6.5E-7));   // 0.134 arcsec
assert_eq!(22, best_starting_depth(9.537E-8)); // 20 mas
```

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

### Get Starting Row for an Index Element

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/sort/scindex/struct.BorrowedImplicitSHCIndex.html

Returns the index of the first row that is indexed by a specific element `i` of the Sampled Cumulative Index. This is calculated as `i * n` for valid `i`, otherwise it returns `n_rows`.

```rust
fn starting_row(&self, i: usize) -> u64
```

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

### Show Image with Default Application (Linux)

Source: https://docs.rs/cdshealpix/latest/src/cdshealpix/nested/map/img.rs.html

Opens an image file using the default application on Linux systems. Requires the `xdg-open` command to be available.

```rust
pub fn show_with_default_app(path: &str) -> Result<(), io::Error> {
  use std::process::Command;
  Command::new("xdg-open").args([path]).output()?;
  // .map_err(|e| e.into())?;
  Ok(())
}
```

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

### Calculate Path Along Cell Edge

Source: https://docs.rs/cdshealpix/latest/src/cdshealpix/nested/mod.rs.html

Computes a list of positions tracing the entire boundary of a HEALPix cell. Use this to get the full perimeter path, specifying a starting vertex and direction (clockwise or counter-clockwise).

```rust
pub fn path_along_cell_edge(
    &self,
    hash: u64,
    starting_vertex: &Cardinal,
    clockwise_direction: bool,
    n_segments_by_side: u32,
  ) -> Box<[(f64, f64)]> {
    // Prepare space for the result
    let mut path_points: Vec<(f64, f64)> = Vec::with_capacity((n_segments_by_side << 2) as usize);
    // Compute center
    let proj_center = self.center_of_projected_cell(hash);
    // Unrolled loop over successive sides
    // - compute vertex sequence
    let (v1, v2, v3, v4) = if clockwise_direction {
      starting_vertex.clockwise_cycle()
    } else {
      starting_vertex.counter_clockwise_cycle()
    };
    // - make the four sides
    self.path_along_cell_side_internal(
      proj_center,
      &v1,
      &v2,
      false,
      n_segments_by_side,
      &mut path_points,
    );
    self.path_along_cell_side_internal(
      proj_center,
      &v2,
      &v3,
      false,
      n_segments_by_side,
      &mut path_points,
    );
    self.path_along_cell_side_internal(
      proj_center,
      &v3,
      &v4,
      false,
      n_segments_by_side,
      &mut path_points,
    );
    self.path_along_cell_side_internal(
      proj_center,
      &v4,
      &v1,
      false,
      n_segments_by_side,
      &mut path_points,
    );
    path_points.into_boxed_slice()
  }
```

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

### Get Path Along Cell Edge

Source: https://docs.rs/cdshealpix/latest/src/cdshealpix/nested/mod.rs.html

Generates a path along a cell edge, starting from a specified vertex and proceeding clockwise with a given number of segments per side. This is a convenience function calling `Layer::path_along_cell_edge`.

```rust
pub fn path_along_cell_edge(
  depth: u8,
  hash: u64,
  starting_vertex: &Cardinal,
  clockwise_direction: bool,
  n_segments_by_side: u32,
) -> Box<[(f64, f64)]> {
  get(depth).path_along_cell_edge(hash, starting_vertex, clockwise_direction, n_segments_by_side)
}
```

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

### Show Image with Default Application (macOS)

Source: https://docs.rs/cdshealpix/latest/src/cdshealpix/nested/map/img.rs.html

Opens an image file using the default application on macOS. Requires the `open` command to be available.

```rust
pub fn show_with_default_app(path: &str) -> Result<(), io::Error> {
  use std::process::Command;
  Command::new("open").args(&[path]).output()?;
  Ok(())
}
```

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

### Get Row Range for a Range of Index Elements

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/sort/scindex/struct.BorrowedImplicitSHCIndex.html

Returns the starting and ending row indices that are covered by a given range of elements within the Sampled Cumulative Index. This is useful for determining the total row span of a set of index entries.

```rust
fn row_range(&self, _: Range<usize>) -> Range<u64>
```

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

### Create Sort Parameters from Info

Source: https://docs.rs/cdshealpix/latest/src/cdshealpix/nested/sort/mod.rs.html

Initializes sort parameters from an existing directory and sorting information.

```rust
fn from_dir_and_info(tmp_dir: PathBuf, info: &SimpleExtSortInfo) -> Self {
    Self {
      tmp_dir,
      n_elems_per_chunk: info.n_elems_per_chunk,
      n_threads: info.n_threads,
      clean: info.clean,
    }
  }
```

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

### Vec with Capacity and Push Example

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/map/mom/impls/ported_from_mom_builder/tree/type.Tree.html

Demonstrates creating a vector with a specific capacity using `with_capacity_in` and adding elements using `push`. It also shows the behavior with zero-sized types.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let mut vec = Vec::with_capacity_in(10, System);

// The vector contains no items, even though it has capacity for more
assert_eq!(vec.len(), 0);
assert!(vec.capacity() >= 10);

// These are all done without reallocating...
for i in 0..10 {
    vec.push(i);
}
assert_eq!(vec.len(), 10);
assert!(vec.capacity() >= 10);

// ...but this may make the vector reallocate
vec.push(11);
assert_eq!(vec.len(), 11);
assert!(vec.capacity() >= 11);

// A vector of a zero-sized type will always over-allocate, since no
// allocation is necessary
let vec_units = Vec::<(), System>::with_capacity_in(10, System);
assert_eq!(vec_units.capacity(), usize::MAX);

```

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

### Get first hash in South polar cap

Source: https://docs.rs/cdshealpix/latest/cdshealpix/ring/fn.first_hash_in_spc.html

Use this function to find the index of the first cell fully contained within the South polar cap for a given nside. The examples show expected outputs for nside values of 1, 2, and 4.

```rust
use cdshealpix::ring::{first_hash_in_spc};

assert_eq!(first_hash_in_spc(1),  12);
assert_eq!(first_hash_in_spc(2),  44);
assert_eq!(first_hash_in_spc(4), 168);
```

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

### Get Cumulative Value by Hash

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/sort/cindex/struct.BorrowedCIndexExplicit.html

Retrieves the cumulative value associated with a given hash. The range of values for a cell is obtained by calling get(i) and get(i+1).

```rust
fn get(&self, hash: u64) -> Self::V
```

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

### Creating a Vec<T> from Allocated Memory

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/map/mom/impls/ported_from_mom_builder/tree/type.Tree.html

This example demonstrates creating a Vec<T> from memory allocated manually using `std::alloc::alloc`. It highlights the importance of managing memory layout and safety invariants when using raw pointers.

```rust
#![feature(box_vec_non_null)]

use std::alloc::{alloc, Layout};
use std::ptr::NonNull;

fn main() {
    let layout = Layout::array::<u32>(16).expect("overflow cannot happen");

    let vec = unsafe {
        let Some(mem) = NonNull::new(alloc(layout).cast::<u32>()) else {
            return;
        };

        mem.write(1_000_000);

        Vec::from_parts(mem, 1, 16)
    };

    assert_eq!(vec, &[1_000_000]);
    assert_eq!(vec.capacity(), 16);
}
```

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

### take

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/iter/sortedhash2hashcount/struct.SortedHash2HashCountIncludingZeroIt.html

Creates an iterator that yields the first `n` elements.

```APIDOC
## fn take(self, n: usize) -> Take<Self>

### Description
Creates an iterator that yields the first `n` elements, or fewer if the underlying iterator ends sooner.

### Parameters
#### Path Parameters
- **n** (usize) - The number of elements to take.
```

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

### Get Type ID

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/moc/struct.OwnedMOC.html

Gets the `TypeId` of `self`. This is a standard method for trait objects.

```rust
fn type_id(&self) -> TypeId

```

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

### LastPix get Method

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/map/fits/keywords/struct.LastPix.html

Implementation of the get method for the LastPix struct, returning a u64 value.

```rust
pub fn get(&self) -> u64
```

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

### ExplicitSkyMapBTree SkyMap Trait Implementation: Len and Get

Source: https://docs.rs/cdshealpix/latest/src/cdshealpix/nested/map/skymap/explicit.rs.html

Implements the `len` and `get` methods for the SkyMap trait. `len` returns the number of entries, and `get` returns a reference to the value for a given hash, or a zero value if not found.

```rust
  fn len(&self) -> usize {
    self.entries.len()
  }

  fn get(&self, hash: Self::HashType) -> &Self::ValueType {
    match self.entries.get(&hash) {
      Some(v) => v,
      None => &self._zero,
    }
  }
  // ... other methods
```

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

### Pointable::Init

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/bmoc/struct.BMOCFlatIter.html

The type used for initializers.

```APIDOC
## type Init = T

### Description
The type for initializers.
```

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

### Nside get Method

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/map/fits/keywords/struct.Nside.html

Implementation of the get method for the Nside struct, which returns the Nside value as a u32.

```rust
pub fn get(&self) -> u32
```

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

### Function Signature: show_with_default_app

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/map/img/fn.show_with_default_app.html

This is the function signature for `show_with_default_app`. It takes a file path as a string slice and returns a Result, indicating success or an error.

```rust
pub fn show_with_default_app(path: &str) -> Result<(), Error>
```

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

### OwnedCIndexExplicit::get

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/sort/cindex/struct.OwnedCIndexExplicit.html

Retrieves the cumulative value associated with a given HEALPix index. The range of values for a cell is obtained by `get(i)` and `get(i+1)`.

```APIDOC
## fn get(&self, hash: u64) -> Self::V

Returns the cumulative value associated to the given index. The starting cumulative value associated to a HEALPix cell of index `i` is obtained by `get(i)` while the ending cumulative value is obtained by `get(i+1)`. It means that the largest index equals the number of HEALPix cells at the index depth, and the number of stored values equals this number plus one.
```

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

### Vec Try Reserve Example

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/map/mom/impls/ported_from_mom_builder/tree/type.Tree.html

Illustrates using `try_reserve` to safely reserve capacity, handling potential allocation errors.

```rust
use std::collections::TryReserveError;

fn process_data(data: &[u32]) -> Result<Vec<u32>, TryReserveError> {
    let mut output = Vec::new();

    // Pre-reserve the memory, exiting if we can't
    output.try_reserve(data.len())?;

    // Now we know this can't OOM in the middle of our complex work
    output.extend(data.iter().map(|&val| {
        val * 2 + 5 // very complicated
    }));

    Ok(output)
}

```

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

### Get Iterator Length or Size Hint

Source: https://docs.rs/cdshealpix/latest/cdshealpix/compass_point/struct.CardinalSetIterator.html

Use `try_len` to get the exact length of an iterator if available, otherwise returns the result of `size_hint()`.

```rust
fn try_len(&self) -> Result<usize, (usize, Option<usize>)>
```

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

### Pointable::Init

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/bmoc/struct.BMOCFlatIterCell.html

Type alias for the initializer type.

```APIDOC
### impl<T> Pointable for T
#### type Init = T

### Description
The type for initializers.

### Type Alias
`Init`
```

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

### OwnedCIndexExplicitBTree::get

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/sort/cindex/struct.OwnedCIndexExplicitBTree.html

Retrieves the cumulative value associated with a given HEALPix hash. The range of values for a cell is obtained by calling `get(i)` and `get(i+1)`.

```APIDOC
## `OwnedCIndexExplicitBTree::get`

### Description

Retrieves the cumulative value associated with a given HEALPix hash. The range of values for a cell is obtained by calling `get(i)` and `get(i+1)`.

### Signature

```rust
fn get(&self, hash: u64) -> Self::V
```

### Parameters

*   **hash** (`u64`) - The HEALPix hash for which to retrieve the value.

### Returns

The cumulative value (`Self::V`) associated with the given hash.
```

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

### Create or Overwrite 'all' File

Source: https://docs.rs/cdshealpix/latest/src/cdshealpix/nested/sort/mod.rs.html

Opens or creates the 'all' file in the temporary directory, truncating it if it already exists. This is used for writing all sorted data.

```rust
fn create_file_all(&self) -> Result<File, IoError> {
    let mut path = self.tmp_dir.clone();
    path.push(Self::ALL_FILENAME);
    debug!(
      "Create or open to overwrite file:જી"
      path.to_string_lossy()
    );
    OpenOptions::new()
      .append(false)
      .write(true)
      .create(true)
      .truncate(true)
      .open(path)
  }
```

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

### Nested HEALPIX Cell Indices (Example 11)

Source: https://docs.rs/cdshealpix/latest/src/cdshealpix/nested/mod.rs.html

Another example of nested HEALPIX cell indices, potentially used for data partitioning or querying.

```rust
vec![
          720851, 720857, 720859, 720881, 720883, 720889, 720891, 720855, 720854, 415057, 415059,
          415062, 415063, 131074, 131075, 131078, 131079, 131090, 131091, 131089, 502459, 502457,
          502451, 502449, 502427, 502425, 502419, 502418, 502407, 502406, 502403, 502402,
        ]
```

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

### Nested HEALPIX Cell Indices (Example 9)

Source: https://docs.rs/cdshealpix/latest/src/cdshealpix/nested/mod.rs.html

Another example of nested HEALPIX cell indices, potentially used for data partitioning or querying.

```rust
vec![
          196648, 196649, 196652, 196646, 196644, 196622, 196620, 196614, 196612, 305838, 305836,
          305833, 305832, 786412, 786414, 786429, 786428, 786425, 786424, 786413, 480580, 480582,
          480588, 480590, 480612, 480614, 480620, 480621, 480632, 480633, 480636, 480637,
        ]
```

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

### MomVecImpl Constructors

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/map/mom/impls/zvec/struct.MomVecImpl.html

This section details the methods used to construct new MomVecImpl instances.

```APIDOC
## from_hpx_sorted_entries

### Description
Constructs a `MomVecImpl` from an iterator of HEALPix sorted entries.

### Method
`from_hpx_sorted_entries<I, M>(depth: u8, sorted_entries_it: I, merger: M) -> Self`

### Type Parameters
- `I`: An iterator yielding `(Self::ZUniqHType, Self::ValueType)`.
- `M`: A merger function that takes depth, Zuniq hash, and an array of 4 values, returning a `Result` with a single value or an error.

### Parameters
- `depth` (u8): The depth of the HEALPix cells.
- `sorted_entries_it` (I): An iterator over sorted HEALPix entries.
- `merger` (M): The function to merge values for overlapping cells.

### Response
- `Self`: A new `MomVecImpl` instance.
```

```APIDOC
## from_hpx_sorted_entries_fallible

### Description
Constructs a `MomVecImpl` from an iterator of HEALPix sorted entries, with fallible error handling.

### Method
`from_hpx_sorted_entries_fallible<E, I, M>(depth: u8, sorted_entries_it: I, merger: M) -> Result<Self, E>`

### Type Parameters
- `E`: The error type.
- `I`: An iterator yielding `Result<(Self::ZUniqHType, Self::ValueType), E>`.
- `M`: A merger function that takes depth, Zuniq hash, and an array of 4 values, returning a `Result` with a single value or an error.

### Parameters
- `depth` (u8): The depth of the HEALPix cells.
- `sorted_entries_it` (I): An iterator over fallible sorted HEALPix entries.
- `merger` (M): The function to merge values for overlapping cells.

### Response
- `Result<Self, E>`: A result containing a new `MomVecImpl` instance or an error.
```

```APIDOC
## from_skymap

### Description
Constructs a `MomVecImpl` from a `SkyMap`.

### Method
`from_skymap<'s, S, M>(skymap: S, merger: M) -> Self`

### Type Parameters
- `'s`: Lifetime parameter.
- `S`: Type implementing the `SkyMap` trait.
- `M`: A merger function that takes depth, Zuniq hash, and an array of 4 values, returning a `Result` with a single value or an error.

### Parameters
- `skymap` (S): The input `SkyMap`.
- `merger` (M): The function to merge values for overlapping cells.

### Response
- `Self`: A new `MomVecImpl` instance.
```

```APIDOC
## merge

### Description
Merges two input MOMs to produce an output MOM.

### Method
`merge<'s, L, R, S, O, M>(lhs: L, rhs: R, split: S, op: O, merge: M) -> Self`

### Type Parameters
- `'s`: Lifetime parameter.
- `L`: The left-hand side `Mom` type.
- `R`: The right-hand side `Mom` type.
- `S`: A function to split cells.
- `O`: An operation function for combining values.
- `M`: A merger function for overlapping cells.

### Parameters
- `lhs` (L): The left-hand side MOM.
- `rhs` (R): The right-hand side MOM.
- `split` (S): The function to split cells.
- `op` (O): The operation to apply to combined values.
- `merge` (M): The function to merge overlapping cells.

### Response
- `Self`: The merged `MomVecImpl` instance.
```

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

### Vec<T> Creation from Slices and Arrays

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/map/mom/impls/ported_from_mom_builder/tree/type.Tree.html

Demonstrates how to create a Vec<T> by cloning or moving elements from various slice and array types.

```APIDOC
## impl<T> From<&[T]> for Vec<T>

### Description
Creates a `Vec<T>` by cloning elements from a slice.
Available on `non-`no_global_oom_handling`` only.

#### fn from(s: &[T]) -> Vec<T>

### Description
Allocates a `Vec<T>` and fills it by cloning `s`’s items.

### Method
`from()`

### Parameters
* `s` (&[T]) - The slice to clone elements from.

### Examples
```rust
assert_eq!(Vec::from(&[1, 2, 3][..]), vec![1, 2, 3]);
```

## impl<T, const N: usize> From<&[T; N]> for Vec<T>

### Description
Creates a `Vec<T>` by cloning elements from an array reference.
Available on `non-`no_global_oom_handling`` only.

#### fn from(s: &[T; N]) -> Vec<T>

### Description
Allocates a `Vec<T>` and fills it by cloning `s`’s items.

### Method
`from()`

### Parameters
* `s` (&[T; N]) - The array reference to clone elements from.

### Examples
```rust
assert_eq!(Vec::from(&[1, 2, 3]), vec![1, 2, 3]);
```

## impl<T> From<&mut [T]> for Vec<T>

### Description
Creates a `Vec<T>` by cloning elements from a mutable slice.
Available on `non-`no_global_oom_handling`` only.

#### fn from(s: &mut [T]) -> Vec<T>

### Description
Allocates a `Vec<T>` and fills it by cloning `s`’s items.

### Method
`from()`

### Parameters
* `s` (&mut [T]) - The mutable slice to clone elements from.

### Examples
```rust
assert_eq!(Vec::from(&mut [1, 2, 3][..]), vec![1, 2, 3]);
```

## impl<T, const N: usize> From<&mut [T; N]> for Vec<T>

### Description
Creates a `Vec<T>` by cloning elements from a mutable array reference.
Available on `non-`no_global_oom_handling`` only.

#### fn from(s: &mut [T; N]) -> Vec<T>

### Description
Allocates a `Vec<T>` and fills it by cloning `s`’s items.

### Method
`from()`

### Parameters
* `s` (&mut [T; N]) - The mutable array reference to clone elements from.

### Examples
```rust
assert_eq!(Vec::from(&mut [1, 2, 3]), vec![1, 2, 3]);
```

## impl<T, const N: usize> From<[T; N]> for Vec<T>

### Description
Creates a `Vec<T>` by moving elements from an array.
Available on `non-`no_global_oom_handling`` only.

#### fn from(s: [T; N]) -> Vec<T>

### Description
Allocates a `Vec<T>` and moves `s`’s items into it.

### Method
`from()`

### Parameters
* `s` ([T; N]) - The array to move elements from.

### Examples
```rust
assert_eq!(Vec::from([1, 2, 3]), vec![1, 2, 3]);
```
```

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

### Nested HEALPIX Cell Indices (Example 5)

Source: https://docs.rs/cdshealpix/latest/src/cdshealpix/nested/mod.rs.html

Another example of nested HEALPIX cell indices, potentially representing a different region or resolution.

```rust
vec![
          131112, 131113, 131116, 131110, 131108, 131086, 131084, 131078, 131076, 502446, 502444,
          502441, 502440, 720876, 720878, 720893, 720892, 720889, 720888, 720877, 415044, 415046,
          415052, 415054, 415076, 415078, 415084, 415085, 415096, 415097, 415100, 415101,
        ]
```

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

### Nested HEALPIX Cell Indices (Example 3)

Source: https://docs.rs/cdshealpix/latest/src/cdshealpix/nested/mod.rs.html

A third example of nested HEALPIX cell indices, demonstrating a different range or set of values.

```rust
vec![
          589779, 589785, 589787, 589809, 589811, 589817, 589819, 589783, 589782, 283985, 283987,
          283990, 283991, 2, 3, 6, 7, 18, 19, 17, 371387, 371385, 371379, 371377, 371355, 371353,
          371347, 371346, 371335, 371334, 371331, 371330,
        ]
```

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

### FitsCard Implementation for Ordering

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/map/fits/keywords/enum.Ordering.html

Provides methods to handle the 'ORDERING' keyword in FITS files. This includes parsing and writing the keyword value, which must be enclosed in quotes.

```rust
const KEYWORD: &'static [u8; 8] = b"ORDERING";
```

```rust
fn specific_parse_value(keyword_record: &[u8]) -> Result<Self, FitsError>
```

```rust
fn to_fits_value(&self) -> String {
    Must be in quotes `'val'` if value type is string
}
```

```rust
fn keyword_str() -> &'static str
```

```rust
fn keyword_string() -> String
```

```rust
fn parse_value(keyword_record: &[u8]) -> Result<Self, FitsError>
```

```rust
fn write_keyword_record(
    &self,
    keyword_record: &mut [u8],
) -> Result<(), FitsError>
```

```rust
fn predefine_val_err(
    parsed_value: &[u8],
    expected_values: &[&[u8]],
) -> FitsError {
    Generate an error in case the parsed value does not match a pre-define list of possible values To be called in `specific_parse_value`. Essentially, it converts &str in String (because once the error is raised, the str in the read buffer are out-of-scope.
}
```

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

### Nested HEALPIX Cell Indices (Example 2)

Source: https://docs.rs/cdshealpix/latest/src/cdshealpix/nested/mod.rs.html

Provides another example of nested HEALPIX cell indices, showcasing different values that can be represented.

```rust
vec![
          21828, 21830, 21831, 21842, 21843, 21846, 21847, 109230, 109228, 109222, 109220, 109198,
          109196, 109190, 109187, 109186, 393158, 393164, 393166, 393188, 393190, 393196, 393198,
          393175, 393174, 393171, 393170, 393159,
        ]
```

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

### Module Documentation

Source: https://docs.rs/cdshealpix/latest/src/cdshealpix/nested/map/astrometry/mod.rs.html

Documentation for the astrometry module, explaining its purpose and current status.

```rust
1//! This module contains codes duplicated from the not-yet-publish `astrometry` crate.
2//! It will be replaced by the `astrometry` crate when the later will be public.
3//!
4//! We use it for frame transformations (such as Galactic to Equatorial).
5
6pub mod gal;
7pub mod math;

```

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

### Clone Vec with clone_from Example

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/map/mom/impls/ported_from_mom_builder/tree/type.Tree.html

Demonstrates cloning a vector's contents into another vector using `clone_from`. This method is efficient as it avoids reallocation if the destination vector has sufficient capacity.

```rust
let x = vec![5, 6, 7];
let mut y = vec![8, 9, 10];
let yp: *const i32 = y.as_ptr();

y.clone_from(&x);

// The value is the same
assert_eq!(x, y);

// And no reallocation occurred
assert_eq!(yp, y.as_ptr());

```

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

### OwnedCIndex::get

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/sort/cindex/struct.OwnedCIndex.html

Retrieves the cumulative value associated with a given HEALPix index hash. The range of cumulative values for a cell is determined by `get(i)` and `get(i+1)`.

```APIDOC
## fn get(&self, hash: u64) -> Self::V

### Description
Returns the cumulative value associated with the given index `hash`. The starting cumulative value for a HEALPix cell of index `i` is obtained by `get(i)`, and the ending cumulative value is obtained by `get(i+1)`. The largest index corresponds to the number of HEALPix cells at the index depth, and the number of stored values is this number plus one.

### Parameters
*   **hash** (u64) - The HEALPix index hash.

### Returns
*   Self::V - The cumulative value associated with the hash.
```

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

### Nested HEALPIX Cell Indices (Example 12)

Source: https://docs.rs/cdshealpix/latest/src/cdshealpix/nested/mod.rs.html

A final example of nested HEALPIX cell indices, potentially for a different HEALPIX resolution or data set.

```rust
vec![
          720898, 720899, 720902, 720900, 524296, 524297, 524300, 524301, 524312, 524313, 524316,
          524310, 524308, 655394, 655395, 655393, 655371, 655369, 655363, 655361, 589864, 589865,
        ]
```

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

### SkyMapEnum Implementations

Source: https://docs.rs/cdshealpix/latest/cdshealpix/nested/map/skymap/enum.SkyMapEnum.html

Provides methods for creating, converting, and serializing SkyMapEnum instances, including reading from FITS files, converting between representations, and generating PNG visualizations.

```APIDOC
## Implementations for SkyMapEnum

### `from_fits_file<P: AsRef<Path>>(path: P) -> Result<Self, FitsError>`
Creates a `SkyMapEnum` instance from a FITS file.

### `from_fits<R: Read + Seek>(reader: BufReader<R>) -> Result<Self, FitsError>`
Creates a `SkyMapEnum` instance from a FITS reader.

### `is_implicit_the_best_representation(&self, null_value_provided: NullValueProvider, impl_over_expl_limit_ratio: f64) -> bool`
Determines if the implicit representation is the best for serialization based on byte size and a given ratio limit.

*   **Params**:
    *   `impl_over_expl_limit_ratio` (f64): Limit on the ratio of implicit byte size over explicit byte size. If exceeded, the explicit representation is chosen.

### `to_implicit(self, null_value_provided: NullValueProvider) -> Self`
Converts the `SkyMapEnum` instance to its implicit representation.

### `to_explicit(self, null_value_provided: NullValueProvider) -> Self`
Converts the `SkyMapEnum` instance to its explicit representation.

### `to_count_map(self) -> Result<CountMap, String>`
Converts the `SkyMapEnum` instance to a `CountMap`.

### `to_dens_map(self) -> Result<ImplicitDensityMap, String>`
Converts the `SkyMapEnum` instance to an `ImplicitDensityMap`.

### `par_add(self, rhs: Self, null_value_provider: NullValueProvider) -> Result<Self, FitsError>`
Performs a parallel addition of two `SkyMapEnum` instances.

### `degraded_sum(self, depth: u8) -> Self`
Calculates a degraded sum of the `SkyMapEnum` instance up to a specified depth.

### `depth(&self) -> u8`
Returns the depth of the `SkyMapEnum` instance.

### `to_fits<W: Write>(&self, writer: W) -> Result<(), FitsError>`
Serializes the `SkyMapEnum` instance to FITS format and writes it to a writer.

### `to_fits_file<P: AsRef<Path>>(&self, path: P) -> Result<(), FitsError>`
Serializes the `SkyMapEnum` instance to FITS format and writes it to a file.

### `to_skymap_png_file<P: CanonicalProjection, W: AsRef<Path>>(&self, img_size: (u16, u16), proj: Option<P>, proj_center: Option<(f64, f64)>, proj_bounds: Option<(RangeInclusive<f64>, RangeInclusive<f64>)>, pos_convert: Option<PosConversion>, color_map: Option<Gradient>, color_map_func_type: Option<ColorMapFunctionType>, path: W, view: bool) -> Result<(), Box<dyn Error>>`
Generates and saves a PNG visualization of the sky map to a file.

### `to_skymap_png<P: CanonicalProjection, W: Write>(&self, img_size: (u16, u16), proj: Option<P>, proj_center: Option<(f64, f64)>, proj_bounds: Option<(RangeInclusive<f64>, RangeInclusive<f64>)>, pos_convert: Option<PosConversion>, color_map: Option<Gradient>, color_map_func_type: Option<ColorMapFunctionType>, writer: W) -> Result<(), Box<dyn Error>>`
Generates a PNG visualization of the sky map and writes it to a writer.
```

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

### Get Nested HEALPix Layer by Depth

Source: https://docs.rs/cdshealpix/latest/src/cdshealpix/nested/mod.rs.html

Retrieves a reference to the `Layer` struct for a given HEALPix depth. This is typically used to get the appropriate grid configuration for calculations.

```rust
use cdshealpix::nested::get;

let depth = 12_u8;
let nested12 = get(depth);
assert!(nested12.depth() == depth);
```

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

### Nested HEALPIX Cell Indices (SPC Example 3)

Source: https://docs.rs/cdshealpix/latest/src/cdshealpix/nested/mod.rs.html

A third SPC example showing nested HEALPIX cell indices, possibly for a specific region or data type.

```rust
vec![
          283972, 283974, 283975, 283986, 283987, 283990, 283991, 2, 3, 6, 4, 371374, 371372,
          371366, 371364, 371342, 371340, 371334, 371331, 371330, 589766, 589772, 589774, 589796,
          589798, 589804, 589806, 589783, 589782, 589779, 589778, 589767,
        ]
```