span_core/

span.rs

use std::fmt;
use std::ops::{Range as Fin, Sub};
use std::ops::RangeFrom as Infin;
use num_traits::{CheckedAdd, One};
use thiserror::Error;

/// 闭开区间 或 闭无限区间。<br>
/// 即 `start..end` 或 `start..`。<br>
/// 即 `[start,end)` 或 `[start,+∞)`。
///
/// 当为闭开区间时，`start <= i < end` 视为i包含于这个 `Span` <br>
/// 当闭无限区间时，`start <= i` 视为i包含于这个 `Span`
///
/// `start >= end` 时视为空。
///
/// # Examples
///
/// 使用 `into` 来将 `Range` 和 `RangeFrom` 转换为 `Span` :
///
/// ```
/// assert_eq!((3..5).into(), vault_utils::span::Span::new_finite(3,5));
/// assert_eq!((3..).into(), vault_utils::span::Span::new_infinite(3));
/// ```
///
/// 判断元素是否包含在区间内:
/// ```
/// let finite = Span::new_finite(2, 7);
/// assert!(finite.contains(&3));
/// assert!(!finite.contains(&7));
///
/// let infinite = Span::new_infinite(5);
/// assert!(infinite.contains(&10));
/// assert!(!infinite.contains(&3));
/// ```
///
/// 判断区间是否为空:
/// ```
/// assert!(Span::new_finite(5, 3).is_empty());
/// assert!(!Span::new_finite(3,5).is_empty());
/// assert!(!Span::new_infinite(0).is_empty());
/// assert!(!Span::new_infinite(usize::MAX).is_empty());
/// ```
#[derive(Clone, PartialEq, Eq, Hash, Debug)] // not Copy -- see #27186
#[derive(serde::Deserialize, serde::Serialize)]
pub enum Span<T>
{
    Finite(Fin<T>),
    Infinite(Infin<T>),
}

impl<T> Span<T> {
    #[inline]
    pub fn from_finite(range: Fin<T>) -> Self {
        Span::Finite(range)
    }
    
    #[inline]
    pub fn from_infinite(range_from: Infin<T>) -> Self {
        Span::Infinite(range_from)
    }
    
    #[inline]
    pub fn new_finite(start: T, end: T) -> Self {Self::Finite(start..end)}
    
    #[inline]
    pub fn new_infinite(start: T) -> Self {Self::Infinite(start..)}
    
    #[inline]
    pub fn start(&self) -> &T {
        match self {
            Self::Finite(r) => &r.start,
            Self::Infinite(r) => &r.start
        }
    }
    
    #[inline]
    pub fn end(&self) -> Option<&T> {
        match self {
            Self::Finite(r) => Some(&r.end),
            Self::Infinite(_) => None
        }
    }
    
    #[inline]
    pub fn as_finite(&self) -> Option<&Fin<T>> {
        match self {
            Self::Finite(r) => Some(r),
            Self::Infinite(_) => None,
        }
    }
    
    #[inline]
    pub fn as_infinite(&self) -> Option<&Infin<T>> {
        match self {
            Self::Infinite(r) => Some(r),
            Self::Finite(_) => None,
        }
    }
    
    #[inline]
    pub fn into_finite(self) -> Option<Fin<T>> {
        match self {
            Self::Finite(r) => Some(r),
            Self::Infinite(_) => None,
        }
    }
    
    #[inline]
    pub fn into_infinite(self) -> Option<Infin<T>> {
        match self {
            Self::Infinite(r) => Some(r),
            Self::Finite(_) => None,
        }
    }
    
    #[inline]
    pub fn is_finite(&self) -> bool {
        matches!(self, Self::Finite(_))
    }
    
    #[inline]
    pub fn is_infinite(&self) -> bool {
        matches!(self, Self::Infinite(_))
    }
}

impl<T: PartialOrd> Span<T> {
    /// Returns `true` if `item` is contained in the range.
    #[inline]
    pub fn contains<U>(&self, item: &U) -> bool
    where
        T: PartialOrd<U>,
        U: ?Sized + PartialOrd<T>,
    {
        match self {
            Self::Finite(r) => item >= &r.start && item < &r.end,
            Self::Infinite(r) => item >= &r.start,
        }
    }
    
    /// Returns `true` if the range contains no items.
    ///
    /// 仅有限区间可能为空。
    #[inline]
    pub fn is_empty(&self) -> bool {
        matches!(self, Self::Finite(r) if r.start >= r.end)
    }
    
    /// 判断当前区间是否完全包含另一个区间
    pub fn contains_span(&self, other: &Self) -> bool {
        if self.start() > other.start() {
            return false;
        }
        match (self.end(), other.end()) {
            // 无限区间 → 只要起始满足，就包含所有后续区间
            (None, _) => true,
            // 有限区间 → 当前结束 ≥ 另一个结束
            (Some(self_end), Some(other_end)) => self_end >= other_end,
            // 自身有限、另一个无限 → 无法包含
            (Some(_), None) => false,
        }
    }
}

#[derive(Error, Debug, Clone, PartialEq, Eq)]
pub enum SpanError {
    #[error("有限区间为空，无法计算大小")]
    EmptyFiniteSpan,
}

impl<T,O> Span<T>
where
    T: Sub<T, Output = O> + Copy + PartialOrd,
    O: Sized,
{
    /// 返回区间的大小
    ///
    /// 空区间返回Err <br>
    /// 无限区间返回Ok(None) <br>
    /// 有限区间返回Ok(Some)
    pub fn size(&self) -> Result<Option<O>,SpanError> {
        match self.end() {
            Some(end) => {
                if self.is_empty() {
                    Err(SpanError::EmptyFiniteSpan)
                } else {
                    Ok(Some( * end - * self.start()))
                }
            }
            None => Ok(None),
        }
    }
}

impl<T> From<Fin<T>> for Span<T> {
    #[inline]
    fn from(value: Fin<T>) -> Self {
        Self::Finite(value)
    }
}

impl<T> From<Infin<T>> for Span<T> {
    #[inline]
    fn from(value: Infin<T>) -> Self {
        Self::Infinite(value)
    }
}

impl<T: Default> Default for Span<T> {
    /// 返回 `T::default..`
    #[inline]
    fn default() -> Self {
        Self::new_infinite(T::default())
    }
}

impl<T> Iterator for Span<T>
where
    T: One + CheckedAdd + PartialOrd + Copy,
{
    type Item = T;
    
    #[inline]
    fn next(&mut self) -> Option<Self::Item> {
        match self {
            // 有限范围：迭代 Range<T>，到 end 停止
            Self::Finite(range) => {
                let next_val = range.start.checked_add(&T::one())?;
                if next_val < range.end {
                    range.start = next_val;
                    Some(next_val)
                } else {
                    None
                }
            }
            // 无限范围：一直迭代，永不停止
            Self::Infinite(range) => {
                let current = range.start;
                range.start = current.checked_add(&T::one())?;
                Some(current)
            }
        }
    }
}

impl<T: fmt::Display> fmt::Display for Span<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Finite(r) => write!(f, "[{}, {})", r.start, r.end),
            Self::Infinite(r) => write!(f, "[{}, +∞)", r.start),
        }
    }
}