lim 0.1.0

//! `lim` provides a robust, generic bounding limit type for Rust.
//!
//! It allows you to define a value constrained within a specific range,
//! with configurable inclusive or exclusive bounds. When modifying the value
//! or the bounds, `lim` guarantees the constraints are maintained, offering
//! safe clamping and fine-grained, structured error handling via `thiserror`.
//!
//! # Examples
//!
//! ```
//! use lim::{Lim, LimError};
//!
//! // Create a value between 0 and 10 (inclusive)
//! let mut health = Lim::new(10, 0, 10, true, true).unwrap();
//! assert_eq!(*health, 10);
//!
//! // Attempt to set a value out of bounds without clamping
//! assert!(matches!(health.set_value(15), Err(LimError::OutOfBounds { .. })));
//!
//! // Safely clamp to a new bound
//! health.set_max(5, true, true).unwrap();
//! assert_eq!(*health, 5);
//! ```

use std::{fmt::Debug, ops::Deref};
use serde::{Deserialize, Deserializer, Serialize};
use thiserror::Error;

/// Errors that can occur when manipulating a [`Lim`] instance.
///
/// This enum provides structured, fine-grained error variants to help
/// callers understand exactly why an operation failed, rather than
/// relying on generic string messages.
#[derive(Debug, Error)]
pub enum LimError<T: Debug> {
    /// The defined bounds are mathematically invalid (e.g., `min > max`).
    #[error("invalid bounds: min ({min:?}) > max ({max:?})")]
    InvalidBounds {
        min: T,
        max: T,
    },

    /// The value falls outside the defined bounds, and clamping was either
    /// disabled or not applicable.
    #[error("value ({value:?}) out of bounds (min: {min:?}, max: {max:?})")]
    OutOfBounds {
        value: T,
        min: T,
        max: T,
    },

    /// Clamping was requested, but the target bound is exclusive, making it
    /// mathematically impossible to clamp the value exactly to the bound.
    #[error("cannot clamp to exclusive bound ({bound:?})")]
    ExclusiveBoundClamp {
        bound: T,
    },

    /// The current value sits exactly on a new exclusive bound, creating
    /// ambiguity about which valid value to clamp to.
    #[error("ambiguous clamp at exclusive bound ({value:?})")]
    AmbiguousClamp {
        value: T,
    },
}

#[derive(Deserialize)]
struct LimHelper<T> {
    value: T,
    min: T,
    max: T,
    include_min: bool,
    include_max: bool,
}

/// A strictly typed bounding limit that guarantees a value stays within
/// defined constraints.
///
/// `Lim` encapsulates a `value` along with its `min` and `max` bounds.
/// Bounds can be configured as inclusive or exclusive. Any mutation
/// to the value or the bounds is strictly validated to maintain the
/// mathematical invariants of the range.
#[derive(Serialize, Debug, Clone)]
pub struct Lim<T: PartialOrd + Clone + Debug> {
    value: T,
    min: T,
    max: T,
    include_min: bool,
    include_max: bool,
}

impl<T: Clone + Copy + PartialOrd + Debug> Copy for Lim<T> {}

impl<T: Clone + PartialOrd + Debug> Lim<T> {
    /// Creates a new `Lim` instance.
    ///
    /// # Arguments
    /// * `value` - The initial value.
    /// * `min` - The lower bound.
    /// * `max` - The upper bound.
    /// * `include_min` - Whether the lower bound is inclusive (`>=`) or exclusive (`>`).
    /// * `include_max` - Whether the upper bound is inclusive (`<=`) or exclusive (`<`).
    ///
    /// # Errors
    /// Returns [`LimError::InvalidBounds`] if `min > max`.
    /// Returns [`LimError::OutOfBounds`] if `value` does not satisfy the bounds.
    pub fn new(value: T, min: T, max: T, include_min: bool, include_max: bool) -> Result<Self, LimError<T>> {
        if min > max {
            return Err(LimError::InvalidBounds {
                min,
                max,
            });
        }

        let min_ok = if include_min {
            value >= min
        } else {
            value > min
        };
        let max_ok = if include_max {
            value <= max
        } else {
            value < max
        };

        if min_ok && max_ok {
            Ok(Self {
                value,
                min,
                max,
                include_min,
                include_max,
            })
        } else {
            Err(LimError::OutOfBounds { value, min, max })
        }
    }

    /// Returns a reference to the current value.
    pub fn value(&self) -> &T {
        &self.value
    }

    /// Returns a reference to the lower bound.
    pub fn min(&self) -> &T {
        &self.min
    }

    /// Returns a reference to the upper bound.
    pub fn max(&self) -> &T {
        &self.max
    }

    /// Returns `true` if the lower bound is inclusive.
    pub fn include_min(&self) -> bool {
        self.include_min
    }

    /// Returns `true` if the upper bound is inclusive.
    pub fn include_max(&self) -> bool {
        self.include_max
    }

    /// Checks if a given value satisfies the current bounds.
    pub fn contains(&self, value: &T) -> bool {
        let min_ok = if self.include_min {
            value >= &self.min
        } else {
            value > &self.min
        };
        let max_ok = if self.include_max {
            value <= &self.max
        } else {
            value < &self.max
        };
        min_ok && max_ok
    }

    /// Updates the current value.
    ///
    /// # Errors
    /// Returns [`LimError::OutOfBounds`] if the new value does not satisfy the current bounds.
    pub fn set_value(&mut self, value: T) -> Result<(), LimError<T>> {
        if self.contains(&value) {
            self.value = value;
        } else {
            return Err(LimError::OutOfBounds {
                value,
                min: self.min.clone(),
                max: self.max.clone(),
            });
        }
        Ok(())
    }

    /// Updates the lower bound.
    ///
    /// # Arguments
    /// * `min` - The new lower bound.
    /// * `include_min` - Whether the new bound is inclusive or exclusive.
    /// * `clamp` - If `true` and the current value falls outside the new bound,
    ///   the value will be clamped to the new bound (if mathematically possible).
    ///   If `false`, an error is returned if the value is out of bounds.
    ///
    /// # Errors
    /// - [`LimError::InvalidBounds`]: If `min > current_max`.
    /// - [`LimError::OutOfBounds`]: If the current value is out of bounds and `clamp` is false.
    /// - [`LimError::ExclusiveBoundClamp`]: If `clamp` is true, but the new bound is exclusive
    ///   and the value cannot be safely clamped to it.
    /// - [`LimError::AmbiguousClamp`]: If the current value exactly equals the new exclusive bound.
    pub fn set_min(&mut self, min: T, include_min: bool, clamp: bool) -> Result<(), LimError<T>> {
        if min > self.max {
            return Err(LimError::InvalidBounds {
                min,
                max: self.max.clone(),
            });
        }

        let value_ok = if include_min {
            self.value >= min
        } else {
            self.value > min
        };

        if value_ok {
            self.min = min;
            self.include_min = include_min;
            Ok(())
        } else if include_min && clamp {
            self.value = min.clone();
            self.min = min;
            self.include_min = include_min;
            Ok(())
        } else {
            if clamp {
                if self.value == min && !include_min {
                    Err(LimError::AmbiguousClamp {
                        value: self.value.clone(),
                    })
                } else {
                    Err(LimError::ExclusiveBoundClamp {
                        bound: min,
                    })
                }
            } else if !include_min {
                Err(LimError::OutOfBounds {
                    value: self.value.clone(),
                    min,
                    max: self.max.clone(),
                })
            } else {
                Err(LimError::OutOfBounds {
                    value: self.value.clone(),
                    min,
                    max: self.max.clone(),
                })
            }
        }
    }

    /// Updates the upper bound.
    ///
    /// # Arguments
    /// * `max` - The new upper bound.
    /// * `include_max` - Whether the new bound is inclusive or exclusive.
    /// * `clamp` - If `true` and the current value falls outside the new bound,
    ///   the value will be clamped to the new bound (if mathematically possible).
    ///   If `false`, an error is returned if the value is out of bounds.
    ///
    /// # Errors
    /// - [`LimError::InvalidBounds`]: If `max < current_min`.
    /// - [`LimError::OutOfBounds`]: If the current value is out of bounds and `clamp` is false.
    /// - [`LimError::ExclusiveBoundClamp`]: If `clamp` is true, but the new bound is exclusive
    ///   and the value cannot be safely clamped to it.
    /// - [`LimError::AmbiguousClamp`]: If the current value exactly equals the new exclusive bound.
    pub fn set_max(&mut self, max: T, include_max: bool, clamp: bool) -> Result<(), LimError<T>> {
        if max < self.min {
            return Err(LimError::InvalidBounds {
                min: self.min.clone(),
                max,
            });
        }

        let value_ok = if include_max {
            self.value <= max
        } else {
            self.value < max
        };

        if value_ok {
            self.max = max;
            self.include_max = include_max;
            Ok(())
        } else if include_max && clamp {
            self.value = max.clone();
            self.max = max;
            self.include_max = include_max;
            Ok(())
        } else {
            if clamp {
                if self.value == max && !include_max {
                    Err(LimError::AmbiguousClamp {
                        value: self.value.clone(),
                    })
                } else {
                    Err(LimError::ExclusiveBoundClamp {
                        bound: max,
                    })
                }
            } else if !include_max {
                Err(LimError::OutOfBounds {
                    value: self.value.clone(),
                    min: self.min.clone(),
                    max,
                })
            } else {
                Err(LimError::OutOfBounds {
                    value: self.value.clone(),
                    min: self.min.clone(),
                    max,
                })
            }
        }
    }
    
    /// Updates both the lower and upper bounds simultaneously.
    ///
    /// # Arguments
    /// * `min` - The new lower bound.
    /// * `max` - The new upper bound.
    /// * `include_min` - Whether the new lower bound is inclusive or exclusive.
    /// * `include_max` - Whether the new upper bound is inclusive or exclusive.
    /// * `clamp` - If `true`, the current value will be clamped to fit within the new bounds.
    ///
    /// # Errors
    /// Returns specific [`LimError`] variants if the bounds are invalid, if clamping is
    /// impossible due to exclusive bounds, or if the value is out of bounds and `clamp` is false.
    pub fn set_bounds(
        &mut self,
        min: T,
        max: T,
        include_min: bool,
        include_max: bool,
        clamp: bool
    ) -> Result<(), LimError<T>> {
        if min > max {
            return Err(LimError::InvalidBounds {
                min,
                max,
            });
        }

        let min_ok = if include_min {
            self.value >= min
        } else {
            self.value > min
        };
        let max_ok = if include_max {
            self.value <= max
        } else {
            self.value < max
        };
        let value_ok = min_ok && max_ok;

        if value_ok {
            self.min = min;
            self.max = max;
            self.include_min = include_min;
            self.include_max = include_max;
            Ok(())
        } else if clamp {
            let mut new_value = self.value.clone();

            if !min_ok {
                if self.value == min && !include_min {
                    return Err(LimError::AmbiguousClamp {
                        value: self.value.clone(),
                    });
                }
                if !include_min {
                    return Err(LimError::ExclusiveBoundClamp {
                        bound: min,
                    });
                }
                new_value = min.clone();
            }

            if !max_ok {
                if new_value == max && !include_max {
                    return Err(LimError::AmbiguousClamp {
                        value: new_value.clone(),
                    });
                }
                if !include_max {
                    return Err(LimError::ExclusiveBoundClamp {
                        bound: max,
                    });
                }
                if new_value > max || (!include_max && new_value == max) {
                    if new_value == max && !include_max {
                        return Err(LimError::AmbiguousClamp {
                            value: new_value.clone(),
                        });
                    }
                    new_value = max.clone();
                }
            }

            self.value = new_value;
            self.min = min;
            self.max = max;
            self.include_min = include_min;
            self.include_max = include_max;
            Ok(())
        } else {
            if !min_ok {
                if !include_min && self.value == min {
                    Err(LimError::OutOfBounds {
                        value: self.value.clone(),
                        min,
                        max,
                    })
                } else {
                    Err(LimError::OutOfBounds {
                        value: self.value.clone(),
                        min,
                        max,
                    })
                }
            } else {
                if !include_max && self.value == max {
                    Err(LimError::OutOfBounds {
                        value: self.value.clone(),
                        min,
                        max,
                    })
                } else {
                    Err(LimError::OutOfBounds {
                        value: self.value.clone(),
                        min,
                        max,
                    })
                }
            }
        }
    }
}

/// Allows transparent access to the underlying value.
impl<T: PartialOrd + Clone + Debug> Deref for Lim<T> {
    type Target = T;

    fn deref(&self) -> &Self::Target {
        &self.value
    }
}

/// Implements deserialization, strictly validating the bounds and value
/// invariants during the parsing process.
impl<'de, T> Deserialize<'de> for Lim<T>
where
    T: Deserialize<'de> + PartialOrd + Clone + Debug,
{
    fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        let helper = LimHelper::deserialize(deserializer)?;
        Lim::new(
            helper.value,
            helper.min,
            helper.max,
            helper.include_min,
            helper.include_max,
        )
        .map_err(|e| serde::de::Error::custom(format!("Lim invariant violated: {}", e)))
    }
}