casacore
Slice.h
Go to the documentation of this file.
1 //# Slice.h: Define a (start,length,increment) along an axis
2 //# Copyright (C) 1993,1994,1995,1997
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_SLICE_2_H
29 #define CASA_SLICE_2_H
30 
31 #include <cassert>
32 #include <unistd.h> //# for ssize_t
33 
34 #include "ArrayFwd.h"
35 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 //# Forward Declarations.
39 class Slicer;
40 class IPosition;
41 
42 // <summary> define a (start,length,increment) along an axis </summary>
43 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="" demos="">
44 // </reviewed>
45 //
46 // <synopsis>
47 // A "slice" (aka Section) is a a regular sub-Array (and ultimately sub-Image)
48 // that is defined by defining a (start,length,increment) for each axis in
49 // the array. That is, the output array's axis is of size "length", and the
50 // elements are sampled by stepping along the input array in strides of
51 // "increment".
52 // <note role=warning>
53 // The "length" is the length of the OUTPUT array, the output length
54 // is NOT divided by the increment/stride.
55 // </note>
56 // If increment is not defined, then it defaults to one.
57 // (Increment, if defined, must be >= 1). If length
58 // is not defined, then it defaults to a length of one also (i.e. just the pixel
59 // "start"). If start is also undefined, then all pixels along this axis are
60 // chosen. This class deprecates the "_" (IndexRange) class, which had a failed
61 // syntax and used (start,end,increment) which is generally less convenient.
62 // Some simple examples follow:
63 // <srcblock>
64 // Vector<int> vi(100); // Vector of length 100;
65 // //...
66 // // Copy odd values onto even values
67 // vi(Slice(0,50,2)) = vi(Slice(1,50,2));
68 //
69 // Matrix<float> mf(100,50), smallMf;
70 // smallMf.reference(mf(Slice(0,10,10), Slice(0,5,10)));
71 // // smallMF is now a "dezoomed" (every 10th pix)
72 // // refference to mf. Of course we could also
73 // // make it a copy by using assignment; e.g:
74 //
75 // smallMf.resize(0,0); // Make it so it will "size to fit"
76 // smallMf = mf(Slice(0,10,10), Slice(0,5,10));
77 // </srcblock>
78 // As shown above, normally Slices will normally be used as temporaries,
79 // but they may also be put into variables if desired (the default
80 // copy constructors and assignment operators suffice for this class).
81 //
82 // While it will be unusual for a user to want this, a zero-length slice
83 // is allowable.
84 //
85 // Another way to produce a slice from any of the Array classes is to use
86 // SomeArray(blc,trc,inc) where blc,trc,inc are IPositions. This is described
87 // in the documentation for Array<T>.
88 // </synopsis>
89 
90 class Slice
91 {
92 public:
93  // The entire range of indices on the axis is desired.
94  Slice();
95  // Create a Slice with a given start, length, and increment. The latter
96  // two default to one if not given.
97  Slice(size_t Start, size_t Length=1, size_t Inc=1);
98  // Create a Slice with a given start, end or length, and increment.
99  // If <src>endIsLength=false</src>, end is interpreted as length.
100  Slice(size_t Start, size_t End, size_t Inc, bool endIsLength);
101  // Was the entire range of indices on this axis selected?
102  bool all() const;
103  // Report the selected starting position. If all() is true,
104  // start=len=inc=0 is set.
105  size_t start() const;
106  // Report the defined length. If all() is true, start=len=inc=0 is set.
107  size_t length() const;
108  // Report the defined increment. If all() is true, start=len=inc=0 is set.
109  size_t inc() const;
110  // Attempt to report the last element of the slice. If all() is
111  // true, end() returns -1 (which is less than start(), which returns
112  // zero in that case).
113  size_t end() const;
114 
115  // Check a vector of slices.
116  // If a vector of an axis is empty or missing, it is replaced by a Slice
117  // representing the entire axis.
118  // It checks if the Slices do not exceed the array shape.
119  // It returns the shape of the combined slices and fills the Slicer
120  // for the first array part defined by the slices.
122  const IPosition& shape);
123 
124 private:
125  //# Inc of <0 is used as a private flag to mean that the whole axis is
126  //# selected. Users are given a size_t in their interface, so they cannot
127  //# set it to this. Chose Inc rather than length since it's more likely
128  //# that we'd need all bits of length than of inc. The "p" in the names
129  //# stands for private to avoid it colliding with the accessor names.
130  //# incp < 0 is chosen as the flag since the user can set inc to be zero
131  //# although that is an error that can be caught if AIPS_DEBUG is defined).
132  size_t startp;
133  ssize_t incp;
134  size_t lengthp;
135 };
136 
137 inline Slice::Slice() : startp(0), incp(-1), lengthp(0)
138 {
139  // Nothing
140 }
141 
142 inline
143 Slice::Slice(size_t Start, size_t Length, size_t Inc)
144  : startp(Start), incp(Inc), lengthp(Length)
145 {
146 #if defined(AIPS_DEBUG)
147  assert(incp > 0);
148 #endif
149 }
150 
151 inline
152 Slice::Slice(size_t Start, size_t End, size_t Inc, bool endIsLength)
153  : startp(Start), incp(Inc), lengthp(endIsLength ? End : 1+(End-Start)/Inc)
154 {
155 #if defined(AIPS_DEBUG)
156  if (! endIsLength) {
157  assert(End >= Start);
158  }
159  assert(incp > 0);
160 #endif
161 }
162 
163 inline bool Slice::all() const
164 {
165  return incp<0;
166 }
167 
168 inline size_t Slice::start() const
169 {
170  return startp;
171 }
172 
173 inline size_t Slice::length() const
174 {
175  return lengthp;
176 }
177 
178 inline size_t Slice::inc() const
179 {
180  if (all()) {
181  return 0;
182  } else {
183  return incp;
184  }
185 }
186 
187 inline size_t Slice::end() const
188 {
189  // return -1 if all()
190  return startp + (lengthp-1)*incp;
191 }
192 
193 
194 } //# NAMESPACE CASACORE - END
195 
196 #endif
ssize_t incp
Definition: Slice.h:133
size_t inc() const
Report the defined increment.
Definition: Slice.h:178
size_t lengthp
Definition: Slice.h:134
size_t end() const
Attempt to report the last element of the slice.
Definition: Slice.h:187
static IPosition checkSlices(Vector< Vector< Slice > > &slices, Slicer &first, const IPosition &shape)
Check a vector of slices.
size_t startp
Definition: Slice.h:132
size_t start() const
Report the selected starting position.
Definition: Slice.h:168
bool all() const
Was the entire range of indices on this axis selected?
Definition: Slice.h:163
Slice()
The entire range of indices on the axis is desired.
Definition: Slice.h:137
size_t length() const
Report the defined length.
Definition: Slice.h:173
struct Node * first
Definition: malloc.h:330
this file contains all the compiler specific defines
Definition: mainpage.dox:28
TableExprNode shape(const TableExprNode &array)
Function operating on any scalar or array resulting in a Double array containing the shape.
Definition: ExprNode.h:1987