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

#ifndef _theplu_yat_utility_vector_
#define _theplu_yat_utility_vector_

// $Id: vector.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

  This file is part of the yat library, http://trac.thep.lu.se/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;

  /**
     @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 vector : public VectorMutable
  {
  public:

    /**
       \brief The default constructor.
    */
    vector(void);

    /**
       \brief Allocates memory space for \a n elements, and sets all
       elements to \a init_value.
       
       \throw GSL_error if memory allocation fails.
    */
    vector(size_t n, double init_value=0);

    /**
       \brief The copy constructor.

       \note If the object to be copied is a vector view, the values
       of the view will be copied, i.e. the view is not copied.

       \throw A GSL_error is indirectly thrown if memory allocation
       fails.
    */
    vector(const vector& other);

    /**
       \brief The copy constructor.

       \note If the object to be copied is a vector view, the values
       of the view will be copied, i.e. the view is not copied.

       \throw A GSL_error is indirectly thrown if memory allocation
       fails.
    */
    vector(const VectorBase& other);

    /**
       \brief The istream constructor.

       Either elements should be separated with white space characters
       (default), or elements should be separated by the delimiter \a
       sep. When delimiter \a sep is used empty elements are stored as
       NaN's (except that empty lines are ignored). The end of input
       to the vector is at end of file marker.

       \throw GSL_error if memory allocation fails, IO_error if
       unexpected input is found in the input stream.
    */
    explicit vector(std::istream &, char sep='\0')
      throw(utility::IO_error, std::exception);

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

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

    /**
       @brief Resize vector
       
       All elements are set to @a init_value.

       \note Underlying GSL vector is destroyed and a view into this
       vector becomes invalid.
    */
    void resize(size_t n, double init_value);

    //    using VectorBase::operator=;

    /**
       \brief The assignment operator.

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

  private:
    const vector& assign(const VectorBase& other);
    //const VectorBase& assign(VectorBase& other);

    /**
       \brief Create a new copy of the internal GSL vector.

       Necessary memory for the new GSL vector is allocated and the
       caller is responsible for freeing the allocated memory.

       \return A pointer to a copy of the internal GSL vector.

       \throw GSL_error if memory cannot be allocated for the new
       copy, or if dimensions mis-match.
    */
    gsl_vector* create_gsl_vector_copy(const VectorBase&) const;

    void delete_allocated_memory(void);
  };

  /**
     \brief Swap vector elements by copying.

     The two vectors must have the same length.

     \throw GSL_error if vector lengths differs.
  */
  void swap(vector&, vector&);

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

#endif