//!
//! Algebraic _multiplicative_ _group_ traits.
//!
//! An algebraic _multiplicative_ _group_ is a _multiplicative_
//! _monoid_ `M`, where each _invertible_ group element `g` has a
//! unique multiplicative _inverse_ denoted `g^-1`.  The inverse
//! operation is called _invert_.
//!
//! # Axioms
//!
//! ```notrust
//! ∀g ∈ M
//! 
//! Inverse: ∃g^-1 ∈ M: g × g^-1 = g^-1 × g = 1.
//! ```
//!
//! # References
//!
//! See [references] for a formal definition of a multiplicative
//! group.
//!
#![doc(include = "../doc/references.md")]

use monoid::mul_monoid::*;


///
/// An algebraic _multiplicative group_.
///
pub trait MulGroup: MulMonoid {

  /// The unique multiplicative inverse of a group element.
  /// Inversion is only defined for _invertible_ group elements.
  fn invert(&self) -> Self;


  /// Test for an _invertible_ group element.
  fn is_invertible(&self) -> bool;


  /// The multiplicative "division" of two group elements.
  fn div(&self, other: &Self) -> Self {
    self.mul(&other.invert())
  }


  /// Test the left axiom of inversion.
  fn axiom_left_invert(&self) -> bool {
     self.invert().mul(self) == Self::one()
  }


  /// Test the right axiom of inversion.
  fn axiom_right_invert(&self) -> bool {
    self.mul(&self.invert()) == Self::one()
  }
}


///
/// A "numeric" algebraic _multiplicative group_.
///
/// `NumAddGroup` trait is for types that only form multiplicative
/// groups when "numeric" comparisons are used, e.g. floating point
/// types.
///
pub trait NumMulGroup: NumMulMonoid {

  /// The unique multiplicative inverse of a group element.
  /// Inversion is only defined for _invertible_ group
  /// elements.
  fn invert(&self) -> Self;


  /// Test for an _invertible_ group element.
  fn is_invertible(&self) -> bool;


  /// The multiplicative "division" of two group elements.
  fn div(&self, other: &Self) -> Self {
    self.mul(&other.invert())
  }


  /// Numerically test the left axiom of inversion.
  fn axiom_left_invert(&self, eps: &Self::Error) -> bool {
    self.invert().mul(self).num_eq(&Self::one(), eps)
  }


  /// Numerically test the right axiom of inversion.
  fn axiom_right_invert(&self, eps: &Self::Error) -> bool {
    self.mul(&self.invert()).num_eq(&Self::one(), eps)
  }
}


///
/// Trait implementation macro for floating point types.
///
/// A macro used to avoid writing repetitive, boilerplate
/// `NumMulGroup` implementations for built-in signed floating point
/// types.  Probably not needed if Rust had a `Float` super-trait.
///
macro_rules! float_num_mul_group {
  ($type:ty) => {
    impl NumMulGroup for $type {
      
      /// Inversion is just floating point inversion.
      fn invert(&self) -> Self {
        1.0 / *self
      }

      /// Non-zero elements are invertible.
      fn is_invertible(&self) -> bool {
        *self != 0.0
      }
    }
  };

  ($type:ty, $($others:ty),+) => {
    float_num_mul_group! {$type}
    float_num_mul_group! {$($others),+}
  };
}


// Numeric multiplicative group floating point types.
float_num_mul_group! {
  f32, f64
}


///
/// 0-tuples form a multiplicative group.
///
impl MulGroup for () {

  /// Inverted value can only be constant `()`.
  fn invert(&self) -> Self {
    ()
  }

  /// The only value is invertible.
  fn is_invertible(&self) -> bool {
    true
  }
}


///
/// 1-tuples form a multiplicative group if their items form a
/// multiplicative group.
///
impl<A: MulGroup> MulGroup for (A,) {

  /// Inversion is by matching element.
  fn invert(&self) -> Self {
    (self.0.invert(), )
  }


  /// Invertibility is across the tuple.
  fn is_invertible(&self) -> bool {
    self.0.is_invertible()
  }  
}


///
/// 1-tuples form a numeric multiplicative group if their
/// corresponding items form numeric multiplicative groups.
///
impl<A: NumMulGroup> NumMulGroup for (A,) {

  /// Inversion is by matching element.
  fn invert(&self) -> Self {
    (self.0.invert(), )
  }


  /// Invertibility is across the tuple.
  fn is_invertible(&self) -> bool {
    self.0.is_invertible()
  }  
}


///
/// 2-tuples form a multiplicative group if their items form a
/// multiplicative group.
///
impl<A: MulGroup, B: MulGroup> MulGroup for (A, B) {

  /// Inversion is by matching element.
  fn invert(&self) -> Self {
    (self.0.invert(), self.1.invert())
  }


  /// Invertibility is across the tuple.
  fn is_invertible(&self) -> bool {
    self.0.is_invertible() && self.1.is_invertible()
  }  
}


///
/// Homogeneous 2-tuples form a numeric multiplicative group if
/// their corresponding items form numeric multiplicative groups. We
/// can only implement homogeneous tuples since numeric comparisons
/// require a single numeric error type.
///
impl<A: NumMulGroup> NumMulGroup for (A, A) {

  /// Inversion is by matching element.
  fn invert(&self) -> Self {
    (self.0.invert(), self.1.invert())
  }


  /// Invertibility is across the tuple.
  fn is_invertible(&self) -> bool {
    self.0.is_invertible() && self.1.is_invertible()
  }  
}


///
/// 3-tuples form a multiplicative group if their items form a
/// multiplicative group.
///
impl<A: MulGroup, B: MulGroup, C: MulGroup> MulGroup for (A, B, C) {

  /// Inversion is by matching element.
  fn invert(&self) -> Self {
    let (a, b, c) = self;

    (a.invert(), b.invert(), c.invert())
  }


  /// Invertibility is across the tuple.
  fn is_invertible(&self) -> bool {
    let (a, b, c) = self;
    
    a.is_invertible() && b.is_invertible() && c.is_invertible()
  }  
}


///
/// Homogeneous 3-tuples form a numeric multiplicative group if
/// their corresponding items form numeric multiplicative groups. We
/// can only implement homogeneous tuples since numeric comparisons
/// require a single numeric error type.
///
impl<A: NumMulGroup> NumMulGroup for (A, A, A) {

  /// Inversion is by matching element.
  fn invert(&self) -> Self {
    let (a, b, c) = self;

    (a.invert(), b.invert(), c.invert())
  }


  /// Invertibility is across the tuple.
  fn is_invertible(&self) -> bool {
    let (a, b, c) = self;
    
    a.is_invertible() && b.is_invertible() && c.is_invertible()
  }  
}


// Module unit tests are in a separate file.
#[cfg(test)]
#[path = "mul_group_test.rs"]
mod mul_group_test;