casacore
Loading...
Searching...
No Matches
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
36namespace casacore { //# NAMESPACE CASACORE - BEGIN
37
38//# Forward Declarations.
39class Slicer;
40class 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
90class Slice
91{
92public:
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
124private:
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
137inline Slice::Slice() : startp(0), incp(-1), lengthp(0)
138{
139 // Nothing
140}
141
142inline
143Slice::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
151inline
152Slice::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
163inline bool Slice::all() const
164{
165 return incp<0;
166}
167
168inline size_t Slice::start() const
169{
170 return startp;
171}
172
173inline size_t Slice::length() const
174{
175 return lengthp;
176}
177
178inline size_t Slice::inc() const
179{
180 if (all()) {
181 return 0;
182 } else {
183 return incp;
184 }
185}
186
187inline 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