source: trunk/yat/utility/VectorView.h @ 1437

#ifndef _theplu_yat_utility_vector_view_
#define _theplu_yat_utility_vector_view_

// $Id: VectorView.h 1437 2008-08-25 17:55:00Z peter $

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

  This file is part of the yat library, http://dev.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 "VectorMutable.h"
#include "Exception.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_view. 

     This class can be used to create a vector view into a Matrix or a
     VectorMutable. Modifying a view will also modify the underlying
     data, i.e., the Matrix or VectorMutable that is viewed into. For
     that reason all constructors are taking non-const references to
     disallow mutable views into a const objects. 

     The fact that there is no copy constructor with const argument,
     but only a so-called move constructor (copying a non-const
     reference), implies that temporary objects such as objects
     returned from functions can not be copied directly. Instead the
     copying is done via a proxy class (see VectorMutable). Also since
     we can not bind a temporary to a non-const reference, a
     VectorView returned from a function cannot be sent directly to a
     function.
     For example
     @code
     Matrix m(10,10);
     sum(m.row_view(0));
     @endcode
     but you need to use create a dummie object
     @code
     Matrix m(10,10);
     VectorView vv = m.row_view(0);
     sum(vv);
     @endcode
     or since sum is a const function, you can use VectorConstView
     @code
     Matrix m(10,10);
     sum(m.row_const_view(0));
     @endcode

     Note that VectorView does not own underlying data, and a
     VectorView is not valid if Vector/Matrix owning the data is
     deallocated.
  */
  class VectorView : public VectorMutable
  {
  public:
    /**
       \brief Default constructor.

       Creates a view into nothing and behaves like an empty Vector.
    */
    VectorView(void);

    /**
       \brief The copy constructor.

       Modifications to created VectorView will also modify \a
       other. Created VectorView is not dependent on \a other, but if
       underlying data (Vector or Matrix) is deallocated VectorView is
       invalid.
    */ 
    VectorView(VectorView& other);

    /**
       \brief copy another VectorMutable

       \note If the object viewed by the view goes out of scope or is
       deleted, the view becomes invalid and the result of further use
       is undefined.
    */
    VectorView(VectorMutable& other);

    /**
       \brief VectorView constructor.

       Create a view of VectorMutable \a v, with starting index \a offset,
       size \a n, and an optional \a stride.

       \note If the object viewed by the view goes out of scope or is
       deleted, the view becomes invalid and the result of further use
       is undefined.
    */
    VectorView(VectorMutable& v, size_t offset, size_t n, size_t stride=1);

    ///
    /// Matrix row/column view constructor.
    ///
    /// Create a row/column VectorView view of matrix \a m, pointing at
    /// row/column \a i. The parameter \a row is used to set whether
    /// the view should be a row or column view. If \a row is set to
    /// true, the view will be a row view (default behaviour), and,
    /// naturally, a column view otherwise.
    ///
    /// A VectorView view can be used as any VectorMutable with the
    /// difference that changes made to the view will also change the
    /// object that is viewed. 
    ///
    /// @note If the object viewed by the view goes out of scope or is
    /// deleted, the view becomes invalid and the result of further
    /// use is undefined.
    ///
    VectorView(Matrix& m, size_t i, bool row=true);

    /**
       \brief create VectorView from proxy class
     */
    VectorView(proxy p);

    ///
    /// The destructor.
    ///
    ~VectorView(void);

    /**
       \return true
    */
    bool isview(void) const; 

    /**
       \brief The assignment operator.

       \return A const reference to the resulting vector.

       \note modifies underlying data.

       \throw GSL_error if dimensions mis-match or if assignment fails
    */
    const VectorView& operator=(const VectorView&);

    /**
       \brief The assignment operator.

       \return A const reference to the resulting vector.

       \note modifies underlying data.

       \throw GSL_error if dimensions mis-match or if assignment fails
    */
    const VectorView& operator=(const VectorBase&);

  private:
    const VectorView& assign(const VectorBase& other);
    void copy(gsl_vector*);
    void delete_allocated_memory(void);

    gsl_vector_view* view_;
  };

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

#endif