source: trunk/yat/utility/VectorBase.h @ 1041

Last change on this file since 1041 was 1041, checked in by Peter, 14 years ago

generalized StrideIterator? to work with Iterators as well - not only pointers

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 8.3 KB
Line 
1#ifndef _theplu_yat_utility_vector_base_
2#define _theplu_yat_utility_vector_base_
3
4// $Id: VectorBase.h 1041 2008-02-06 17:36:54Z 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, Markus Ringnér, Peter Johansson
10  Copyright (C) 2006 Jari Häkkinen, Markus Ringnér
11  Copyright (C) 2007 Jari Häkkinen, Peter Johansson
12  Copyright (C) 2008 Peter Johansson
13
14  This file is part of the yat library, http://trac.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 2 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 this program; if not, write to the Free Software
28  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
29  02111-1307, USA.
30*/
31
32#include "Exception.h"
33#include "StrideIterator.h"
34
35#include <iostream>
36#include <vector>
37#include <utility>
38
39#include <gsl/gsl_vector.h>
40#include <gsl/gsl_sort_vector.h>
41
42namespace theplu {
43namespace yat {
44namespace utility {
45
46  class matrix;
47  class vector;
48
49  /**
50     @brief This is the yat interface to GSL vector.
51
52     For time being 'double' is the only type supported.
53
54     \par File streams:
55     Reading and writing vectors to file streams are of course
56     supported. These are implemented without using GSL functionality,
57     and thus binary read and write to streams are not supported.
58
59     \par Vector views:
60     GSL vector views are supported and these are disguised as
61     ordinary utility::vectors. A support function is added,
62     utility::vector::isview(), that can be used to check if a vector
63     object is a view. Note that view vectors do not own the
64     underlying data, and a view is not valid if the vector/matrix
65     owing the data is deallocated.
66
67     \par
68     Currently there is no restriction on how a vector is used when
69     the vector is a const view into another vector or matrix. To
70     avoid unexpected runtime errors, the programmer must declare
71     const view vectors as 'const' in order to get compile time
72     diagnostics about improper use of a const view vector object. If
73     'const' is not used and the const view vector is used erroneously
74     (such as on the left hand side in assignments), the compiler will
75     not catch the error and runtime error will occur. assert(3) is
76     used to catch the runtime error during development. Example on
77     bad and proper use of const view vectors:
78     @code
79  const vector vm(13,1.0);
80  vector v1(vm,2,4);       // bad code! not const!
81  v1(0)=-123;              // accepted by compiler, runtime abort will occur
82                           // or catched by assert depending on compiler flags
83  const vector v2(vm,2,4); // proper code
84  v2(0)=-123;              // not acceptable for the compiler
85     @endcode
86  */
87
88  class VectorBase
89  {
90  public:
91    /// \brief VectorBase::const_iterator
92    typedef StrideIterator<const double*> const_iterator;
93
94    /**
95       \brief Constructor.
96    */
97    VectorBase(const gsl_vector* v=NULL);
98
99    ///
100    /// The destructor.
101    ///
102    virtual ~VectorBase(void);
103
104    /**
105       \return read-only iterator to start of VectorBase
106     */
107    const_iterator begin(void) const;
108
109    /**
110       \return read-only iterator to end of VectorBase
111     */
112    const_iterator end(void) const;
113
114    /**
115       \brief Check whether VectorBases are equal within a user defined
116       precision, set by \a precision.
117
118       \return True if each element deviates less or equal than \a
119       d. If any VectorBase contain a NaN, false is always returned.
120
121       \see operator== and operator!=
122    */
123    bool equal(const VectorBase&, const double precision=0) const;
124
125    ///
126    /// @return A const pointer to the internal GSL vector,
127    ///
128    const gsl_vector* gsl_vector_p(void) const;
129
130    /**
131       Check if the vector object is a view (sub-vector) to another
132       vector.
133   
134       \return True if the object is a view, false othwerwise.
135     */
136    virtual bool isview(void) const=0; 
137
138    ///
139    /// @return the number of elements in the VectorBase.
140    ///
141    size_t size(void) const;
142
143    /**
144       \brief Element access operator.
145
146       \return Const reference to element \a i.
147
148       \throw If GSL range checks are enabled in the underlying GSL
149       library a GSL_error exception is thrown if either index is out
150       of range.
151    */
152    const double& operator()(size_t i) const;
153    // Peter, remove this one
154    const double& operator[](size_t i) const;
155
156    /**
157       \brief Comparison operator. Takes linear time.
158
159       Checks are performed with exact matching, i.e., rounding off
160       effects may destroy comparison. Use the equal function for
161       comparing elements within a user defined precision.
162
163       \return True if all elements are equal otherwise false.
164
165       \see equal(const VectorBase&, const double precision=0)
166    */
167    bool operator==(const VectorBase&) const;
168
169    /**
170       \brief Comparison operator. Takes linear time.
171
172       Checks are performed with exact matching, i.e., rounding off
173       effects may destroy comparison. Use the equal function for
174       comparing elements within a user defined precision.
175
176       \return False if all elements are equal otherwise true.
177
178       \see equal(const VectorBase&, const double precision=0)
179    */
180    bool operator!=(const VectorBase&) const;
181
182    ///
183    /// @return The dot product.
184    ///
185    double operator*(const VectorBase&) const;
186
187  protected:
188    const gsl_vector* const_vec_;
189
190  private:
191    // copy assignment no allowed
192    const VectorBase& operator=(const VectorBase&);
193  };
194
195  /**
196     \brief Check if all elements of the VectorBase are zero.
197
198     \return True if all elements in the VectorBase is zero, false
199     othwerwise.
200  */
201  bool isnull(const VectorBase&);
202
203  /**
204     \brief Get the maximum value of the VectorBase.
205
206     \return The maximum value of the VectorBase.
207  */
208  double max(const VectorBase&);
209
210  /**
211     \brief Locate the maximum value in the VectorBase.
212
213     \return The index to the maximum value of the VectorBase.
214
215     \note Lower index has precedence.
216  */
217  size_t max_index(const VectorBase&);
218
219  /**
220     \brief Get the minimum value of the VectorBase.
221
222     \return The minimum value of the VectorBase.
223  */
224  double min(const VectorBase&);
225
226  /**
227     \brief Locate the minimum value in the VectorBase.
228
229     \return The index to the minimum value of the VectorBase.
230
231     \note Lower index has precedence.
232  */
233  size_t min_index(const VectorBase&);
234
235  /**
236     \brief Create a VectorBase \a flag indicating NaN's in another VectorBase
237     \a templat.
238
239     The \a flag VectorBase is changed to contain 1's and 0's only. A 1
240     means that the corresponding element in the \a templat VectorBase is
241     valid and a zero means that the corresponding element is a NaN.
242
243     \note Space for VectorBase \a flag is reallocated to fit the size of
244     VectorBase \a templat if sizes mismatch.
245
246     \return True if the \a templat VectorBase contains at least one NaN.
247  */
248  bool nan(const VectorBase& templat, vector& flag);
249
250  /**
251     Create a vector \a sort_index containing the indeces of
252     elements in a another VectorBase \a invec.  The elements of \a
253     sort_index give the index of the VectorBase element which would
254     have been stored in that position if the VectorBase had been sorted
255     in place. The first element of \a sort_index gives the index of the least
256     element in \a invec, and the last element of \a sort_index gives the
257     index of the greatest element in \a invec . The VectorBase \a invec
258     is not changed.
259  */
260  void sort_index(std::vector<size_t>& sort_index, const VectorBase& invec);
261
262  /**
263      Similar to sort_index but creates a VectorBase with indices to the \a k
264  smallest elements in \a invec. 
265  */
266  void sort_smallest_index(std::vector<size_t>& sort_index, size_t k, 
267                           const VectorBase& invec);
268
269  /**
270      Similar to sort_index but creates a VectorBase with indices to the \a k
271  largest elements in \a invec. 
272  */
273  void sort_largest_index(std::vector<size_t>& sort_index, size_t k, 
274                          const VectorBase& invec);
275
276  /**
277     \brief Calculate the sum of all VectorBase elements.
278
279     \return The sum.
280  */
281  double sum(const VectorBase&);
282
283  /**
284     \brief The output operator for the VectorBase class.
285  */
286  std::ostream& operator<<(std::ostream&, const VectorBase&);
287
288}}} // of namespace utility, yat, and theplu
289
290#endif
Note: See TracBrowser for help on using the repository browser.