// Copyright © 2016–2017 University of Malta

// This program is free software: you can redistribute it and/or modify
// it under the terms of either
//
// * the GNU Lesser General Public License as published by the Free
//   Software Foundation, either version 3 of the License, or (at your
//   option) any later version, or
//
// * the GNU General Public License as published by the Free Software
//   Foundation, either version 3 of the License, or (at your option)
//   any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program.  If not, see <http://www.gnu.org/licenses/>.

//! # Rust bindings for GMP and MPFR
//!
//! The `gmp_mpfr` crate uses the
//! [GNU Multiple Precision Arithmetic Library](https://gmplib.org/)
//! (GMP), for integer and rational numbers.
//! The [GNU MPFR Library](http://www.mpfr.org/), a library for
//! multiple-precision floating-point computations, is used for
//! floating-point numbers.
//!
//! To understand the exact operation of the functions in this crate,
//! you can see the online documentation available at the
//! [GMP](https://gmplib.org/manual/) and
//! [MPFR](http://www.mpfr.org/mpfr-current/mpfr.html) pages.
//!
//! Just like GMP and MPFR, this crate is free software: you can
//! redistribute it and/or modify it under the terms of either
//!
//! * the GNU Lesser General Public License as published by the Free
//!   Software Foundation, either version 3 of the License, or (at
//!   your option) any later version, or
//! * the GNU General Public License as published by the Free Software
//!   Foundation, either version 3 of the License, or (at your option)
//!   any later version.
//!
//! # Basic use
//!
//! There are three main types defined in this crate:
//!
//! * [`Integer`](./struct.Integer.html) which holds an arbitrary
//!   precision integer,
//! * [`Rational`](./struct.Rational.html) which holds an arbitrary
//!   precision rational number, and
//! * [`Float`](./struct.Float.html) which holds a floating-point
//!   number with an exact precision.
//!
//! You can construct these types from primitive data types. The
//! standard arithmetic operators work on these types. Operators can
//! also operate on these types and primitive types; in this case, the
//! result is returned as an arbitrary precision type.
//!
//! # Examples
//!
//! You can construct arbitrary precision types from primitive types:
//!
//! ```rust
//! use gmp_mpfr::{Float, FromPrec, Integer, Rational};
//!
//! // Create an integer initialized as zero.
//! let int = Integer::new();
//! // Create a rational number, -22 / 4.
//! let rat = Rational::from((-22, 4));
//! // Create floating-point number with 16 bits of precision.
//! let flo = Float::from_prec(0xff00ff, 16);
//!
//! assert!(int.to_u32() == 0);
//! assert!(int == 0);
//! assert!(rat.numer().to_i32() == -11);
//! assert!(rat.denom().to_i32() == 2);
//! assert!(rat.to_f32() == -5.5);
//! assert!(flo.to_f64() == 0xff0100 as f64);
//! ```
//!
//! Arithmetic operations with mixed arbitrary and primitive types are
//! allowed.
//!
//! ```rust
//! use gmp_mpfr::Integer;
//!
//! let mut a = Integer::from(0xc);
//! a = (a << 80) + 0xffee;
//! assert!(a.to_string_radix(16) == "c0000000000000000ffee");
//! //                                 ^   ^   ^   ^   ^
//! //                                80  64  48  32  16
//! ```
//!
//! Note that in the above example, there is only one construction.
//! The `Integer` instance is moved into the shift operation so that
//! the result can be stored in the same instance, then that result is
//! similarly consumed by the addition operation.

extern crate gmp_mpfr_sys;

mod float;
mod integer;
mod rational;

pub use float::{Constant, Exp, Float, Prec, Round, Special, exp_max, exp_min,
                prec_max, prec_min};
pub use integer::{BitCount, Integer};
pub use rational::{MutNumerDenom, Rational};
use std::cmp::Ordering;

/// Assigns to a number from another value.
pub trait Assign<T> {
    /// Peforms the assignement.
    fn assign(&mut self, T);
}

/// Assigns to a number from another value, applying the specified
/// rounding method.
pub trait AssignRound<T> {
    /// Peforms the assignment and rounding.
    fn assign_round(&mut self, T, Round) -> Ordering;
}

/// Construct `Self` via a conversion with a specified precision.
pub trait FromPrec<T> {
    /// Performs the conversion.
    fn from_prec(T, Prec) -> Self;
}

/// Construct `Self` via a conversion with a specified precision,
/// applying the specified rounding method.
pub trait FromPrecRound<T>
    where Self: Sized
{
    /// Performs the conversion.
    fn from_prec_round(T, Prec, Round) -> (Self, Ordering);
}

/// Negates the value inside `self`.
pub trait NegAssign {
    /// Peforms the negation.
    fn neg_assign(&mut self);
}

/// Provides negation with a specified rounding method.
pub trait NegRound {
    /// The resulting type after the negation.
    type Output;
    /// Performs the negation.
    fn neg_round(self, Round) -> (Self::Output, Ordering);
}

/// Subtract and assigns the result to the rhs operand.
/// `rhs.sub_from_assign(lhs)` has the same effect as
/// `rhs = lhs - rhs`.
///
/// # Examples
///
/// ```rust
/// use gmp_mpfr::{Integer, SubFromAssign};
/// let mut i = Integer::from(10);
/// i.sub_from_assign(100);
/// // i = 100 - 10
/// assert!(i == 90);
/// ```
pub trait SubFromAssign<Lhs = Self> {
    /// Peforms the subtraction.
    fn sub_from_assign(&mut self, Lhs);
}

/// Divide and assign the result to the rhs operand.
/// `rhs.div_from_assign(lhs)` has the same effect as
/// `rhs = lhs / rhs`.
///
/// # Examples
///
/// ```rust
/// use gmp_mpfr::{DivFromAssign, Float, FromPrec};
/// let mut f = Float::from_prec(1.5, 53);
/// f.div_from_assign(3);
/// // f = 3 / 1.5
/// assert!(f == 2);
/// ```
pub trait DivFromAssign<Lhs = Self> {
    /// Peforms the division.
    fn div_from_assign(&mut self, Lhs);
}

/// Provides addition with a specified rounding method.
pub trait AddRound<T> {
    /// The resulting type after the addition.
    type Output;
    /// Performs the addition.
    fn add_round(self, T, Round) -> (Self::Output, Ordering);
}

/// Provides subtraction with a specified rounding method.
pub trait SubRound<T> {
    /// The resulting type after the subtraction.
    type Output;
    /// Performs the subtraction.
    fn sub_round(self, T, Round) -> (Self::Output, Ordering);
}

/// Provides multiplication with a specified rounding method.
pub trait MulRound<T> {
    /// The resulting type after the multiplication.
    type Output;
    /// Performs the multiplication.
    fn mul_round(self, T, Round) -> (Self::Output, Ordering);
}

/// Provides division with a specified rounding method.
pub trait DivRound<T> {
    /// The resulting type after the division.
    type Output;
    /// Performs the division.
    fn div_round(self, T, Round) -> (Self::Output, Ordering);
}

/// Provides the left shift operation with a specified rounding
/// method.
pub trait ShlRound<T> {
    /// The resulting type after the left shift operation.
    type Output;
    /// Performs the left shift operation.
    fn shl_round(self, T, Round) -> (Self::Output, Ordering);
}

/// Provides the right shift operation with a specified rounding
/// method.
pub trait ShrRound<T> {
    /// The resulting type after the right shift operation.
    type Output;
    /// Performs the right shift operation.
    fn shr_round(self, T, Round) -> (Self::Output, Ordering);
}

/// Provides the power operation.
pub trait Pow<T> {
    /// The resulting type after the power operation.
    type Output;
    /// Performs the power operation.
    fn pow(self, T) -> Self::Output;
}

/// Provides the power operation inside `self`.
pub trait PowAssign<T> {
    /// Peforms the power operation.
    fn pow_assign(&mut self, T);
}

/// Provides the power operation inside `self` with a specified
/// rounding method.
pub trait PowRound<T> {
    /// The resulting type after the power operation.
    type Output;
    /// Performs the power operation.
    fn pow_round(self, T, Round) -> (Self::Output, Ordering);
}