grid1d 0.5.2

#![deny(rustdoc::broken_intra_doc_links)]

//! Zero-sized marker types that encode boundary semantics at the type level.
//!
//! This module provides the foundational marker types used throughout the bounds system
//! to distinguish boundary *side* (lower vs upper) and boundary *type* (open vs closed)
//! purely at compile time, with no runtime cost.
//!
//! ## Marker Types
//!
//! ### Boundary Side ([`BoundSide`])
//!
//! | Type | Meaning | Example |
//! |------|---------|--------|
//! | [`Lower`] | Left/minimum boundary | `[a` or `(a` |
//! | [`Upper`] | Right/maximum boundary | `b]` or `b)` |
//!
//! ### Boundary Type ([`BoundType`])
//!
//! | Type | Inclusion | Example |
//! |------|-----------|--------|
//! | [`Closed`] | Includes boundary value | `[a` or `b]` |
//! | [`Open`] | Excludes boundary value | `(a` or `b)` |
//!
//! ## Usage
//!
//! These types are used as phantom type parameters in [`IntervalBound<T, Side, Type>`](crate::bounds::IntervalBound)
//! and in the marker traits [`BoundSide`] and [`BoundType`].
//! End users typically interact with the ready-made type aliases
//! ([`LowerBoundClosed`](crate::bounds::LowerBoundClosed), [`UpperBoundOpen`](crate::bounds::UpperBoundOpen), etc.)
//! rather than with these markers directly.
//!
//! ```rust
//! use grid1d::bounds::{Lower, Upper, Open, Closed};
//! use grid1d::bounds::traits::{BoundSide, BoundType};
//!
//! assert!(Lower::is_lower());
//! assert!(Upper::is_upper());
//! assert!(Open::is_open());
//! assert!(Closed::is_closed());
//! ```

use crate::bounds::traits::{BoundSide, BoundType};
use serde::{Deserialize, Serialize};
use std::fmt::Debug;

//------------------------------------------------------------------------------------------------
/// Marker type for upper bounds
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Upper;

/// Marker type for lower bounds
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Lower;

impl BoundSide for Upper {
    type Opposite = Lower;

    #[inline(always)]
    fn is_upper() -> bool {
        true
    }
}

impl BoundSide for Lower {
    type Opposite = Upper;

    #[inline(always)]
    fn is_upper() -> bool {
        false
    }
}
//------------------------------------------------------------------------------------------------

//------------------------------------------------------------------------------------------------
/// Marker type for open bounds that exclude their boundary values.
///
/// [`Open`] is a zero-sized type that implements [`BoundType`] to represent boundary
/// semantics where the boundary value is **excluded** from the constraint. This type
/// enables compile-time verification of open boundary semantics in interval arithmetic.
///
/// ## Mathematical Semantics
///
/// Open bounds exclude their boundary values from constraints:
///
/// | Bound Type | Mathematical Constraint | Notation | Boundary Value |
/// |------------|------------------------|----------|----------------|
/// | `LowerBound<T, Open>` | `x > bound_value` | `(a` | **Excluded** |
/// | `UpperBound<T, Open>` | `x < bound_value` | `b)` | **Excluded** |
///
/// ## Usage Examples
///
/// ### Basic Open Bound Construction
///
/// ```rust
/// use grid1d::bounds::*;
/// use try_create::New;
///
/// // Lower open bound: x > 5
/// let lower_open: LowerBoundOpen<f64> = LowerBound::new(5.0);
/// assert!(lower_open.is_open());
/// assert!(!lower_open.includes_boundary());
///
/// // Upper open bound: x < 10
/// let upper_open: UpperBoundOpen<f64> = UpperBound::new(10.0);
/// assert!(upper_open.is_open());
/// assert!(!upper_open.includes_boundary());
/// ```
///
/// ### Constraint Testing
///
/// ```rust
/// use grid1d::bounds::*;
/// use try_create::New;
///
/// let open_lower = LowerBoundOpen::new(5.0);  // x > 5
/// let open_upper = UpperBoundOpen::new(10.0); // x < 10
///
/// // Boundary values are excluded
/// assert!(!open_lower.value_within_bound(&5.0));   // 5 > 5 → false
/// assert!(!open_upper.value_within_bound(&10.0));  // 10 < 10 → false
///
/// // Interior values are included
/// assert!(open_lower.value_within_bound(&5.1));    // 5.1 > 5 → true
/// assert!(open_upper.value_within_bound(&9.9));    // 9.9 < 10 → true
/// ```
///
/// ## Type-Level Programming
///
/// ### Compile-Time Type Safety
///
/// ```rust
/// use grid1d::bounds::*;
/// use try_create::New;
///
/// fn create_open_interval<T>(lower: T, upper: T) -> (LowerBound<T, Open>, UpperBound<T, Open>)
/// where
///     T: num_valid::RealScalar,
/// {
///     (LowerBound::new(lower), UpperBound::new(upper))
/// }
///
/// let (lower, upper) = create_open_interval(0.0, 1.0); // (0, 1)
/// assert!(lower.is_open());
/// assert!(upper.is_open());
/// ```
///
/// ### Generic Algorithm Support
///
/// ```rust
/// use grid1d::bounds::*;
/// use try_create::New;
///
/// fn describe_bound<S: BoundSide, T: BoundType>() -> &'static str {
///     match (S::is_lower(), T::is_open()) {
///         (true, true) => "lower open bound (x > value)",
///         (true, false) => "lower closed bound (x ≥ value)",
///         (false, true) => "upper open bound (x < value)",
///         (false, false) => "upper closed bound (x ≤ value)",
///     }
/// }
///
/// assert_eq!(describe_bound::<Lower, Open>(), "lower open bound (x > value)");
/// assert_eq!(describe_bound::<Upper, Open>(), "upper open bound (x < value)");
/// ```
///
/// ## Mathematical Properties
///
/// ### Interval Notation
///
/// Open bounds use parentheses in mathematical interval notation:
///
/// ```rust
/// use grid1d::bounds::*;
/// use try_create::New;
///
/// // Mathematical: (0, 1) = {x ∈ ℝ : 0 < x < 1}
/// let lower = LowerBoundOpen::new(0.0);   // (0
/// let upper = UpperBoundOpen::new(1.0);   // 1)
/// ```
///
/// ### Ordering Semantics
///
/// Open bounds are "looser" than closed bounds with the same value:
///
/// ```rust
/// use grid1d::bounds::*;
/// use try_create::New;
///
/// let open_lower = LowerBoundOpen::new(5.0);    // (5
/// let closed_lower = LowerBoundClosed::new(5.0); // [5
///
/// // For lower bounds: closed < open (tighter constraint < looser constraint)
/// assert!(closed_lower < open_lower);
///
/// let open_upper = UpperBoundOpen::new(5.0);    // 5)
/// let closed_upper = UpperBoundClosed::new(5.0); // 5]
///
/// // For upper bounds: open < closed (tighter constraint < looser constraint)
/// assert!(open_upper < closed_upper);
/// ```
///
/// ## Integration with Intervals
///
/// ### Open Interval Construction
///
/// ```rust
/// use grid1d::{bounds::*, intervals::*};
/// use try_create::{IntoInner, New};
///
/// let lower = LowerBoundOpen::new(0.0);
/// let upper = UpperBoundOpen::new(1.0);
///
/// // Create open interval (0, 1)
/// let interval = IntervalOpen::new(lower.into_inner(), upper.into_inner());
/// assert!(!interval.contains_point(&0.0)); // Excludes endpoints
/// assert!(!interval.contains_point(&1.0)); // Excludes endpoints
/// assert!(interval.contains_point(&0.5));  // Includes interior
/// ```
///
/// ### Mixed Interval Types
///
/// ```rust
/// use grid1d::{bounds::*, intervals::*};
/// use try_create::{IntoInner, New};
///
/// let open_lower = LowerBoundOpen::new(0.0);
/// let closed_upper = UpperBoundClosed::new(1.0);
///
/// // Create half-open interval (0, 1]
/// let interval = IntervalLowerOpenUpperClosed::new(
///     open_lower.into_inner(),
///     closed_upper.into_inner()
/// );
/// assert!(!interval.contains_point(&0.0)); // Excludes lower
/// assert!(interval.contains_point(&1.0));  // Includes upper
/// ```
///
/// ## Performance Characteristics
///
/// ### Zero-Cost Abstractions
/// - **Size**: Zero bytes (empty struct)
/// - **Alignment**: No storage requirements
/// - **Operations**: All compile to constants
/// - **Type checking**: Pure compile-time verification
///
/// ### Optimization Benefits
///
/// ```rust
/// use grid1d::bounds::*;
/// use try_create::New;
///
/// fn optimized_constraint_check<T: BoundType>(bound: &LowerBound<f64, T>, value: f64) -> bool {
///     // This compiles to direct comparison with no runtime branching
///     if T::is_open() {
///         value > *bound.as_ref()  // Constant folded for Open
///     } else {
///         value >= *bound.as_ref() // Never executed for Open
///     }
/// }
///
/// let open_bound = LowerBoundOpen::new(5.0);
/// // Compiles to: value > 5.0 (no type checking overhead)
/// assert!(!optimized_constraint_check(&open_bound, 5.0));
/// ```
///
/// ## Trait Implementation
///
/// ### BoundType Implementation
///
/// ```rust
/// # use grid1d::bounds::*;
/// assert!(!Open::includes_boundary()); // Always false for open bounds
/// assert!(Open::is_open());            // Always true for open bounds
/// assert!(!Open::is_closed());         // Always false for open bounds
/// ```
///
/// ### Required Traits
///
/// The [`Open`] type implements all required traits for boundary type markers:
/// - **Debug**: For diagnostic output
/// - **Clone**: For copying (zero-cost)
/// - **PartialEq + Eq**: For type equality
/// - **Serialize + Deserialize**: For boundary serialization
///
/// ## Best Practices
///
/// ### When to Use Open Bounds
/// - ✅ **Strict inequalities**: When boundary values must be excluded
/// - ✅ **Mathematical limits**: Approaching but not reaching boundary values
/// - ✅ **Asymptotic behavior**: Modeling behaviors near but not at boundaries
/// - ✅ **Convergence criteria**: When exact boundary values indicate non-convergence
///
/// ### Example Applications
///
/// ```rust
/// use grid1d::bounds::*;
/// use try_create::New;
///
/// // Modeling asymptotic behavior
/// fn model_asymptote() -> UpperBoundOpen<f64> {
///     UpperBoundOpen::new(1.0) // x < 1, approaching but never reaching 1
/// }
///
/// // Strict positivity constraints
/// fn positive_domain() -> LowerBoundOpen<f64> {
///     LowerBoundOpen::new(0.0) // x > 0, strictly positive
/// }
///
/// // Convergence tolerance
/// fn convergence_bound(tolerance: f64) -> UpperBoundOpen<f64> {
///     UpperBoundOpen::new(tolerance) // error < tolerance
/// }
/// ```
///
/// ## Mathematical Guarantees
///
/// The [`Open`] type maintains mathematical correctness by:
///
/// - **Exclusion Semantics**: Always excludes boundary values from constraints
/// - **Ordering Consistency**: Maintains proper mathematical ordering with [`Closed`]
/// - **Type Safety**: Prevents accidental inclusion of boundary values at compile time
/// - **Zero-Cost**: Provides complete type safety with no runtime overhead
///
/// Use [`Open`] when you need strict inequality constraints with compile-time verification
/// and zero runtime cost. For runtime flexibility, use [`IntervalBoundRuntime::Open`](crate::bounds::IntervalBoundRuntime::Open).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Open;

/// Marker type for closed bounds that include their boundary values.
///
/// [`Closed`] is a zero-sized type that implements [`BoundType`] to represent boundary
/// semantics where the boundary value is **included** in the constraint. This type
/// enables compile-time verification of closed boundary semantics in interval arithmetic.
///
/// ## Mathematical Semantics
///
/// Closed bounds include their boundary values in constraints:
///
/// | Bound Type | Mathematical Constraint | Notation | Boundary Value |
/// |------------|------------------------|----------|----------------|
/// | `LowerBound<T, Closed>` | `x ≥ bound_value` | `[a` | **Included** |
/// | `UpperBound<T, Closed>` | `x ≤ bound_value` | `b]` | **Included** |
///
/// ## Usage Examples
///
/// ### Basic Closed Bound Construction
///
/// ```rust
/// use grid1d::bounds::*;
/// use try_create::New;
///
/// // Lower closed bound: x ≥ 5
/// let lower_closed: LowerBoundClosed<f64> = LowerBound::new(5.0);
/// assert!(lower_closed.is_closed());
/// assert!(lower_closed.includes_boundary());
///
/// // Upper closed bound: x ≤ 10
/// let upper_closed: UpperBoundClosed<f64> = UpperBound::new(10.0);
/// assert!(upper_closed.is_closed());
/// assert!(upper_closed.includes_boundary());
/// ```
///
/// ### Constraint Testing
///
/// ```rust
/// use grid1d::bounds::*;
/// use try_create::New;
///
/// let closed_lower = LowerBoundClosed::new(5.0);  // x ≥ 5
/// let closed_upper = UpperBoundClosed::new(10.0); // x ≤ 10
///
/// // Boundary values are included
/// assert!(closed_lower.value_within_bound(&5.0));   // 5 ≥ 5 → true
/// assert!(closed_upper.value_within_bound(&10.0));  // 10 ≤ 10 → true
///
/// // Interior values are also included
/// assert!(closed_lower.value_within_bound(&5.1));   // 5.1 ≥ 5 → true
/// assert!(closed_upper.value_within_bound(&9.9));   // 9.9 ≤ 10 → true
///
/// // Values outside the bound are excluded
/// assert!(!closed_lower.value_within_bound(&4.9));  // 4.9 ≥ 5 → false
/// assert!(!closed_upper.value_within_bound(&10.1)); // 10.1 ≤ 10 → false
/// ```
///
/// ## Type-Level Programming
///
/// ### Compile-Time Type Safety
///
/// ```rust
/// use grid1d::bounds::*;
/// use try_create::New;
///
/// fn create_closed_interval<T>(lower: T, upper: T) -> (LowerBound<T, Closed>, UpperBound<T, Closed>)
/// where
///     T: num_valid::RealScalar,
/// {
///     (LowerBound::new(lower), UpperBound::new(upper))
/// }
///
/// let (lower, upper) = create_closed_interval(0.0, 1.0); // [0, 1]
/// assert!(lower.is_closed());
/// assert!(upper.is_closed());
/// ```
///
/// ### Generic Algorithm Support
///
/// ```rust
/// use grid1d::bounds::*;
/// use try_create::New;
///
/// fn bound_description<S: BoundSide, T: BoundType>() -> &'static str {
///     match (S::is_lower(), T::is_closed()) {
///         (true, true) => "lower closed bound (x ≥ value)",
///         (true, false) => "lower open bound (x > value)",
///         (false, true) => "upper closed bound (x ≤ value)",
///         (false, false) => "upper open bound (x < value)",
///     }
/// }
///
/// assert_eq!(bound_description::<Lower, Closed>(), "lower closed bound (x ≥ value)");
/// assert_eq!(bound_description::<Upper, Closed>(), "upper closed bound (x ≤ value)");
/// ```
///
/// ## Mathematical Properties
///
/// ### Interval Notation
///
/// Closed bounds use square brackets in mathematical interval notation:
///
/// ```rust
/// use grid1d::bounds::*;
/// use try_create::New;
///
/// // Mathematical: [0, 1] = {x ∈ ℝ : 0 ≤ x ≤ 1}
/// let lower = LowerBoundClosed::new(0.0);   // [0
/// let upper = UpperBoundClosed::new(1.0);   // 1]
/// ```
///
/// ### Ordering Semantics
///
/// Closed bounds are "tighter" than open bounds with the same value:
///
/// ```rust
/// use grid1d::bounds::*;
/// use try_create::New;
///
/// let closed_lower = LowerBoundClosed::new(5.0); // [5
/// let open_lower = LowerBoundOpen::new(5.0);     // (5
///
/// // For lower bounds: closed < open (tighter constraint < looser constraint)
/// assert!(closed_lower < open_lower);
///
/// let closed_upper = UpperBoundClosed::new(5.0); // 5]
/// let open_upper = UpperBoundOpen::new(5.0);     // 5)
///
/// // For upper bounds: open < closed (tighter constraint < looser constraint)
/// assert!(open_upper < closed_upper);
/// ```
///
/// ## Integration with Intervals
///
/// ### Closed Interval Construction
///
/// ```rust
/// use grid1d::{bounds::*, intervals::*};
/// use try_create::{IntoInner, New};
///
/// let lower = LowerBoundClosed::new(0.0);
/// let upper = UpperBoundClosed::new(1.0);
///
/// // Create closed interval [0, 1]
/// let interval = IntervalClosed::new(lower.into_inner(), upper.into_inner());
/// assert!(interval.contains_point(&0.0)); // Includes endpoints
/// assert!(interval.contains_point(&1.0)); // Includes endpoints
/// assert!(interval.contains_point(&0.5)); // Includes interior
/// ```
///
/// ### Mixed Interval Types
///
/// ```rust
/// use grid1d::{bounds::*, intervals::*};
/// use try_create::{IntoInner, New};
///
/// let closed_lower = LowerBoundClosed::new(0.0);
/// let open_upper = UpperBoundOpen::new(1.0);
///
/// // Create half-open interval [0, 1)
/// let interval = IntervalLowerClosedUpperOpen::new(
///     closed_lower.into_inner(),
///     open_upper.into_inner()
/// );
/// assert!(interval.contains_point(&0.0));  // Includes lower
/// assert!(!interval.contains_point(&1.0)); // Excludes upper
/// ```
///
/// ## Performance Characteristics
///
/// ### Zero-Cost Abstractions
/// - **Size**: Zero bytes (empty struct)
/// - **Alignment**: No storage requirements
/// - **Operations**: All compile to constants
/// - **Type checking**: Pure compile-time verification
///
/// ### Optimization Benefits
///
/// ```rust
/// use grid1d::bounds::*;
/// use try_create::New;
///
/// fn optimized_constraint_check<T: BoundType>(bound: &LowerBound<f64, T>, value: f64) -> bool {
///     // This compiles to direct comparison with no runtime branching
///     if T::is_closed() {
///         value >= *bound.as_ref() // Constant folded for Closed
///     } else {
///         value > *bound.as_ref()  // Never executed for Closed
///     }
/// }
///
/// let closed_bound = LowerBoundClosed::new(5.0);
/// // Compiles to: value >= 5.0 (no type checking overhead)
/// assert!(optimized_constraint_check(&closed_bound, 5.0));
/// ```
///
/// ## Trait Implementation
///
/// ### BoundType Implementation
///
/// ```rust
/// # use grid1d::bounds::*;
/// assert!(Closed::includes_boundary()); // Always true for closed bounds
/// assert!(!Closed::is_open());          // Always false for closed bounds
/// assert!(Closed::is_closed());         // Always true for closed bounds
/// ```
///
/// ### Required Traits
///
/// The [`Closed`] type implements all required traits for boundary type markers:
/// - **Debug**: For diagnostic output
/// - **Clone**: For copying (zero-cost)
/// - **PartialEq + Eq**: For type equality
/// - **Serialize + Deserialize**: For boundary serialization
///
/// ## Best Practices
///
/// ### When to Use Closed Bounds
/// - ✅ **Inclusive constraints**: When boundary values are valid/required
/// - ✅ **Physical boundaries**: Real-world limits that can be achieved
/// - ✅ **Optimization bounds**: When optimal values can occur at boundaries
/// - ✅ **Discrete domains**: When working with finite precision arithmetic
///
/// ### Example Applications
///
/// ```rust
/// use grid1d::bounds::*;
/// use try_create::New;
///
/// // Physical constraint (temperature can be exactly 0°C)
/// fn temperature_bound() -> LowerBoundClosed<f64> {
///     LowerBoundClosed::new(0.0) // T ≥ 0°C (absolute zero in Celsius)
/// }
///
/// // Probability constraint (probability can be exactly 1.0)
/// fn probability_upper_bound() -> UpperBoundClosed<f64> {
///     UpperBoundClosed::new(1.0) // p ≤ 1.0
/// }
/// ```
///
/// ## Common Use Cases
///
/// ### Standard Mathematical Intervals
///
/// ```rust
/// use grid1d::bounds::*;
/// use try_create::New;
///
/// // Unit interval [0, 1]
/// let unit_lower = LowerBoundClosed::new(0.0);
/// let unit_upper = UpperBoundClosed::new(1.0);
///
/// // Non-negative reals [0, +∞)
/// let non_negative = LowerBoundClosed::new(0.0);
///
/// // Bounded domain [-1, 1]
/// let symmetric_lower = LowerBoundClosed::new(-1.0);
/// let symmetric_upper = UpperBoundClosed::new(1.0);
/// ```
///
/// ## Mathematical Guarantees
///
/// The [`Closed`] type maintains mathematical correctness by:
///
/// - **Inclusion Semantics**: Always includes boundary values in constraints
/// - **Ordering Consistency**: Maintains proper mathematical ordering with [`Open`]
/// - **Type Safety**: Ensures boundary values are considered valid at compile time
/// - **Zero-Cost**: Provides complete type safety with no runtime overhead
///
/// Use [`Closed`] when you need inclusive constraint semantics with compile-time verification
/// and zero runtime cost. For runtime flexibility, use [`IntervalBoundRuntime::Closed`](crate::bounds::IntervalBoundRuntime::Closed).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Closed;

impl BoundType for Open {
    type Opposite = Closed;

    #[inline(always)]
    fn includes_boundary() -> bool {
        false
    }
}

impl BoundType for Closed {
    type Opposite = Open;

    #[inline(always)]
    fn includes_boundary() -> bool {
        true
    }
}
//------------------------------------------------------------------------------------------------