casacore
Vector.h
Go to the documentation of this file.
1 //# Vector.h: A 1-D Specialization of the Array Class
2 //# Copyright (C) 1993,1994,1995,1996,1998,1999,2000,2001,2002,2003
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 #ifndef CASA_VECTOR_H
29 #define CASA_VECTOR_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/casa/Arrays/Array.h>
34 
35 //# Forward declarations
36 //template <class T, class U> class vector;
37 #if defined(WHATEVER_VECTOR_FORWARD_DEC)
39 #else
40 #include <casacore/casa/stdvector.h>
41 #endif
42 
43 namespace casacore { //#Begin namespace casacore
44 
45 // <summary> A 1-D Specialization of the Array class </summary>
46 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="" demos="">
47 // </reviewed>
48 //
49 // Vector objects are one-dimensional specializations (e.g., more convenient
50 // and efficient indexing) of the general Array class. You might also want
51 // to look at the Array documentation to see inherited functionality.
52 //
53 // Generally the member functions of Array are also available in
54 // Vector versions
55 // which take an integer where the array needs an IPosition. Since the Vector
56 // is one-dimensional, the IPositions are overkill, although you may
57 // use those versions if you want to.
58 // <srcblock>
59 // Vector<Int> vi(100); // Vector 100 elements long.
60 // vi.resize(50); // Now only 50 long.
61 // </srcblock>
62 //
63 // Slices may be taken with the Slice class. To take a slice, one "indexes"
64 // with Slice(start, length, inc) where end and inc are optional.
65 // <srcblock>
66 // Vector<Float> vf(100);
67 // //...
68 // vf(Slice(0,50,2)) = vf(Slice(1,50,2)); // Copy values from odd onto even
69 // Vector<Float> firstHalf, secondHalf;
70 // firstHalf.reference(vf(Slice(0,50)));
71 // secondHalf.reference(vf(Slice(50,50)));
72 // // Now we have aliases for two slices into the Vector
73 // </srcblock>
74 //
75 // Element-by-element arithmetic and logical operations are available (in
76 // aips/ArrayMath.h and aips/ArrayLogical.h) as well as dot and cross
77 // products (in aips/MatrixMath.h).
78 //
79 // A Vector can be constructed from an STL <src>vector</src>. The reverse
80 // operation (<src>Array::tovector()</src>) can construct an STL
81 // <src>vector</src> from any Array.
82 // <note role=tip> To create any other STL container from an Array (or
83 // the reverse), always create from/to a <src>vector</src>, and use the
84 // range constructor to create from/to others (like set, list, deque). </note>
85 //
86 // As with the Arrays, if the preprocessor symbol AIPS_DEBUG is
87 // defined at compile time invariants will be checked on entry to most
88 // member functions. Additionally, if AIPS_ARRAY_INDEX_CHECK is defined
89 // index operations will be bounds-checked. Neither of these should
90 // be defined for production code.
91 
92 template<class T> class Vector : public Array<T>
93 {
94 public:
95  // A zero-length Vector.
96  Vector();
97 
98  // A Vector with a defined length and origin of zero.
99  // <group>
100  explicit Vector(size_t Length);
101  Vector(size_t Length, ArrayInitPolicy initPolicy);
102  explicit Vector(const IPosition& Length);
103  Vector(const IPosition& Length, ArrayInitPolicy initPolicy);
104  // </group>
105 
106  // A Vector with a defined length and origin of zero.
107  // Fill it with the initial value.
108  // <group>
109  Vector(size_t Length, const T &initialValue);
110  Vector(const IPosition& Length, const T &initialValue);
111  // </group>
112 
113  // Create a Vector from the given Block "other." Make it length "nr"
114  // and copy over that many elements.
115  Vector(const Block<T> &other, Int64 nr);
116  // Create a Vector of length other.nelements() and copy over its values.
117  explicit Vector(const Block<T> &other);
118 
119  // Create a reference to other.
120  Vector(const Vector<T> &other);
121 
122  // Create a reference to the other array.
123  // It is always possible if the array has zero or one axes.
124  // If it has > 1 axes, it is only possible if the array has at most
125  // one axis with length > 1. In that case the degenerated axes are removed.
126  Vector(const Array<T> &other);
127 
128  // Create an Vector of a given shape from a pointer.
129  Vector(const IPosition &shape, T *storage, StorageInitPolicy policy = COPY);
130  // Create an Vector of a given shape from a pointer.
131  Vector(const IPosition &shape, T *storage, StorageInitPolicy policy, AbstractAllocator<T> const &allocator);
132  // Create an Vector of a given shape from a pointer. Because the pointer
133  // is const, a copy is always made.
134  Vector(const IPosition &shape, const T *storage);
135 
136  // Create a Vector from an STL vector (see <src>tovector()</src> in
137  // <linkto class=Array>Array</linkto> for the reverse operation).
138  // <note role=tip> Both this constructor and the tovector() are
139  // defined in <src>Vector2.cc</src>. </note>
140  // It does implicit promotion/demotion of the type U if different from T.
141  template <class U, class V>
142  Vector(const vector<U, V> &other);
143 
144  // Create a Vector from a container iterator and its length.
145  // <note> The length is used instead of last, because the distance
146  // function needed to calculate the length can be expensive.
147  // <br>A third dummy argument is unfortunately needed to avoid ambiguity
148  // with another Vector constructor (taking two uInts).
149  // </note>
150  template<typename Iterator>
151  Vector(Iterator first, size_t size, int dummy);
152 
153  // Define a destructor, otherwise the compiler makes a static one.
154  virtual ~Vector();
155 
156  // Assign the other array (which must be of dimension one) to this vector.
157  // If the shapes mismatch, this array is resized.
158  virtual void assign (const Array<T>& other);
159 
160  // Create a reference to "other", which must be of dimension one.
161  virtual void reference(const Array<T> &other);
162 
163  // Resize this Vector to the given length.
164  // The default copyValues flag is False.
165  //# Note that the 3rd resize function is necessary, because that
166  //# function is virtual in the base class (otherwise it would
167  //# be hidden).
168  // Resize without argument is equal to resize(0, False).
169  // <group>
170  using Array<T>::resize;
171  void resize(size_t len, Bool copyValues=False)
172  { Vector<T>::resize(len, copyValues, Array<T>::defaultArrayInitPolicy()); }
173  void resize(size_t len, Bool copyValues, ArrayInitPolicy policy)
174  { if (len != this->nelements()) resize (IPosition(1,len), copyValues, policy); }
175  virtual void resize();
176  virtual void resize(const IPosition &len, Bool copyValues, ArrayInitPolicy policy);
177  // </group>
178 
179  // Assign to this Vector. If this Vector is zero-length, then resize
180  // to be the same size as other. Otherwise this and other have to be
181  // conformant (same size).
182  // <br>Note that the assign function can be used to assign a
183  // non-conforming vector.
184  // <group>
185  Vector<T> &operator=(const Vector<T> &other);
186  // Other must be a 1-dimensional array.
187  virtual Array<T> &operator=(const Array<T> &other);
188  // </group>
189 
190  // Set every element of this Vector to Val.
191  Array<T> &operator=(const T &val)
192  { return Array<T>::operator=(val); }
193 
194  // Copy to this those values in marray whose corresponding elements
195  // in marray's mask are True.
197  { Array<T> (*this) = marray; return *this; }
198 
199  // Convert a Vector to a Block, resizing the block and copying values.
200  // This is done this way to avoid having the simpler Block class
201  // containing dependencies on the Vector class.
202  void toBlock(Block<T> &other) const;
203 
204  // Single-pixel addressing. If AIPS_ARRAY_INDEX_CHECK is defined,
205  // bounds checking is performed (not for [])..
206  // <group>
207  T &operator[](size_t index)
208  { return (this->contiguous_p ? this->begin_p[index] : this->begin_p[index*this->inc_p(0)]); }
209  const T &operator[](size_t index) const
210  { return (this->contiguous_p ? this->begin_p[index] : this->begin_p[index*this->inc_p(0)]); }
211  T &operator()(const IPosition &i)
212  { return Array<T>::operator()(i); }
213  const T &operator()(const IPosition &i) const
214  { return Array<T>::operator()(i); }
215  T &operator()(size_t index)
216  {
217 #if defined(AIPS_ARRAY_INDEX_CHECK)
218  this->validateIndex(index); //# Throws an exception on failure
219 #endif
220  return *(this->begin_p + index*this->inc_p(0));
221  }
222 
223  const T &operator()(size_t index) const
224  {
225 #if defined(AIPS_ARRAY_INDEX_CHECK)
226  this->validateIndex(index); //# Throws an exception on failure
227 #endif
228  return *(this->begin_p + index*this->inc_p(0));
229  }
230  // </group>
231 
232  // Take a slice of this vector. Slices are always indexed starting
233  // at zero. This uses reference semantics, i.e. changing a value
234  // in the slice changes the original.
235  // <srcblock>
236  // Vector<Double> vd(100);
237  // //...
238  // vd(Slice(0,10)) = -1.0; // First 10 elements of vd set to -1
239  // </srcblock>
240  // <group>
241  Vector<T> operator()(const Slice &slice);
242  const Vector<T> operator()(const Slice &slice) const;
243  // </group>
244 
245  // Slice using IPositions. Required to be defined, otherwise the base
246  // class versions are hidden.
247  // <group>
248  Array<T> operator()(const IPosition &blc, const IPosition &trc,
249  const IPosition &incr)
250  { return Array<T>::operator()(blc,trc,incr); }
251  const Array<T> operator()(const IPosition &blc, const IPosition &trc,
252  const IPosition &incr) const
253  { return Array<T>::operator()(blc,trc,incr); }
254  Array<T> operator()(const IPosition &blc, const IPosition &trc)
255  { return Array<T>::operator()(blc,trc); }
256  const Array<T> operator()(const IPosition &blc, const IPosition &trc) const
257  { return Array<T>::operator()(blc,trc); }
258  Array<T> operator()(const Slicer& slicer)
259  { return Array<T>::operator()(slicer); }
260  const Array<T> operator()(const Slicer& slicer) const
261  { return Array<T>::operator()(slicer); }
262  // </group>
263 
264  // The array is masked by the input LogicalArray.
265  // This mask must conform to the array.
266  // <group>
267 
268  // Return a MaskedArray.
269  MaskedArray<T> operator() (const LogicalArray &mask) const
270  { return Array<T>::operator() (mask); }
271 
272  // Return a MaskedArray.
273  MaskedArray<T> operator() (const LogicalArray &mask)
274  { return Array<T>::operator() (mask); }
275 
276  // </group>
277 
278 
279  // The array is masked by the input MaskedLogicalArray.
280  // The mask is effectively the AND of the internal LogicalArray
281  // and the internal mask of the MaskedLogicalArray.
282  // The MaskedLogicalArray must conform to the array.
283  // <group>
284 
285  // Return a MaskedArray.
286  MaskedArray<T> operator() (const MaskedLogicalArray &mask) const
287  { return Array<T>::operator() (mask); }
288 
289  // Return a MaskedArray.
290  MaskedArray<T> operator() (const MaskedLogicalArray &mask)
291  { return Array<T>::operator() (mask); }
292 
293  // </group>
294 
295 
296  // The length of the Vector.
297  const IPosition &shape() const
298  { return this->length_p; }
299  void shape(Int &Shape) const
300  { Shape = this->length_p(0); }
301 
302  // Verify that dimensionality is 1 and then call Array<T>::ok()
303  virtual Bool ok() const;
304 
305 protected:
306  virtual void preTakeStorage(const IPosition &shape);
307  // Remove the degenerate axes from other and store result in this vector.
308  // An exception is thrown if removing degenerate axes does not result
309  // in a vector.
310  virtual void doNonDegenerate(const Array<T> &other,
311  const IPosition &ignoreAxes);
312 
313 private:
314  // Helper functions for constructors.
315  void initVector(const Block<T> &, Int64 nr); // copy semantics
316 };
317 
318 
319 //# Declare extern templates for often used types.
320  extern template class Vector<Bool>;
321  extern template class Vector<Char>;
322  extern template class Vector<Short>;
323  extern template class Vector<uShort>;
324  extern template class Vector<Int>;
325  extern template class Vector<uInt>;
326  extern template class Vector<Int64>;
327  extern template class Vector<Float>;
328  extern template class Vector<Double>;
329  extern template class Vector<Complex>;
330  extern template class Vector<DComplex>;
331  extern template class Vector<String>;
332 
333 } //#End namespace casacore
334 
335 
336 #ifndef CASACORE_NO_AUTO_TEMPLATES
337 #include <casacore/casa/Arrays/Vector.tcc>
338 #include <casacore/casa/Arrays/Vector2.tcc>
339 #endif //# CASACORE_NO_AUTO_TEMPLATES
340 #endif
Bool contiguous_p
Are the data contiguous?
Definition: ArrayBase.h:268
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:119
size_t size() const
Definition: ArrayBase.h:101
const IPosition & shape() const
The length of the Vector.
Definition: Vector.h:297
T & operator[](size_t index)
Single-pixel addressing.
Definition: Vector.h:207
A 1-D Specialization of the Array class.
Definition: ArrayIO.h:45
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
int Int
Definition: aipstype.h:50
Vector()
A zero-length Vector.
const Array< T > operator()(const IPosition &blc, const IPosition &trc, const IPosition &incr) const
Definition: Vector.h:251
LatticeExprNode mask(const LatticeExprNode &expr)
This function returns the mask of the given expression.
struct Node * first
Definition: malloc.h:330
StorageInitPolicy
A global enum used by some Array constructors.
Definition: ArrayBase.h:53
const T & operator()(const IPosition &i) const
Definition: Vector.h:213
const T & operator[](size_t index) const
Definition: Vector.h:209
TableExprNode marray(const TableExprNode &array, const TableExprNode &mask)
Form a masked array.
Definition: ExprNode.h:2111
#define WHATEVER_VECTOR_FORWARD_DEC
Definition: aipsdef.h:112
A global enum used by some Array/Block constructors.
Definition: Allocator.h:52
IPosition length_p
Used to hold the shape, increment into the underlying storage and originalLength of the array...
Definition: ArrayBase.h:271
Array< T > operator()(const IPosition &blc, const IPosition &trc)
Definition: Vector.h:254
virtual void doNonDegenerate(const Array< T > &other, const IPosition &ignoreAxes)
Remove the degenerate axes from other and store result in this vector.
Class for masking an Array for operations on that Array.
Definition: Array.h:55
virtual void resize()
Make this array a different shape.
const T & operator()(size_t index) const
Definition: Vector.h:223
Array< T > & operator=(const T &val)
Set every element of this Vector to Val.
Definition: Vector.h:191
Array< T > operator()(const IPosition &blc, const IPosition &trc, const IPosition &incr)
Slice using IPositions.
Definition: Vector.h:248
size_t nelements() const
How many elements does this array have? Product of all axis lengths.
Definition: ArrayBase.h:99
Vector< T > & operator=(const Vector< T > &other)
Assign to this Vector.
virtual void assign(const Array< T > &other)
Assign the other array (which must be of dimension one) to this vector.
define a (start,length,increment) along an axis
Definition: Slice.h:93
virtual Array< T > & operator=(const Array< T > &other)
Copy the values in other to this.
void shape(Int &Shape) const
Definition: Vector.h:299
void initVector(const Block< T > &, Int64 nr)
Helper functions for constructors.
T & operator()(const IPosition &)
Access a single element of the array.
virtual Bool ok() const
Verify that dimensionality is 1 and then call Array<T>::ok()
T & operator()(size_t index)
Definition: Vector.h:215
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
virtual ~Vector()
Define a destructor, otherwise the compiler makes a static one.
virtual void resize()
Make this array a different shape.
T * begin_p
This pointer is adjusted to point to the first element of the array.
Definition: Array.h:916
const Bool False
Definition: aipstype.h:44
virtual void preTakeStorage(const IPosition &shape)
pre/post processing hook of takeStorage() for subclasses.
template <class T, class U> class vector;
Definition: Array.h:169
Array< T > operator()(const Slicer &slicer)
Definition: Vector.h:258
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:289
simple 1-D array
Definition: ArrayIO.h:47
COPY is used when an internal copy of the storage is to be made.
Definition: ArrayBase.h:56
const Array< T > operator()(const IPosition &blc, const IPosition &trc) const
Definition: Vector.h:256
void resize(size_t len, Bool copyValues, ArrayInitPolicy policy)
Definition: Vector.h:173
void resize(size_t len, Bool copyValues=False)
Definition: Vector.h:171
virtual void reference(const Array< T > &other)
Create a reference to "other", which must be of dimension one.
void validateIndex(const IPosition &) const
void toBlock(Block< T > &other) const
Convert a Vector to a Block, resizing the block and copying values.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
T & operator()(const IPosition &i)
Definition: Vector.h:211
const Array< T > operator()(const Slicer &slicer) const
Definition: Vector.h:260