calcucalc 0.2.1

#![forbid(unsafe_code)]
#![warn(clippy::pedantic)]

//! # 🔢 calcucalc 📈
//!
//! A Rust library for doing general-purpose **calculus**.
//!
//! ## 🌱 Getting Started
//!
//! The goal of this project is to provide a simple and easy-to-use library for doing calculus operations.
//!
//! ### 🦀 Prerequisites
//!
//! You will need to have Rust and the Cargo package manager installed on your machine. You can install them by following the instructions on the [official Rust lang site](https://www.rust-lang.org/tools/install).
//!
//! ### 🖥️ Installing
//!
//! To install this library, add the following to your `Cargo.toml` file:
//!
//! ```toml
//! [dependencies]
//! calcucalc = "VERSION_GOES_HERE"
//! ```
//!
//! It is recommended to use the latest version. You can find the latest version on [this library's crates.io page](https://crates.io/crates/calcucalc).
//!
//! ## 🛠️ Usage
//!
//! This documentation provides examples of how to use the library. Just navigate to the item you want to learn more about, and the description and examples will be there.
//!
//! Overall, this library relies heavily on the use of the `f64` type for the sake of flexibility and generality.
//!

use std::panic::{RefUnwindSafe, UnwindSafe};

use serde::{Deserialize, Serialize};
use static_assertions::assert_impl_all;

pub mod math_helpers;

/// A monomial is a product of a coefficient and an exponent of x.
/// For example, in the monomial `3x^2`, the coefficient is `3` and the exponent of x is `2`.
/// The monomial `3x^2` can be represented as a struct with the coefficient `3` and the exponent `2`. Using the calcucalc library, this monomial would be represented in this way
/// ```rust
/// use calcucalc::Monomial;
///
/// let three_x_squared = Monomial { c: 3.0, e: 2.0 }; // 3x^2
/// ```
///
/// One of the beautiful things about the monomial is its flexibility. For example, we can represent a **fraction** like `5/x` as a monomial. This is because `5/x` is equivalent to `5 * x^-1`. In this case, the coefficient is `5` and the exponent of x is `-1`.
///
/// ```rust
/// use calcucalc::Monomial;
///
/// let five_divided_by_x = Monomial { c: 5.0, e: -1.0 }; // 5/x
/// ```
///
/// We can also represent a **constant** as a monomial. For example, the number `1` can be represented as `1 * x^0`. In this case, the coefficient is `1` and the exponent of x is `0`.
///
/// ```rust
/// use calcucalc::Monomial;
///
/// let one = Monomial { c: 1.0, e: 0.0 }; // 1
/// ```
/// This library is intended to be as general-purpose as possible, which is why the coefficient and exponent are represented as floating-point numbers (as opposed to integers). This allows for more flexibility in the types of functions that can be represented.
///
/// Here is a table showing example monomials and their corresponding struct representations:
/// | Monomial | Struct Representation |
/// | --- | --- |
/// | `3x^2` | `Monomial { c: 3.0, e: 2.0 }` |
/// | `2x` | `Monomial { c: 2.0, e: 1.0 }` |
/// | `1` | `Monomial { c: 1.0, e: 0.0 }` |
/// | `0` | `Monomial { c: 0.0, e: 0.0 }` |
/// | `5x^-1` aka `5/x` | `Monomial { c: 5.0, e: -1.0 }` |
/// | `3x^-2` aka `3/(x^2)` | `Monomial { c: 3.0, e: -2.0 }` |
/// | `2x^0.5` aka `2 * √x` | `Monomial { c: 2.0, e: 0.5 }` |
/// | `1.5x^0.25` aka `1.5 * ∜x` | `Monomial { c: 1.5, e: 0.25 }` |
/// | `2x^π` | `Monomial { c: 2.0, e: std::f64::consts::PI }` |
/// | `3x^e` | `Monomial { c: 3.0, e: std::f64::consts::E }` |
///
/// #### Accessing monomial fields
///
/// The coefficient and exponent of a monomial can be accessed using the `c` and `e` fields, respectively.
///
/// ```rust
/// use calcucalc::Monomial;
///
/// let m = Monomial { c: 1.0, e: 2.0 };
/// assert_eq!(m.c, 1.0);
/// assert_eq!(m.e, 2.0);
/// ```
///
#[derive(Clone, Copy, Debug, Default, Deserialize, PartialEq, PartialOrd, Serialize)]
#[must_use]
pub struct Monomial {
    /// <u>c</u>oefficient
    pub c: f64, // Coefficient
    /// <u>e</u>xponent
    pub e: f64, // Exponent
}

assert_impl_all!(Monomial: RefUnwindSafe, Send, Sized, Sync, Unpin, UnwindSafe);

impl Monomial {
    /// Creates a new monomial
    ///
    /// #### Example
    /// ```rust
    /// use calcucalc::Monomial;
    ///
    /// let m = Monomial::new(1.0, 2.0);
    /// assert_eq!(m, Monomial { c: 1.0, e: 2.0 });
    /// ```
    pub fn new(c: f64, e: f64) -> Self {
        Self { c, e }
    }

    /// Calculates the value of the monomial for a given value of x.
    ///
    /// #### Example
    /// ```rust
    /// use calcucalc::Monomial;
    ///
    /// let m = Monomial { c: 2.0, e: 3.0 };
    /// assert_eq!(m.value(2.0), 16.0);
    /// assert_eq!(m.value(3.0), 54.0);
    /// assert_eq!(m.value(4.0), 128.0);
    /// assert_eq!(m.value(5.0), 250.0);
    /// ```
    #[must_use]
    pub fn value(&self, x: f64) -> f64 {
        self.c * (x.powf(self.e))
    }

    /// Adds one monomial to another, if they have the same exponent of x.
    ///
    /// #### Example
    /// ```rust
    /// use calcucalc::Monomial;
    ///
    /// let m1 = Monomial { c: 1.0, e: 3.141592653589793 };
    /// let m2 = Monomial { c: 2.0, e: 3.141592653589793 };
    /// let m3 = Monomial { c: 3.0, e: 3.141592653589793 };
    /// assert_eq!(m3, m1.add_monomial_of_same_power(&m2).unwrap());
    /// ```
    ///
    /// ## Errors
    ///
    /// If the two monomials do not have the same exponent of x, an error is returned.
    ///
    pub fn add_monomial_of_same_power(&self, other: &Self) -> Result<Self, String> {
        if !math_helpers::is_equal_within_tolerance_to(&self.e, &other.e) {
            return Err("Cannot add monomials with different powers of x.".to_string());
        }
        Ok(Self {
            c: self.c + other.c,
            e: self.e,
        })
    }

    /// Multiplies one monomial by another.
    ///
    /// #### Example
    /// ```rust
    /// use calcucalc::Monomial;
    ///
    /// let m1 = Monomial { c: 1.0, e: 3.141592653589793 };
    /// let m2 = Monomial { c: 2.0, e: 3.141592653589793 };
    /// let m3 = Monomial { c: 2.0, e: 6.283185307179586 };
    /// assert_eq!(m3, m1.multiply_monomial(&m2));
    /// ```
    pub fn multiply_monomial(&self, other: &Self) -> Self {
        Self {
            c: self.c * other.c,
            e: self.e + other.e,
        }
    }

    /// Calculates the derivative of the monomial.
    /// The derivative of a monomial is the product of the exponent and the coefficient, times x raised to the power of the exponent minus one.
    ///
    /// #### Example
    /// ```rust
    /// use calcucalc::Monomial;
    ///
    /// let m = Monomial { c: 1.0, e: 3.141592653589793 };
    /// let m_derivative = Monomial { c: 3.141592653589793, e: 2.141592653589793 };
    /// assert_eq!(m_derivative, m.derivative());
    /// ```
    pub fn derivative(&self) -> Self {
        Self {
            c: self.c * self.e,
            e: self.e - 1_f64,
        }
    }

    /// Calculates the nth derivative of the monomial.
    ///
    /// The nth derivative of a monomial is the result of taking the derivative of the monomial `n` times.
    ///
    /// #### Example
    /// ```rust
    /// use calcucalc::Monomial;
    ///
    /// let m = Monomial { c: 1.0, e: 3.141592653589793 };
    /// let m_nth_derivative = m.nth_derivative(2);
    /// assert_eq!(m_nth_derivative, Monomial { c: 6.728011747499565, e: 1.1415926535897931 });
    /// ```
    pub fn nth_derivative(&self, n: u32) -> Self {
        let mut new_monomial = *self;
        for _ in 0..n {
            new_monomial = new_monomial.derivative();
        }
        new_monomial
    }

    /// Checks if two monomials are equal within a certain tolerance.
    /// The default tolerance is determined by the `is_equal_within_tolerance_to` function in the `math_helpers` module.
    ///
    /// #### Example
    /// ```rust
    /// use calcucalc::Monomial;
    ///
    /// let m1 = Monomial { c: 1.00000000001, e: 2.00000000001 };
    /// let m2 = Monomial { c: 1.00000000002, e: 2.00000000002 };
    /// assert!(m1.is_equal_within_tolerance_to(&m2));
    /// ```
    #[must_use]
    pub fn is_equal_within_tolerance_to(&self, other: &Self) -> bool {
        let c_equal = math_helpers::is_equal_within_tolerance_to(&self.c, &other.c);
        let e_equal = math_helpers::is_equal_within_tolerance_to(&self.e, &other.e);

        c_equal && e_equal
    }
}

/// A polynomial is a sum of monomials.
/// For example, the polynomial `3x^2 + 2x + 1` can be represented as a vector of monomials, which is how this library represents it.
///
/// #### Example
/// ```rust
/// use calcucalc::{Monomial, Polynomial};
///
/// let my_polynomial = Polynomial(vec![
///    Monomial { c: 3.0, e: 2.0 },
///    Monomial { c: 2.0, e: 1.0 },
///    Monomial { c: 1.0, e: 0.0 },
/// ]);
/// ```
#[derive(Clone, Debug, Default, Deserialize, PartialEq, PartialOrd, Serialize)]
#[must_use]
pub struct Polynomial(pub Vec<Monomial>);

assert_impl_all!(Polynomial: RefUnwindSafe, Send, Sized, Sync, Unpin, UnwindSafe);

impl Polynomial {
    /// Creates a new polynomial with no monomials.
    ///
    /// #### Example
    /// ```rust
    /// use calcucalc::Polynomial;
    ///
    /// let my_polynomial = Polynomial::new();
    /// assert_eq!(my_polynomial.0.len(), 0);
    /// assert_eq!(my_polynomial, Polynomial(vec![]));
    /// ```
    pub fn new() -> Self {
        Self(vec![])
    }

    /// Calculates the value of a polynomial for a given value of x.
    ///
    /// #### Example
    /// ```rust
    /// use calcucalc::{Monomial, Polynomial};
    ///
    /// let my_polynomial = Polynomial(vec![
    ///    Monomial { c: 1.0, e: 2.0 },
    ///    Monomial { c: 3.0, e: 1.0 },
    ///    Monomial { c: 2.0, e: 0.0 },
    /// ]);
    /// assert_eq!(my_polynomial.value(-1.0), 0.0);
    /// assert_eq!(my_polynomial.value(0.0), 2.0);
    /// assert_eq!(my_polynomial.value(1.0), 6.0);
    /// assert_eq!(my_polynomial.value(2.0), 12.0);
    /// assert_eq!(my_polynomial.value(3.0), 20.0);
    /// ```
    #[must_use]
    pub fn value(&self, x: f64) -> f64 {
        let elements = &self.0;
        let mut value = 0_f64;
        for element in elements {
            value += element.value(x);
        }
        value
    }

    /// Simplifies the polynomial by combining elements which have the same exponent of x, and then sorting the elements by the exponent of x (in descending order).
    ///
    /// This function is equivalent to calling `simplify_by_combining_alike_powers()`, `eliminate_zero_coefficients()`, and `sort_by_exponent()` in sequence.
    ///
    /// In most cases, if you want to simplify a polynomial, you should use this function.
    ///
    /// #### Example
    /// ```rust
    /// use calcucalc::{Monomial, Polynomial};
    ///
    /// let my_polynomial = Polynomial(vec![
    ///     Monomial { c: 1.0, e: 2.0 },
    ///     Monomial { c: -5.0, e: 0.0 },
    ///     Monomial { c: 2.0, e: 2.0 },
    ///     Monomial { c: 2.0, e: 1.0 },
    ///     Monomial { c: 0.0, e: 1.0 },
    ///     Monomial { c: 3.0, e: 0.0 },
    ///     Monomial { c: 500.0, e: 0.453 },
    ///     Monomial { c: -500.0, e: 0.453 },
    /// ]);
    ///
    /// let simplified_polynomial = my_polynomial.simplified().unwrap();
    ///
    /// assert_eq!(simplified_polynomial, Polynomial(vec![
    ///     Monomial { c: 3.0, e: 2.0 },
    ///     Monomial { c: 2.0, e: 1.0 },
    ///     Monomial { c: -2.0, e: 0.0 },
    /// ]));
    /// ```
    ///
    /// ## Errors
    ///
    /// If two monomials with different exponents are attempted to be combined, an error is returned.
    pub fn simplified(&self) -> Result<Self, String> {
        Ok(self
            .simplify_by_combining_alike_powers()?
            .eliminate_zero_coefficients()
            .sort_by_exponent())
    }

    /// Combines elements which have the same exponent of x.
    ///
    /// #### Example
    /// ```rust
    /// use calcucalc::{Monomial, Polynomial};
    ///
    /// let my_polynomial = Polynomial(vec![
    ///     Monomial { c: 1.0, e: 2.0 },
    ///     Monomial { c: 2.0, e: 2.0 },
    ///     Monomial { c: 3.0, e: 2.0 },
    /// ]);
    /// let simplified_polynomial = my_polynomial.simplify_by_combining_alike_powers().unwrap();
    /// assert_eq!(simplified_polynomial, Polynomial(vec![
    ///     Monomial { c: 6.0, e: 2.0 },
    /// ]));
    /// ```
    /// ## Errors
    ///
    /// If two monomials with different exponents are attempted to be combined, an error is returned.
    pub fn simplify_by_combining_alike_powers(&self) -> Result<Self, String> {
        let elements = &self.0;
        let mut simplified_elements = Self::new();

        let mut first_element_transferred = false;

        for element in elements {
            if !first_element_transferred {
                simplified_elements.0.push(*element);
                first_element_transferred = true;
                continue;
            }

            let mut found_match = false;
            for simplified_element in &mut simplified_elements.0 {
                if math_helpers::is_equal_within_tolerance_to(&element.e, &simplified_element.e) {
                    *simplified_element = simplified_element.add_monomial_of_same_power(element)?;
                    found_match = true;
                    break;
                }
            }
            if !found_match {
                simplified_elements.0.push(*element);
            }
        }
        Ok(simplified_elements)
    }

    /// Eliminates elements with coefficients of `0`.
    ///
    /// As `0` multiplied by any number is `0`, elements with a coefficient of `0` do not affect the value of the polynomial, and can be safely ignored.
    ///
    /// #### Example
    /// ```rust
    /// use calcucalc::{Monomial, Polynomial};
    ///
    /// let my_polynomial = Polynomial(vec![
    ///     Monomial { c: 1.0, e: 2.0 },
    ///     Monomial { c: 0.0, e: 1.0 },
    /// ]);
    /// let simplified_polynomial = my_polynomial.eliminate_zero_coefficients();
    /// assert_eq!(simplified_polynomial, Polynomial(vec![
    ///    Monomial { c: 1.0, e: 2.0 },
    /// ]));
    /// ```
    pub fn eliminate_zero_coefficients(&self) -> Self {
        let elements = &self.0;
        let mut new_elements = vec![];
        for element in elements {
            if element.c != 0_f64 {
                new_elements.push(*element);
            }
        }
        Self(new_elements)
    }

    /// Sorts the elements of the polynomial by the exponent of x (in descending order).
    ///
    /// #### Example
    /// ```rust
    /// use calcucalc::{Monomial, Polynomial};
    ///
    /// let my_polynomial = Polynomial(vec![
    ///     Monomial { c: 3.0, e: -2.0 },
    ///     Monomial { c: 3.0, e: 0.0 },
    ///     Monomial { c: 3.0, e: 0.5 },
    ///     Monomial { c: 3.0, e: 25.4 },
    ///     Monomial { c: 3.0, e: 0.0 },
    ///     Monomial { c: 3.0, e: 12.0 },
    /// ]);
    /// let sorted_polynomial = my_polynomial.sort_by_exponent();
    /// assert_eq!(sorted_polynomial, Polynomial(vec![
    ///     Monomial { c: 3.0, e: 25.4 },
    ///     Monomial { c: 3.0, e: 12.0 },
    ///     Monomial { c: 3.0, e: 0.5 },
    ///     Monomial { c: 3.0, e: 0.0 },
    ///     Monomial { c: 3.0, e: 0.0 },  // Does not perform any combination of elements with the same exponent. Only sorts.
    ///     Monomial { c: 3.0, e: -2.0 },
    /// ]));
    /// ```
    pub fn sort_by_exponent(&self) -> Self {
        let mut elements = self.0.clone();
        elements.sort_by(|a, b| b.e.partial_cmp(&a.e).unwrap_or(std::cmp::Ordering::Equal));
        Self(elements)
    }

    /// Adds one polynomial to another.
    ///
    /// #### Example
    /// ```rust
    /// use calcucalc::{Monomial, Polynomial};
    ///
    /// let my_polynomial1 = Polynomial(vec![
    ///     Monomial { c: 1.0, e: 2.0 },
    ///     Monomial { c: 2.0, e: 1.0 },
    /// ]);
    /// let my_polynomial2 = Polynomial(vec![
    ///     Monomial { c: 3.0, e: 2.0 },
    ///     Monomial { c: 4.0, e: 1.0 },
    /// ]);
    /// let my_sum = my_polynomial1.add_polynomial(my_polynomial2).unwrap();
    /// assert_eq!(my_sum, Polynomial(vec![
    ///     Monomial { c: 4.0, e: 2.0 },
    ///     Monomial { c: 6.0, e: 1.0 },
    /// ]));
    /// ```
    ///
    /// `add_polynomial()` itself calls `simplified()` before returning the result.
    ///
    /// ## Errors
    ///
    /// If two monomials with different exponents are attempted to be combined, an error is returned.
    pub fn add_polynomial(&self, other: Self) -> Result<Self, String> {
        let mut elements = self.0.clone();
        elements.extend(other.0.clone());
        let new_polynomial = Self(elements);
        new_polynomial.simplified()
    }

    /// Multiplies one polynomial by another.
    ///
    /// #### Example
    /// ```rust
    /// use calcucalc::{Monomial, Polynomial};
    ///
    /// let my_polynomial1 = Polynomial(vec![
    ///    Monomial { c: 1.0, e: 2.0 },
    ///    Monomial { c: 2.0, e: 1.0 },
    /// ]);
    /// let my_polynomial2 = Polynomial(vec![
    ///    Monomial { c: 4.0, e: 1.0 },
    ///    Monomial { c: 3.0, e: 2.0 },
    /// ]);
    /// let my_product = my_polynomial1.multiply_polynomial(my_polynomial2).unwrap();
    /// assert_eq!(my_product, Polynomial(vec![
    ///    Monomial { c: 3.0, e: 4.0 },
    ///    Monomial { c: 10.0, e: 3.0 },
    ///    Monomial { c: 8.0, e: 2.0 },
    /// ]));
    /// ```
    ///
    /// `multiply_polynomial()` itself calls `simplified()` before returning the result.
    ///
    /// ## Errors
    ///
    /// If two monomials with different exponents are attempted to be combined, an error is returned.
    pub fn multiply_polynomial(&self, other: Self) -> Result<Self, String> {
        let mut elements = vec![];
        for element1 in &self.0 {
            for element2 in &other.0 {
                elements.push(element1.multiply_monomial(element2));
            }
        }
        let new_polynomial = Self(elements);
        new_polynomial.simplified()
    }

    /// Calculates the derivative of the polynomial.
    ///
    /// The derivative of a polynomial is the sum of the derivatives of each monomial in the polynomial.
    ///
    /// #### Example
    /// ```rust
    /// use calcucalc::{Monomial, Polynomial};
    ///
    /// let mut my_polynomial = Polynomial(vec![
    ///     Monomial { c: 1.0, e: 2.0 },
    ///     Monomial { c: 2.0, e: 1.0 },
    ///     Monomial { c: 3.0, e: 0.0 },
    /// ]);
    /// let my_derivative = my_polynomial.derivative().unwrap();
    /// assert_eq!(my_derivative, Polynomial(vec![Monomial { c: 2.0, e: 1.0 }, Monomial { c: 2.0, e: 0.0 }]));
    /// ```
    ///
    /// The above code does the same as the following mathematical expression:
    /// ```math
    /// f(x) = x^2 + 2x + 3
    /// f'(x) = 2x + 2
    /// ```
    ///
    /// `derivative()` itself calls `simplified()` before returning the result.
    ///
    /// ## Errors
    ///
    /// If two monomials with different exponents are attempted to be combined, an error is returned.
    pub fn derivative(&self) -> Result<Self, String> {
        let mut elements = vec![];
        for element in &self.0 {
            elements.push(element.derivative());
        }
        Self(elements).simplified()
    }

    /// Calculates the nth derivative of the polynomial.
    ///
    /// The nth derivative of a polynomial is the result of taking the derivative of the polynomial `n` times.
    ///
    /// #### Example
    /// ```rust
    /// use calcucalc::{Monomial, Polynomial};
    ///
    /// let my_polynomial = Polynomial(vec![
    ///     Monomial { c: 1.0, e: 2.0 },
    ///     Monomial { c: 2.0, e: 1.0 },
    ///     Monomial { c: 3.0, e: 0.0 },
    /// ]);
    /// let my_nth_derivative = my_polynomial.nth_derivative(2).unwrap();
    /// assert_eq!(my_nth_derivative, Polynomial(vec![Monomial { c: 2.0, e: 0.0 }]));
    /// ```
    ///
    /// The above code does the same as the following mathematical expression:
    /// ```math
    /// f(x) = x^2 + 2x + 3
    /// f''(x) = 2
    /// ```
    ///
    /// Let's level up the complexity a bit:
    /// ```rust
    /// use calcucalc::{Monomial, Polynomial};
    ///
    /// let my_polynomial = Polynomial(vec![
    ///     Monomial { c: 1.0, e: 3.0 },
    ///     Monomial { c: 2.0, e: 2.0 },
    ///     Monomial { c: 3.0, e: 1.0 },
    ///     Monomial { c: 4.0, e: 0.0 },
    /// ]);
    /// let my_nth_derivative = my_polynomial.nth_derivative(3).unwrap();
    /// assert_eq!(my_nth_derivative, Polynomial(vec![Monomial { c: 6.0, e: 0.0 }]));  // The third derivative of a constant is always 0.
    /// ```
    ///
    /// ## Errors
    ///
    /// If two monomials with different exponents are attempted to be combined, an error is returned.
    pub fn nth_derivative(&self, n: u32) -> Result<Self, String> {
        let mut new_polynomial = self.clone();
        for _ in 0..n {
            new_polynomial = new_polynomial.derivative()?;
        }
        Ok(new_polynomial)
    }

    /// Checks if the polynomial is equal to another polynomial within a certain tolerance.
    ///
    /// This function is to overcome floating point arithmetic errors.
    ///
    /// #### Example
    /// ```rust
    /// use calcucalc::{Monomial, Polynomial};
    ///
    /// let my_polynomial1 = Polynomial(vec![
    ///     Monomial { c: 1.0, e: 2.000000000001 },
    ///     Monomial { c: 1.999999999999, e: 1.0 },
    /// ]);
    /// let my_polynomial2 = Polynomial(vec![
    ///     Monomial { c: 1.0, e: 2.0 },
    ///     Monomial { c: 2.0, e: 1.0 },
    /// ]);
    /// assert!(my_polynomial1.is_equal_within_tolerance_to(my_polynomial2).unwrap());
    /// ```
    ///
    /// The above code will return `true` because the two polynomials are equal within the tolerance defined in the `math_helpers` module.
    ///
    /// ## Errors
    ///
    /// If two monomials with different exponents are attempted to be combined during simplification, an error is returned.
    pub fn is_equal_within_tolerance_to(&self, other: Self) -> Result<bool, String> {
        let simplified_self = self.simplified()?;
        let simplified_other = other.simplified()?;
        if simplified_self.0.len() != simplified_other.0.len() {
            return Ok(false);
        }
        for (element1, element2) in simplified_self.0.iter().zip(simplified_other.0.iter()) {
            if !math_helpers::is_equal_within_tolerance_to(&element1.c, &element2.c)
                || !math_helpers::is_equal_within_tolerance_to(&element1.e, &element2.e)
            {
                return Ok(false);
            }
        }
        Ok(true)
    }

    /// Checks whether the values of a given interval of a polynomial overall is increasing, decreasing, staying constant, or is undefined.
    /// The interval is defined by the start and end values.
    ///
    /// #### Example
    /// ```rust
    /// use calcucalc::{Monomial, Polynomial};
    ///
    /// let my_polynomial = Polynomial(vec![
    ///     Monomial { c: 1.0, e: 2.0 },
    ///     Monomial { c: -2.0, e: 1.0 },
    ///     Monomial { c: 1.0, e: 0.0 },
    /// ]);
    /// assert_eq!(my_polynomial.trend_over_interval(-1.0, 1.0), "decreasing");
    /// assert_eq!(my_polynomial.trend_over_interval(1.0, 2.0), "increasing");
    /// assert_eq!(my_polynomial.trend_over_interval(-1.0, 0.0), "decreasing");
    /// assert_eq!(my_polynomial.trend_over_interval(0.0, 2.0), "constant");
    /// ```
    ///
    /// While it is recommended to order the start and end x-values in ascending order, this function will automatically swap them if they are not.
    pub fn trend_over_interval(&self, start: f64, end: f64) -> String {
        // Validate the start and end x-values are in the correct order,
        // and swap them if they are not.
        let mut start_x = start;
        let mut end_x = end;
        if start_x > end_x {
            std::mem::swap(&mut start_x, &mut end_x);
        }

        let start_value = self.value(start_x);
        let end_value = self.value(end_x);
        if start_value < end_value {
            "increasing".to_string()
        } else if start_value > end_value {
            "decreasing".to_string()
        } else if start_value == end_value {
            "constant".to_string()
        } else {
            "undefined".to_string()
        }
    }

    /// Checks whether a given interval of a polynomial is "concave up", "concave down", or "undefined".
    /// The interval is defined by the start and end values. This function does not take into account anything in between. In other words, it only tells you whether or not the **overall** concavity of the polynomial is up or down over the interval. It says nothing about the concavity at any specific point within the interval.
    ///
    /// #### Example
    /// ```rust
    /// use calcucalc::{Monomial, Polynomial};
    ///
    /// let my_polynomial = Polynomial(vec![
    ///     Monomial { c: 1.0, e: 3.0 },
    ///     Monomial { c: 1.0, e: 2.0 },
    ///     Monomial { c: -2.0, e: 1.0 },
    ///     Monomial { c: 1.0, e: 0.0 },
    /// ]);
    /// assert_eq!(my_polynomial.concavity_over_interval(-2.0, -1.0).unwrap(), "concave down");
    /// assert_eq!(my_polynomial.concavity_over_interval(-1.0, 0.0).unwrap(), "undefined");
    /// assert_eq!(my_polynomial.concavity_over_interval(0.0, 1.0).unwrap(), "concave up");
    ///
    /// ```
    ///
    /// ## Errors
    ///
    /// If the second derivative cannot be calculated, an error is returned.
    pub fn concavity_over_interval(&self, start: f64, end: f64) -> Result<String, String> {
        // Validate the start and end x-values are in the correct order,
        // and swap them if they are not.
        let mut start_x = start;
        let mut end_x = end;
        if start_x > end_x {
            std::mem::swap(&mut start_x, &mut end_x);
        }

        // Calculate the second derivative of the polynomial
        let second_derivative = self.nth_derivative(2)?;

        // Calculate the second derivative at the start and end x-values
        let start_value = second_derivative.value(start_x);
        let end_value = second_derivative.value(end_x);

        if start_value > 0.0 && end_value > 0.0 {
            Ok("concave up".to_string())
        } else if start_value < 0.0 && end_value < 0.0 {
            Ok("concave down".to_string())
        } else {
            Ok("undefined".to_string())
        }
    }
}

#[cfg(test)]
mod tests;