math-quaternion.qbk

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

   T R_component_1() const;
   T R_component_2() const;
   T R_component_3() const;
   T R_component_4() const;

A quaternion having four real components, these are returned by these four 
functions. Hence real and R_component_1 return the same value.

[h4 Individual Complex  Components]

   ::std::complex<T>	C_component_1() const;
   ::std::complex<T>	C_component_2() const;

A quaternion likewise has two complex components, and as we have seen above, 
for any quaternion __quat_formula we also have __quat_complex_formula. These functions return them. 
The real part of `q.C_component_1()` is the same as `q.real()`.

[h3 Quaternion Member Operators]
[h4 Assignment Operators]

   quaternion<T>& operator = (quaternion<T> const & a_affecter);
   template<typename X> 
   quaternion<T>& operator = (quaternion<X> const& a_affecter);
   quaternion<T>& operator = (T const& a_affecter);
   quaternion<T>& operator = (::std::complex<T> const& a_affecter);

These perform the expected assignment, with type modification if necessary 
(for instance, assigning from a base type will set the real part to that 
value, and all other components to zero). For the unspecialized form, 
the base type's assignment operators must not throw.

[h4 Addition Operators]

   quaternion<T>& operator += (T const & rhs)
   quaternion<T>& operator += (::std::complex<T> const & rhs);
   template<typename X>	
   quaternion<T>& operator += (quaternion<X> const & rhs);

These perform the mathematical operation `(*this)+rhs` and store the result in 
`*this`. The unspecialized form has exception guards, which the specialized 
forms do not, so as to insure exception safety. For the unspecialized form, 
the base type's assignment operators must not throw.

[h4 Subtraction Operators]

   quaternion<T>& operator -= (T const & rhs)
   quaternion<T>& operator -= (::std::complex<T> const & rhs);
   template<typename X>	
   quaternion<T>& operator -= (quaternion<X> const & rhs);

These perform the mathematical operation `(*this)-rhs` and store the result 
in `*this`. The unspecialized form has exception guards, which the 
specialized forms do not, so as to insure exception safety. 
For the unspecialized form, the base type's assignment operators 
must not throw.

[h4 Multiplication Operators]

   quaternion<T>& operator *= (T const & rhs)
   quaternion<T>& operator *= (::std::complex<T> const & rhs);
   template<typename X>	
   quaternion<T>& operator *= (quaternion<X> const & rhs);

These perform the mathematical operation `(*this)*rhs` [*in this order] 
(order is important as multiplication is not commutative for quaternions) 
and store the result in `*this`. The unspecialized form has exception guards, 
which the specialized forms do not, so as to insure exception safety. 
For the unspecialized form, the base type's assignment operators must not throw.

[h4 Division Operators]

   quaternion<T>& operator /= (T const & rhs)
   quaternion<T>& operator /= (::std::complex<T> const & rhs);
   template<typename X>	
   quaternion<T>& operator /= (quaternion<X> const & rhs);

These perform the mathematical operation `(*this)*inverse_of(rhs)` [*in this 
order] (order is important as multiplication is not commutative for quaternions) 
and store the result in `*this`. The unspecialized form has exception guards, 
which the specialized forms do not, so as to insure exception safety. 
For the unspecialized form, the base type's assignment operators must not throw.

[endsect]
[section:non_mem Quaternion Non-Member Operators]

[h4 Unary Plus]

   template<typename T>	
   quaternion<T> operator + (quaternion<T> const & q);

This unary operator simply returns q.

[h4 Unary Minus]

   template<typename T>
   quaternion<T> operator - (quaternion<T> const & q);

This unary operator returns the opposite of q.

[h4 Binary Addition Operators]

   template<typename T>	quaternion<T>	operator + (T const & lhs, quaternion<T> const & rhs);
   template<typename T>	quaternion<T>	operator + (quaternion<T> const & lhs, T const & rhs);
   template<typename T>	quaternion<T>	operator + (::std::complex<T> const & lhs, quaternion<T> const & rhs);
   template<typename T>	quaternion<T>	operator + (quaternion<T> const & lhs, ::std::complex<T> const & rhs);
   template<typename T>	quaternion<T>	operator + (quaternion<T> const & lhs, quaternion<T> const & rhs);

These operators return `quaternion<T>(lhs) += rhs`.

[h4 Binary Subtraction Operators]

   template<typename T>	quaternion<T>	operator - (T const & lhs, quaternion<T> const & rhs);
   template<typename T>	quaternion<T>	operator - (quaternion<T> const & lhs, T const & rhs);
   template<typename T>	quaternion<T>	operator - (::std::complex<T> const & lhs, quaternion<T> const & rhs);
   template<typename T>	quaternion<T>	operator - (quaternion<T> const & lhs, ::std::complex<T> const & rhs);
   template<typename T>	quaternion<T>	operator - (quaternion<T> const & lhs, quaternion<T> const & rhs);

These operators return `quaternion<T>(lhs) -= rhs`.

[h4 Binary Multiplication Operators]

   template<typename T>	quaternion<T>	operator * (T const & lhs, quaternion<T> const & rhs);
   template<typename T>	quaternion<T>	operator * (quaternion<T> const & lhs, T const & rhs);
   template<typename T>	quaternion<T>	operator * (::std::complex<T> const & lhs, quaternion<T> const & rhs);
   template<typename T>	quaternion<T>	operator * (quaternion<T> const & lhs, ::std::complex<T> const & rhs);
   template<typename T>	quaternion<T>	operator * (quaternion<T> const & lhs, quaternion<T> const & rhs);

These operators return `quaternion<T>(lhs) *= rhs`.

[h4 Binary Division Operators]

   template<typename T>	quaternion<T>	operator / (T const & lhs, quaternion<T> const & rhs);
   template<typename T>	quaternion<T>	operator / (quaternion<T> const & lhs, T const & rhs);
   template<typename T>	quaternion<T>	operator / (::std::complex<T> const & lhs, quaternion<T> const & rhs);
   template<typename T>	quaternion<T>	operator / (quaternion<T> const & lhs, ::std::complex<T> const & rhs);
   template<typename T>	quaternion<T>	operator / (quaternion<T> const & lhs, quaternion<T> const & rhs);

These operators return `quaternion<T>(lhs) /= rhs`. It is of course still an 
error to divide by zero...

[h4 Equality Operators]

   template<typename T>	bool	operator == (T const & lhs, quaternion<T> const & rhs);
   template<typename T>	bool	operator == (quaternion<T> const & lhs, T const & rhs);
   template<typename T>	bool	operator == (::std::complex<T> const & lhs, quaternion<T> const & rhs);
   template<typename T>	bool	operator == (quaternion<T> const & lhs, ::std::complex<T> const & rhs);
   template<typename T>	bool	operator == (quaternion<T> const & lhs, quaternion<T> const & rhs);

These return true if and only if the four components of `quaternion<T>(lhs)`
are equal to their counterparts in `quaternion<T>(rhs)`. As with any 
floating-type entity, this is essentially meaningless.

[h4 Inequality Operators]

   template<typename T>	bool	operator != (T const & lhs, quaternion<T> const & rhs);
   template<typename T>	bool	operator != (quaternion<T> const & lhs, T const & rhs);
   template<typename T>	bool	operator != (::std::complex<T> const & lhs, quaternion<T> const & rhs);
   template<typename T>	bool	operator != (quaternion<T> const & lhs, ::std::complex<T> const & rhs);
   template<typename T>	bool	operator != (quaternion<T> const & lhs, quaternion<T> const & rhs);

These return true if and only if `quaternion<T>(lhs) == quaternion<T>(rhs)` is 
false. As with any floating-type entity, this is essentially meaningless.

[h4 Stream Extractor]

   template<typename T, typename charT, class traits>
   ::std::basic_istream<charT,traits>& operator >> (::std::basic_istream<charT,traits> & is, quaternion<T> & q);

Extracts a quaternion q of one of the following forms 
(with a, b, c and d of type `T`):

[^a (a), (a,b), (a,b,c), (a,b,c,d) (a,(c)), (a,(c,d)), ((a)), ((a),c), ((a),(c)), ((a),(c,d)), ((a,b)), ((a,b),c), ((a,b),(c)), ((a,b),(c,d))]

The input values must be convertible to `T`. If bad input is encountered, 
calls `is.setstate(ios::failbit)` (which may throw ios::failure (27.4.5.3)).

[*Returns:] `is`.

The rationale for the list of accepted formats is that either we have a 
list of up to four reals, or else we have a couple of complex numbers, 
and in that case if it formated as a proper complex number, then it should 
be accepted. Thus potential ambiguities are lifted (for instance (a,b) is 
(a,b,0,0) and not (a,0,b,0), i.e. it is parsed as a list of two real numbers 
and not two complex numbers which happen to have imaginary parts equal to zero).

[h4 Stream Inserter]

   template<typename T, typename charT, class traits>
   ::std::basic_ostream<charT,traits>& operator << (::std::basic_ostream<charT,traits> & os, quaternion<T> const & q);

Inserts the quaternion q onto the stream `os` as if it were implemented as follows:

   template<typename T, typename charT, class traits>
   ::std::basic_ostream<charT,traits>& operator << (	
                  ::std::basic_ostream<charT,traits> & os,
                  quaternion<T> const & q)
   {
      ::std::basic_ostringstream<charT,traits>	s;

      s.flags(os.flags());
      s.imbue(os.getloc());
      s.precision(os.precision());

      s << '(' << q.R_component_1() << ','
               << q.R_component_2() << ','
               << q.R_component_3() << ','
               << q.R_component_4() << ')';

      return os << s.str();
   }
   
[endsect]

[section:value_op Quaternion Value Operations]

[h4 real and unreal]

   template<typename T>	T              real(quaternion<T> const & q);
   template<typename T>	quaternion<T>  unreal(quaternion<T> const & q);

These return `q.real()` and `q.unreal()` respectively.

[h4 conj]

   template<typename T>	quaternion<T>  conj(quaternion<T> const & q);

This returns the conjugate of the quaternion.

[h4 sup]

template<typename T>	T  sup(quaternion<T> const & q);

This return the sup norm (the greatest among