grid1d 0.5.0

#![deny(rustdoc::broken_intra_doc_links)]

//! Core traits defining the behaviour and capabilities of all interval types.
//!
//! This module contains the fundamental traits that all interval implementations
//! must satisfy. Concrete implementations live in [`bounded`](crate::intervals::bounded),
//! [`unbounded`](crate::intervals::unbounded), and the
//! [`Interval`] enum in [`crate::intervals`].
//!
//! ## Trait Overview
//!
//! | Trait | Purpose | Key Methods |
//! |-------|---------|------------|
//! | [`IntervalTrait`] | Universal interface for all interval types | `into_interval()`, `length()`, `midpoint()` |
//! | [`IntervalBoundsRuntime`] | Runtime access to lower and upper bounds | `lower_bound_runtime()`, `upper_bound_runtime()` |
//! | [`IntervalHull`] | Smallest interval enclosing two intervals | `hull(&other)` |
//! | [`Contains`] | Point and interval containment testing | `contains_point(&x)`, `contains_interval(&i)` |
//! | [`GetLowerBoundValue`] | Access to the finite lower bound value | `lower_bound_value()` |
//! | [`GetUpperBoundValue`] | Access to the finite upper bound value | `upper_bound_value()` |
//!
//! ## Example
//!
//! ```rust
//! use grid1d::intervals::*;
//!
//! let a = IntervalClosed::new(0.0_f64, 2.0);
//! let b = IntervalClosed::new(1.0_f64, 3.0);
//!
//! assert!(a.contains_point(&1.5));
//! assert_eq!(a.lower_bound_value(), &0.0);
//! assert_eq!(b.upper_bound_value(), &3.0);
//! ```

use crate::{
    bounds::{LowerBoundRuntime, UpperBoundRuntime},
    intervals::{Interval, operations::IntervalOperations},
};
use num_valid::{RealScalar, scalars::NonNegativeRealScalar};
use serde::{Deserialize, Serialize};
use std::fmt::Debug;

//------------------------------------------------------------------------------------------------
/// Universal interface for all interval types providing common operations.
///
/// This trait provides a unified API for working with intervals regardless of their
/// specific type (closed, open, bounded, unbounded, etc.) and scalar type. It's the
/// foundation for generic interval programming in this library.
///
/// ## Core Operations
///
/// All intervals support three fundamental operations:
///
/// 1. **Point Containment**: [`contains_point`](Contains::contains_point)
///    - Tests if a single value lies within the interval
///    - Respects boundary conditions (open vs closed)
///    - O(1) operation for all interval types
///
/// 2. **Interval Containment**: [`contains_interval`](Contains::contains_interval)
///    - Tests if one interval is completely contained within another
///    - Handles complex boundary interactions correctly
///    - Supports cross-type containment testing
///
/// 3. **Intersection**: [`intersection`](IntervalOperations::intersection)
///    - Computes the overlap between two intervals
///    - Returns `None` for disjoint intervals
///    - Produces the most specific interval type possible
///
/// ## Mathematical Properties
///
/// The trait implementations guarantee these mathematical properties:
///
/// - **Reflexivity**: Every interval contains itself
/// - **Transitivity**: If A ⊆ B and B ⊆ C, then A ⊆ C
/// - **Commutativity**: A ∩ B = B ∩ A
/// - **Associativity**: (A ∩ B) ∩ C = A ∩ (B ∩ C)
/// - **Monotonicity**: If A ⊆ B, then A ∩ C ⊆ B ∩ C
///
/// ## Performance Characteristics by Scalar Type
///
/// | Operation | [`f64`] | [`RealNative64StrictFiniteInDebug`](num_valid::RealNative64StrictFiniteInDebug) | [`RealNative64StrictFinite`](num_valid::RealNative64StrictFinite) |
/// |-----------|---------|-----------------------------------|----------------------------|
/// | **Point queries** | O(1) raw | **O(1) identical** | O(1) + validation |
/// | **Containment** | O(1) comparisons | **O(1) identical** | O(1) + validation |
/// | **Intersections** | O(1) arithmetic | **O(1) identical** | O(1) + validation |
/// | **Memory usage** | 8-16 bytes | **8-16 bytes** | 8-16 bytes + metadata |
///
/// ## Generic Programming Examples
///
/// ### Interval Analysis Function
/// ```rust
/// use grid1d::intervals::*;
/// use num_valid::RealScalar;
///
/// fn analyze_interval<I, T>(interval: &I) -> String
/// where
///     I: IntervalTrait<RealType = T>,
///     T: RealScalar + std::fmt::Display,
/// {
///     if interval.contains_point(&T::zero()) {
///         "Contains zero".to_string()
///     } else {
///         "Does not contain zero".to_string()
///     }
/// }
///
/// // Works with any interval type
/// let closed = IntervalClosed::new(-1.0, 1.0);
/// let open = IntervalOpen::new(0.0, 2.0);
/// let unbounded = IntervalLowerClosedUpperUnbounded::new(0.0);
///
/// assert_eq!(analyze_interval(&closed), "Contains zero");
/// assert_eq!(analyze_interval(&open), "Does not contain zero");
/// assert_eq!(analyze_interval(&unbounded), "Contains zero");
/// ```
///
/// ### Generic Intersection Function
/// ```rust
/// use grid1d::intervals::*;
///
/// fn safe_intersection<I1, I2>(a: &I1, b: &I2) -> Option<Interval<f64>>
/// where
///     I1: IntervalTrait<RealType = f64>,
///     I2: IntervalTrait<RealType = f64>,
/// {
///     a.intersection(b)
/// }
///
/// let closed = IntervalClosed::new(0.0, 2.0);
/// let open = IntervalOpen::new(1.0, 3.0);
///
/// if let Some(result) = safe_intersection(&closed, &open) {
///     println!("Intersection found: {:?}", result);
/// }
/// ```
///
/// ## Conversion to General Interval Type
///
/// All concrete types implementing `IntervalTrait` can be converted to the general
/// [`Interval`] enum via the [`Into`]/[`From`] traits:
///
/// ```rust
/// use grid1d::intervals::*;
///
/// // All concrete interval types convert to Interval<T>
/// let closed = IntervalClosed::new(0.0, 1.0);
/// let general: Interval<f64> = closed.into();
///
/// let open = IntervalOpen::new(0.0, 1.0);
/// let general2 = Interval::from(open);
///
/// let half_open = IntervalLowerClosedUpperOpen::new(0.0, 1.0);
/// let general3: Interval<f64> = half_open.into();
/// ```
///
/// This conversion is available for all interval types in the library:
/// - All bounded intervals: [`IntervalClosed`](crate::intervals::IntervalClosed), [`IntervalOpen`](crate::intervals::IntervalOpen), [`IntervalLowerClosedUpperOpen`](crate::intervals::IntervalLowerClosedUpperOpen), [`IntervalLowerOpenUpperClosed`](crate::intervals::IntervalLowerOpenUpperClosed)
/// - All unbounded intervals: [`IntervalLowerClosedUpperUnbounded`](crate::intervals::IntervalLowerClosedUpperUnbounded), [`IntervalLowerOpenUpperUnbounded`](crate::intervals::IntervalLowerOpenUpperUnbounded),
///   [`IntervalLowerUnboundedUpperClosed`](crate::intervals::IntervalLowerUnboundedUpperClosed), [`IntervalLowerUnboundedUpperOpen`](crate::intervals::IntervalLowerUnboundedUpperOpen), [`IntervalLowerUnboundedUpperUnbounded`](crate::intervals::IntervalLowerUnboundedUpperUnbounded)
/// - Singleton intervals: [`IntervalSingleton`](crate::intervals::IntervalSingleton)
/// - Enum variants: [`IntervalFinitePositiveLength`](crate::intervals::IntervalFinitePositiveLength), [`IntervalFiniteLength`](crate::intervals::IntervalFiniteLength), [`IntervalInfiniteLength`](crate::intervals::IntervalInfiniteLength)
pub trait IntervalTrait: Serialize + for<'a> Deserialize<'a> + IntervalOperations {
    /// Convert this interval into the general [`Interval`] enum by consuming it.
    ///
    /// This method provides an explicit, ergonomic way to convert any interval type
    /// to the most general `Interval<RealType>` enum, which can represent all possible
    /// interval types in a unified way. The conversion consumes `self` and is zero-cost.
    ///
    /// # Naming Convention
    ///
    /// This method follows Rust naming conventions:
    /// - `into_*`: Consumes `self`, zero-cost conversion (this method)
    /// - `to_*`: May clone or allocate, potentially expensive
    /// - `as_*`: Borrows `self`, returns a reference
    ///
    /// # Examples
    ///
    /// ```rust
    /// use grid1d::intervals::*;
    ///
    /// let closed = IntervalClosed::new(0.0, 1.0);
    /// let general = closed.into_interval();
    /// assert!(matches!(general, Interval::FiniteLength(_)));
    ///
    /// let unbounded = IntervalLowerClosedUpperUnbounded::new(0.0);
    /// let general2 = unbounded.into_interval();
    /// assert!(matches!(general2, Interval::InfiniteLength(_)));
    /// ```
    ///
    /// # Type Flexibility
    ///
    /// This method is particularly useful when working with heterogeneous collections
    /// of intervals or when you need to return different interval types from a function:
    ///
    /// ```rust
    /// use grid1d::intervals::*;
    ///
    /// fn make_interval(bounded: bool) -> Interval<f64> {
    ///     if bounded {
    ///         IntervalClosed::new(0.0, 1.0).into_interval()
    ///     } else {
    ///         IntervalLowerClosedUpperUnbounded::new(0.0).into_interval()
    ///     }
    /// }
    /// ```
    ///
    /// # Working with Generic IntervalBounded
    ///
    /// The conversion also works with the generic `IntervalBounded<T, L, U>` type:
    ///
    /// ```rust
    /// use grid1d::{
    ///     bounds::{Closed, Open},
    ///     intervals::{*, bounded::*},
    /// };
    ///
    /// // Generic IntervalBounded can be converted to Interval
    /// let bounded: IntervalBounded<f64, Closed, Open> = IntervalBounded::new(0.0, 1.0);
    /// let general: Interval<f64> = bounded.into_interval();
    ///
    /// // This works because IntervalClosed, IntervalOpen, etc. are just type aliases
    /// // for IntervalBounded with specific bound type parameters
    /// ```
    #[inline(always)]
    fn into_interval(self) -> Interval<Self::RealType>
    where
        Self: Sized + Into<Interval<Self::RealType>>,
    {
        self.into()
    }
}
//------------------------------------------------------------------------------------------------

//------------------------------------------------------------------------------------------------
/// Fundamental trait for runtime access to interval boundary information with dynamic bound type handling.
///
/// [`IntervalBoundsRuntime`] provides a unified interface for accessing interval boundaries where
/// the open/closed nature of bounds is determined at runtime rather than compile time. This trait
/// serves as the foundation for all interval types in the grid1d library, enabling dynamic boundary
/// introspection, cross-type operations, and flexible interval manipulation.
///
/// ## Design Philosophy
///
/// ### Runtime vs Compile-Time Boundary Access
///
/// Unlike compile-time bound access where boundary types are encoded in the type system,
/// [`IntervalBoundsRuntime`] provides dynamic access to boundary information:
///
/// ```rust
/// use grid1d::{bounds::*, intervals::*};
/// use try_create::New;
///
/// // Different interval types with different boundary semantics
/// let closed = IntervalClosed::new(0.0, 1.0);           // [0, 1]
/// let open = IntervalOpen::new(0.0, 1.0);               // (0, 1)
/// let half_open = IntervalLowerClosedUpperOpen::new(0.0, 1.0); // [0, 1)
/// let unbounded = IntervalLowerClosedUpperUnbounded::new(0.0); // [0, ∞)
///
/// // All can be accessed uniformly through the trait
/// fn inspect_bounds<I: IntervalBoundsRuntime>(
///     interval: &I
/// ) -> (Option<LowerBoundRuntime<I::RealType>>, Option<UpperBoundRuntime<I::RealType>>) {
///     (interval.lower_bound_runtime(), interval.upper_bound_runtime())
/// }
///
/// let (lower, upper) = inspect_bounds(&closed);
/// // lower: Some(LowerBoundRuntime::Closed(...))
/// // upper: Some(UpperBoundRuntime::Closed(...))
///
/// let (lower, upper) = inspect_bounds(&unbounded);
/// // lower: Some(LowerBoundRuntime::Closed(...))
/// // upper: None (unbounded above)
/// ```
///
/// ### Unified Boundary Operations
///
/// The trait enables unified operations across different interval types:
///
/// | Operation | Purpose | Returns |
/// |-----------|---------|---------|
/// | [`lower_bound_runtime`](crate::intervals::IntervalBoundsRuntime::lower_bound_runtime) | Access lower boundary with type info | `Option<LowerBoundRuntime<T>>` |
/// | [`upper_bound_runtime`](crate::intervals::IntervalBoundsRuntime::upper_bound_runtime) | Access upper boundary with type info | `Option<UpperBoundRuntime<T>>` |
/// | [`max_lower_bound`](crate::intervals::IntervalBoundsRuntime::max_lower_bound) | Find most restrictive lower bound | `Option<LowerBoundRuntime<T>>` |
/// | [`min_upper_bound`](crate::intervals::IntervalBoundsRuntime::min_upper_bound) | Find most restrictive upper bound | `Option<UpperBoundRuntime<T>>` |
///
/// ## Associated Types
///
/// ### `RealType: RealScalar`
/// The scalar type used for boundary values and computations. Must implement [`num_valid::RealScalar`]
/// to ensure mathematical correctness and provide validation capabilities.
///
/// ## Core Operations
///
/// ### Boundary Access Methods
///
/// #### [`lower_bound_runtime`](crate::intervals::IntervalBoundsRuntime::lower_bound_runtime)
/// Returns the lower boundary information with runtime type encoding:
///
/// ```rust
/// use grid1d::{bounds::*, intervals::*};
/// use try_create::New;
///
/// let closed_interval = IntervalClosed::new(1.0, 5.0);
/// let unbounded_interval = IntervalLowerUnboundedUpperClosed::new(5.0);
///
/// // Bounded interval returns boundary info
/// if let Some(lower) = closed_interval.lower_bound_runtime() {
///     match lower {
///         LowerBoundRuntime::Closed(bound) => {
///             println!("Lower bound [{}:", bound.as_ref()); // "[1.0:"
///         }
///         LowerBoundRuntime::Open(bound) => {
///             println!("Lower bound ({}:", bound.as_ref());
///         }
///     }
/// }
///
/// // Unbounded interval returns None
/// assert_eq!(unbounded_interval.lower_bound_runtime(), None);
/// ```
///
/// **Returns:**
/// - `Some(LowerBoundRuntime::Closed(_))` for intervals with closed lower bounds
/// - `Some(LowerBoundRuntime::Open(_))` for intervals with open lower bounds  
/// - `None` for intervals unbounded below (extending to -∞)
///
/// #### [`upper_bound_runtime`](crate::intervals::IntervalBoundsRuntime::upper_bound_runtime)
/// Returns the upper boundary information with runtime type encoding:
///
/// ```rust
/// use grid1d::{bounds::*, intervals::*};
/// use try_create::New;
///
/// let closed_interval = IntervalClosed::new(1.0, 5.0);
/// let unbounded_interval = IntervalLowerClosedUpperUnbounded::new(1.0);
///
/// // Bounded interval returns boundary info
/// if let Some(upper) = closed_interval.upper_bound_runtime() {
///     match upper {
///         UpperBoundRuntime::Closed(bound) => {
///             println!(":{}]", bound.as_ref()); // ":5.0]"
///         }
///         UpperBoundRuntime::Open(bound) => {
///             println!(":{})", bound.as_ref());
///         }
///     }
/// }
///
/// // Unbounded interval returns None
/// assert_eq!(unbounded_interval.upper_bound_runtime(), None);
/// ```
///
/// **Returns:**
/// - `Some(UpperBoundRuntime::Closed(_))` for intervals with closed upper bounds
/// - `Some(UpperBoundRuntime::Open(_))` for intervals with open upper bounds
/// - `None` for intervals unbounded above (extending to +∞)
///
/// ### Boundary Comparison Operations
///
/// #### [`max_lower_bound`](crate::intervals::IntervalBoundsRuntime::max_lower_bound)
/// Finds the most restrictive (maximum) lower bound between two intervals:
///
/// ```rust
/// use grid1d::{bounds::*, intervals::*};
/// use try_create::New;
///
/// let interval_a = IntervalClosed::new(0.0, 10.0);      // [0, 10]
/// let interval_b = IntervalLowerClosedUpperOpen::new(2.0, 8.0); // [2, 8)
///
/// // The most restrictive lower bound is [2
/// let max_lower = interval_a.max_lower_bound(&interval_b);
/// if let Some(LowerBoundRuntime::Closed(bound)) = max_lower {
///     assert_eq!(*bound.as_ref(), 2.0);
/// }
///
/// // With unbounded intervals
/// let unbounded = IntervalLowerUnboundedUpperClosed::new(5.0); // (-∞, 5]
/// let max_with_unbounded = interval_a.max_lower_bound(&unbounded);
/// // Returns [0 since unbounded has no lower bound
/// if let Some(LowerBoundRuntime::Closed(bound)) = max_with_unbounded {
///     assert_eq!(*bound.as_ref(), 0.0);
/// }
/// ```
///
/// **Behavior:**
/// - Returns the higher (more restrictive) of the two lower bounds
/// - If one interval is unbounded below, returns the other's lower bound
/// - If both are unbounded below, returns `None`
/// - Properly handles open vs closed boundary precedence
///
/// #### [`min_upper_bound`](crate::intervals::IntervalBoundsRuntime::min_upper_bound)
/// Finds the most restrictive (minimum) upper bound between two intervals:
///
/// ```rust
/// use grid1d::{bounds::*, intervals::*};
/// use try_create::New;
///
/// let interval_a = IntervalClosed::new(0.0, 10.0);     // [0, 10]
/// let interval_b = IntervalOpen::new(2.0, 8.0);        // (2, 8)
///
/// // The most restrictive upper bound is 8)
/// let min_upper = interval_a.min_upper_bound(&interval_b);
/// if let Some(UpperBoundRuntime::Open(bound)) = min_upper {
///     assert_eq!(*bound.as_ref(), 8.0);
/// }
///
/// // With unbounded intervals
/// let unbounded = IntervalLowerClosedUpperUnbounded::new(0.0); // [0, +∞)
/// let min_with_unbounded = interval_a.min_upper_bound(&unbounded);
/// // Returns 10] since unbounded has no upper bound
/// if let Some(UpperBoundRuntime::Closed(bound)) = min_with_unbounded {
///     assert_eq!(*bound.as_ref(), 10.0);
/// }
/// ```
///
/// **Behavior:**
/// - Returns the lower (more restrictive) of the two upper bounds
/// - If one interval is unbounded above, returns the other's upper bound
/// - If both are unbounded above, returns `None`
/// - Properly handles open vs closed boundary precedence
///
/// ## Implementation Patterns
///
/// ### Finite Intervals
/// All finite intervals (closed, open, half-open) return `Some(_)` for both bounds:
///
/// ```rust,ignore
/// impl<RealType: RealScalar> IntervalBoundsRuntime for IntervalClosed<RealType> {
///     type RealType = RealType;
///
///     fn lower_bound_runtime(&self) -> Option<LowerBoundRuntime<RealType>> {
///         Some(IntervalBoundRuntime::Closed(self.lower_bound().clone()))
///     }
///
///     fn upper_bound_runtime(&self) -> Option<UpperBoundRuntime<RealType>> {
///         Some(IntervalBoundRuntime::Closed(self.upper_bound().clone()))
///     }
/// }
/// ```
///
/// ### Semi-Bounded Intervals
/// Semi-bounded intervals return `Some(_)` for the finite bound and `None` for the infinite bound:
///
/// ```rust,ignore
/// impl<RealType: RealScalar> IntervalBoundsRuntime for IntervalLowerClosedUpperUnbounded<RealType> {
///     type RealType = RealType;
///
///     fn lower_bound_runtime(&self) -> Option<LowerBoundRuntime<RealType>> {
///         Some(IntervalBoundRuntime::Closed(self.lower_bound().clone()))
///     }
///
///     fn upper_bound_runtime(&self) -> Option<UpperBoundRuntime<RealType>> {
///         None  // Unbounded above
///     }
/// }
/// ```
///
/// ### Unbounded Intervals
/// Fully unbounded intervals return `None` for both bounds:
///
/// ```rust,ignore
/// impl<RealType: RealScalar> IntervalBoundsRuntime for IntervalLowerUnboundedUpperUnbounded<RealType> {
///     type RealType = RealType;
///
///     fn lower_bound_runtime(&self) -> Option<LowerBoundRuntime<RealType>> {
///         None  // Unbounded below
///     }
///
///     fn upper_bound_runtime(&self) -> Option<UpperBoundRuntime<RealType>> {
///         None  // Unbounded above
///     }
/// }
/// ```
///
/// ### Singleton Intervals
/// Singleton intervals return the same value for both bounds with closed semantics:
///
/// ```rust,ignore
/// impl<RealType: RealScalar> IntervalBoundsRuntime for IntervalSingleton<RealType> {
///     type RealType = RealType;
///
///     fn lower_bound_runtime(&self) -> Option<LowerBoundRuntime<RealType>> {
///         Some(IntervalBoundRuntime::Closed(LowerBoundClosed::new(self.value().clone())))
///     }
///
///     fn upper_bound_runtime(&self) -> Option<UpperBoundRuntime<RealType>> {
///         Some(IntervalBoundRuntime::Closed(UpperBoundClosed::new(self.value().clone())))
///     }
/// }
/// ```
///
/// ## Advanced Usage Patterns
///
/// ### Generic Intersection Algorithm
///
/// ```rust
/// use grid1d::{bounds::*, intervals::*};
/// use num_valid::RealScalar;
///
/// /// Generic intersection algorithm using runtime bounds
/// fn intersection_bounds<I1, I2, T>(
///     a: &I1,
///     b: &I2,
/// ) -> Option<(LowerBoundRuntime<T>, UpperBoundRuntime<T>)>
/// where
///     I1: IntervalBoundsRuntime<RealType = T>,
///     I2: IntervalBoundsRuntime<RealType = T>,
///     T: RealScalar,
/// {
///     // Find most restrictive bounds
///     let lower = a.max_lower_bound(b)?;
///     let upper = a.min_upper_bound(b)?;
///     
///     // Check if intersection is valid (lower ≤ upper)
///     let lower_val = lower.as_ref();
///     let upper_val = upper.as_ref();
///     
///     if lower_val <= upper_val {
///         // Additional boundary compatibility check for exact equality
///         if lower_val == upper_val {
///             match (&lower, &upper) {
///                 (LowerBoundRuntime::Closed(_), UpperBoundRuntime::Closed(_)) => {
///                     Some((lower, upper)) // [a, a] is valid (singleton)
///                 }
///                 _ => None, // (a, a], [a, a), or (a, a) are empty
///             }
///         } else {
///             Some((lower, upper))
///         }
///     } else {
///         None // Disjoint intervals
///     }
/// }
///
/// let a = IntervalClosed::new(0.0, 2.0);    // [0, 2]
/// let b = IntervalOpen::new(1.0, 3.0);      // (1, 3)
///
/// if let Some((lower, upper)) = intersection_bounds(&a, &b) {
///     println!("Intersection exists:");
///     match lower {
///         LowerBoundRuntime::Open(bound) => println!("  Lower: ({}", bound.as_ref()),
///         LowerBoundRuntime::Closed(bound) => println!("  Lower: [{}",bound.as_ref()),
///     }
///     match upper {
///         UpperBoundRuntime::Open(bound) => println!("  Upper: {})", bound.as_ref()),
///         UpperBoundRuntime::Closed(bound) => println!("  Upper: {}]", bound.as_ref()),
///     }
/// }
/// // Output: Intersection is (1, 2]
/// ```
///
/// ### Interval Classification
///
/// ```rust
/// use grid1d::{bounds::*, intervals::*};
/// use num_valid::RealScalar;
///
/// #[derive(Debug, PartialEq)]
/// enum IntervalType {
///     Finite { closed_lower: bool, closed_upper: bool },
///     LowerBounded { closed: bool },
///     UpperBounded { closed: bool },
///     Unbounded,
///     Singleton,
/// }
///
/// /// Classify any interval based on its runtime bounds
/// fn classify_interval<I, T>(interval: &I) -> IntervalType
/// where
///     I: IntervalBoundsRuntime<RealType = T>,
///     T: RealScalar,
/// {
///     let lower = interval.lower_bound_runtime();
///     let upper = interval.upper_bound_runtime();
///     
///     match (lower, upper) {
///         (Some(lower_bound), Some(upper_bound)) => {
///             // Check if it's a singleton
///             let lower_val = lower_bound.as_ref();
///             let upper_val = upper_bound.as_ref();
///             
///             if lower_val == upper_val &&
///                matches!((&lower_bound, &upper_bound),
///                        (LowerBoundRuntime::Closed(_), UpperBoundRuntime::Closed(_))) {
///                 IntervalType::Singleton
///             } else {
///                 IntervalType::Finite {
///                     closed_lower: matches!(lower_bound, LowerBoundRuntime::Closed(_)),
///                     closed_upper: matches!(upper_bound, UpperBoundRuntime::Closed(_)),
///                 }
///             }
///         }
///         (Some(lower_bound), None) => {
///             IntervalType::LowerBounded {
///                 closed: matches!(lower_bound, LowerBoundRuntime::Closed(_)),
///             }
///         }
///         (None, Some(upper_bound)) => {
///             IntervalType::UpperBounded {
///                 closed: matches!(upper_bound, UpperBoundRuntime::Closed(_)),
///             }
///         }
///         (None, None) => IntervalType::Unbounded,
///     }
/// }
/// ```
///
/// ## Mathematical Properties
///
/// ### Boundary Ordering
/// The trait respects mathematical ordering of boundaries:
///
/// ```rust
/// use grid1d::{bounds::*, intervals::*};
///
/// // Lower bounds: more restrictive (higher) values dominate
/// let a = IntervalClosed::new(0.0, 5.0);    // [0, 5]
/// let b = IntervalClosed::new(2.0, 3.0);    // [2, 3]
///
/// let max_lower = a.max_lower_bound(&b);
/// // Returns [2 (more restrictive)
///
/// // Upper bounds: more restrictive (lower) values dominate  
/// let min_upper = a.min_upper_bound(&b);
/// // Returns 3] (more restrictive)
/// ```
///
/// ### Boundary Type Precedence
/// When bounds have the same value, the more restrictive type wins:
///
/// ```rust
/// use grid1d::{bounds::*, intervals::*};
///
/// let closed_interval = IntervalClosed::new(1.0, 2.0);        // [1, 2]
/// let half_open_interval = IntervalLowerOpenUpperClosed::new(1.0, 2.0); // (1, 2]
///
/// // For lower bounds with same value: closed ([) is more restrictive than open (()
/// let max_lower = closed_interval.max_lower_bound(&half_open_interval);
/// // Returns [1 (closed bound wins)
/// ```
///
/// ## Performance Characteristics
///
/// ### Memory Layout
/// - **Associated Type**: `RealType` adds no runtime overhead
/// - **Boundary Access**: Methods return owned [`IntervalBoundRuntime`](crate::intervals::IntervalBoundRuntime) values
/// - **Comparison Operations**: Default implementations with optimal algorithms
///
/// ### Time Complexity
/// | Operation | Complexity | Notes |
/// |-----------|------------|-------|
/// | [`lower_bound_runtime`](crate::intervals::IntervalBoundsRuntime::lower_bound_runtime) | O(1) | Direct field access and enum construction |
/// | [`upper_bound_runtime`](crate::intervals::IntervalBoundsRuntime::upper_bound_runtime) | O(1) | Direct field access and enum construction |
/// | [`max_lower_bound`](crate::intervals::IntervalBoundsRuntime::max_lower_bound) | O(1) | Pattern matching and comparison |
/// | [`min_upper_bound`](crate::intervals::IntervalBoundsRuntime::min_upper_bound) | O(1) | Pattern matching and comparison |
///
/// ### Space Complexity
/// - **Return Values**: Owned [`IntervalBoundRuntime`](crate::intervals::IntervalBoundRuntime) values (small enum + scalar)
/// - **No Allocation**: All operations work on stack-allocated data
/// - **Generic Efficiency**: Monomorphization ensures optimal code generation
///
/// ## Integration with Grid1D Architecture
///
/// ### Cross-Type Operations
/// The trait enables operations between different interval types:
///
/// ```rust
/// use grid1d::{bounds::*, intervals::*};
/// use num_valid::RealScalar;
///
/// fn can_intervals_intersect<I1, I2, T>(a: &I1, b: &I2) -> bool
/// where
///     I1: IntervalBoundsRuntime<RealType = T>,
///     I2: IntervalBoundsRuntime<RealType = T>,
///     T: RealScalar,
/// {
///     // Use runtime boundary information to check intersection possibility
///     let max_lower = a.max_lower_bound(b);
///     let min_upper = a.min_upper_bound(b);
///     
///     match (max_lower, min_upper) {
///         (Some(lower), Some(upper)) => {
///             // Extract values for comparison
///             let lower_val = lower.as_ref();
///             let upper_val = upper.as_ref();
///             
///             lower_val <= upper_val // Non-empty intersection possible
///         }
///         _ => true, // At least one interval is unbounded
///     }
/// }
///
/// // Works across all interval types
/// let closed = IntervalClosed::new(0.0, 2.0);
/// let open = IntervalOpen::new(1.0, 3.0);
/// let unbounded = IntervalLowerClosedUpperUnbounded::new(-1.0);
///
/// assert!(can_intervals_intersect(&closed, &open));       // [0,2] ∩ (1,3) ≠ ∅
/// assert!(can_intervals_intersect(&closed, &unbounded));  // [0,2] ∩ [-1,∞) ≠ ∅
/// ```
///
/// ## Best Practices
///
/// ### When to Use Runtime Boundary Access
/// - ✅ **Dynamic interval analysis**: When interval types vary at runtime
/// - ✅ **Generic algorithms**: Operations that work across different interval types  
/// - ✅ **Intersection computations**: Finding overlaps between arbitrary intervals
/// - ✅ **Serialization/deserialization**: Converting intervals to/from external formats
/// - ✅ **User interfaces**: Displaying interval information to users
///
/// ### Type Safety Guidelines
///
/// ```rust
/// use grid1d::{bounds::*, intervals::*};
/// use num_valid::RealScalar;
///
/// // RECOMMENDED: Use associated types for consistency
/// fn process_interval_bounds<I>(interval: &I) -> String
/// where
///     I: IntervalBoundsRuntime,
///     I::RealType: std::fmt::Display,
/// {
///     let lower = interval.lower_bound_runtime();
///     let upper = interval.upper_bound_runtime();
///     // Process using I::RealType consistently
///     format!("Interval bounds processed")
/// }
/// ```
///
/// ## Error Handling and Edge Cases
///
/// ### Boundary Validation
/// Runtime boundary access preserves the validation guarantees of the underlying scalar types:
///
/// ```rust
/// use grid1d::{bounds::*, intervals::*};
/// use num_valid::RealNative64StrictFiniteInDebug;
/// use try_create::TryNew;
///
/// type SafeReal = RealNative64StrictFiniteInDebug;
///
/// // Validation happens at interval construction, not boundary access
/// let safe_interval = IntervalClosed::new(
///     SafeReal::try_new(0.0).unwrap(),
///     SafeReal::try_new(1.0).unwrap()
/// );
///
/// // Boundary access is always safe after valid construction
/// let lower = safe_interval.lower_bound_runtime();
/// // lower is guaranteed to contain valid RealNative64StrictFiniteInDebug values
/// ```
///
/// ### Degenerate Cases
/// The trait handles degenerate interval cases correctly:
///
/// ```rust
/// use grid1d::{bounds::*, intervals::*};
/// use try_create::New;
///
/// // Singleton interval
/// let singleton = IntervalSingleton::new(5.0);
/// let lower = singleton.lower_bound_runtime().unwrap();
/// let upper = singleton.upper_bound_runtime().unwrap();
///
/// // Both bounds point to the same value with closed semantics
/// match (lower, upper) {
///     (LowerBoundRuntime::Closed(l), UpperBoundRuntime::Closed(u)) => {
///         assert_eq!(l.as_ref(), u.as_ref());
///         assert_eq!(*l.as_ref(), 5.0);
///     }
///     _ => panic!("Singleton should have closed bounds"),
/// }
/// ```
///
/// The [`IntervalBoundsRuntime`] trait provides the essential foundation for dynamic interval
/// boundary access and manipulation in the grid1d library. It enables flexible, type-safe
/// operations across all interval types while maintaining mathematical correctness and optimal
/// performance through Rust's zero-cost abstractions.
pub trait IntervalBoundsRuntime: Debug {
    /// The scalar type used for interval bounds.
    ///
    /// This associated type must implement [`RealScalar`], ensuring it supports
    /// all necessary mathematical operations and comparisons.
    type RealType: RealScalar;

    /// Returns the lower boundary value if the interval is bounded below.
    ///
    /// # Returns
    /// - `Some(&value)` if the interval has a finite lower bound
    /// - `None` if the interval extends to negative infinity
    ///
    /// # Examples
    /// ```rust
    /// use grid1d::{bounds::*, intervals::*};
    /// use try_create::New;
    ///
    /// let bounded = IntervalClosed::new(1.0, 5.0);
    /// let unbounded = IntervalLowerUnboundedUpperClosed::new(5.0);
    ///
    /// assert_eq!(bounded.lower_bound_runtime(), Some(LowerBoundRuntime::Closed(LowerBoundClosed::new(1.0))));
    /// assert_eq!(unbounded.lower_bound_runtime(), None);
    /// ```
    fn lower_bound_runtime(&self) -> Option<LowerBoundRuntime<Self::RealType>>;

    /// Returns the upper boundary value if the interval is bounded above.
    ///
    /// # Returns
    /// - `Some(&value)` if the interval has a finite upper bound
    /// - `None` if the interval extends to positive infinity
    ///
    /// # Examples
    /// ```rust
    /// use grid1d::{bounds::*, intervals::*};
    /// use try_create::New;
    ///
    /// let bounded = IntervalClosed::new(1.0, 5.0);
    /// let unbounded = IntervalLowerClosedUpperUnbounded::new(1.0);
    ///
    /// assert_eq!(bounded.upper_bound_runtime(), Some(UpperBoundRuntime::Closed(UpperBoundClosed::new(5.0))));
    /// assert_eq!(unbounded.upper_bound_runtime(), None);
    /// ```
    fn upper_bound_runtime(&self) -> Option<UpperBoundRuntime<Self::RealType>>;

    /// Finds the most restrictive (maximum) lower bound between two intervals.
    ///
    /// This method compares the lower bounds of two intervals and returns the one that
    /// is more restrictive (higher value). This is essential for intersection operations
    /// where the resulting interval's lower bound must satisfy both input intervals.
    ///
    /// # Mathematical Behavior
    /// - Returns the higher (more restrictive) of the two lower bounds
    /// - If one interval is unbounded below, returns the other's lower bound
    /// - If both are unbounded below, returns `None`
    /// - Properly handles open vs closed boundary precedence (closed is more restrictive)
    ///
    /// # Type Parameters
    /// - `Other`: Another interval type implementing `IntervalBoundsRuntime` with the same scalar type
    ///
    /// # Returns
    /// - `Some(LowerBoundRuntime)`: The most restrictive lower bound
    /// - `None`: If both intervals are unbounded below
    ///
    /// # Examples
    /// ```rust
    /// use grid1d::{bounds::*, intervals::*};
    /// use try_create::New;
    ///
    /// let interval_a = IntervalClosed::new(0.0, 10.0);      // [0, 10]
    /// let interval_b = IntervalLowerClosedUpperOpen::new(2.0, 8.0); // [2, 8)
    ///
    /// // The most restrictive lower bound is [2
    /// let max_lower = interval_a.max_lower_bound(&interval_b);
    /// if let Some(LowerBoundRuntime::Closed(bound)) = max_lower {
    ///     assert_eq!(*bound.as_ref(), 2.0);
    /// }
    ///
    /// // With unbounded intervals
    /// let unbounded = IntervalLowerUnboundedUpperClosed::new(5.0); // (-∞, 5]
    /// let max_with_unbounded = interval_a.max_lower_bound(&unbounded);
    /// // Returns [0 since unbounded has no lower bound
    /// if let Some(LowerBoundRuntime::Closed(bound)) = max_with_unbounded {
    ///     assert_eq!(*bound.as_ref(), 0.0);
    /// }
    /// ```
    fn max_lower_bound<Other>(&self, other: &Other) -> Option<LowerBoundRuntime<Self::RealType>>
    where
        Other: IntervalBoundsRuntime<RealType = Self::RealType>,
    {
        let lb_self = self.lower_bound_runtime();
        let lb_other = other.lower_bound_runtime();
        match (lb_self, lb_other) {
            (None, lb_other) => lb_other,
            (lb_self, None) => lb_self,
            (Some(lb_self), Some(lb_other)) => {
                Some(crate::bounds::max_lower_bound(lb_self, lb_other))
            }
        }
    }

    /// Finds the most restrictive (minimum) upper bound between two intervals.
    ///
    /// This method compares the upper bounds of two intervals and returns the one that
    /// is more restrictive (lower value). This is essential for intersection operations
    /// where the resulting interval's upper bound must satisfy both input intervals.
    ///
    /// # Mathematical Behavior
    /// - Returns the lower (more restrictive) of the two upper bounds
    /// - If one interval is unbounded above, returns the other's upper bound
    /// - If both are unbounded above, returns `None`
    /// - Properly handles open vs closed boundary precedence (open is more restrictive)
    ///
    /// # Type Parameters
    /// - `Other`: Another interval type implementing `IntervalBoundsRuntime` with the same scalar type
    ///
    /// # Returns
    /// - `Some(UpperBoundRuntime)`: The most restrictive upper bound
    /// - `None`: If both intervals are unbounded above
    ///
    /// # Examples
    /// ```rust
    /// use grid1d::{bounds::*, intervals::*};
    /// use try_create::New;
    ///
    /// let interval_a = IntervalClosed::new(0.0, 10.0);     // [0, 10]
    /// let interval_b = IntervalOpen::new(2.0, 8.0);        // (2, 8)
    ///
    /// // The most restrictive upper bound is 8)
    /// let min_upper = interval_a.min_upper_bound(&interval_b);
    /// if let Some(UpperBoundRuntime::Open(bound)) = min_upper {
    ///     assert_eq!(*bound.as_ref(), 8.0);
    /// }
    ///
    /// // With unbounded intervals
    /// let unbounded = IntervalLowerClosedUpperUnbounded::new(0.0); // [0, +∞)
    /// let min_with_unbounded = interval_a.min_upper_bound(&unbounded);
    /// // Returns 10] since unbounded has no upper bound
    /// if let Some(UpperBoundRuntime::Closed(bound)) = min_with_unbounded {
    ///     assert_eq!(*bound.as_ref(), 10.0);
    /// }
    /// ```
    fn min_upper_bound<Other>(&self, other: &Other) -> Option<UpperBoundRuntime<Self::RealType>>
    where
        Other: IntervalBoundsRuntime<RealType = Self::RealType>,
    {
        let ub_self = self.upper_bound_runtime();
        let ub_other = other.upper_bound_runtime();
        match (ub_self, ub_other) {
            (None, ub_other) => ub_other,
            (ub_self, None) => ub_self,
            (Some(ub_self), Some(ub_other)) => {
                Some(crate::bounds::min_upper_bound(ub_self, ub_other))
            }
        }
    }
}
//------------------------------------------------------------------------------------------------

//------------------------------------------------------------------------------------------------
/// Trait for computing the **convex hull** (interval hull) between two intervals.
///
/// The convex hull is the smallest interval that contains both input intervals,
/// preserving the most **inclusive boundary semantics**.
///
/// ## Mathematical Definition
///
/// For two intervals `A` and `B`, their convex hull `hull(A, B)` is defined as:
///
/// ```text
/// hull(A, B) = [min(inf A, inf B), max(sup A, sup B)]
/// ```
///
/// where the boundary types follow the **most inclusive principle**:
/// - **Lower bound**: Take the minimum value with the **most inclusive** boundary type
/// - **Upper bound**: Take the maximum value with the **most inclusive** boundary type
/// - **Inclusion hierarchy**: `Closed ⊃ Open` (closed is more inclusive than open)
///
/// ### Boundary Inclusion Rules
///
/// When computing the hull, boundary types are resolved according to inclusion precedence:
///
/// | Input Bounds | Result Bound | Rationale |
/// |--------------|--------------|-----------|
/// | `Closed` + `Closed` | `Closed` | Both include boundary → include in hull |
/// | `Closed` + `Open` | `Closed` | Closed is more inclusive → include in hull |
/// | `Open` + `Open` | `Open` | Both exclude boundary → exclude in hull |
///
/// **Example**: For intervals `[0, 1]` and `(0, 2)`:
/// - Lower bound: Both have value 0, but `[` (closed) is more inclusive than `(` (open) → result uses `[`
/// - Upper bound: Values 1 vs 2, take max(1,2)=2 with bound type from `(0, 2)` → result uses `)`
/// - Final hull: `[0, 2)`
///
/// This ensures that the hull contains **exactly** the union of all points contained
/// in either input interval, with no points added or removed incorrectly.
///
/// ## Core Operation
///
/// ### [`hull`](IntervalHull::hull) Method
///
/// Computes the convex hull between `self` and another interval of potentially different type.
///
/// **Signature**: `fn hull(&self, other: &Other) -> Self::Output`
///
/// **Parameters**:
/// - `other`: Another finite positive-length interval (may be different type)
///
/// **Returns**: An interval containing both input intervals with correct boundary semantics
///
/// ## Generic Design and Type Safety
///
/// The trait is designed for maximum flexibility while maintaining type safety:
/// - **Generic over interval types**: Works between any interval implementing the trait [`IntervalTrait`]
/// - **Scalar type consistency**: Both intervals must use the same `RealType`
/// - **Type-safe output**: Result type depends on input boundary combinations
/// - **Compile-time verification**: Invalid combinations are caught at compile time
///
/// ## Mathematical Properties
///
/// All implementations guarantee these fundamental mathematical properties:
///
/// ### 1. **Containment Property**
/// ```text
/// A ⊆ hull(A, B) and B ⊆ hull(A, B)
/// ```
/// The hull always contains both input intervals completely.
///
/// ### 2. **Minimality Property**
/// ```text
/// If A ⊆ C and B ⊆ C, then hull(A, B) ⊆ C
/// ```
/// The hull is the smallest interval containing both inputs.
///
/// ### 3. **Commutativity Property**
/// ```text
/// hull(A, B) = hull(B, A)
/// ```
/// Order of operands doesn't affect the result.
///
/// ### 4. **Idempotence Property**
/// ```text
/// hull(A, A) = A (for compatible types)
/// ```
/// Hull of an interval with itself is the interval.
///
/// ### 5. **Associativity Property**
/// ```text
/// hull(hull(A, B), C) = hull(A, hull(B, C))
/// ```
/// Grouping doesn't affect the final result.
///
/// ## Comprehensive Usage Examples
///
/// ### Basic Hull Operations
/// ```rust
/// use grid1d::intervals::*;
/// use num_valid::RealNative64StrictFiniteInDebug;
/// use try_create::TryNew;
///
/// type Real = RealNative64StrictFiniteInDebug;
///
/// // Same boundary types → preserve type
/// let closed1 = IntervalClosed::new(
///     Real::try_new(1.0).unwrap(),
///     Real::try_new(3.0).unwrap()
/// );
/// let closed2 = IntervalClosed::new(
///     Real::try_new(2.0).unwrap(),
///     Real::try_new(5.0).unwrap()
/// );
///
/// let hull = closed1.hull(&closed2);
/// // Result: [1.0, 5.0] (closed)
/// assert_eq!(hull.lower_bound_value(), &1.0);
/// assert_eq!(hull.upper_bound_value(), &5.0);
/// ```
///
/// ### Cross-Type Hull Operations
/// ```rust
/// use grid1d::intervals::*;
/// use try_create::TryNew;
///
/// let closed = IntervalClosed::new(1.0, 3.0);      // [1, 3]
/// let open = IntervalOpen::new(2.0, 5.0);          // (2, 5)
///
/// let hull = closed.hull(&open);
/// // Result: [1.0, 5.0) - closed lower wins, open upper wins  
/// match hull {
///     IntervalFinitePositiveLength::LowerClosedUpperOpen(result) => {
///         assert_eq!(*result.lower_bound_value(), 1.0);
///         assert_eq!(*result.upper_bound_value(), 5.0);
///     }
///     _ => unreachable!(),
/// }
/// ```
///
/// ### Complex Boundary Combinations
/// ```rust
/// use grid1d::intervals::*;
///
/// let left_closed = IntervalLowerClosedUpperOpen::new(1.0, 3.0);   // [1, 3)
/// let right_closed = IntervalLowerOpenUpperClosed::new(2.0, 5.0);  // (2, 5]
///
/// let hull = left_closed.hull(&right_closed);
/// // Result: [1.0, 5.0] - closed lower wins, closed upper wins
/// match hull {
///     IntervalFinitePositiveLength::Closed(result) => {
///         assert_eq!(*result.lower_bound_value(), 1.0);
///         assert_eq!(*result.upper_bound_value(), 5.0);
///     }
///     _ => unreachable!(),
/// }
/// ```
///
/// ### Disjoint Intervals
/// ```rust
/// use grid1d::intervals::*;
///
/// let left = IntervalClosed::new(1.0, 2.0);    // [1, 2]
/// let right = IntervalClosed::new(4.0, 5.0);   // [4, 5]
///
/// let hull = left.hull(&right);
/// // Result: [1.0, 5.0] - spans both intervals and the gap
/// assert_eq!(*hull.lower_bound_value(), 1.0);
/// assert_eq!(*hull.upper_bound_value(), 5.0);
/// assert_eq!(*hull.length().as_ref(), 4.0);  // Includes the gap
/// ```
///
/// ### Containment Relationships
/// ```rust
/// use grid1d::intervals::*;
///
/// let outer = IntervalClosed::new(0.0, 10.0);  // [0, 10]
/// let inner = IntervalClosed::new(3.0, 7.0);   // [3, 7]
///
/// let hull = outer.hull(&inner);
/// // Result: [0.0, 10.0] - same as outer interval
/// assert_eq!(*hull.lower_bound_value(), 0.0);
/// assert_eq!(*hull.upper_bound_value(), 10.0);
/// ```
///
/// ## Advanced Usage Patterns
///
/// ### Multi-Interval Hull
/// ```rust
/// use grid1d::intervals::*;
///
/// /// Compute hull of multiple intervals using fold
/// fn multi_hull(intervals: Vec<IntervalClosed<f64>>) -> Option<IntervalFinitePositiveLength<f64>> {
///     let mut iter = intervals.into_iter();
///     let first = iter.next()?;
///     Some(iter.fold(first.into(), |acc: IntervalFinitePositiveLength<f64>, interval| {
///         acc.hull(&interval)
///     }))
/// }
///
/// let intervals = vec![
///     IntervalClosed::new(1.0, 2.0),
///     IntervalClosed::new(3.0, 4.0),
///     IntervalClosed::new(5.0, 6.0),
/// ];
///
/// if let Some(hull) = multi_hull(intervals) {
///     // Result: [1.0, 6.0]
///     assert_eq!(*hull.lower_bound_value(), 1.0);
///     assert_eq!(*hull.upper_bound_value(), 6.0);
/// }
/// ```
///
/// ### Boundary-Aware Hull Analysis
/// ```rust
/// use grid1d::intervals::*;
///
/// /// Analyze how boundary types affect hull computation
/// let closed = IntervalClosed::new(0.0, 1.0);           // [0, 1]
/// let open = IntervalOpen::new(0.0, 1.0);               // (0, 1)
/// let left_open = IntervalLowerOpenUpperClosed::new(0.0, 1.0);  // (0, 1]
/// let right_open = IntervalLowerClosedUpperOpen::new(0.0, 1.0); // [0, 1)
///
/// // Same bounds, different boundary types
/// let hull_closed_open = closed.hull(&open);
/// let hull_left_right = left_open.hull(&right_open);
///
/// // Both should result in closed intervals due to boundary inclusion rules
/// // (closed boundaries win over open boundaries at same values)
/// match (hull_closed_open, hull_left_right) {
///     (
///         IntervalFinitePositiveLength::Closed(h1),
///         IntervalFinitePositiveLength::Closed(h2)
///     ) => {
///         assert_eq!(h1.lower_bound_value(), h2.lower_bound_value());
///         assert_eq!(h1.upper_bound_value(), h2.upper_bound_value());
///     }
///     _ => unreachable!("Expected closed intervals"),
/// }
/// ```
///
/// ## Implementation Strategy
///
/// The trait provides implementations for all combinations of finite positive-length intervals:
///
/// ### Homogeneous Implementations
/// - [`IntervalClosed`](crate::intervals::IntervalClosed) with [`IntervalClosed`](crate::intervals::IntervalClosed) → [`IntervalClosed`](crate::intervals::IntervalClosed)
/// - [`IntervalOpen`](crate::intervals::IntervalOpen) with [`IntervalOpen`](crate::intervals::IntervalOpen) → [`IntervalOpen`](crate::intervals::IntervalOpen)
/// - [`IntervalLowerClosedUpperOpen`](crate::intervals::IntervalLowerClosedUpperOpen) with [`IntervalLowerClosedUpperOpen`](crate::intervals::IntervalLowerClosedUpperOpen) → [`IntervalLowerClosedUpperOpen`](crate::intervals::IntervalLowerClosedUpperOpen)
/// - [`IntervalLowerOpenUpperClosed`](crate::intervals::IntervalLowerOpenUpperClosed) with [`IntervalLowerOpenUpperClosed`](crate::intervals::IntervalLowerOpenUpperClosed) → [`IntervalLowerOpenUpperClosed`](crate::intervals::IntervalLowerOpenUpperClosed)
///
/// ### Heterogeneous Implementations
/// All combinations between different interval types, following boundary inclusion rules:
/// - [`IntervalClosed`](crate::intervals::IntervalClosed) with [`IntervalOpen`](crate::intervals::IntervalOpen) → Result depends on boundary positions (e.g., [`IntervalLowerClosedUpperOpen`](crate::intervals::IntervalLowerClosedUpperOpen))
/// - [`IntervalClosed`](crate::intervals::IntervalClosed) with [`IntervalLowerClosedUpperOpen`](crate::intervals::IntervalLowerClosedUpperOpen) → Result depends on boundary positions  
/// - [`IntervalClosed`](crate::intervals::IntervalClosed) with [`IntervalLowerOpenUpperClosed`](crate::intervals::IntervalLowerOpenUpperClosed) → Result depends on boundary positions
/// - And all symmetric variants...
///
/// ### Enum Implementation
/// - [`IntervalFinitePositiveLength`](crate::intervals::IntervalFinitePositiveLength) with [`IntervalFinitePositiveLength`](crate::intervals::IntervalFinitePositiveLength) → [`IntervalFinitePositiveLength`](crate::intervals::IntervalFinitePositiveLength)
///
/// ## Performance Characteristics
///
/// ### Time Complexity
/// - **All operations**: O(1) - constant time regardless of interval types
/// - **Boundary analysis**: O(1) - simple comparisons and type matching
/// - **Result construction**: O(1) - direct value assignment
///
/// ### Space Complexity
/// - **Memory usage**: O(1) - no additional allocation beyond result interval
/// - **Stack usage**: Minimal - simple function calls with value parameters
/// - **Cache efficiency**: Excellent - operates on compact interval data
///
/// ### Scalar Type Performance Impact
/// ```rust
/// use grid1d::intervals::*;
/// use num_valid::{RealNative64StrictFiniteInDebug, RealNative64StrictFinite};
///
/// // Performance comparison across scalar types
/// type FastInterval = IntervalClosed<f64>;
/// type OptimalInterval = IntervalClosed<RealNative64StrictFiniteInDebug>;
/// type SafeInterval = IntervalClosed<RealNative64StrictFinite>;
///
/// // All have nearly identical hull performance:
/// // - f64: Maximum speed, no validation overhead
/// // - RealNative64StrictFiniteInDebug: Same speed as f64 in release builds
/// // - RealNative64StrictFinite: Small overhead for validation
/// ```
///
/// ## Error Handling and Edge Cases
///
/// ### Compile-Time Safety
/// ```rust
/// use grid1d::intervals::*;
///
/// // This won't compile - scalar type mismatch:
/// // let interval_f64 = IntervalClosed::new(1.0_f64, 2.0_f64);
/// // let interval_f32 = IntervalClosed::new(1.0_f32, 2.0_f32);
/// // let hull = interval_f64.hull(&interval_f32); // ERROR!
/// ```
///
/// ### Precision Considerations
/// ```rust
/// use grid1d::intervals::*;
///
/// // Very small intervals
/// let tiny1 = IntervalClosed::new(0.0, f64::EPSILON);
/// let tiny2 = IntervalClosed::new(f64::EPSILON, 2.0 * f64::EPSILON);
///
/// let hull = tiny1.hull(&tiny2);
/// // Result: [0.0, 2ε] - mathematically correct even for tiny intervals
/// ```
///
/// ## Integration with Other Traits
///
/// ### Containment Verification
/// ```rust
/// use grid1d::intervals::*;
///
/// /// Verify that hull satisfies containment property
/// fn verify_hull_containment<I1, I2>(a: &I1, b: &I2) -> bool
/// where
///     I1: IntervalHull<I2> + Clone,
///     I2: IntervalFinitePositiveLengthTrait<RealType = I1::RealType> + Clone,
///     I1::Output: Contains<RealType = I1::RealType>,
///     Interval<I1::RealType>: From<I1> + From<I2> + From<I1::Output>,
/// {
///     let hull = a.hull(b);
///     let hull_general: Interval<I1::RealType> = hull.into();
///     let a_general: Interval<I1::RealType> = a.clone().into();
///     let b_general: Interval<I1::RealType> = b.clone().into();
///     
///     hull_general.contains_interval(&a_general) &&
///     hull_general.contains_interval(&b_general)
/// }
/// ```
///
/// ### Set Operations Integration
/// ```rust
/// use grid1d::intervals::*;
///
/// /// Compare hull with union operation
/// fn hull_vs_union_comparison() {
///     let a = IntervalClosed::new(1.0, 3.0);
///     let b = IntervalClosed::new(2.0, 5.0);
///     
///     // Hull always produces a single connected interval
///     let hull = a.hull(&b);
///     
///     // Union might produce disjoint intervals (but not in this case)
///     let union = a.union(&b);
///     
///     match union {
///         IntervalUnion::SingleConnected(connected) => {
///             // When union is connected, it should match the hull
///             // (modulo boundary type differences)
///         }
///         IntervalUnion::TwoDisjoint { .. } => {
///             // Hull always connects disjoint intervals
///             // This is where hull differs from union
///         }
///     }
/// }
/// ```
///
/// ## Mathematical Foundations and Proofs
///
/// ### Correctness Theorem
/// For any intervals `A` and `B` with finite positive length:
/// ```text
/// hull(A, B) = [min(inf A, inf B), max(sup A, sup B)]
/// ```
/// where boundary inclusion follows the most inclusive principle.
///
/// ### Proof Sketch of Containment Property
/// 1. **Lower bound**: `min(inf A, inf B) ≤ inf A` and `min(inf A, inf B) ≤ inf B`
/// 2. **Upper bound**: `max(sup A, sup B) ≥ sup A` and `max(sup A, sup B) ≥ sup B`
/// 3. **Boundary inclusion**: Most inclusive boundaries ensure all points in A ∪ B are contained
/// 4. **Therefore**: `A ⊆ hull(A, B)` and `B ⊆ hull(A, B)` ∎
///
/// ### Proof Sketch of Minimality Property
/// 1. **Assumption**: Interval C contains both A and B
/// 2. **Lower bound**: `inf C ≤ inf A` and `inf C ≤ inf B` ⟹ `inf C ≤ min(inf A, inf B)`
/// 3. **Upper bound**: `sup C ≥ sup A` and `sup C ≥ sup B` ⟹ `sup C ≥ max(sup A, sup B)`
/// 4. **Therefore**: `hull(A, B) ⊆ C` ∎
///
/// ## Best Practices and Recommendations
///
/// ### When to Use [`IntervalHull`]
/// - **Bounding box computation**: Find minimal interval containing multiple regions
/// - **Range analysis**: Determine combined range of multiple functions
/// - **Geometric algorithms**: Convex hull computation in 1D space
/// - **Data analysis**: Find overall range of multiple datasets
/// - **Optimization**: Combine constraint domains
///
/// ### Avoiding Common Pitfalls
/// ```rust
/// use grid1d::intervals::*;
///
/// // WRONG: Assuming hull preserves original boundary types
/// fn incorrect_assumption() {
///     let closed = IntervalClosed::new(1.0, 3.0);
///     let open = IntervalOpen::new(2.0, 5.0);
///     let hull = closed.hull(&open);
///     
///     // DON'T assume the result is closed just because one input was closed
///     // The result depends on boundary inclusion rules
/// }
///
/// // CORRECT: Handle all possible result types
/// fn correct_handling() {
///     let closed = IntervalClosed::new(1.0, 3.0);
///     let open = IntervalOpen::new(2.0, 5.0);
///     let hull = closed.hull(&open);
///     
///     match hull {
///         IntervalFinitePositiveLength::Closed(_) => { /* Handle closed */ }
///         IntervalFinitePositiveLength::Open(_) => { /* Handle open */ }
///         IntervalFinitePositiveLength::LowerClosedUpperOpen(_) => { /* Handle half-open */ }
///         IntervalFinitePositiveLength::LowerOpenUpperClosed(_) => { /* Handle half-open */ }
///     }
/// }
/// ```
///
/// The [`IntervalHull`] trait is fundamental for interval arithmetic and computational geometry
/// applications, providing mathematically sound and computationally efficient convex hull
/// operations while maintaining the library's strong type safety guarantees.
///
/// ## Support for All Interval Types
///
/// This trait is **fully generalized** to compute the convex hull between **any two intervals** implementing [`IntervalTrait`], including:
/// - **Bounded intervals**: [`IntervalClosed`](crate::intervals::IntervalClosed), [`IntervalOpen`](crate::intervals::IntervalOpen), [`IntervalLowerClosedUpperOpen`](crate::intervals::IntervalLowerClosedUpperOpen), [`IntervalLowerOpenUpperClosed`](crate::intervals::IntervalLowerOpenUpperClosed)
/// - **Half-unbounded intervals**: [`IntervalLowerClosedUpperUnbounded`](crate::intervals::IntervalLowerClosedUpperUnbounded), [`IntervalLowerOpenUpperUnbounded`](crate::intervals::IntervalLowerOpenUpperUnbounded), [`IntervalLowerUnboundedUpperClosed`](crate::intervals::IntervalLowerUnboundedUpperClosed), [`IntervalLowerUnboundedUpperOpen`](crate::intervals::IntervalLowerUnboundedUpperOpen)
/// - **Fully unbounded**: [`IntervalLowerUnboundedUpperUnbounded`](crate::intervals::IntervalLowerUnboundedUpperUnbounded)
/// - **Singleton intervals**: [`IntervalSingleton`](crate::intervals::IntervalSingleton)
/// - **Enum types**: [`Interval`], [`IntervalFiniteLength`](crate::intervals::IntervalFiniteLength), [`IntervalInfiniteLength`](crate::intervals::IntervalInfiniteLength), [`IntervalFinitePositiveLength`](crate::intervals::IntervalFinitePositiveLength)
///
/// ### Hull Rules for Different Interval Types
///
/// The hull operation follows a fundamental principle:
///
/// **If ANY interval is unbounded in a direction, the hull is unbounded in that direction.**
///
/// Specifically:
/// - **Both bounded**: Returns smallest bounded interval containing both (specific bounded type)
/// - **One or both unbounded above**: Returns interval unbounded above with minimum lower bound
/// - **One or both unbounded below**: Returns interval unbounded below with maximum upper bound
/// - **Both fully unbounded**: Returns the universal interval `(-∞, +∞)`
///
/// ### Examples with Unbounded Intervals
///
/// ```rust
/// use grid1d::intervals::*;
///
/// // Case 1: Both bounded → bounded result
/// let bounded1 = IntervalClosed::new(0.0, 2.0);  // [0, 2]
/// let bounded2 = IntervalClosed::new(1.0, 3.0);  // [1, 3]
/// let hull = bounded1.hull(&bounded2);           // [0, 3]
///
/// // Case 2: Bounded with half-unbounded → unbounded result
/// let bounded = IntervalClosed::new(0.0, 2.0);              // [0, 2]
/// let unbounded = IntervalLowerClosedUpperUnbounded::new(1.0);  // [1, +∞)
/// let hull = bounded.hull(&unbounded);                       // [0, +∞)
/// // Explanation: Takes min lower bound (0) and unbounded upper
///
/// // Case 3: Bounded with opposite-direction unbounded → fully unbounded
/// let bounded = IntervalClosed::new(-2.0, 1.0);              // [-2, 1]
/// let upper_unbounded = IntervalLowerUnboundedUpperClosed::new(0.0);  // (-∞, 0]
/// let hull = bounded.hull(&upper_unbounded);                  // (-∞, 1]
/// // Explanation: Unbounded below, max upper bound (1)
///
/// // Case 4: Two half-unbounded in same direction → half-unbounded result
/// let unbounded1 = IntervalLowerClosedUpperUnbounded::new(0.0);  // [0, +∞)
/// let unbounded2 = IntervalLowerClosedUpperUnbounded::new(5.0);  // [5, +∞)
/// let hull = unbounded1.hull(&unbounded2);                       // [0, +∞)
/// // Explanation: Min lower bound (0), both unbounded above
///
/// // Case 5: Mixed boundary types with unbounded
/// let open = IntervalOpen::new(0.0, 2.0);                        // (0, 2)
/// let unbounded = IntervalLowerClosedUpperUnbounded::new(1.5);   // [1.5, +∞)
/// let hull = open.hull(&unbounded);                              // (0, +∞)
/// // Explanation: Open lower wins (more restrictive), unbounded upper
///
/// // Case 6: Fully unbounded with any interval → fully unbounded
/// let bounded = IntervalClosed::new(0.0, 10.0);     // [0, 10]
/// let fully_unbounded = IntervalLowerUnboundedUpperUnbounded::new();  // (-∞, +∞)
/// let hull = bounded.hull(&fully_unbounded);        // (-∞, +∞)
/// ```
///
/// ### Return Type Strategy
///
/// The trait uses different output types depending on the input combinations:
///
/// - **Bounded-to-bounded**: Returns [`IntervalFinitePositiveLength<RealType>`](crate::intervals::IntervalFinitePositiveLength) to preserve type specificity and performance
/// - **Bounded-to-unbounded**: Returns [`Interval<RealType>`] (universal enum) to accommodate any result type
/// - **Unbounded-to-bounded**: Returns [`Interval<RealType>`]
/// - **Unbounded-to-unbounded**: Returns [`Interval<RealType>`]
/// - **Using enum types**: Always returns [`Interval<RealType>`]
///
/// This design provides optimal performance for bounded intervals while supporting full generality.
pub trait IntervalHull<Other: IntervalTrait<RealType = Self::RealType>>: IntervalTrait {
    /// The type of interval returned by the hull operation.
    ///
    /// This associated type ensures type safety while allowing different implementations
    /// to return the most appropriate interval type based on their boundary semantics.
    /// The output type must implement [`IntervalTrait`] and use the same scalar type
    /// as the input intervals.
    ///
    /// For generalized hulls, the output is typically the universal [`Interval<RealType>`]
    /// enum which can represent any interval type (bounded, unbounded, etc.).
    type Output: IntervalTrait<RealType = Self::RealType>;

    /// Computes the convex hull (interval hull) between this interval and another.
    ///
    /// The convex hull is the smallest interval that contains both input intervals,
    /// following the **most inclusive boundary principle**:
    /// - Takes the minimum of lower bounds with most inclusive boundary type
    /// - Takes the maximum of upper bounds with most inclusive boundary type
    /// - Open boundaries are less inclusive than closed boundaries
    /// - Handles unbounded intervals correctly
    ///
    /// ## Mathematical Guarantee
    ///
    /// The result `H = self.hull(other)` satisfies:
    /// - **Containment**: `self ⊆ H` and `other ⊆ H`
    /// - **Minimality**: If `self ⊆ I` and `other ⊆ I`, then `H ⊆ I`
    /// - **Commutativity**: `self.hull(other) = other.hull(self)`
    ///
    /// ## Parameters
    ///
    /// - `other`: Another interval implementing [`IntervalTrait`] with the same scalar type
    ///
    /// ## Returns
    ///
    /// An interval of type [`Self::Output`] that represents the convex hull.
    /// The exact type depends on the boundary types and boundedness of the input intervals.
    ///
    /// ## Examples
    ///
    /// ```rust
    /// use grid1d::intervals::*;
    ///
    /// // Same types → preserve type when possible
    /// let a = IntervalClosed::new(1.0, 3.0);  // [1, 3]
    /// let b = IntervalClosed::new(2.0, 5.0);  // [2, 5]
    /// let hull = a.hull(&b);                  // [1, 5]
    ///
    /// // Different types → follow inclusion rules
    /// let closed = IntervalClosed::new(1.0, 3.0);  // [1, 3]
    /// let open = IntervalOpen::new(2.0, 5.0);      // (2, 5)
    /// let hull = closed.hull(&open);               // [1, 5) - closed lower wins, open upper wins
    ///
    /// // With unbounded intervals
    /// let bounded = IntervalClosed::new(0.0, 2.0);
    /// let unbounded = IntervalLowerClosedUpperUnbounded::new(1.0);
    /// let hull = bounded.hull(&unbounded);  // [0, +∞)
    /// ```
    fn hull(&self, other: &Other) -> Self::Output;
}
//------------------------------------------------------------------------------------------------

//------------------------------------------------------------------------------------------------
/// Core trait for point containment testing in mathematical intervals.
///
/// The [`Contains`] trait provides the fundamental operation for testing whether a specific
/// point belongs to an interval. This trait forms the foundation for all point-based queries
/// and is complemented by the [`contains_interval`](Contains::contains_interval) method
/// for interval-to-interval containment testing.
///
/// ## Mathematical Foundation
///
/// Point containment is the most basic operation in interval mathematics. For any interval `I`
/// and point `x`, the containment test `x ∈ I` determines whether the point lies within the
/// interval according to its boundary conditions:
///
/// - **Closed intervals** `[a,b]`: `x ∈ [a,b] ⟺ a ≤ x ≤ b`
/// - **Open intervals** `(a,b)`: `x ∈ (a,b) ⟺ a < x < b`
/// - **Half-open intervals** `[a,b)`: `x ∈ [a,b) ⟺ a ≤ x < b`
/// - **Half-open intervals** `(a,b]`: `x ∈ (a,b] ⟺ a < x ≤ b`
/// - **Singleton intervals** `{a}`: `x ∈ {a} ⟺ x = a`
/// - **Unbounded intervals**: Various combinations with infinite extents
///
/// ## Design Philosophy
///
/// The [`Contains`] trait is intentionally minimal and focused:
///
/// - **Single Responsibility**: Only handles point containment, not interval containment
/// - **Generic Design**: Works with any scalar type implementing [`RealScalar`]
/// - **Performance First**: Designed for O(1) operations with minimal overhead
/// - **Type Safety**: Prevents containment queries with incompatible types
/// - **Mathematical Correctness**: Respects boundary semantics exactly
///
/// ## Relationship with Interval Containment
///
/// Point containment ([`contains_point`](Contains::contains_point)) and interval containment
/// ([`contains_interval`](Contains::contains_interval)) are related but distinct operations:
///
/// ```text
/// Point Containment:     x ∈ I     (scalar ∈ interval)
/// Interval Containment:  A ⊆ B     (interval ⊆ interval)
/// ```
///
/// ### Key Differences
///
/// | Aspect | Point Containment | Interval Containment |
/// |--------|-------------------|---------------------|
/// | **Input** | Single scalar value | Another interval |
/// | **Output** | `bool` | `bool` |
/// | **Complexity** | O(1) - at most 2 comparisons | O(1) - boundary logic |
/// | **Use Cases** | Point queries, evaluation domains | Set operations, subset testing |
/// | **Mathematical Basis** | Element membership `x ∈ I` | Subset relation `A ⊆ B` |
///
/// ### Mathematical Relationship
///
/// Interval containment can be expressed in terms of point containment:
/// ```text
/// A ⊆ B ⟺ ∀x ∈ A: x ∈ B
/// ```
/// However, for efficiency, interval containment is implemented by comparing boundaries
/// rather than testing all points.
///
/// ## Core Operation
///
/// ### [`contains_point`](Contains::contains_point)
/// Tests whether a specific point belongs to the interval.
///
/// **Signature**: `fn contains_point(&self, point: &RealType) -> bool`
///
/// **Behavior**:
/// - Returns `true` if the point is within the interval
/// - Returns `false` if the point is outside the interval
/// - Respects boundary inclusion/exclusion semantics
/// - Always O(1) complexity regardless of interval type
///
/// ## Usage Examples
///
/// ### Basic Point Containment
/// ```rust
/// use grid1d::intervals::*;
/// use num_valid::RealNative64StrictFiniteInDebug;
/// use try_create::{New, TryNew};
///
/// type Real = RealNative64StrictFiniteInDebug;
///
/// let closed = IntervalClosed::new(
///     Real::try_new(0.0).unwrap(),
///     Real::try_new(1.0).unwrap()
/// );
/// let open = IntervalOpen::new(
///     Real::try_new(0.0).unwrap(),
///     Real::try_new(1.0).unwrap()
/// );
/// let singleton = IntervalSingleton::new(Real::try_new(0.5).unwrap());
///
/// // Closed interval includes boundaries
/// assert!(closed.contains_point(&Real::try_new(0.0).unwrap()));   // Lower bound
/// assert!(closed.contains_point(&Real::try_new(0.5).unwrap()));   // Interior
/// assert!(closed.contains_point(&Real::try_new(1.0).unwrap()));   // Upper bound
///
/// // Open interval excludes boundaries
/// assert!(!open.contains_point(&Real::try_new(0.0).unwrap()));    // Lower bound excluded
/// assert!(open.contains_point(&Real::try_new(0.5).unwrap()));     // Interior
/// assert!(!open.contains_point(&Real::try_new(1.0).unwrap()));    // Upper bound excluded
///
/// // Singleton contains only exact match
/// assert!(singleton.contains_point(&Real::try_new(0.5).unwrap())); // Exact match
/// assert!(!singleton.contains_point(&Real::try_new(0.4).unwrap())); // Any other value
/// ```
///
/// ### Comparison with Interval Containment
/// ```rust
/// use grid1d::intervals::*;
/// use try_create::New;
///
/// let outer = IntervalClosed::new(0.0, 2.0);    // [0, 2]
/// let inner = IntervalClosed::new(0.5, 1.5);    // [0.5, 1.5]
/// let point_interval = IntervalSingleton::new(1.0); // {1}
///
/// // Point containment: test specific values
/// assert!(outer.contains_point(&1.0));          // Point 1.0 ∈ [0, 2] ✓
/// assert!(inner.contains_point(&1.0));          // Point 1.0 ∈ [0.5, 1.5] ✓
///
/// // Interval containment: test subset relationships
/// assert!(outer.contains_interval(&inner));      // [0, 2] ⊇ [0.5, 1.5] ✓
/// assert!(outer.contains_interval(&point_interval)); // [0, 2] ⊇ {1} ✓
/// assert!(inner.contains_interval(&point_interval)); // [0.5, 1.5] ⊇ {1} ✓
/// assert!(!inner.contains_interval(&outer));     // [0.5, 1.5] ⊉ [0, 2] ✗
/// ```
///
/// ### Generic Programming with Point Containment
/// ```rust
/// use grid1d::intervals::*;
/// use num_valid::RealScalar;
///
/// /// Count how many test points are contained in an interval
/// fn count_contained_points<I, T>(interval: &I, test_points: &[T]) -> usize
/// where
///     I: Contains<RealType = T>,
///     T: RealScalar,
/// {
///     test_points.iter()
///         .filter(|&point| interval.contains_point(point))
///         .count()
/// }
///
/// /// Filter points to only those contained in an interval
/// fn filter_points_in_interval<I, T>(interval: &I, points: Vec<T>) -> Vec<T>
/// where
///     I: Contains<RealType = T>,
///     T: RealScalar,
/// {
///     points.into_iter()
///         .filter(|point| interval.contains_point(point))
///         .collect()
/// }
///
/// let interval = IntervalClosed::new(-1.0, 1.0);
/// let test_points = vec![-2.0, -1.0, -0.5, 0.0, 0.5, 1.0, 2.0];
///
/// let count = count_contained_points(&interval, &test_points);
/// assert_eq!(count, 5); // -1.0, -0.5, 0.0, 0.5, 1.0
///
/// let filtered = filter_points_in_interval(&interval, test_points);
/// assert_eq!(filtered, vec![-1.0, -0.5, 0.0, 0.5, 1.0]);
/// ```
///
/// ## Performance Characteristics
///
/// ### Time Complexity
/// - **All interval types**: O(1) regardless of interval size or type
/// - **Bounded intervals**: At most 2 comparisons (lower ≤ x ≤ upper)
/// - **Semi-bounded intervals**: 1 comparison (x ≥ lower or x ≤ upper)
/// - **Unbounded intervals**: Constant time (always true)
/// - **Singletons**: 1 equality comparison (x == value)
///
/// ### Space Complexity
/// - **Memory usage**: O(1) - no additional allocation
/// - **Stack usage**: Minimal - simple comparison operations
/// - **Cache efficiency**: Excellent - operates on interval bounds directly
///
/// ### Scalar Type Performance Impact
/// ```rust
/// use grid1d::intervals::*;
/// use num_valid::{RealNative64StrictFiniteInDebug, RealNative64StrictFinite, RealScalar};
///
/// // All these have nearly identical performance for point containment:
/// type FastInterval = IntervalClosed<f64>;
/// type OptimalInterval = IntervalClosed<RealNative64StrictFiniteInDebug>;
/// type SafeInterval = IntervalClosed<RealNative64StrictFinite>;
///
/// fn benchmark_point_containment<T: RealScalar>(
///     interval: &IntervalClosed<T>,
///     test_point: &T
/// ) -> bool {
///     // This compiles to identical assembly for f64 and RealNative64StrictFiniteInDebug
///     // Slight overhead for RealNative64StrictFinite due to validation
///     interval.contains_point(test_point)
/// }
/// ```
///
/// ## Boundary Semantics and Edge Cases
///
/// ### Boundary Inclusion Rules
/// ```rust
/// use grid1d::intervals::*;
/// use num_valid::RealScalar;
///
/// // Demonstrate different boundary behaviors
/// let closed = IntervalClosed::new(0.0, 1.0);           // [0, 1]
/// let open = IntervalOpen::new(0.0, 1.0);               // (0, 1)
/// let left_open = IntervalLowerOpenUpperClosed::new(0.0, 1.0);  // (0, 1]
/// let right_open = IntervalLowerClosedUpperOpen::new(0.0, 1.0); // [0, 1)
///
/// let lower_bound = 0.0;
/// let upper_bound = 1.0;
/// let interior = 0.5;
///
/// // Lower boundary behavior
/// assert!(closed.contains_point(&lower_bound));      // [0,1] includes 0
/// assert!(!open.contains_point(&lower_bound));       // (0,1) excludes 0
/// assert!(!left_open.contains_point(&lower_bound));  // (0,1] excludes 0
/// assert!(right_open.contains_point(&lower_bound));  // [0,1) includes 0
///
/// // Upper boundary behavior
/// assert!(closed.contains_point(&upper_bound));      // [0,1] includes 1
/// assert!(!open.contains_point(&upper_bound));       // (0,1) excludes 1
/// assert!(left_open.contains_point(&upper_bound));   // (0,1] includes 1
/// assert!(!right_open.contains_point(&upper_bound)); // [0,1) excludes 1
///
/// // Interior points (always included for positive-length intervals)
/// assert!(closed.contains_point(&interior));
/// assert!(open.contains_point(&interior));
/// assert!(left_open.contains_point(&interior));
/// assert!(right_open.contains_point(&interior));
/// ```
///
/// ### Floating-Point Precision Considerations
/// ```rust
/// use grid1d::intervals::*;
///
/// let interval = IntervalClosed::new(0.0, 1.0);
///
/// // Exact boundary values
/// assert!(interval.contains_point(&0.0));
/// assert!(interval.contains_point(&1.0));
///
/// // Values very close to boundaries
/// assert!(interval.contains_point(&f64::EPSILON));           // Just above 0
/// assert!(interval.contains_point(&(1.0 - f64::EPSILON)));   // Just below 1
/// assert!(!interval.contains_point(&-f64::EPSILON));         // Just below 0
/// assert!(!interval.contains_point(&(1.0 + f64::EPSILON)));  // Just above 1
///
/// // For very small intervals, be aware of precision limits
/// let tiny = IntervalClosed::new(1.0, 1.0 + f64::EPSILON);
/// assert!(tiny.contains_point(&1.0));
/// assert!(tiny.contains_point(&(1.0 + f64::EPSILON)));
/// assert_eq!(tiny.length().into_inner(), f64::EPSILON);
/// ```
///
/// ## Implementation Requirements
///
/// Types implementing [`Contains`] must guarantee:
///
/// ### Mathematical Correctness
/// ```rust
/// use grid1d::intervals::*;
/// use num_valid::RealScalar;
///
/// // These properties must hold for all implementations:
/// fn verify_contains_properties<I, T>(interval: &I, point: &T)
/// where
///     I: Contains<RealType = T>,
///     T: RealScalar,
/// {
///     let result = interval.contains_point(point);
///     
///     // Consistency: repeated calls must give same result
///     assert_eq!(result, interval.contains_point(point));
///     
///     // The result should be deterministic for the same inputs
///     assert_eq!(result, interval.contains_point(&point.clone()));
/// }
/// ```
///
/// ### Performance Requirements
/// - **O(1) time complexity**: All implementations must be constant time
/// - **No allocation**: Point containment should not allocate memory
/// - **Minimal computation**: Use the most efficient boundary checks possible
///
/// ### Type Safety Requirements
/// - **Scalar type consistency**: Point type must match interval's scalar type
/// - **Reference semantics**: Accept points by reference to avoid unnecessary copies
/// - **Generic compatibility**: Work with any [`RealScalar`] implementation
///
/// ## Advanced Usage Patterns
///
/// ### Predicate Functions and Filtering
/// ```rust
/// use grid1d::intervals::*;
/// use num_valid::RealScalar;
///
/// /// Create a predicate function from an interval
/// fn interval_predicate<I, T>(interval: I) -> impl Fn(&T) -> bool
/// where
///     I: Contains<RealType = T>,
///     T: RealScalar,
/// {
///     move |point: &T| interval.contains_point(point)
/// }
///
/// /// Filter a dataset based on multiple interval constraints
/// fn filter_by_intervals<T>(
///     data: Vec<T>,
///     constraints: &[impl Contains<RealType = T>]
/// ) -> Vec<T>
/// where
///     T: RealScalar,
/// {
///     data.into_iter()
///         .filter(|point| {
///             constraints.iter().all(|interval| interval.contains_point(point))
///         })
///         .collect()
/// }
/// ```
///
/// ### Statistical Analysis
/// ```rust
/// use grid1d::intervals::*;
///
/// /// Compute statistics for points within an interval
/// fn interval_statistics<I>(
///     interval: &I,
///     data: &[f64]
/// ) -> Option<(f64, f64, usize)>
/// where
///     I: Contains<RealType = f64>,
/// {
///     let contained_points: Vec<f64> = data.iter()
///         .filter(|&x| interval.contains_point(x))
///         .cloned()
///         .collect();
///         
///     if contained_points.is_empty() {
///         return None;
///     }
///     
///     let count = contained_points.len();
///     let sum: f64 = contained_points.iter().sum();
///     let mean = sum / count as f64;
///     let variance = contained_points.iter()
///         .map(|x| (x - mean).powi(2))
///         .sum::<f64>() / count as f64;
///     
///     Some((mean, variance, count))
/// }
///
/// let interval = IntervalClosed::new(-1.0, 1.0);
/// let data = vec![-2.0, -0.5, 0.0, 0.5, 2.0];
///
/// if let Some((mean, variance, count)) = interval_statistics(&interval, &data) {
///     println!("Points in interval: count={}, mean={}, variance={}", count, mean, variance);
/// }
/// ```
///
/// ## Common Pitfalls and Best Practices
///
/// ### Avoiding Common Mistakes
/// ```rust
/// use grid1d::intervals::*;
///
/// // WRONG: Assuming all intervals include their "endpoints"
/// fn naive_endpoint_test<I>(interval: &I) -> bool
/// where
///     I: Contains<RealType = f64> + GetLowerBoundValue<LowerBoundValue = f64> + GetUpperBoundValue<UpperBoundValue = f64>,
/// {
///     let lower = *interval.lower_bound_value();
///     let upper = *interval.upper_bound_value();
///     
///     // This fails for open intervals!
///     interval.contains_point(&lower) && interval.contains_point(&upper)
/// }
///
/// // CORRECT: Test boundary inclusion explicitly
/// fn proper_boundary_test<I>(interval: &I) -> (bool, bool)
/// where
///     I: Contains<RealType = f64> + GetLowerBoundValue<LowerBoundValue = f64> + GetUpperBoundValue<UpperBoundValue = f64>,
/// {
///     let lower = *interval.lower_bound_value();
///     let upper = *interval.upper_bound_value();
///     
///     (interval.contains_point(&lower), interval.contains_point(&upper))
/// }
///
/// let closed = IntervalClosed::new(0.0, 1.0);
/// let open = IntervalOpen::new(0.0, 1.0);
///
/// assert!(naive_endpoint_test(&closed));     // Works for closed
/// assert!(!naive_endpoint_test(&open));      // Fails for open (correct behavior)
///
/// assert_eq!(proper_boundary_test(&closed), (true, true));   // Both included
/// assert_eq!(proper_boundary_test(&open), (false, false));   // Both excluded
/// ```
///
/// ### Performance Best Practices
/// ```rust
/// use grid1d::intervals::*;
///
/// // GOOD: Reuse intervals for multiple point tests
/// fn efficient_batch_testing(interval: &IntervalClosed<f64>, points: &[f64]) -> Vec<bool> {
///     points.iter()
///         .map(|point| interval.contains_point(point))
///         .collect()
/// }
///
/// // AVOID: Creating intervals repeatedly for the same bounds
/// fn inefficient_testing(lower: f64, upper: f64, points: &[f64]) -> Vec<bool> {
///     points.iter()
///         .map(|point| {
///             let interval = IntervalClosed::new(lower, upper); // Wasteful!
///             interval.contains_point(point)
///         })
///         .collect()
/// }
/// ```
///
/// ## Mathematical Properties and Guarantees
///
/// The [`Contains`] trait implementations maintain these essential properties:
///
/// ### Consistency Properties
/// - **Deterministic**: Same input always produces same output
/// - **Reflexive**: For any point in the interval, containment is stable
/// - **Boundary Correct**: Respects mathematical interval notation exactly
///
/// ### Performance Properties  
/// - **Constant Time**: O(1) for all interval types and point queries
/// - **Memory Efficient**: No allocation, minimal stack usage
/// - **Cache Friendly**: Operations on compact data structures
///
/// ### Type Safety Properties
/// - **Scalar Consistency**: Point and interval scalar types must match
/// - **Generic Correctness**: Works with any [`RealScalar`] implementation
/// - **Reference Safety**: Accepts points by reference safely
///
/// These guarantees are preserved across all interval types and scalar types,
/// ensuring that point containment testing is both mathematically correct and
/// computationally efficient throughout the library.
pub trait Contains: IntervalBoundsRuntime + Clone + PartialEq {
    /// Tests whether a point is contained within this interval.
    ///
    /// This is the fundamental operation that all interval types must implement.
    /// The behavior depends on the specific interval type and its boundary conditions.
    ///
    /// # Boundary Behavior
    ///
    /// - **Closed intervals** `[a, b]`: Include both endpoints
    /// - **Open intervals** `(a, b)`: Exclude both endpoints  
    /// - **Half-open intervals**: Include one endpoint, exclude the other
    /// - **Unbounded intervals**: Have infinite extent in one or both directions
    /// - **Singleton intervals**: Contain exactly one point
    ///
    /// # Examples
    ///
    /// ```rust
    /// use grid1d::intervals::*;
    /// use try_create::New;
    ///
    /// let closed = IntervalClosed::new(0.0, 1.0);
    /// assert!(closed.contains_point(&0.0));    // Endpoints included
    /// assert!(closed.contains_point(&1.0));    // Endpoints included
    /// assert!(closed.contains_point(&0.5));    // Interior point
    ///
    /// let open = IntervalOpen::new(0.0, 1.0);
    /// assert!(!open.contains_point(&0.0));     // Endpoints excluded
    /// assert!(!open.contains_point(&1.0));     // Endpoints excluded
    /// assert!(open.contains_point(&0.5));      // Interior point
    ///
    /// let half_open = IntervalLowerOpenUpperClosed::new(0.0, 1.0);
    /// assert!(!half_open.contains_point(&0.0)); // Lower bound excluded
    /// assert!(half_open.contains_point(&1.0));  // Upper bound included
    ///
    /// let singleton = IntervalSingleton::new(42.0);
    /// assert!(singleton.contains_point(&42.0));  // Exact match
    /// assert!(!singleton.contains_point(&41.0)); // No match
    /// ```
    ///
    /// # Performance
    ///
    /// This operation is O(1) for all interval types, involving at most two comparisons.
    fn contains_point(&self, x: &Self::RealType) -> bool;

    /// Tests whether a point is within `epsilon` distance of this interval.
    ///
    /// Returns `true` if the point `x` lies inside the interval expanded by `epsilon`
    /// on both sides, i.e. if `dist(x, I) ≤ epsilon`. Concretely:
    ///
    /// - If the interval has a finite lower bound `a`: requires `x ≥ a − epsilon`
    /// - If the interval has a finite upper bound `b`: requires `x ≤ b + epsilon`
    /// - Unbounded sides impose no constraint
    ///
    /// # Notes
    ///
    /// The open/closed nature of the boundary is **ignored**: the expansion strip is always
    /// treated as closed. In particular, for `epsilon = 0` this function may return `true`
    /// for boundary points of open intervals where `contains_point` would return `false`.
    /// This behaviour is intentional—the typical use case is numerical tolerance checking
    /// in finite-element or grid methods where boundary semantics are irrelevant.
    ///
    /// # Arguments
    ///
    /// - `x`: the point to test.
    /// - `epsilon`: non-negative tolerance; use
    ///   [`NonNegativeRealScalar::try_new(0.0)`](num_valid::scalars::NonNegativeRealScalar) for
    ///   exact containment with boundary relaxation.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use grid1d::intervals::*;
    /// use num_valid::scalars::NonNegativeRealScalar;
    /// use try_create::TryNew;
    ///
    /// let closed = IntervalClosed::new(0.0, 1.0);
    /// let eps = NonNegativeRealScalar::try_new(0.1).unwrap();
    ///
    /// // Interior point
    /// assert!(closed.contains_point_with_tolerance(&0.5, &eps));
    ///
    /// // Just outside — within tolerance
    /// assert!(closed.contains_point_with_tolerance(&-0.05, &eps));
    /// assert!(closed.contains_point_with_tolerance(&1.05, &eps));
    ///
    /// // Too far outside
    /// assert!(!closed.contains_point_with_tolerance(&-0.2, &eps));
    /// assert!(!closed.contains_point_with_tolerance(&1.2, &eps));
    ///
    /// // Open interval: boundary points are included when epsilon = 0
    /// let open = IntervalOpen::new(0.0, 1.0);
    /// let zero_eps = NonNegativeRealScalar::try_new(0.0).unwrap();
    /// assert!(open.contains_point_with_tolerance(&0.0, &zero_eps)); // differs from contains_point!
    /// ```
    ///
    /// # Performance
    ///
    /// This operation is O(1), involving at most two additions and two comparisons.
    #[inline(always)]
    fn contains_point_with_tolerance(
        &self,
        x: &Self::RealType,
        epsilon: &NonNegativeRealScalar<Self::RealType>,
    ) -> bool {
        let eps = epsilon.as_ref();

        // Check lower side: x >= lower_bound - epsilon  ⟺  x + epsilon >= lower_bound
        let lower_ok = match self.lower_bound_runtime() {
            None => true,
            Some(lower) => &(x.clone() + eps) >= lower.as_ref(),
        };

        if !lower_ok {
            return false;
        }

        // Check upper side: x <= upper_bound + epsilon  ⟺  x - epsilon <= upper_bound
        match self.upper_bound_runtime() {
            None => true,
            Some(upper) => x <= &(upper.as_ref().clone() + eps),
        }
    }

    /// Tests whether this interval completely contains another interval.
    ///
    /// Returns `true` if and only if every point in `other` is also contained in `self`.
    /// This includes proper handling of boundary conditions - for example, the closed
    /// interval `[0., 1.]` contains the open interval `(0., 1.)`, but not vice versa.
    ///
    /// # Mathematical Definition
    ///
    /// For intervals A and B, A contains B (A ⊇ B) if and only if:
    /// - The lower bound of A is ≤ the lower bound of B (with proper boundary handling)
    /// - The upper bound of A is ≥ the upper bound of B (with proper boundary handling)
    ///
    /// # Boundary Rules
    ///
    /// - Closed bounds can contain open bounds at the same value
    /// - Open bounds cannot contain closed bounds at the same value
    /// - Unbounded sides always contain any bounded side
    ///
    /// # Examples
    ///
    /// ```rust
    /// use grid1d::intervals::*;
    ///
    /// let outer = IntervalClosed::new(0.0, 2.0);       // [0, 2]
    /// let inner = IntervalOpen::new(0.5, 1.5);         // (0.5, 1.5)
    /// let boundary = IntervalClosed::new(0.0, 1.0);    // [0, 1]
    /// let open_boundary = IntervalOpen::new(0.0, 1.0); // (0, 1)
    ///
    /// assert!(outer.contains_interval(&inner));      // [0, 2] ⊇ (0.5, 1.5) ✓
    /// assert!(outer.contains_interval(&boundary));   // [0, 2] ⊇ [0, 1] ✓
    /// assert!(boundary.contains_interval(&open_boundary)); // [0, 1] ⊇ (0, 1) ✓
    /// assert!(!open_boundary.contains_interval(&boundary)); // (0, 1) ⊉ [0, 1] ✗
    /// ```
    ///
    /// # Performance
    ///
    /// This operation is O(1) and involves only bound comparisons.
    fn contains_interval<IntervalType: IntervalTrait<RealType = Self::RealType>>(
        &self,
        other: &IntervalType,
    ) -> bool {
        let lower_bound_b_is_contained =
            match (self.lower_bound_runtime(), other.lower_bound_runtime()) {
                // If the lower bound of `self` is unbounded, it will contain any other lower bound
                (None, _) => true,

                // If the lower bound of `self` is not unbounded while the lower bound of `other` is unbounded, `self` cannot contain `other`
                (_, None) => false,

                (Some(lower_bound_a), Some(lower_bound_b)) => lower_bound_a <= lower_bound_b,
            };

        let upper_bound_b_is_contained =
            match (self.upper_bound_runtime(), other.upper_bound_runtime()) {
                // If the upper bound of `self` is unbounded, it will contain any other upper bound
                (None, _) => true,

                // If the upper bound of `self` is not unbounded while the upper bound of `other` is unbounded, `self` cannot contain `other`
                (_, None) => false,

                (Some(upper_bound_a), Some(upper_bound_b)) => upper_bound_b <= upper_bound_a,
            };

        lower_bound_b_is_contained && upper_bound_b_is_contained
    }
}
//------------------------------------------------------------------------------------------------

//------------------------------------------------------------------------------------------------
/// Common interface for intervals that have a finite lower bound.
///
/// The [`GetLowerBoundValue`] trait provides unified access to the lower bound of intervals
/// that have a finite lower boundary. This enables generic programming over intervals
/// with lower bounds while maintaining type safety and performance.
///
/// ## Implementing Types
///
/// All interval types with finite lower bounds implement this trait:
///
/// ### Bounded Intervals
/// - [`IntervalClosed`](crate::intervals::IntervalClosed): `[a, b]`, [`IntervalOpen`](crate::intervals::IntervalOpen): `(a, b)`
/// - [`IntervalLowerOpenUpperClosed`](crate::intervals::IntervalLowerOpenUpperClosed): `(a, b]`, [`IntervalLowerClosedUpperOpen`](crate::intervals::IntervalLowerClosedUpperOpen): `[a, b)`
///
/// ### Lower-Bounded, Upper-Unbounded Intervals
/// - [`IntervalLowerClosedUpperUnbounded`](crate::intervals::IntervalLowerClosedUpperUnbounded): `[a, +∞)`
/// - [`IntervalLowerOpenUpperUnbounded`](crate::intervals::IntervalLowerOpenUpperUnbounded): `(a, +∞)`
///
/// ## Core Operation
///
/// - [`lower_bound_value`](GetLowerBoundValue::lower_bound_value): Returns a reference to the lower bound value
///
/// This method provides **read-only access** with **zero computational cost**.
///
/// ## Usage Examples
///
/// ### Basic Lower Bound Access
/// ```rust
/// use grid1d::intervals::*;
/// use num_valid::RealNative64StrictFiniteInDebug;
/// use try_create::TryNew;
///
/// type Real = RealNative64StrictFiniteInDebug;
///
/// let closed = IntervalClosed::new(
///     Real::try_new(-2.0).unwrap(),
///     Real::try_new(5.0).unwrap()
/// );
/// let unbounded = IntervalLowerClosedUpperUnbounded::new(
///     Real::try_new(0.0).unwrap()
/// );
///
/// assert_eq!(closed.lower_bound_value(), &-2.0);
/// assert_eq!(unbounded.lower_bound_value(), &0.0);
/// ```
///
/// ### Generic Programming Over Lower-Bounded Intervals
/// ```rust
/// use grid1d::intervals::*;
/// use num_valid::RealScalar;
///
/// fn analyze_lower_bound<I, T>(interval: &I) -> String
/// where
///     I: GetLowerBoundValue<LowerBoundValue = T>,
///     T: RealScalar + std::fmt::Display,
/// {
///     format!("Lower bound: {}", interval.lower_bound_value())
/// }
///
/// let closed = IntervalClosed::new(-1.0, 1.0);
/// let unbounded = IntervalLowerOpenUpperUnbounded::new(5.0);
///
/// println!("{}", analyze_lower_bound(&closed));      // "Lower bound: -1"
/// println!("{}", analyze_lower_bound(&unbounded));   // "Lower bound: 5"
/// ```
///
/// ### Constraint Processing
/// ```rust
/// use grid1d::intervals::*;
/// use num_valid::RealScalar;
///
/// fn find_minimum_lower_bound<I, T>(intervals: &[I]) -> Option<T>
/// where
///     I: GetLowerBoundValue<LowerBoundValue = T>,
///     T: RealScalar + Clone + PartialOrd,
/// {
///     intervals.iter()
///         .map(|interval| interval.lower_bound_value())
///         .min_by(|a, b| a.partial_cmp(b).unwrap())
///         .cloned()
/// }
///
/// let intervals = vec![
///     IntervalClosed::new(1.0, 5.0),
///     IntervalClosed::new(-2.0, 3.0),
///     IntervalClosed::new(0.0, 4.0),
/// ];
///
/// let min_lower = find_minimum_lower_bound(&intervals).unwrap();
/// assert_eq!(min_lower, -2.0);
/// ```
pub trait GetLowerBoundValue: Debug {
    /// The scalar type used for the lower bound value.
    type LowerBoundValue: RealScalar;

    /// Return the lower bound of the interval.
    ///
    /// This method provides read-only access to the interval's lower bound value.
    /// The returned reference is guaranteed to be valid for the lifetime of the interval.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use grid1d::intervals::*;
    ///
    /// let interval = IntervalClosed::new(1.0, 3.0);
    /// assert_eq!(interval.lower_bound_value(), &1.0);
    ///
    /// let lower_closed_interval = IntervalLowerClosedUpperUnbounded::new(5.0);
    /// let lower_open_interval = IntervalLowerOpenUpperUnbounded::new(10.0);
    ///
    /// assert_eq!(lower_closed_interval.lower_bound_value(), &5.0);
    /// assert_eq!(lower_open_interval.lower_bound_value(), &10.0);
    ///
    /// // Both intervals extend infinitely to the right
    /// assert!(lower_closed_interval.contains_point(&1000.0));
    /// assert!(lower_open_interval.contains_point(&1000.0));
    ///
    /// // But they differ in their treatment of the lower bound
    /// assert!(lower_closed_interval.contains_point(&5.0));   // [5, +∞) includes 5
    /// assert!(!lower_open_interval.contains_point(&10.0));   // (10, +∞) excludes 10
    /// ```
    ///
    /// # Performance
    ///
    /// This operation is O(1) and typically compiles to a simple memory access.
    /// There is no computational overhead regardless of the scalar type used.
    fn lower_bound_value(&self) -> &Self::LowerBoundValue;

    /// Check if the lower bound is closed (included in the interval).
    ///
    /// This method returns `true` if the lower bound value is part of the interval,
    /// and `false` if it is excluded. This corresponds to the mathematical distinction
    /// between closed bounds `[a` and open bounds `(a`.
    ///
    /// ## Mathematical Interpretation
    ///
    /// - **Closed lower bound** (`true`): The interval includes its lower bound value
    ///   - Mathematical notation: `[a, ...` where `x ≥ a`
    ///   - The boundary point `a` is contained in the interval
    ///
    /// - **Open lower bound** (`false`): The interval excludes its lower bound value
    ///   - Mathematical notation: `(a, ...` where `x > a`
    ///   - The boundary point `a` is not contained in the interval
    ///
    /// ## Examples
    ///
    /// ```rust
    /// use grid1d::intervals::*;
    /// use num_valid::RealNative64StrictFiniteInDebug;
    /// use try_create::TryNew;
    ///
    /// type Real = RealNative64StrictFiniteInDebug;
    ///
    /// let closed = IntervalClosed::new(
    ///     Real::try_new(0.0).unwrap(),
    ///     Real::try_new(1.0).unwrap()
    /// );
    /// assert!(closed.is_lower_bound_closed());      // [0, 1] has closed lower bound
    ///
    /// let open = IntervalOpen::new(
    ///     Real::try_new(0.0).unwrap(),
    ///     Real::try_new(1.0).unwrap()
    /// );
    /// assert!(!open.is_lower_bound_closed());       // (0, 1) has open lower bound
    ///
    /// let half_open = IntervalLowerClosedUpperOpen::new(
    ///     Real::try_new(0.0).unwrap(),
    ///     Real::try_new(1.0).unwrap()
    /// );
    /// assert!(half_open.is_lower_bound_closed());   // [0, 1) has closed lower bound
    ///
    /// let other_half = IntervalLowerOpenUpperClosed::new(
    ///     Real::try_new(0.0).unwrap(),
    ///     Real::try_new(1.0).unwrap()
    /// );
    /// assert!(!other_half.is_lower_bound_closed()); // (0, 1] has open lower bound
    /// ```
    ///
    /// ## Relationship with Point Containment
    ///
    /// The lower bound closure directly affects point containment at the boundary:
    ///
    /// ```rust
    /// use grid1d::intervals::*;
    ///
    /// let closed = IntervalClosed::new(0.0, 1.0);
    /// let open = IntervalOpen::new(0.0, 1.0);
    ///
    /// // Closed lower bound contains the boundary value
    /// assert!(closed.is_lower_bound_closed());
    /// assert!(closed.contains_point(&0.0));        // Lower bound included
    ///
    /// // Open lower bound excludes the boundary value
    /// assert!(!open.is_lower_bound_closed());
    /// assert!(!open.contains_point(&0.0));         // Lower bound excluded
    /// ```
    ///
    /// ## Generic Programming Applications
    ///
    /// ```rust
    /// use grid1d::intervals::*;
    /// use num_valid::RealScalar;
    ///
    /// fn analyze_lower_boundary<I, T>(interval: &I) -> String
    /// where
    ///     I: GetLowerBoundValue<LowerBoundValue = T>,
    ///     T: RealScalar + std::fmt::Display,
    /// {
    ///     let bound_value = interval.lower_bound_value();
    ///     let inclusion = if interval.is_lower_bound_closed() {
    ///         "included"
    ///     } else {
    ///         "excluded"
    ///     };
    ///     
    ///     format!("Lower bound {} is {}", bound_value, inclusion)
    /// }
    ///
    /// let closed = IntervalClosed::new(-1.0, 1.0);
    /// let open = IntervalLowerOpenUpperClosed::new(-1.0, 1.0);
    ///
    /// assert_eq!(analyze_lower_boundary(&closed), "Lower bound -1 is included");
    /// assert_eq!(analyze_lower_boundary(&open), "Lower bound -1 is excluded");
    /// ```
    ///
    /// ## Performance
    ///
    /// This operation is O(1) and typically compiles to a simple constant or type-based
    /// determination. There is no computational overhead regardless of the scalar type used.
    fn is_lower_bound_closed(&self) -> bool;

    /// Check if the lower bound is open (excluded from the interval).
    ///
    /// This method returns `true` if the lower bound value is excluded from the interval,
    /// and `false` if it is included. This is the logical complement of [`is_lower_bound_closed()`](GetLowerBoundValue::is_lower_bound_closed).
    ///
    /// ## Mathematical Interpretation
    ///
    /// - **Open lower bound** (`true`): The interval excludes its lower bound value
    ///   - Mathematical notation: `(a, ...` where `x > a`
    ///   - The boundary point `a` is not contained in the interval
    ///
    /// - **Closed lower bound** (`false`): The interval includes its lower bound value
    ///   - Mathematical notation: `[a, ...` where `x ≥ a`
    ///   - The boundary point `a` is contained in the interval
    ///
    /// ## Relationship with `is_lower_bound_closed()`
    ///
    /// This method is defined as the logical complement of [`is_lower_bound_closed()`](GetLowerBoundValue::is_lower_bound_closed):
    /// ```text
    /// is_lower_bound_open() == !is_lower_bound_closed()
    /// ```
    ///
    /// ## Examples
    ///
    /// ```rust
    /// use grid1d::intervals::*;
    /// use num_valid::RealNative64StrictFiniteInDebug;
    /// use try_create::TryNew;
    ///
    /// type Real = RealNative64StrictFiniteInDebug;
    ///
    /// let open = IntervalOpen::new(
    ///     Real::try_new(0.0).unwrap(),
    ///     Real::try_new(1.0).unwrap()
    /// );
    /// assert!(open.is_lower_bound_open());          // (0, 1) has open lower bound
    /// assert!(!open.is_lower_bound_closed());       // Complement relationship
    ///
    /// let closed = IntervalClosed::new(
    ///     Real::try_new(0.0).unwrap(),
    ///     Real::try_new(1.0).unwrap()
    /// );
    /// assert!(!closed.is_lower_bound_open());       // [0, 1] has closed lower bound
    /// assert!(closed.is_lower_bound_closed());      // Complement relationship
    ///
    /// let half_open = IntervalLowerOpenUpperClosed::new(
    ///     Real::try_new(0.0).unwrap(),
    ///     Real::try_new(1.0).unwrap()
    /// );
    /// assert!(half_open.is_lower_bound_open());     // (0, 1] has open lower bound
    /// assert!(!half_open.is_lower_bound_closed());  // Complement relationship
    /// ```
    ///
    /// ## Usage in Boundary Analysis
    ///
    /// ```rust
    /// use grid1d::intervals::*;
    /// use num_valid::RealScalar;
    ///
    /// fn check_boundary_types<I, T>(interval: &I) -> (bool, bool)
    /// where
    ///     I: GetLowerBoundValue<LowerBoundValue = T>,
    ///     T: RealScalar,
    /// {
    ///     let lower_open = interval.is_lower_bound_open();
    ///     let lower_closed = interval.is_lower_bound_closed();
    ///     
    ///     // These should always be complements
    ///     assert_eq!(lower_open, !lower_closed);
    ///     
    ///     (lower_open, lower_closed)
    /// }
    ///
    /// let open_interval = IntervalOpen::new(0.0, 1.0);
    /// let (is_open, is_closed) = check_boundary_types(&open_interval);
    /// assert!(is_open && !is_closed);
    ///
    /// let closed_interval = IntervalClosed::new(0.0, 1.0);
    /// let (is_open, is_closed) = check_boundary_types(&closed_interval);
    /// assert!(!is_open && is_closed);
    /// ```
    ///
    /// ## Strict Inequality Testing
    ///
    /// ```rust
    /// use grid1d::intervals::*;
    /// use num_valid::RealScalar;
    ///
    /// fn requires_strict_lower_bound<I, T>(interval: &I) -> bool
    /// where
    ///     I: GetLowerBoundValue<LowerBoundValue = T>,
    ///     T: RealScalar,
    /// {
    ///     // Check if the interval enforces x > lower_bound (strict inequality)
    ///     interval.is_lower_bound_open()
    /// }
    ///
    /// let strict_interval = IntervalOpen::new(0.0, 1.0);           // (0, 1) requires x > 0
    /// let inclusive_interval = IntervalClosed::new(0.0, 1.0);      // [0, 1] allows x ≥ 0
    ///
    /// assert!(requires_strict_lower_bound(&strict_interval));      // true: x > 0 required
    /// assert!(!requires_strict_lower_bound(&inclusive_interval));  // false: x ≥ 0 allowed
    /// ```
    ///
    /// ## Performance
    ///
    /// This operation is O(1) and typically compiles to a simple constant or type-based
    /// determination. Since it's implemented as the logical complement of
    /// [`is_lower_bound_closed()`](GetLowerBoundValue::is_lower_bound_closed), it has identical performance characteristics.
    #[inline(always)]
    fn is_lower_bound_open(&self) -> bool {
        !self.is_lower_bound_closed()
    }
}

/// Common interface for intervals that have a finite upper bound.
///
/// The [`GetUpperBoundValue`] trait provides unified access to the upper bound of intervals
/// that have a finite upper boundary. This enables generic programming over intervals
/// with upper bounds while maintaining type safety and performance.
///
/// ## Implementing Types
///
/// All interval types with finite upper bounds implement this trait:
///
/// ### Bounded Intervals
/// - [`IntervalClosed`](crate::intervals::IntervalClosed): `[a, b]`, [`IntervalOpen`](crate::intervals::IntervalOpen): `(a, b)`
/// - [`IntervalLowerOpenUpperClosed`](crate::intervals::IntervalLowerOpenUpperClosed): `(a, b]`, [`IntervalLowerClosedUpperOpen`](crate::intervals::IntervalLowerClosedUpperOpen): `[a, b)`
///
/// ### Upper-Bounded, Lower-Unbounded Intervals
/// - [`IntervalLowerUnboundedUpperClosed`](crate::intervals::IntervalLowerUnboundedUpperClosed): `(-∞, b]`
/// - [`IntervalLowerUnboundedUpperOpen`](crate::intervals::IntervalLowerUnboundedUpperOpen): `(-∞, b)`
///
/// ## Core Operation
///
/// - [`upper_bound_value`](GetUpperBoundValue::upper_bound_value): Returns a reference to the upper bound value
///
/// This method provides **read-only access** with **zero computational cost**.
///
/// ## Usage Examples
///
/// ### Basic Upper Bound Access
/// ```rust
/// use grid1d::intervals::*;
/// use num_valid::RealNative64StrictFiniteInDebug;
/// use try_create::TryNew;
///
/// type Real = RealNative64StrictFiniteInDebug;
///
/// let closed = IntervalClosed::new(
///     Real::try_new(-2.0).unwrap(),
///     Real::try_new(5.0).unwrap()
/// );
/// let unbounded = IntervalLowerUnboundedUpperClosed::new(
///     Real::try_new(10.0).unwrap()
/// );
///
/// assert_eq!(closed.upper_bound_value(), &5.0);
/// assert_eq!(unbounded.upper_bound_value(), &10.0);
/// ```
///
/// ### Generic Programming Over Upper-Bounded Intervals
/// ```rust
/// use grid1d::intervals::*;
/// use num_valid::RealScalar;
///
/// fn analyze_upper_bound<I, T>(interval: &I) -> String
/// where
///     I: GetUpperBoundValue<UpperBoundValue = T>,
///     T: RealScalar + std::fmt::Display,
/// {
///     format!("Upper bound: {}", interval.upper_bound_value())
/// }
///
/// let closed = IntervalClosed::new(-1.0, 1.0);
/// let unbounded = IntervalLowerUnboundedUpperClosed::new(5.0);
///
/// println!("{}", analyze_upper_bound(&closed));      // "Upper bound: 1"
/// println!("{}", analyze_upper_bound(&unbounded));   // "Upper bound: 5"
/// ```
pub trait GetUpperBoundValue: Debug {
    /// The scalar type used for the upper bound value.
    ///
    /// This type must satisfy the [`RealScalar`] trait, ensuring it represents
    /// a valid real number suitable for interval arithmetic.
    type UpperBoundValue: RealScalar;

    /// Return the upper bound of the interval.
    ///
    /// This method provides read-only access to the interval's upper bound value.
    /// The returned reference is guaranteed to be valid for the lifetime of the interval.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use grid1d::intervals::*;
    ///
    /// let interval = IntervalClosed::new(1.0, 3.0);
    /// assert_eq!(interval.upper_bound_value(), &3.0);
    ///
    /// let upper_closed_interval = IntervalLowerUnboundedUpperClosed::new(15.0);
    /// let upper_open_interval = IntervalLowerUnboundedUpperOpen::new(20.0);
    /// assert_eq!(upper_closed_interval.upper_bound_value(), &15.0);
    /// assert_eq!(upper_open_interval.upper_bound_value(), &20.0);
    ///
    /// // Both intervals extend infinitely to the left
    /// assert!(upper_closed_interval.contains_point(&-1000.0));
    /// assert!(upper_open_interval.contains_point(&-1000.0));
    ///
    /// // But they differ in their treatment of the upper bound
    /// assert!(upper_closed_interval.contains_point(&15.0));   // (-∞, 15] includes 15
    /// assert!(!upper_open_interval.contains_point(&20.0));    // (-∞, 20) excludes 20
    /// ```
    ///
    /// # Performance
    ///
    /// This operation is O(1) and typically compiles to a simple memory access.
    /// There is no computational overhead regardless of the scalar type used.
    fn upper_bound_value(&self) -> &Self::UpperBoundValue;

    /// Check if the upper bound of the interval is closed (inclusive).
    ///
    /// Returns `true` if the upper boundary point is included in the interval,
    /// `false` if it is excluded. This determines whether the interval uses
    /// a `≤` (closed) or `<` (open) relation at the upper endpoint.
    ///
    /// # Boundary Semantics
    ///
    /// The upper bound closure affects:
    /// - **Point containment**: Whether `upper_bound_value` is in the interval
    /// - **Mathematical notation**: Closed uses `]`, open uses `)`
    /// - **Interval arithmetic**: Affects intersection and union operations
    ///
    /// ## Interval Type Behavior
    ///
    /// | Interval Type                    | Notation    | Returns |
    /// |----------------------------------|-------------|---------|
    /// | `IntervalClosed`                 | `[a, b]`    | `true`  |
    /// | `IntervalOpen`                   | `(a, b)`    | `false` |
    /// | `IntervalLowerClosedUpperOpen`   | `[a, b)`    | `false` |
    /// | `IntervalLowerOpenUpperClosed`   | `(a, b]`    | `true`  |
    /// | `IntervalLowerUnboundedUpperClosed` | `(-∞, b]` | `true`  |
    /// | `IntervalLowerUnboundedUpperOpen`   | `(-∞, b)` | `false` |
    /// | `IntervalSingleton`              | `{a}`       | `true`  |
    ///
    /// # Examples
    ///
    /// ```rust
    /// use grid1d::intervals::*;
    ///
    /// // Closed upper bound - includes the endpoint
    /// let closed = IntervalClosed::new(0.0, 10.0);
    /// assert!(closed.is_upper_bound_closed());
    /// assert!(closed.contains_point(&10.0));  // 10 is in [0, 10]
    ///
    /// // Open upper bound - excludes the endpoint
    /// let half_open = IntervalLowerClosedUpperOpen::new(0.0, 10.0);
    /// assert!(!half_open.is_upper_bound_closed());
    /// assert!(!half_open.contains_point(&10.0));  // 10 is not in [0, 10)
    ///
    /// // Unbounded intervals
    /// let upper_closed = IntervalLowerUnboundedUpperClosed::new(5.0);
    /// assert!(upper_closed.is_upper_bound_closed());  // (-∞, 5] includes 5
    /// assert!(upper_closed.contains_point(&5.0));
    ///
    /// let upper_open = IntervalLowerUnboundedUpperOpen::new(5.0);
    /// assert!(!upper_open.is_upper_bound_closed());   // (-∞, 5) excludes 5
    /// assert!(!upper_open.contains_point(&5.0));
    /// ```
    ///
    /// # Generic Programming
    ///
    /// ```rust
    /// use grid1d::intervals::*;
    /// use num_valid::RealScalar;
    ///
    /// fn check_endpoint_inclusion<I>(interval: &I, point: &I::RealType) -> bool
    /// where
    ///     I: GetUpperBoundValue + IntervalTrait,
    ///     I::UpperBoundValue: PartialEq<I::RealType>,
    /// {
    ///     if interval.upper_bound_value() == point {
    ///         interval.is_upper_bound_closed()
    ///     } else {
    ///         interval.contains_point(point)
    ///     }
    /// }
    ///
    /// let closed = IntervalClosed::new(0.0, 10.0);
    /// let open = IntervalOpen::new(0.0, 10.0);
    ///
    /// assert!(check_endpoint_inclusion(&closed, &10.0));   // Closed includes endpoint
    /// assert!(!check_endpoint_inclusion(&open, &10.0));    // Open excludes endpoint
    /// ```
    ///
    /// # See Also
    ///
    /// - [`is_upper_bound_open`](GetUpperBoundValue::is_upper_bound_open) - Logical complement
    /// - [`is_lower_bound_closed`](GetLowerBoundValue::is_lower_bound_closed) - Lower bound closure
    /// - [`upper_bound_value`](GetUpperBoundValue::upper_bound_value) - Get the upper bound value
    fn is_upper_bound_closed(&self) -> bool;

    /// Check if the upper bound of the interval is open (exclusive).
    ///
    /// Returns `true` if the upper boundary point is excluded from the interval,
    /// `false` if it is included. This is the logical complement of
    /// [`is_upper_bound_closed`](GetUpperBoundValue::is_upper_bound_closed).
    ///
    /// # Boundary Semantics
    ///
    /// An open upper bound means:
    /// - The interval uses a strict `<` inequality at the upper endpoint
    /// - The upper bound value itself is **not** contained in the interval
    /// - Mathematical notation uses `)` instead of `]`
    /// - The interval extends arbitrarily close to, but never reaches, the upper bound
    ///
    /// ## Interval Type Behavior
    ///
    /// | Interval Type                    | Notation    | Returns |
    /// |----------------------------------|-------------|---------|
    /// | `IntervalClosed`                 | `[a, b]`    | `false` |
    /// | `IntervalOpen`                   | `(a, b)`    | `true`  |
    /// | `IntervalLowerClosedUpperOpen`   | `[a, b)`    | `true`  |
    /// | `IntervalLowerOpenUpperClosed`   | `(a, b]`    | `false` |
    /// | `IntervalLowerUnboundedUpperClosed` | `(-∞, b]` | `false` |
    /// | `IntervalLowerUnboundedUpperOpen`   | `(-∞, b)` | `true`  |
    /// | `IntervalSingleton`              | `{a}`       | `false` |
    ///
    /// # Examples
    ///
    /// ```rust
    /// use grid1d::intervals::*;
    ///
    /// // Half-open interval [0, 10) - open upper bound
    /// let half_open = IntervalLowerClosedUpperOpen::new(0.0, 10.0);
    /// assert!(half_open.is_upper_bound_open());
    /// assert!(!half_open.contains_point(&10.0));  // 10 excluded
    /// assert!(half_open.contains_point(&9.999));  // Points arbitrarily close included
    ///
    /// // Fully open interval (0, 10) - open upper bound
    /// let open = IntervalOpen::new(0.0, 10.0);
    /// assert!(open.is_upper_bound_open());
    /// assert!(!open.contains_point(&10.0));
    ///
    /// // Closed interval [0, 10] - NOT open upper bound
    /// let closed = IntervalClosed::new(0.0, 10.0);
    /// assert!(!closed.is_upper_bound_open());
    /// assert!(closed.contains_point(&10.0));  // 10 included
    ///
    /// // Unbounded open interval (-∞, 5)
    /// let unbounded = IntervalLowerUnboundedUpperOpen::new(5.0);
    /// assert!(unbounded.is_upper_bound_open());
    /// assert!(!unbounded.contains_point(&5.0));
    /// ```
    ///
    /// # Complement Relationship
    ///
    /// This method is the logical complement of `is_upper_bound_closed()`:
    ///
    /// ```rust
    /// use grid1d::intervals::*;
    ///
    /// // Test complement relationship for each interval type
    /// let closed = IntervalClosed::new(0.0, 1.0);
    /// assert_eq!(closed.is_upper_bound_open(), !closed.is_upper_bound_closed());
    ///
    /// let open = IntervalOpen::new(0.0, 1.0);
    /// assert_eq!(open.is_upper_bound_open(), !open.is_upper_bound_closed());
    ///
    /// let half_open1 = IntervalLowerClosedUpperOpen::new(0.0, 1.0);
    /// assert_eq!(half_open1.is_upper_bound_open(), !half_open1.is_upper_bound_closed());
    ///
    /// let half_open2 = IntervalLowerOpenUpperClosed::new(0.0, 1.0);
    /// assert_eq!(half_open2.is_upper_bound_open(), !half_open2.is_upper_bound_closed());
    /// ```
    ///
    /// # Implementation Note
    ///
    /// This method has a default implementation as `!self.is_upper_bound_closed()`.
    /// Types implementing [`GetUpperBoundValue`] only need to implement
    /// `is_upper_bound_closed()`, and this method is automatically derived.
    ///
    /// # See Also
    ///
    /// - [`is_upper_bound_closed`](GetUpperBoundValue::is_upper_bound_closed) - Logical complement
    /// - [`is_lower_bound_open`](GetLowerBoundValue::is_lower_bound_open) - Lower bound openness
    /// - [`upper_bound_value`](GetUpperBoundValue::upper_bound_value) - Get the upper bound value
    #[inline(always)]
    fn is_upper_bound_open(&self) -> bool {
        !self.is_upper_bound_closed()
    }
}
//------------------------------------------------------------------------------------------------