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

Last change on this file since 1679 was 1679, checked in by Peter, 12 years ago

correcting docs on proxy in VecetorView?

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 6.1 KB
Line 
1#ifndef _theplu_yat_utility_vector_view_
2#define _theplu_yat_utility_vector_view_
3
4// $Id: VectorView.h 1679 2008-12-29 18:28:03Z peter $
5
6/*
7  Copyright (C) 2003 Daniel Dalevi, Peter Johansson
8  Copyright (C) 2004 Jari Häkkinen, Peter Johansson
9  Copyright (C) 2005 Jari Häkkinen, Peter Johansson, Markus Ringnér
10  Copyright (C) 2006 Jari Häkkinen, Markus Ringnér
11  Copyright (C) 2007 Jari Häkkinen, Peter Johansson, Markus Ringnér
12  Copyright (C) 2008 Peter Johansson
13
14  This file is part of the yat library, http://dev.thep.lu.se/trac/yat
15
16  The yat library is free software; you can redistribute it and/or
17  modify it under the terms of the GNU General Public License as
18  published by the Free Software Foundation; either version 3 of the
19  License, or (at your option) any later version.
20
21  The yat library is distributed in the hope that it will be useful,
22  but WITHOUT ANY WARRANTY; without even the implied warranty of
23  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
24  General Public License for more details.
25
26  You should have received a copy of the GNU General Public License
27  along with yat. If not, see <http://www.gnu.org/licenses/>.
28*/
29
30#include "VectorMutable.h"
31#include "Exception.h"
32
33#include <iostream>
34#include <vector>
35#include <utility>
36
37#include <gsl/gsl_vector.h>
38#include <gsl/gsl_sort_vector.h>
39
40namespace theplu {
41namespace yat {
42namespace utility {
43
44  class Matrix;
45  class Vector;
46
47  /**
48     @brief This is the yat interface to gsl_vector_view.
49
50     This class can be used to create a vector view into a Matrix or a
51     VectorMutable. Modifying a view will also modify the underlying
52     data, i.e., the Matrix or VectorMutable that is viewed into. For
53     that reason all constructors are taking non-const references to
54     disallow mutable views into a const objects.
55
56     The fact that there is no copy constructor with const argument,
57     but only a so-called move constructor (copying a non-const
58     reference), implies that temporary objects such as objects
59     returned from functions can not be copied directly. Instead the
60     copying is done via a proxy class. Also since we can not bind a
61     temporary to a non-const reference, a VectorView returned from a
62     function cannot be sent directly to a function.
63     For example
64     @code
65     Matrix m(10,10);
66     sum(m.row_view(0));
67     @endcode
68     but you need to create a dummie object
69     @code
70     Matrix m(10,10);
71     VectorView vv = m.row_view(0);
72     sum(vv);
73     @endcode
74     or since sum is a const function, you can use VectorConstView
75     @code
76     Matrix m(10,10);
77     sum(m.row_const_view(0));
78     @endcode
79
80     Note that VectorView does not own underlying data, and a
81     VectorView is not valid if Vector/Matrix owning the data is
82     deallocated.
83  */
84  class VectorView : public VectorMutable
85  {
86  public:
87    /**
88       \brief Default constructor.
89
90       Creates a view into nothing and behaves like an empty Vector.
91    */
92    VectorView(void);
93
94    /**
95       \brief The copy constructor.
96
97       Modifications to created VectorView will also modify \a
98       other. Created VectorView is not dependent on \a other, but if
99       underlying data (Vector or Matrix) is deallocated VectorView is
100       invalid.
101    */ 
102    VectorView(VectorView& other);
103
104    /**
105       \brief copy another VectorMutable
106
107       \note If the object viewed by the view goes out of scope or is
108       deleted, the view becomes invalid and the result of further use
109       is undefined.
110    */
111    explicit VectorView(VectorMutable& other);
112
113    /**
114       \brief VectorView constructor.
115
116       Create a view of VectorMutable \a v, with starting index \a offset,
117       size \a n, and an optional \a stride.
118
119       \note If the object viewed by the view goes out of scope or is
120       deleted, the view becomes invalid and the result of further use
121       is undefined.
122    */
123    VectorView(VectorMutable& v, size_t offset, size_t n, size_t stride=1);
124
125    ///
126    /// Matrix row/column view constructor.
127    ///
128    /// Create a row/column VectorView view of matrix \a m, pointing at
129    /// row/column \a i. The parameter \a row is used to set whether
130    /// the view should be a row or column view. If \a row is set to
131    /// true, the view will be a row view (default behaviour), and,
132    /// naturally, a column view otherwise.
133    ///
134    /// A VectorView view can be used as any VectorMutable with the
135    /// difference that changes made to the view will also change the
136    /// object that is viewed.
137    ///
138    /// @note If the object viewed by the view goes out of scope or is
139    /// deleted, the view becomes invalid and the result of further
140    /// use is undefined.
141    ///
142    VectorView(Matrix& m, size_t i, bool row=true);
143
144    ///
145    /// The destructor.
146    ///
147    ~VectorView(void);
148
149    /**
150       \return true
151    */
152    bool isview(void) const; 
153
154    /**
155       \brief The assignment operator.
156
157       \return A const reference to the resulting vector.
158
159       \note modifies underlying data.
160
161       \throw GSL_error if dimensions mis-match or if assignment fails
162    */
163    const VectorView& operator=(const VectorView&);
164
165    /**
166       \brief The assignment operator.
167
168       \return A const reference to the resulting vector.
169
170       \note modifies underlying data.
171
172       \throw GSL_error if dimensions mis-match or if assignment fails
173    */
174    const VectorView& operator=(const VectorBase&);
175
176  private:
177    const VectorView& assign(const VectorBase& other);
178    void copy(gsl_vector*);
179    void delete_allocated_memory(void);
180
181    gsl_vector_view* view_;
182
183    /**
184       Proxy class used to allow copy and assignment of VectorView. By
185       design vectors and matrices are passed as non-const references
186       in all constructors of VectorView. Because the standard does
187       not allow temporary objects to be bound to non-const
188       references, it is not possible to directly construct a
189       VectorView from a temporary VectorView returned from a
190       function. Instead this proxy class is created from the
191       temporary object and then a VectorView can be created from this
192       proxy.
193     */
194    struct proxy
195    { 
196      /// pointer to GSL vector keeping everything we need to create a
197      /// new VectorMutable from a proxy.
198      gsl_vector* vec_;
199    };
200
201  public:
202    /**
203       \brief create VectorView from proxy class
204     */
205    VectorView(proxy p);
206
207    /**
208       conversion operator to private proxy class.
209     */
210    operator proxy();
211  };
212
213}}} // of namespace utility, yat, and theplu
214
215#endif
Note: See TracBrowser for help on using the repository browser.