laburnum 1.17.0

// Copyright Two Neutron Stars Incorporated and contributors
// SPDX-License-Identifier: BlueOak-1.0.0

//! Heterogeneous list (HList) primitives.
//!
//! This module provides generic HList building blocks - a type-safe way to store
//! heterogeneous collections where each element can have a different type.
//!
//! # Architecture
//!
//! An HList is a nested structure of `HCons` cells terminated by `HNil`:
//!
//! ```text
//! HCons<A, HCons<B, HCons<C, HNil>>>
//! ```
//!
//! Type-level indices (`Here`, `There<There<Here>>`) allow accessing specific
//! positions in the list at compile time, with no runtime overhead.
//!
//! # Usage
//!
//! Typically used via the [`define_partitions!`](crate::define_partitions) macro
//! which builds HLists of `PartitionStore`s. See [`partition_store`](super::partition_store)
//! for partition-specific HList traits.

use std::marker::PhantomData;

/// The empty HList, used as the terminator for all HList chains.
///
/// `HNil` marks the end of an HList. Every HList ends with `HNil`:
///
/// ```text
/// HCons<A, HCons<B, HNil>>
///                   ^^^^
/// ```
pub struct HNil;

/// A cons cell in an HList, holding a head element and a tail.
///
/// `HCons` is the building block for heterogeneous lists. Each cell holds:
/// - `head`: The current element
/// - `tail`: The rest of the list (another `HCons` or `HNil`)
///
/// # Type Parameters
///
/// - `H`: The type of the head element
/// - `T`: The type of the tail (must be another HList type)
pub struct HCons<H, T> {
  /// The element at this position in the list.
  pub head: H,
  /// The remainder of the list.
  pub tail: T,
}

impl<H, T> HCons<H, T> {
  /// Creates a new cons cell with the given head and tail.
  pub fn new(head: H, tail: T) -> Self {
    Self { head, tail }
  }
}

/// Type-level index indicating the current (head) position in an HList.
///
/// Used for compile-time indexing into HLists. For deeper positions, wrap with [`There`].
///
/// # Example
///
/// ```text
/// Here           -> position 0 (head)
/// There<Here>    -> position 1
/// There<There<Here>> -> position 2
/// ```
pub struct Here;

/// Type-level index indicating a position deeper in the HList.
///
/// `There<Idx>` means "skip the head and look at position `Idx` in the tail".
/// Combined with [`Here`], these types form compile-time natural numbers.
///
/// # Type Parameters
///
/// - `T`: The index within the tail (either `Here` or another `There<...>`)
pub struct There<T>(PhantomData<T>);

// SAFETY: HNil contains no data, so it's trivially Send and Sync.
unsafe impl Send for HNil {}
unsafe impl Sync for HNil {}

// SAFETY: HCons is Send/Sync if both its head and tail are Send/Sync.
unsafe impl<H: Send, T: Send> Send for HCons<H, T> {}
unsafe impl<H: Sync, T: Sync> Sync for HCons<H, T> {}