//
// MathVector.h
//
// This file contains declarations for the Vector class.
// This code is part of the Bioinformatics Template Library (BTL).
//
// Copyright (C) 1997 Birkbeck College, Malet Street, London WC1E 7HX, U.K.
// (classlib@mail.cryst.bbk.ac.uk)
//
// This library is free software; you can
// redistribute it and/or modify it under the terms of
// the GNU Library General Public License as published by the Free
// Software Foundation; either version 2 of the License, or (at your
// option) any later version.  This library 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 Library General Public License for more details.
// You should have received a copy of the GNU Library General Public
// License along with this library; if not, write to the Free Software
// Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
///////////////////////////////////////////////////////////////////////////



#if !defined(MATHVECTOR_H)
#define MATHVECTOR_H


#include "Typedefn.h"
#include <math.h>
#include <iostream.h>

#if !defined(SGI_CC)

#include <vector>
using namespace std;

#else

#include <vector.h>

#endif


/**#: [Description =" his class represents a mathematical vector of any 
    dimension.<P>

                             V = xi + yj + zk + ...<P>

    However, its primary use will probably in representing the position of atoms
    in three dimensions. The default contructor contructs a 3D Vector.<P>

    There are several types associated with this class:<P>

    <CODE>value_type</CODE> : same as the type REAL which is defined in
                              Typedefn.h<P>
    <CODE>iterator</CODE> : this is a STL type iterator. It can be used to
    sequentailly access the elements of the Vector e.g.<P><CODE>

    	    	    Vector v1;
    	    	     	...
    	    	    for (Vector::iterator i = v1.begin(); i != v1.end(); i++)
    	    	    	cout << *i;

    <P>const_iterator</CODE> : used to access const Vector.<P>
    <CODE>size_type</CODE> : this is an unsigned integer type that represents
    the size of any Vector object."]
    [Authors = "W.R.Pitt, D.S.Moss"]
    [Files = "<A HREF=./btl/MathVector.h>MathVector.h</A>,
              <A HREF=./btl/MathVector.cpp>MathVector.cpp</A>"]
    [Friends="Friend equivalents to some functions are available and are
    	      documented with these functions. Also available is: friend
    	      ostream& operator<<(ostream &os, const Matrix &m); "]
    [Dependencies="<A HREF=#NumericLimits>NumericLimits</A>
                   <A HREF=#NumericUtilities>NumericUtilities</A>"]*/

class Vector
{
public:

    	typedef REAL	    	    	    value_type;
    	typedef vector<value_type>	    container;
    	typedef container::iterator 	    iterator;
    	typedef container::const_iterator   const_iterator;
    	typedef container::size_type	    size_type;

private:

	container vec;   // container - will be changed to the more efficient
	    	    	 // valarray<T> when it becomes available.
public:


	friend class Matrix;
	
//.............................................................................
// Constructors/destructor

	    	/**#: [Description="Constructs a 3D vector
	                            and initialised each value to 0.0."]*/
	                            	                            
	Vector() { vec.insert(vec.begin(), 3, 0.0); }

	    	/**#: [Description="Constructs a 3D vector with initialization
	    	       and initialises the values with the numbers given."]*/
	    	    	    	    
	Vector(value_type p, value_type q, value_type r)
	    	{ vec.push_back(p); vec.push_back(q); vec.push_back(r); }

	    	/**#: [Description="Constructor for an n dimensional vector.
	    	    	    	    All n values initiated to 0.0."]*/
	    	    	    	    
	Vector(size_type n) { vec.insert(vec.begin(), n, 0.0);}

	    	/**#: [Description="Construct from a two dimensional array
	    	       of REALs ( given value_type* )"] */

	Vector(const value_type* const array, const size_type& p);
		
	    	/**#: [Description="Copy constructor."]*/
	    	
	Vector(const Vector &v) : vec(v.vec) {}

	    	/**#: [Description="Destructor."]*/
	    	
	~Vector() {}

//.............................................................................
// Access functions

	    	/**#: [Description="Returns iterator that can be used to
	    	       begin traversing through all elements of the Vector."]*/
	    	
    	iterator    	
    	begin() { return vec.begin(); }


	    	/**#: [Description="Same as function above but returns a 
	    	       const_iterator."]*/	    	
    	
    	const_iterator	
    	begin() const { return vec.begin(); }


	    	/**#: [Description="Returns an iterator can be used in
	    	       comparison for ending traversal through the Vector."]*/
    	    	    
    	iterator    	
    	end() { return vec.end(); }
    	

	    	/**#: [Description="Same as function above but returns a 
	    	       const_iterator."]*/	    	
    	    	    
    	const_iterator	
    	end() const { return vec.end(); }
    	    	    

	    	/**#: [Description="Returns the element, i positions
	    	       from the beginning of the Vector, in constant time.
	    	       (i >= 0)."]*/
    	    	    
	value_type& 	
	operator[](const size_type& i);

	    	/**#: [Description="Same as function above but returns a 
	    	       const value."]*/	    	    	    	    

	value_type   
	operator[](const size_type& i) const;


	    	/**#: [Description="Returns the number of elements in the
	    	       Vector."]*/
    	    	    
	size_type   	
	size() const { return vec.size(); }
	

	    	/**#: [Description="Returns the i-th element in the Vector
	    	       (i >= 1)."]*/
    	    	    
	value_type& 	
	operator()(const size_type& i);


	    	/**#: [Description="Same as function above but returns a 
	    	       const value."]*/
    	    	    
	value_type 
	operator()(const size_type& i) const {return vec[i-1];}


	    	/**#: [Description="Vector stream output."]*/
    	    	    
	friend ostream& 
	operator<<(ostream &os, const Vector &v);

//.............................................................................
// Vector comparison

	    	/**#: [Description="Vector equality."]*/

	bool
	operator==(const Vector& v) const;

	    	/**#: [Description="Returns the largest difference between 
	    	       equivalent elements in this and Vector v."]*/
    	    	    
	value_type  	
	MaxDifference(const Vector& v) const;
	
//.............................................................................
// Vector algebra
	

	    	/**#: [Description="Vector assignment."]*/

	Vector&     	
	operator=(const Vector &v) { vec = v.vec;return *this;}


	    	/**#: [Description="Vector addition."]*/

	Vector      	
	operator+(const Vector &v) const;


	    	/**#: [Description="Vector subtraction."]*/
    	    	    
	Vector      	
	operator-(const Vector &v) const;


	    	/**#: [Description="Vector negation (unary minus operator)."]*/
    	    	    
	Vector      	
	operator-() const;


	    	/**#: [Description="Vector increment."]*/
    	    	    
	Vector&     	
	operator+=(const Vector &v);


	    	/**#: [Description="Vector decrement."]*/
    	    	    
	Vector&     	
	operator-=(const Vector &v);


	    	/**#: [Description="Add a scalar to each element in 
	    	       the Vector."]*/

	Vector      	
	operator+(const value_type &s) const;


	    	/**#: [Description="Subtract a scalar from each element in 
	    	       the Vector."]*/
    	    	    
	Vector      	
	operator-(const value_type &s) const;


	    	/**#: [Description="Add a scalar to each element in 
	    	       the Vector."]*/
    	    	    
	Vector&     	
	operator+=(const value_type &s);


	    	/**#: [Description="Subtract a scalar from each element in 
	    	       the Vector."]*/
    	    	    
	Vector&     	
	operator-=(const value_type &s);


	    	/**#: [Description="Vector scalar/dot product."]*/
    	    	    
	value_type
	operator*(const Vector &v) const;


	    	/**#: [Description="Vector cross product."]*/
    	    	    
	Vector      	
	operator%(const Vector &v) const;


	    	/**#: [Description="Vector multiplication by a scalar."]*/
    	    	    
	Vector	
	operator*(const value_type& y) const;


	    	/**#: [Description="Vector multiplication by a scalar."]*/
    	    	    
	friend Vector	
	operator*(const value_type& y, const Vector &v) { return (v * y); }


	    	/**#: [Description="Vector multiplication by a scalar and
	    	      assignment."]*/
    	    	    
	Vector&     	
	operator*=(const value_type& y);


	    	/**#: [Description="Vector division by a scalar."]*/
    	    	    
	Vector      	
	operator/(const value_type& y) const;

	    	/**#: [Description="Vector division by a scalar."]*/
    	    	    
	friend Vector	
	operator/(const value_type& y, const Vector &v) { return (v / y); }


	    	/**#: [Description="Vector division by a scalar and 
	    	       assignment."]*/
    	    	    
	Vector&     	
	operator/=(const value_type& y);

	    	/**#: [Description="Returns the root mean square distance
	    	       between this and Vector v."]*/
    	    	    
	value_type  	
	Distance(const Vector& v) const;


	    	/**#: [Description="Returns zero if the cooresponding Vector
	    	       elements are all identical within the floating point
	    	       precision used. If they are not identical then the
	    	       function finds the largest difference between
	    	       cooresponding elements and outputs the number of
	    	       significant digits in this difference. The range this
	    	       number can take depends on the floating point precision
	    	       used. The maximum is typically equal to 6 for
	    	       single precision (FLT_DIG) and 15 for double precision
	    	       (DBL_DIG)."]*/
    	    	    
    	unsigned int
    	IsNotEqualTo(const Vector& v) const;
    	
	    	/**#: [Description="Returns the modulus/magnitude of the 
	    	                    vector."]*/
    	    	    
	value_type  	
	Modulus() const;

};

#endif // Vector.h