int_interval/

i8.rs

use crate::res::{OneTwo, ZeroOneTwo};

#[cfg(test)]
mod basic_tests;
#[cfg(test)]
mod between_tests;
#[cfg(test)]
mod checked_minkowski_tests;
#[cfg(test)]
mod convex_hull_tests;
#[cfg(test)]
mod difference_tests;
#[cfg(test)]
mod intersection_tests;
#[cfg(test)]
mod symmetric_difference_tests;
#[cfg(test)]
mod union_tests;

#[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
pub struct I8CO {
    start: i8,
    end_excl: i8,
}

// ------------------------------------------------------------
// low-level api: construction / accessors / predicates
// ------------------------------------------------------------
mod basic {

    use super::*;

    impl I8CO {
        #[inline]
        pub const fn try_new(start: i8, end_excl: i8) -> Option<Self> {
            if start < end_excl {
                Some(Self { start, end_excl })
            } else {
                None
            }
        }

        #[inline]
        pub const unsafe fn new_unchecked(start: i8, end_excl: i8) -> Self {
            debug_assert!(start < end_excl);
            Self { start, end_excl }
        }

        #[inline]
        pub const fn start(self) -> i8 {
            self.start
        }

        #[inline]
        pub const fn end_excl(self) -> i8 {
            self.end_excl
        }

        #[inline]
        pub const fn end_incl(self) -> i8 {
            // i8_low_bound =< start < end_excl
            self.end_excl - 1
        }

        #[inline]
        pub const fn len(self) -> u8 {
            const SIGN_MASK: u8 = 1 << (i8::BITS - 1);
            ((self.end_excl as u8) ^ SIGN_MASK) - ((self.start as u8) ^ SIGN_MASK)
        }

        /// Returns the midpoint of the interval `[start, end_excl)`,
        /// using floor division if the length is even.
        ///
        /// # Guarantees
        /// - `midpoint()` ∈ `[self.start, self.end_excl - 1]`
        /// - Works for intervals with maximum length (entire `i8` range)
        #[inline]
        pub const fn midpoint(self) -> i8 {
            self.start + (self.len() / 2) as i8
        }

        /// Constructs an `I8CO` interval from a midpoint and length (`u8`).
        ///
        /// # Parameters
        /// - `mid`: the desired midpoint of the interval
        /// - `len`: the desired length of the interval in units, must be `1..=u8::MAX`
        ///
        /// # Returns
        /// - `Some(I8CO)` if the interval `[start, end_excl)` can be represented in `i8`
        /// - `None` if `len = 0` or the computed `start` / `end_excl` would overflow `i8`
        ///
        /// # Guarantees
        /// - Returned interval satisfies `start < end_excl`
        /// - Maximum accepted input length is `u8::MAX`
        #[inline]
        pub const fn checked_from_midpoint_len(mid: i8, len: u8) -> Option<Self> {
            if len == 0 {
                return None;
            }

            let half = (len / 2) as i8;

            let Some(start) = mid.checked_sub(half) else {
                return None;
            };
            let Some(end_incl) = mid.checked_add(half) else {
                return None;
            };
            let Some(end_excl) = end_incl.checked_add((len % 2) as i8) else {
                return None;
            };

            // # Safety
            // This function uses `unsafe { Self::new_unchecked(start, end_excl) }` internally.
            // The safety is guaranteed by the following checks:
            // 1. `mid.checked_sub(half)` ensures `start` does not underflow `i8`.
            // 2. `mid.checked_add(the_other_half)` ensures `end_excl` does not overflow `i8`.
            // 3. Because `half >= 0` and `the_other_half > 0`, we have `start < end_excl`.
            // 4. Therefore, the half-open interval invariant `[start, end_excl)` is preserved.
            Some(unsafe { Self::new_unchecked(start, end_excl) })
        }

        /// Constructs an `I8CO` interval from a midpoint and length (`u8`) with saturating semantics.
        ///
        /// # Parameters
        /// - `mid`: the desired midpoint of the interval
        /// - `len`: the desired length of the interval in units, must be `1..=u8::MAX`
        ///
        /// # Behavior
        /// - Values are saturated at `i8::MIN` / `i8::MAX` to prevent overflow.
        /// - If `len = 0`, returns `None`.
        ///
        /// # Guarantees
        /// - Returned interval satisfies `start < end_excl`
        /// - Maximum accepted input length is `u8::MAX`
        /// - Fully compatible with codegen for other signed integer interval types
        #[inline]
        pub const fn saturating_from_midpoint_len(mid: i8, len: u8) -> Option<Self> {
            if len == 0 {
                return None;
            }

            let half = (len / 2) as i8;

            let start = mid.saturating_sub(half);
            let end_incl = mid.saturating_add(half);
            let end_excl = end_incl.saturating_add((len % 2) as i8);

            Self::try_new(start, end_excl)
        }

        #[inline]
        pub const fn contains(self, x: i8) -> bool {
            self.start <= x && x < self.end_excl
        }

        #[inline]
        pub const fn contains_interval(self, other: Self) -> bool {
            self.start <= other.start && other.end_excl <= self.end_excl
        }

        #[inline]
        pub const fn iter(self) -> core::ops::Range<i8> {
            self.start..self.end_excl
        }

        #[inline]
        pub const fn to_range(self) -> core::ops::Range<i8> {
            self.start..self.end_excl
        }

        #[inline]
        pub const fn intersects(self, other: Self) -> bool {
            !(self.end_excl <= other.start || other.end_excl <= self.start)
        }

        #[inline]
        pub const fn is_adjacent(self, other: Self) -> bool {
            self.end_excl == other.start || other.end_excl == self.start
        }

        #[inline]
        pub const fn is_contiguous_with(self, other: Self) -> bool {
            self.intersects(other) || self.is_adjacent(other)
        }
    }
}

// ------------------------------------------------------------
// interval algebra api: intersection / convex_hull / between / union / difference / symmetric_difference
// ------------------------------------------------------------

mod interval_algebra {

    use super::*;

    impl I8CO {
        /// Returns the intersection of two intervals.
        ///
        /// If the intervals do not overlap, returns `None`.
        #[inline]
        pub const fn intersection(self, other: Self) -> Option<Self> {
            let start = if self.start >= other.start {
                self.start
            } else {
                other.start
            };

            let end_excl = if self.end_excl <= other.end_excl {
                self.end_excl
            } else {
                other.end_excl
            };

            Self::try_new(start, end_excl)
        }

        /// Returns the convex hull (smallest interval containing both) of two intervals.
        ///
        /// Always returns a valid `I8CO`.
        #[inline]
        pub const fn convex_hull(self, other: Self) -> Self {
            let start = if self.start <= other.start {
                self.start
            } else {
                other.start
            };

            let end_excl = if self.end_excl >= other.end_excl {
                self.end_excl
            } else {
                other.end_excl
            };

            Self { start, end_excl }
        }

        /// Returns the interval strictly between two intervals.
        ///
        /// If the intervals are contiguous or overlap, returns `None`.
        #[inline]
        pub const fn between(self, other: Self) -> Option<Self> {
            let (left, right) = if self.start <= other.start {
                (self, other)
            } else {
                (other, self)
            };

            Self::try_new(left.end_excl, right.start)
        }

        /// Returns the union of two intervals.
        ///
        /// - If intervals are contiguous or overlapping, returns `One` containing the merged interval.
        /// - Otherwise, returns `Two` containing both intervals in ascending order.
        #[inline]
        pub const fn union(self, other: Self) -> OneTwo<Self> {
            if self.is_contiguous_with(other) {
                OneTwo::One(self.convex_hull(other))
            } else if self.start <= other.start {
                OneTwo::Two(self, other)
            } else {
                OneTwo::Two(other, self)
            }
        }

        /// Returns the difference of two intervals (self - other).
        ///
        /// - If no overlap, returns `One(self)`.
        /// - If partial overlap, returns `One` or `Two` depending on remaining segments.
        /// - If fully contained, returns `Zero`.
        #[inline]
        pub const fn difference(self, other: Self) -> ZeroOneTwo<Self> {
            match self.intersection(other) {
                None => ZeroOneTwo::One(self),
                Some(inter) => {
                    let left = Self::try_new(self.start, inter.start);
                    let right = Self::try_new(inter.end_excl, self.end_excl);

                    match (left, right) {
                        (None, None) => ZeroOneTwo::Zero,
                        (Some(x), None) | (None, Some(x)) => ZeroOneTwo::One(x),
                        (Some(x), Some(y)) => ZeroOneTwo::Two(x, y),
                    }
                }
            }
        }

        /// Returns the symmetric difference of two intervals.
        ///
        /// Equivalent to `(self - other) ∪ (other - self)`.
        /// - If intervals do not overlap, returns `Two(self, other)` in order.
        /// - If intervals partially overlap, returns remaining non-overlapping segments as `One` or `Two`.
        #[inline]
        pub const fn symmetric_difference(self, other: Self) -> ZeroOneTwo<Self> {
            match self.intersection(other) {
                None => {
                    if self.start <= other.start {
                        ZeroOneTwo::Two(self, other)
                    } else {
                        ZeroOneTwo::Two(other, self)
                    }
                }
                Some(inter) => {
                    let hull = self.convex_hull(other);
                    let left = Self::try_new(hull.start, inter.start);
                    let right = Self::try_new(inter.end_excl, hull.end_excl);

                    match (left, right) {
                        (None, None) => ZeroOneTwo::Zero,
                        (Some(x), None) | (None, Some(x)) => ZeroOneTwo::One(x),
                        (Some(x), Some(y)) => ZeroOneTwo::Two(x, y),
                    }
                }
            }
        }
    }
}

// ------------------------------------------------------------
// Module: Minkowski arithmetic for I8CO
// Provides checked and saturating Minkowski operations for intervals
// ------------------------------------------------------------

pub mod minkowski {
    use super::*;

    type Min = i8;
    type Max = i8;

    #[inline]
    const fn min_max4(a: i8, b: i8, c: i8, d: i8) -> (Min, Max) {
        let (min1, max1) = if a < b { (a, b) } else { (b, a) };
        let (min2, max2) = if c < d { (c, d) } else { (d, c) };
        let min = if min1 < min2 { min1 } else { min2 };
        let max = if max1 > max2 { max1 } else { max2 };
        (min, max)
    }

    #[inline]
    const fn min_max2(a: i8, b: i8) -> (Min, Max) {
        if a < b { (a, b) } else { (b, a) }
    }

    pub mod checked {
        use super::*;

        // --------------------------------------------------------
        // Interval-to-interval
        // --------------------------------------------------------
        impl I8CO {
            #[inline]
            pub const fn checked_minkowski_add(self, other: Self) -> Option<Self> {
                let Some(start) = self.start.checked_add(other.start) else {
                    return None;
                };
                let Some(end_excl) = self.end_excl.checked_add(other.end_incl()) else {
                    return None;
                };

                // SAFETY:
                // `checked_add` guarantees both endpoint computations succeed without overflow.
                // For half-open intervals, let `a_last = self.end_incl()` and `b_last = other.end_incl()`.
                // Since `self.start <= a_last` and `other.start <= b_last`, we have
                // `self.start + other.start <= a_last + b_last < self.end_excl + other.end_incl()`,
                // hence the computed bounds satisfy `start < end_excl`.
                Some(unsafe { Self::new_unchecked(start, end_excl) })
            }

            #[inline]
            pub const fn checked_minkowski_sub(self, other: Self) -> Option<Self> {
                let Some(start) = self.start.checked_sub(other.end_incl()) else {
                    return None;
                };
                let Some(end_excl) = self.end_excl.checked_sub(other.start) else {
                    return None;
                };

                // SAFETY:
                // `checked_sub` guarantees both endpoint computations succeed without overflow.
                // For interval subtraction, the minimum is attained at `self.start - other.end_incl()`
                // and the exclusive upper bound is `self.end_excl - other.start`.
                // Because `other.start <= other.end_incl()`, we get
                // `self.start - other.end_incl() < self.end_excl - other.start`,
                // so the resulting half-open interval is valid.
                Some(unsafe { Self::new_unchecked(start, end_excl) })
            }

            #[inline]
            pub const fn checked_minkowski_mul(self, other: Self) -> Option<Self> {
                let a = self.start;
                let b = self.end_incl();
                let c = other.start;
                let d = other.end_incl();

                let Some(p1) = a.checked_mul(c) else {
                    return None;
                };
                let Some(p2) = a.checked_mul(d) else {
                    return None;
                };
                let Some(p3) = b.checked_mul(c) else {
                    return None;
                };
                let Some(p4) = b.checked_mul(d) else {
                    return None;
                };

                let (start, end_incl) = min_max4(p1, p2, p3, p4);

                let Some(end_excl) = end_incl.checked_add(1) else {
                    return None;
                };

                // SAFETY:
                // All four corner products are computed with `checked_mul`, so no intermediate
                // multiplication overflows. For multiplication over a closed integer rectangle
                // `[a, b] × [c, d]`, every attainable extremum occurs at a corner, so
                // `min_max4(p1, p2, p3, p4)` yields the true inclusive lower/upper bounds.
                // Therefore `start <= end_incl` holds by construction.
                // `checked_add(1)` then safely converts the inclusive upper bound to the exclusive
                // upper bound, and implies `end_excl = end_incl + 1`, hence `start < end_excl`.
                Some(unsafe { Self::new_unchecked(start, end_excl) })
            }

            #[inline]
            pub const fn checked_minkowski_div(self, other: Self) -> Option<Self> {
                if other.start <= 0 && other.end_incl() >= 0 {
                    return None;
                }

                let a = self.start;
                let b = self.end_incl();
                let c = other.start;
                let d = other.end_incl();

                let Some(p1) = a.checked_div(c) else {
                    return None;
                };
                let Some(p2) = a.checked_div(d) else {
                    return None;
                };
                let Some(p3) = b.checked_div(c) else {
                    return None;
                };
                let Some(p4) = b.checked_div(d) else {
                    return None;
                };

                let (start, end_incl) = min_max4(p1, p2, p3, p4);

                let Some(end_excl) = end_incl.checked_add(1) else {
                    return None;
                };

                // SAFETY:
                // The guard `other.start <= 0 && other.end_incl() >= 0` rejects any divisor interval
                // that contains zero, so division by zero cannot occur anywhere in the divisor set.
                // Each corner quotient is computed with `checked_div`, so exceptional signed cases
                // such as `MIN / -1` are also rejected.
                // On each connected component of the divisor domain that excludes zero, integer division
                // is monotone with respect to the rectangle corners relevant to the extremum search;
                // thus the global inclusive bounds over the interval pair are captured by the four
                // corner quotients and recovered by `min_max4`, giving `start <= end_incl`.
                // `checked_add(1)` safely converts the inclusive upper bound to half-open form, so
                // the final bounds satisfy `start < end_excl`.
                Some(unsafe { Self::new_unchecked(start, end_excl) })
            }
        }

        // --------------------------------------------------------
        // Scalar
        // --------------------------------------------------------
        impl I8CO {
            #[inline]
            pub const fn checked_minkowski_add_n(self, n: i8) -> Option<Self> {
                let Some(start) = self.start.checked_add(n) else {
                    return None;
                };
                let Some(end_excl) = self.end_excl.checked_add(n) else {
                    return None;
                };

                // SAFETY:
                // `checked_add` guarantees both translated bounds are computed without overflow.
                // Adding the same scalar to both endpoints preserves the interval width exactly,
                // so a valid half-open interval remains valid and still satisfies `start < end_excl`.
                Some(unsafe { Self::new_unchecked(start, end_excl) })
            }

            #[inline]
            pub const fn checked_minkowski_sub_n(self, n: i8) -> Option<Self> {
                let Some(start) = self.start.checked_sub(n) else {
                    return None;
                };
                let Some(end_excl) = self.end_excl.checked_sub(n) else {
                    return None;
                };

                // SAFETY:
                // `checked_sub` guarantees both translated bounds are computed without overflow.
                // Subtracting the same scalar from both endpoints preserves the interval width exactly,
                // so the strict half-open ordering is unchanged and `start < end_excl` still holds.
                Some(unsafe { Self::new_unchecked(start, end_excl) })
            }

            #[inline]
            pub const fn checked_minkowski_mul_n(self, n: i8) -> Option<Self> {
                let Some(a) = self.start.checked_mul(n) else {
                    return None;
                };
                let Some(b) = self.end_incl().checked_mul(n) else {
                    return None;
                };

                let (start, end_incl) = min_max2(a, b);

                let Some(end_excl) = end_incl.checked_add(1) else {
                    return None;
                };

                // SAFETY:
                // Both endpoint products are computed with `checked_mul`, so no signed overflow occurs.
                // Multiplication by a scalar maps the closed source interval endpoints to the two extreme
                // candidates; `min_max2` therefore recovers the true inclusive lower/upper bounds whether
                // `n` is positive, zero, or negative, giving `start <= end_incl`.
                // `checked_add(1)` safely converts the inclusive upper bound into the exclusive upper bound,
                // which guarantees the final half-open interval satisfies `start < end_excl`.
                Some(unsafe { Self::new_unchecked(start, end_excl) })
            }

            #[inline]
            pub const fn checked_minkowski_div_n(self, n: i8) -> Option<Self> {
                if n == 0 {
                    return None;
                }

                let Some(a) = self.start.checked_div(n) else {
                    return None;
                };
                let Some(b) = self.end_incl().checked_div(n) else {
                    return None;
                };

                let (start, end_incl) = min_max2(a, b);

                let Some(end_excl) = end_incl.checked_add(1) else {
                    return None;
                };

                // SAFETY:
                // The guard `n != 0` excludes division by zero, and `checked_div` additionally rejects
                // the only overflowing signed case (`MIN / -1`).
                // Division by a fixed nonzero scalar sends the source closed interval endpoints to the
                // two extreme candidates for the image interval, so `min_max2` yields the true inclusive
                // lower/upper bounds and ensures `start <= end_incl`.
                // `checked_add(1)` safely restores half-open representation, therefore the constructed
                // interval satisfies `start < end_excl`.
                Some(unsafe { Self::new_unchecked(start, end_excl) })
            }
        }
    }

    // ========================================================
    // SATURATING
    // ========================================================
    pub mod saturating {
        use super::*;

        impl I8CO {
            #[inline]
            pub const fn saturating_minkowski_add(self, other: Self) -> Option<Self> {
                let start = self.start.saturating_add(other.start);
                let end_excl = self.end_excl.saturating_add(other.end_incl());
                Self::try_new(start, end_excl)
            }

            #[inline]
            pub const fn saturating_minkowski_sub(self, other: Self) -> Option<Self> {
                let start = self.start.saturating_sub(other.end_incl());
                let end_excl = self.end_excl.saturating_sub(other.start);
                Self::try_new(start, end_excl)
            }

            #[inline]
            pub const fn saturating_minkowski_mul(self, other: Self) -> Option<Self> {
                let a = self.start.saturating_mul(other.start);
                let b = self.start.saturating_mul(other.end_incl());
                let c = self.end_incl().saturating_mul(other.start);
                let d = self.end_incl().saturating_mul(other.end_incl());

                let (start, end_incl) = min_max4(a, b, c, d);

                let end_excl = end_incl.saturating_add(1);
                Self::try_new(start, end_excl)
            }

            #[inline]
            pub const fn saturating_minkowski_div(self, other: Self) -> Option<Self> {
                if other.start <= 0 && other.end_incl() >= 0 {
                    return None;
                }

                let a = self.start / other.start;
                let b = self.start / other.end_incl();
                let c = self.end_incl() / other.start;
                let d = self.end_incl() / other.end_incl();

                let (start, end_incl) = min_max4(a, b, c, d);

                let end_excl = end_incl.saturating_add(1);
                Self::try_new(start, end_excl)
            }
        }

        impl I8CO {
            #[inline]
            pub const fn saturating_minkowski_add_n(self, n: i8) -> Option<Self> {
                let start = self.start.saturating_add(n);
                let end_excl = self.end_excl.saturating_add(n);
                Self::try_new(start, end_excl)
            }

            #[inline]
            pub const fn saturating_minkowski_sub_n(self, n: i8) -> Option<Self> {
                let start = self.start.saturating_sub(n);
                let end_excl = self.end_excl.saturating_sub(n);
                Self::try_new(start, end_excl)
            }

            #[inline]
            pub const fn saturating_minkowski_mul_n(self, n: i8) -> Option<Self> {
                let a = self.start.saturating_mul(n);
                let b = self.end_incl().saturating_mul(n);

                let (start, end_incl) = min_max2(a, b);

                let end_excl = end_incl.saturating_add(1);
                Self::try_new(start, end_excl)
            }

            #[inline]
            pub const fn saturating_minkowski_div_n(self, n: i8) -> Option<Self> {
                if n == 0 {
                    return None;
                }

                let a = self.start / n;
                let b = self.end_incl() / n;

                let (start, end_incl) = min_max2(a, b);

                let end_excl = end_incl.saturating_add(1);
                Self::try_new(start, end_excl)
            }
        }
    }
}