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_2_H
29 #define CASA_VECTOR_2_H
30 
31 //# Includes
32 #include "Array.h"
33 
34 namespace casacore { //#Begin namespace casacore
35 
36 // <summary> A 1-D Specialization of the Array class </summary>
37 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="" demos="">
38 // </reviewed>
39 //
40 // Vector objects are one-dimensional specializations (e.g., more convenient
41 // and efficient indexing) of the general Array class. You might also want
42 // to look at the Array documentation to see inherited functionality.
43 //
44 // Generally the member functions of Array are also available in
45 // Vector versions
46 // which take an integer where the array needs an IPosition. Since the Vector
47 // is one-dimensional, the IPositions are overkill, although you may
48 // use those versions if you want to.
49 // <srcblock>
50 // Vector<int> vi(100); // Vector 100 elements long.
51 // vi.resize(50); // Now only 50 long.
52 // </srcblock>
53 //
54 // Slices may be taken with the Slice class. To take a slice, one "indexes"
55 // with Slice(start, length, inc) where end and inc are optional.
56 // <srcblock>
57 // Vector<float> vf(100);
58 // //...
59 // vf(Slice(0,50,2)) = vf(Slice(1,50,2)); // Copy values from odd onto even
60 // Vector<float> firstHalf, secondHalf;
61 // firstHalf.reference(vf(Slice(0,50)));
62 // secondHalf.reference(vf(Slice(50,50)));
63 // // Now we have aliases for two slices into the Vector
64 // </srcblock>
65 //
66 // Element-by-element arithmetic and logical operations are available (in
67 // aips/ArrayMath.h and aips/ArrayLogical.h) as well as dot and cross
68 // products (in aips/MatrixMath.h).
69 //
70 // A Vector can be constructed from an STL <src>vector</src>. The reverse
71 // operation (<src>Array::tovector()</src>) can construct an STL
72 // <src>vector</src> from any Array.
73 // <note role=tip> To create any other STL container from an Array (or
74 // the reverse), always create from/to a <src>vector</src>, and use the
75 // range constructor to create from/to others (like set, list, deque). </note>
76 //
77 // As with the Arrays, if the preprocessor symbol AIPS_DEBUG is
78 // defined at compile time invariants will be checked on entry to most
79 // member functions. Additionally, if AIPS_ARRAY_INDEX_CHECK is defined
80 // index operations will be bounds-checked. Neither of these should
81 // be defined for production code.
82 
83 template<typename T, typename Alloc> class Vector : public Array<T, Alloc>
84 {
85 public:
86  // A zero-length Vector.
87  Vector();
88 
89  // A Vector with a defined length and origin of zero.
90  // <group>
91  explicit Vector(size_t Length);
92  explicit Vector(const IPosition& Length);
93  // </group>
94 
95  // A Vector with a defined length and origin of zero.
96  // Fill it with the initial value.
97  // <group>
98  Vector(size_t Length, const T &initialValue);
99  Vector(const IPosition& Length, const T &initialValue);
100  // </group>
101 
102  // An uninitialized Vector with a defined length.
103  // <group>
104  Vector(size_t Length, typename Array<T, Alloc>::uninitializedType, const Alloc& allocator=Alloc());
105  Vector(const IPosition& Length, typename Array<T, Alloc>::uninitializedType, const Alloc& allocator=Alloc());
106  // </group>
107 
108  // Create a Vector from the given std::vector "other." Make it length "nr"
109  // and copy over that many elements.
110  // This used to take a 'Block'
111  Vector(const std::vector<T> &other, long long nr);
112 
113  // Create a Vector of length other.size() and copy over its values.
114  // This used to take a 'Block'
115  explicit Vector(const std::vector<T> &other, const Alloc& allocator=Alloc());
116 
117  // Create a Vector from an initializer list.
118  Vector(std::initializer_list<T> list);
119 
120  // Create a reference to other.
121  Vector(const Vector<T, Alloc> &other);
122 
123  // Move
124  Vector(Vector<T, Alloc>&& source) noexcept;
125 
126  // Create a reference to the other array.
127  // It is always possible if the array has zero or one axes.
128  // If it has > 1 axes, it is only possible if the array has at most
129  // one axis with length > 1. In that case the degenerated axes are removed.
130  Vector(const Array<T, Alloc> &other);
131 
132  // Create an Vector of a given shape from a pointer.
133  Vector(const IPosition &shape, T *storage, StorageInitPolicy policy = COPY);
134  // Create an Vector of a given shape from a pointer.
135  Vector(const IPosition &shape, T *storage, StorageInitPolicy policy, Alloc& allocator);
136  // Create an Vector of a given shape from a pointer. Because the pointer
137  // is const, a copy is always made.
138  Vector(const IPosition &shape, const T *storage);
139 
140  template<typename InputIterator>
141  Vector(InputIterator startIter, InputIterator endIter, const Alloc& allocator = Alloc());
142 
143  // Create a Vector from an STL vector (see <src>tovector()</src> in
144  // <linkto class=Array>Array</linkto> for the reverse operation).
145  // <note role=tip> Both this constructor and the tovector() are
146  // defined in <src>Vector2.cc</src>. </note>
147  // It does implicit promotion/demotion of the type U if different from T.
148  template <typename U, typename V>
149  explicit Vector(const std::vector<U, V> &other);
150 
151  // Create a Vector from a container iterator and its length.
152  // <note> The length is used instead of last, because the distance
153  // function needed to calculate the length can be expensive.
154  // <br>A third dummy argument is unfortunately needed to avoid ambiguity
155  // with another Vector constructor (taking two uInts).
156  // </note>
157  template<typename Iterator>
158  Vector(Iterator first, size_t size, int dummy);
159 
160  // Resize this Vector to the given length.
161  // The default copyValues flag is false.
162  //# Note that the 3rd resize function is necessary, because that
163  //# function is virtual in the base class (otherwise it would
164  //# be hidden).
165  // Resize without argument is equal to resize(0, false).
166  // <group>
168  void resize(size_t len, bool copyValues=false)
169  { if (len != this->nelements()) resize(IPosition(1,len), copyValues); }
170  virtual void resize(const IPosition &len, bool copyValues=false) final override;
171  // </group>
172 
173  // Assign to this Vector. If this Vector is zero-length, then resize
174  // to be the same size as other. Otherwise this and other have to be
175  // conformant (same size).
176  // <br>Note that the assign function can be used to assign a
177  // non-conforming vector.
178  // <group>
179  // TODO unlike Array, a Vector assign to an empty Vector does
180  // not create a reference but does a value copy of the source.
181  // This should be made consistent.
182  using Array<T, Alloc>::assign_conforming;
183  Vector<T, Alloc>& assign_conforming(const Vector<T, Alloc>& source)
184  {
185  return assign_conforming_implementation(source, std::is_copy_assignable<T>());
186  }
188  // source must be a 1-dimensional array.
191  // </group>
192 
195  { return assign_conforming(source); }
197  { return assign_conforming(std::move(source)); }
199  { assign_conforming(source); return *this; }
201  { assign_conforming(std::move(source)); return *this; }
202 
203  // Convert a Vector to a Block, resizing the block and copying values.
204  // This is done this way to avoid having the simpler Block class
205  // containing dependencies on the Vector class.
206  //void toBlock(Block<T> &other) const;
207 
208  // Single-pixel addressing. If AIPS_ARRAY_INDEX_CHECK is defined,
209  // bounds checking is performed (not for [])..
210  // <group>
211  T &operator[](size_t index)
212  { return (this->contiguous_p ? this->begin_p[index] : this->begin_p[index*this->inc_p(0)]); }
213  const T &operator[](size_t index) const
214  { return (this->contiguous_p ? this->begin_p[index] : this->begin_p[index*this->inc_p(0)]); }
215  T &operator()(const IPosition &i)
216  { return Array<T>::operator()(i); }
217  const T &operator()(const IPosition &i) const
218  { return Array<T>::operator()(i); }
219  T &operator()(size_t index)
220  {
221 #if defined(AIPS_ARRAY_INDEX_CHECK)
222  this->validateIndex(index); //# Throws an exception on failure
223 #endif
224  return *(this->begin_p + index*this->inc_p(0));
225  }
226 
227  const T &operator()(size_t index) const
228  {
229 #if defined(AIPS_ARRAY_INDEX_CHECK)
230  this->validateIndex(index); //# Throws an exception on failure
231 #endif
232  return *(this->begin_p + index*this->inc_p(0));
233  }
234  // </group>
235 
236  // Take a slice of this vector. Slices are always indexed starting
237  // at zero. This uses reference semantics, i.e. changing a value
238  // in the slice changes the original.
239  // <srcblock>
240  // Vector<double> vd(100);
241  // //...
242  // vd(Slice(0,10)) = -1.0; // First 10 elements of vd set to -1
243  // </srcblock>
244  // <group>
246  const Vector<T, Alloc> operator()(const Slice &slice) const;
247  // </group>
248 
249  // Slice using IPositions. Required to be defined, otherwise the base
250  // class versions are hidden.
251  // <group>
253  const IPosition &incr)
254  { return Array<T, Alloc>::operator()(blc,trc,incr); }
255  const Array<T, Alloc> operator()(const IPosition &blc, const IPosition &trc,
256  const IPosition &incr) const
257  { return Array<T, Alloc>::operator()(blc,trc,incr); }
259  { return Array<T, Alloc>::operator()(blc,trc); }
260  const Array<T, Alloc> operator()(const IPosition &blc, const IPosition &trc) const
261  { return Array<T, Alloc>::operator()(blc,trc); }
263  { return Array<T, Alloc>::operator()(slicer); }
264  const Array<T, Alloc> operator()(const Slicer& slicer) const
265  { return Array<T, Alloc>::operator()(slicer); }
266  // </group>
267 
268  // The array is masked by the input LogicalArray.
269  // This mask must conform to the array.
270  // <group>
271 
272  // Return a MaskedArray.
274  { return Array<T>::operator() (mask); }
275 
276  // Return a MaskedArray.
278  { return Array<T>::operator() (mask); }
279 
280  // </group>
281 
282 
283  // The array is masked by the input MaskedLogicalArray.
284  // The mask is effectively the AND of the internal LogicalArray
285  // and the internal mask of the MaskedLogicalArray.
286  // The MaskedLogicalArray must conform to the array.
287  // <group>
288 
289  // Return a MaskedArray.
291  { return Array<T>::operator() (mask); }
292 
293  // Return a MaskedArray.
295  { return Array<T>::operator() (mask); }
296 
297  // </group>
298 
299 
300  // The length of the Vector.
301  const IPosition &shape() const
302  { return this->length_p; }
303  void shape(int &Shape) const
304  { Shape = this->length_p(0); }
305 
306  // Verify that dimensionality is 1 and then call Array<T>::ok()
307  virtual bool ok() const final override;
308 
309 protected:
310  // Remove the degenerate axes from other and store result in this vector.
311  // An exception is thrown if removing degenerate axes does not result
312  // in a vector.
313  virtual void doNonDegenerate(const Array<T> &other,
314  const IPosition &ignoreAxes) final override;
315 
316  virtual size_t fixedDimensionality() const final override { return 1; }
317 
318 private:
321 
322  // Helper functions for constructors.
323  void initVector(const std::vector<T>&, long long nr); // copy semantics
324 
325  // The following two constructors are used to make distinguish between
326  // Vector<literal>(literal size, literal value)
327  // and
328  // Vector<literal>(iterator, iterator)
329  template<typename InputIterator>
330  Vector(InputIterator startIter, InputIterator endIter, const Alloc& allocator, std::false_type /* T is not a literal */);
331 
332  template<typename InputIterator>
333  Vector(InputIterator startIter, InputIterator endIter, const Alloc& allocator, std::true_type /* T is literal */);
334 };
335 
336 } //#End namespace casacore
337 
338 #include "Vector.tcc"
339 #include "Vector2.tcc"
340 
341 #endif
void validateIndex(const IPosition &) const
size_t nelements() const
How many elements does this array have? Product of all axis lengths.
Definition: ArrayBase.h:103
size_t size() const
Definition: ArrayBase.h:105
bool contiguous_p
Are the data contiguous?
Definition: ArrayBase.h:273
IPosition length_p
Used to hold the shape, increment into the underlying storage and originalLength of the array.
Definition: ArrayBase.h:276
T & operator()(const IPosition &)
Access a single element of the array.
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:986
Alloc & allocator()
Retrieve the allocator associated with this array.
Definition: Array.h:234
Vector(InputIterator startIter, InputIterator endIter, const Alloc &allocator=Alloc())
Array< T, Alloc > operator()(const IPosition &blc, const IPosition &trc, const IPosition &incr)
Slice using IPositions.
Definition: Vector.h:252
T & operator()(size_t index)
Definition: Vector.h:219
Vector(const std::vector< T > &other, long long nr)
Create a Vector from the given std::vector "other." Make it length "nr" and copy over that many eleme...
const Array< T, Alloc > operator()(const IPosition &blc, const IPosition &trc, const IPosition &incr) const
Definition: Vector.h:255
Vector< T, Alloc > & assign_conforming(Vector< T, Alloc > &&source)
void shape(int &Shape) const
Definition: Vector.h:303
Array< T, Alloc > operator()(const Slicer &slicer)
Definition: Vector.h:262
Vector(const Vector< T, Alloc > &other)
Create a reference to other.
const Vector< T, Alloc > operator()(const Slice &slice) const
Vector()
A zero-length Vector.
Vector< T, Alloc > operator()(const Slice &slice)
Take a slice of this vector.
const Array< T, Alloc > operator()(const Slicer &slicer) const
Definition: Vector.h:264
Array< T, Alloc > operator()(const IPosition &blc, const IPosition &trc)
Definition: Vector.h:258
Vector< T, Alloc > & assign_conforming_implementation(const Vector< T, Alloc > &v, std::false_type isCopyable)
Vector(const IPosition &Length)
const T & operator()(size_t index) const
Definition: Vector.h:227
Vector< T, Alloc > & assign_conforming(const Vector< T, Alloc > &source)
Definition: Vector.h:183
Vector(InputIterator startIter, InputIterator endIter, const Alloc &allocator, std::false_type)
The following two constructors are used to make distinguish between Vector<literal>(literal size,...
const T & operator[](size_t index) const
Definition: Vector.h:213
Vector(const IPosition &Length, typename Array< T, Alloc >::uninitializedType, const Alloc &allocator=Alloc())
Vector(Iterator first, size_t size, int dummy)
Create a Vector from a container iterator and its length.
Vector< T, Alloc > & operator=(const Vector< T, Alloc > &source)
Definition: Vector.h:194
Vector(const IPosition &shape, T *storage, StorageInitPolicy policy=COPY)
Create an Vector of a given shape from a pointer.
Vector(const IPosition &Length, const T &initialValue)
Vector< T, Alloc > & assign_conforming(const Array< T, Alloc > &source)
source must be a 1-dimensional array.
T & operator()(const IPosition &i)
Definition: Vector.h:215
Vector(Vector< T, Alloc > &&source) noexcept
Move.
Vector< T, Alloc > & operator=(Array< T, Alloc > &&source)
Definition: Vector.h:200
Vector< T, Alloc > & assign_conforming(Array< T, Alloc > &&source)
Vector< T, Alloc > & assign_conforming_implementation(const Vector< T, Alloc > &v, std::true_type isCopyable)
const IPosition & shape() const
The length of the Vector.
Definition: Vector.h:301
const Array< T, Alloc > operator()(const IPosition &blc, const IPosition &trc) const
Definition: Vector.h:260
Vector(const std::vector< U, V > &other)
Create a Vector from an STL vector (see tovector() in Array for the reverse operation).
Vector(const IPosition &shape, const T *storage)
Create an Vector of a given shape from a pointer.
virtual bool ok() const final override
Verify that dimensionality is 1 and then call Array<T>::ok()
virtual void resize(const IPosition &len, bool copyValues=false) final override
Resize the array and optionally copy the values.
Vector< T, Alloc > & operator=(const Array< T, Alloc > &source)
Definition: Vector.h:198
virtual size_t fixedDimensionality() const final override
Subclasses can return their dimensionality.
Definition: Vector.h:316
Vector(size_t Length)
A Vector with a defined length and origin of zero.
Vector(const IPosition &shape, T *storage, StorageInitPolicy policy, Alloc &allocator)
Create an Vector of a given shape from a pointer.
Vector< T, Alloc > & operator=(Vector< T, Alloc > &&source)
Definition: Vector.h:196
const T & operator()(const IPosition &i) const
Definition: Vector.h:217
Vector(const Array< T, Alloc > &other)
Create a reference to the other array.
void initVector(const std::vector< T > &, long long nr)
Helper functions for constructors.
Vector(const std::vector< T > &other, const Alloc &allocator=Alloc())
Create a Vector of length other.size() and copy over its values.
Vector(std::initializer_list< T > list)
Create a Vector from an initializer list.
Vector(InputIterator startIter, InputIterator endIter, const Alloc &allocator, std::true_type)
T & operator[](size_t index)
Convert a Vector to a Block, resizing the block and copying values.
Definition: Vector.h:211
virtual void doNonDegenerate(const Array< T > &other, const IPosition &ignoreAxes) final override
Remove the degenerate axes from other and store result in this vector.
Vector(size_t Length, const T &initialValue)
A Vector with a defined length and origin of zero.
Vector(size_t Length, typename Array< T, Alloc >::uninitializedType, const Alloc &allocator=Alloc())
An uninitialized Vector with a defined length.
void resize(size_t len, bool copyValues=false)
Definition: Vector.h:168
StorageInitPolicy
Definition: ArrayBase.h:51
@ COPY
COPY is used when an internal copy of the storage is to be made.
Definition: ArrayBase.h:54
struct Node * first
Definition: malloc.h:330
this file contains all the compiler specific defines
Definition: mainpage.dox:28
LatticeExprNode mask(const LatticeExprNode &expr)
This function returns the mask of the given expression.
This is a tag for the constructor that may be used to construct an uninitialized Array.
Definition: Array.h:181