source: trunk/yat/utility/VectorMutable.h @ 1027

#ifndef _theplu_yat_utility_vector_mutable_
#define _theplu_yat_utility_vector_mutable_

// $Id: VectorMutable.h 1027 2008-02-02 21:29:29Z peter $

/*
  Copyright (C) 2003 Daniel Dalevi, Peter Johansson
  Copyright (C) 2004 Jari Häkkinen, Peter Johansson
  Copyright (C) 2005 Jari Häkkinen, Markus Ringnér, Peter Johansson
  Copyright (C) 2006 Jari Häkkinen, Markus Ringnér
  Copyright (C) 2007 Jari Häkkinen, Peter Johansson
  Copyright (C) 2008 Peter Johansson

  This file is part of the yat library, http://trac.thep.lu.se/trac/yat

  The yat library is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License as
  published by the Free Software Foundation; either version 2 of the
  License, or (at your option) any later version.

  The yat 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
  General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
  02111-1307, USA.
*/

#include "VectorBase.h"
#include "Exception.h"
#include "Iterator.h"

#include <iostream>
#include <vector>
#include <utility>

#include <gsl/gsl_vector.h>
#include <gsl/gsl_sort_vector.h>

namespace theplu {
namespace yat {
namespace utility {

  class matrix;
  class vector;

  /**
     @brief This is the yat interface to GSL vector. 

     For time being 'double' is the only type supported.

     \par File streams:
     Reading and writing vectors to file streams are of course
     supported. These are implemented without using GSL functionality,
     and thus binary read and write to streams are not supported.

     \par Vector views:
     GSL vector views are supported and these are disguised as
     ordinary utility::vectors. A support function is added,
     utility::vector::isview(), that can be used to check if a vector
     object is a view. Note that view vectors do not own the
     underlying data, and a view is not valid if the vector/matrix
     owing the data is deallocated.

     \par
     Currently there is no restriction on how a vector is used when
     the vector is a const view into another vector or matrix. To
     avoid unexpected runtime errors, the programmer must declare
     const view vectors as 'const' in order to get compile time
     diagnostics about improper use of a const view vector object. If
     'const' is not used and the const view vector is used erroneously
     (such as on the left hand side in assignments), the compiler will
     not catch the error and runtime error will occur. assert(3) is
     used to catch the runtime error during development. Example on
     bad and proper use of const view vectors:
     @code
  const vector vm(13,1.0);
  vector v1(vm,2,4);       // bad code! not const!
  v1(0)=-123;              // accepted by compiler, runtime abort will occur
                           // or catched by assert depending on compiler flags
  const vector v2(vm,2,4); // proper code
  v2(0)=-123;              // not acceptable for the compiler
     @endcode
  */

  class VectorMutable : public VectorBase
  {
  public:
    /**
       \brief mutable iterator
    */
    typedef Iterator<double&, VectorMutable> iterator;

    /**
       \brief default constructor
    */
    VectorMutable(void);

    /**
       \brief Constructor.
    */
    VectorMutable(gsl_vector*);

    /**
       \brief Constructor.
    */
    VectorMutable(const gsl_vector*);

    ///
    /// The destructor.
    ///
    virtual ~VectorMutable(void);

    ///
    /// Set all elements to \a value.
    ///
    void all(double value);

    /**
       \return mutable iterator to start of VectorBase
     */
    iterator begin(void);

    // to allow overload from base class
    using VectorBase::begin;

    /**
       \brief This function performs element-wise division, \f$
       this_i = this_i / other_i \; \forall i \f$.

       \throw GSL_error if dimensions mis-match.
    */
    void div(const VectorBase& other);

    /**
       \return mutable iterator to end of VectorMutable
     */
    iterator end(void);

    // to allow overload from base class
    using VectorBase::end;

    /**
       @return A pointer to the internal GSL vector,
    */
    gsl_vector* gsl_vector_p(void);

    using VectorBase::gsl_vector_p;

    /**
       Check if the vector object is a view (sub-vector) to another
       vector.
    
       \return True if the object is a view, false othwerwise.
    
     */
    virtual bool isview(void) const=0; 

    /**
       \brief This function performs element-wise multiplication, \f$
       this_i = this_i * other_i \; \forall i \f$.

       \throw GSL_error if dimensions mis-match.
    */
    void mul(const VectorBase& other);

    /**
       \brief Reverse the order of elements in the VectorMutable.
    */
    void reverse(void);

    /**
       \brief Exchange elements \a i and \a j.
    */
    void swap(size_t i, size_t j);

    /**
       \brief Element access operator.

       \return Reference to element \a i.

       \throw If GSL range checks are enabled in the underlying GSL
       library a GSL_error exception is thrown if either index is out
       of range.
    */
    double& operator()(size_t i);
    // Peter, remove this one
    double& operator[](size_t i);
    // to allow overload from base class
    using VectorBase::operator();
    using VectorBase::operator[];

    /**
       \brief Addition and assign operator. VectorBase addition, \f$
       this_i = this_i + other_i \; \forall i \f$.

       \return A const reference to the resulting VectorBase.

       \throw GSL_error if dimensions mis-match.
    */
    const VectorMutable& operator+=(const VectorBase&);

    /**
       \brief Add a constant to a VectorBase, \f$ this_i = this_i + d \;
       \forall i \f$.

       \return A const reference to the resulting VectorBase.
    */
    const VectorMutable& operator+=(double d);

    /**
       \brief Subtract and assign operator. VectorBase subtraction, \f$
       this_i = this_i - other_i \; \forall i \f$.

       \return A const reference to the resulting VectorBase.

       \throw GSL_error if dimensions mis-match.
    */
    const VectorMutable& operator-=(const VectorBase&);

    /**
       \brief Subtract a constant to a VectorBase, \f$ this_i = this_i - d
       \; \forall i \f$.

       \return A const reference to the resulting VectorBase.
    */
    const VectorMutable& operator-=(double d);

    /**
       \brief Multiply with scalar and assign operator, \f$ this_i =
       this_i * d \; \forall i \f$.

       \return A const reference to the resulting VectorBase.
    */
    const VectorMutable& operator*=(double d);

  protected:
    gsl_vector* vec_;

    // Peter document
    struct proxy 
    { 
      gsl_vector* vec_;
    };

  private:
    // copy assignment no allowed
    const VectorMutable& operator=(const VectorMutable&);
  public:
    /**
     */
    operator proxy();

  };

  /**
     Randomly shuffles the elements in VectorBase \a invec
  */
  void shuffle(VectorMutable& invec); 

  /**
     Sort the elements in the VectorBase.
  */
  void sort(VectorMutable&);

}}} // of namespace utility, yat, and theplu

#endif