phys_geom/

interval.rs

// Copyright (C) 2020-2025 phys-geom authors. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! One-dimensional interval arithmetic utilities.
//!
//! This module provides functionality for working with one-dimensional intervals
//! on the real number line. Intervals are fundamental for various geometric
//! algorithms including:
//! - Collision detection and response
//! - Spatial partitioning and culling
//! - Numerical robustness in geometric computations
//! - Bounding box projections and intersections
//!
//! # Overview
//!
//! An interval represents a closed range [min, max] on the real number line.
//! The interval is inclusive, meaning both endpoints are considered part of
//! the interval.
//!
//! # Examples
//!
//! ```rust
//! use phys_geom::Interval;
//!
//! // Create an interval from 0.0 to 1.0
//! let interval = Interval::new(0.0, 1.0);
//!
//! // Check properties
//! assert_eq!(interval.min(), 0.0);
//! assert_eq!(interval.max(), 1.0);
//!
//! // Check overlap with another interval
//! let other = Interval::new(0.5, 1.5);
//! assert!(interval.overlaps(&other));
//! ```
//! # Mathematical Properties
//!
//! The interval maintains the invariant that `min <= max`. This is enforced
//! at creation time and all operations preserve this invariant.

use crate::math::Real;

/// A one-dimensional interval on the real number line.
///
/// An interval represents a closed range [min, max] where both endpoints
/// are included. This is a fundamental building block for many geometric
/// algorithms, particularly in collision detection and spatial queries.
///
/// # Mathematical Representation
///
/// The interval represents all real numbers x such that: `min <= x <= max`
///
/// # Examples
///
/// ```rust
/// use phys_geom::Interval;
///
/// // Create an interval representing the range [0.0, 1.0]
/// let interval = Interval::new(0.0, 1.0);
///
/// // Check if a value is within the interval
/// let contains_0_5 = interval.min() <= 0.5 && 0.5 <= interval.max();
/// assert!(contains_0_5);
/// ```
///
/// # Common Applications
///
/// - **Separating Axis Theorem**: Testing overlap of projected shapes
/// - **AABB Operations**: Computing intersections along specific axes
/// - **Numerical Robustness**: Handling floating-point precision issues
/// - **Spatial Partitioning**: Determining object overlaps in 1D
///
/// # Invariants
///
/// The struct maintains the invariant that `min <= max`. This is enforced
/// at construction time and preserved by all operations.
///
/// # Memory Layout
///
/// The struct contains exactly two `Real` values and is designed to be
/// efficient for both computation and memory usage.
#[derive(Debug, PartialEq, Clone, Copy)]
pub struct Interval {
    /// The minimum (lower) bound of the interval
    min: Real,
    /// The maximum (upper) bound of the interval
    max: Real,
}

impl Interval {
    /// Creates a new interval with the specified bounds.
    ///
    /// This function creates a closed interval [min, max] that includes both endpoints.
    ///
    /// # Arguments
    ///
    /// * `min` - The minimum (lower) bound of the interval
    /// * `max` - The maximum (upper) bound of the interval
    ///
    /// # Returns
    ///
    /// A new `Interval` instance representing the range [min, max].
    ///
    /// # Panics
    ///
    /// Panics if `min > max`, as this would violate the interval invariant.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::Interval;
    ///
    /// // Create a valid interval
    /// let interval = Interval::new(0.0, 1.0);
    /// assert_eq!(interval.min(), 0.0);
    /// assert_eq!(interval.max(), 1.0);
    ///
    /// // This would panic: Interval::new(1.0, 0.0);
    /// ```
    ///
    /// # Edge Cases
    ///
    /// - `min == max`: Creates a zero-width interval (single point)
    /// - `min < max`: Creates a normal interval with positive width
    #[must_use]
    #[inline]
    pub fn new(min: Real, max: Real) -> Self {
        assert!(min <= max);
        Self { min, max }
    }

    /// Returns the minimum (lower) bound of the interval.
    ///
    /// # Returns
    ///
    /// The minimum value as a `Real`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::Interval;
    ///
    /// let interval = Interval::new(0.0, 1.0);
    /// assert_eq!(interval.min(), 0.0);
    /// ```
    #[must_use]
    #[inline]
    pub fn min(&self) -> Real {
        self.min
    }

    /// Returns the maximum (upper) bound of the interval.
    ///
    /// # Returns
    ///
    /// The maximum value as a `Real`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::Interval;
    ///
    /// let interval = Interval::new(0.0, 1.0);
    /// assert_eq!(interval.max(), 1.0);
    /// ```
    #[must_use]
    #[inline]
    pub fn max(&self) -> Real {
        self.max
    }

    /// Checks if this interval overlaps with another interval.
    ///
    /// Two intervals overlap if they have at least one point in common.
    /// Since these are closed intervals, the overlap condition is:
    /// `self.min <= other.max && self.max >= other.min`
    ///
    /// # Arguments
    ///
    /// * `other` - The other interval to test for overlap
    ///
    /// # Returns
    ///
    /// `true` if the intervals overlap, `false` otherwise.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::Interval;
    ///
    /// let a = Interval::new(0.0, 2.0);
    /// let b = Interval::new(1.0, 3.0);
    /// let c = Interval::new(2.5, 4.0);
    ///
    /// assert!(a.overlaps(&b));  // Overlap in [1.0, 2.0]
    /// assert!(!a.overlaps(&c)); // No overlap
    /// assert!(b.overlaps(&c));  // Overlap at point 2.5
    /// ```
    ///
    /// # Edge Cases
    ///
    /// - **Touching intervals**: `[0,1]` and `[1,2]` overlap at point 1
    /// - **Zero-width intervals**: `[1,1]` overlaps with `[0,2]` but not with `[2,3]`
    /// - **Identical intervals**: Always overlap with themselves
    ///
    /// # Mathematical Definition
    ///
    /// The overlap condition can be written as:
    /// `overlap = [max(self.min, other.min), min(self.max, other.max)]` is non-empty
    ///
    /// Note: This is a closed interval, meaning that the bounds are included
    /// in the overlap calculation.
    #[must_use]
    #[inline]
    pub fn overlaps(&self, other: &Self) -> bool {
        self.min <= other.max && self.max >= other.min
    }
}