source: trunk/lib/gslapi/vector.h @ 341

Last change on this file since 341 was 341, checked in by Jari Häkkinen, 18 years ago

Added exceptions for tracing file format problems when reading vectors.
Changed implentation for reading ints and doubles into stl vectors, now
unexpected characters are skipped instead of treated as zeros.
Some other minor things.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 10.6 KB
Line 
1// $Id: vector.h 341 2005-06-07 14:41:25Z jari $
2
3#ifndef _theplu_gslapi_vector_
4#define _theplu_gslapi_vector_
5
6#include <iostream>
7#include <vector>
8#include <utility>
9
10#include <gsl/gsl_vector.h>
11#include <c++_tools/utility/Exception.h>
12
13namespace theplu {
14namespace gslapi {
15  ///
16  /// This is the C++ tools interface to GSL vector. 'double' is the
17  /// only type supported, maybe we should add a 'complex' type as
18  /// well in the future.
19  ///
20  /// \par[File streams] Reading and writing vectors to file streams
21  /// are of course supported. These are implemented without using GSL
22  /// functionality, and thus binary read and write to streams are not
23  /// supported.
24  ///
25  /// \par[Vector views] GSL vector views are supported and these are
26  /// disguised as ordinary gslapi::vectors. A support function is
27  /// added, gslapi::vector::is_view(), that can be used to check if
28  /// the vector object is a view. Note that view vectors do not own
29  /// the undelying data, and is not valid if the original vector is
30  /// deallocated.
31  ///
32  class vector
33  {
34  public:
35
36    ///
37    /// The default constructor.
38    ///
39    vector(void);
40
41    ///
42    /// Constructor. Allocates memory space for \a n elements, and
43    /// sets all elements to \a init_value.
44    ///
45    vector(const size_t n, const double init_value=0);
46
47    ///
48    /// The copy constructor.
49    ///
50    /// @note If the object to be copied is a vector view, the values
51    /// of the view will be copied, i.e. the view is not copied.
52    ///
53    vector(const vector&);
54
55    ///
56    /// The vector view constructor.
57    ///
58    /// Create a view of vector \a v, with starting index \a offset,
59    /// size \a n, and an optional \a stride.
60    ///
61    /// A vector view can be used as any vector with the difference
62    /// that changes made to the view will also change the object that
63    /// is viewed. Also, using the copy constructor will create a new
64    /// vector object that is a copy of whatever is viewed. If a copy
65    /// of the view is needed the you should use this consturctor to
66    /// get one.
67    ///
68    /// @note If the object viewed by the view goes out of scope or is
69    /// deleted, the view becomes invalid.
70    ///
71    vector(vector& v, size_t offset, size_t n, size_t stride=1);
72
73    ///
74    /// Constructor that imports a GSL vector. The GSL object is owned
75    /// by the created object.
76    ///
77    vector(gsl_vector*);
78
79    ///
80    /// The istream constructor.
81    ///
82    /// Elements should be separated with white space characters, the
83    /// end of input to the vector is at end of file marker.
84    ///
85    explicit vector(std::istream &) throw (utility::IO_error,std::exception);
86
87    ///
88    /// The destructor.
89    ///
90    ~vector(void);
91
92    ///
93    /// Vector addition, \f$this_i = this_i + other_i \; \forall i\f$.
94    ///
95    /// @return GSL_SUCCESS on normal exit.
96    ///
97    // Jari, group as vector_operators
98    inline int add(const vector& other) { return gsl_vector_add(v_,other.v_); }
99
100    ///
101    /// Add a constant to a vector, \f$this_i = this_i + term \;
102    /// \forall i\f$.
103    ///
104    /// @return GSL_SUCCESS on normal exit.
105    ///
106    // Jari, group as vector_operators
107    inline int
108    add_constant(double term) { return gsl_vector_add_constant(v_,term); }
109
110    ///
111    /// This function performs element-wise division, \f$this_i =
112    /// this_i/other_i \; \forall i\f$.
113    ///
114    /// @return GSL_SUCCESS on normal exit.
115    ///
116    // Jari, doxygen group as Vector operators
117    inline int div(const vector& other) { return gsl_vector_div(v_,other.v_); }
118
119    ///
120    /// @return True if all elements in the vector is zero, false
121    /// othwerwise;
122    ///
123    inline bool isnull(void) const { return gsl_vector_isnull(v_); }
124
125    ///
126    /// Check if the vector object is a view (sub vector) to another
127    /// vector.
128    ///
129    /// @return True if the object is a view, false othwerwise;
130    ///
131    inline bool isview(void) const { return view_; }
132
133    ///
134    /// @return A const pointer to the internal GSL vector,
135    ///
136    inline const gsl_vector* gsl_vector_pointer(void) const { return v_; }
137
138    ///
139    /// @return A pointer to the internal GSL vector,
140    ///
141    inline gsl_vector* TEMP_gsl_vector_pointer(void) { return v_; }
142
143    ///
144    /// @return The maximum value of the vector.
145    ///
146    // Jari, doxygen group as Finding maximum and minimum elements
147    inline double max(void) const { return gsl_vector_max(v_); }
148
149    ///
150    /// @return The element index to the maximum value of the
151    /// vector. The lowest index has precedence.
152    ///
153    // Jari, doxygen group as Finding maximum and minimum elements
154    inline size_t max_index(void) const { return gsl_vector_max_index(v_); }
155
156    ///
157    /// @return The minimum value of the vector.
158    ///
159    // Jari, doxygen group as Finding maximum and minimum elements
160    inline double min(void) const { return gsl_vector_min(v_); }
161
162    ///
163    /// @return The element index to the minimum value of the
164    /// vector. The lowest index has precedence.
165    ///
166    // Jari, doxygen group as Finding maximum and minimum elements
167    inline size_t min_index(void) const { return gsl_vector_min_index(v_); }
168
169    ///
170    /// @return The minimum and maximum values of the vector, as the
171    /// \a first and \a second member of the returned \a pair,
172    /// respectively.
173    ///
174    // Jari, doxygen group as Finding maximum and minimum elements
175    std::pair<double,double> minmax(void) const;
176
177    ///
178    /// @return The indecies to the minimum and maximum values of the
179    /// vector, as the \a first and \a second member of the returned
180    /// \a pair, respectively. The lowest index has precedence.
181    ///
182    // Jari, doxygen group as Finding maximum and minimum elements
183    std::pair<size_t,size_t> minmax_index(void) const;
184
185    ///
186    /// This function performs element-wise multiplication, \f$this_i =
187    /// this_i * other_i \; \forall i\f$.
188    ///
189    /// @return GSL_SUCCESS on normal exit.
190    ///
191    // Jari, doxygen group as Vector operators
192    inline int mul(const vector& other) { return gsl_vector_mul(v_,other.v_); }
193
194    ///
195    /// Reverse the order of elements in the vector.
196    ///
197    /// @return GSL_SUCCESS on normal exit.
198    ///
199    // Jari, doxygen group as Exchanging elements
200    inline int reverse(void) { return gsl_vector_reverse(v_);}
201
202    ///
203    /// Rescale vector, \f$this_i = this_i * factor \; \forall i\f$.
204    ///
205    /// @return GSL_SUCCESS on normal exit.
206    ///
207    // Jari, doxygen group as Vector operators
208    inline int scale(double factor) { return gsl_vector_scale(v_,factor); }
209
210    ///
211    /// Set all elements to \a value.
212    ///
213    // Jari, doxygen group as Initializing vector elements
214    inline void set_all(const double& value) { gsl_vector_set_all(v_,value); }
215
216    ///
217    /// Makes a basis vector by setting all elements to
218    /// zero except the \a i-th element which is set to
219    /// one.
220    ///
221    // Jari, doxygen group as Initializing vector elements
222    inline void set_basis(const size_t i) { gsl_vector_set_basis(v_,i); }
223   
224    ///
225    /// Set all elements to zero.
226    ///
227    // Jari, doxygen group as Initializing vector elements
228    inline void set_zero(void) { gsl_vector_set_zero(v_); }
229
230    ///
231    /// @return the number of elements in the vector.
232    ///
233    inline size_t size(void) const { return v_->size; }
234
235    ///
236    /// Vector subtraction, \f$this_i = this_i - other_i \; \forall i\f$.
237    ///
238    /// @return GSL_SUCCESS on normal exit.
239    ///
240    // Jari, doxygen group as Vector operators
241    inline int sub(const vector& other) { return gsl_vector_sub(v_,other.v_); }
242
243    ///
244    /// Calculate the sum of all vector elements.
245    ///
246    /// @return The sum.
247    ///
248    // Jari, doxygen group as "Extends GSL".
249    double sum(void) const;
250
251    ///
252    /// Swap vector elements by copying. The two vectors must have the
253    /// same length.
254    ///
255    /// @return GSL_SUCCESS on normal exit.
256    ///
257    inline int swap(vector& other) { return gsl_vector_swap(v_,other.v_); }
258
259    ///
260    /// Exchange elements \a i and \a j.
261    ///
262    /// @return GSL_SUCCESS on normal exit.
263    ///
264    // Jari, doxygen group as Exchanging elements
265    inline int
266    swap_elements(size_t i,size_t j) { return gsl_vector_swap_elements(v_,i,j);}
267
268    ///
269    /// Element access operator.
270    ///
271    /// @return Reference to element \a i.
272    ///
273    // Jari, doxygen group as Accessing vector elements
274    inline double& operator()(size_t i) { return *gsl_vector_ptr(v_,i); }
275
276    ///
277    /// Const element access operator.
278    ///
279    /// @return The value of element \a i.
280    ///
281    // Jari, doxygen group as Accessing vector elements
282    inline const double& operator()(size_t i) const
283      { return *gsl_vector_const_ptr(v_,i); }
284   
285    ///
286    /// Element access operator.
287    ///
288    /// @return Reference to element \a i.
289    ///
290    // Jari, doxygen group as Accessing vector elements
291    inline double& operator[](size_t i) { return *gsl_vector_ptr(v_,i); }
292
293    ///
294    /// Const element access operator.
295    ///
296    /// @return The value of element \a i.
297    ///
298    // Jari, doxygen group as Accessing vector elements
299    inline const double& operator[](size_t i) const
300      { return *gsl_vector_const_ptr(v_,i); }
301   
302    ///
303    /// @return The negation of the vector.
304    ///
305    vector operator-(void) const;
306
307    ///
308    /// @return The dot product.
309    ///
310    double operator*( const vector &other ) const;
311
312    ///
313    /// Vector with scalar multiplication.
314    ///
315    /// @note This operator is not implemented!
316    ///
317    vector operator*(const double d) const;
318
319    ///
320    /// Vector addition.
321    ///
322    /// @return The resulting vector.
323    ///
324    vector operator+( const vector& other ) const;
325
326    ///
327    /// Vector subtraction.
328    ///
329    /// @return The resulting vector.
330    ///
331    vector operator-( const vector& other ) const;
332
333    ///
334    /// Comparison operator. Takes linear time.
335    ///
336    /// @return True if the sequence of the elements in the vectors
337    /// are element/wise equal.
338    ///
339    bool operator==(const vector&) const;
340
341    ///
342    /// The assignment operator. There is no requirements on
343    /// dimensions.
344    ///
345    vector& operator=(const vector&);
346
347    ///
348    /// Addition and assign operator.
349    ///
350    /// @return The resulting vector.
351    ///
352    inline vector operator+=( const vector& other ) 
353    { gsl_vector_add(v_,other.v_); return *this; }
354
355    ///
356    /// Subtract and assign operator.
357    ///
358    /// @return The resulting vector.
359    ///
360    inline vector operator-=( const vector& other ) 
361    { gsl_vector_sub(v_,other.v_); return *this; }
362
363    ///
364    /// Multiply with scalar and assign operator.
365    ///
366    vector& operator*=(const double d) { gsl_vector_scale(v_,d); return *this; }
367
368
369  private:
370
371    ///
372    /// Create a new copy of the internal GSL vector.
373    ///
374    /// Necessary memory for the new GSL vector is allocated and the
375    /// caller is responsible for freeing the allocated memory.
376    ///
377    /// @return A pointer to a copy of the internal GSL vector.
378    ///
379    gsl_vector* TEMP_gsl_vector_copy(void) const;
380
381    gsl_vector* v_;
382    gsl_vector_view* view_;
383  };
384
385  ///
386  /// The output operator for the vector class.
387  /// @todo make higher precision.
388  std::ostream& operator<<(std::ostream&, const vector& );
389
390
391}} // of namespace gslapi and namespace theplu
392
393#endif
Note: See TracBrowser for help on using the repository browser.