IPosition objects are normally used to index into, and define the shapes of, multi-dimensional arrays. For example, if you have a 5 dimensional array, you need an IPosition of length 5 to index into the array (or to define its shape, etc.).

Unlike Vectors, IPositions always use copy semantics.

    IPosition ip1(5);                         // An IPosition of length 5
    ip1(0) = 11; ip1(1) = 5; ... ip1(4) = 6;  // Indices 0-based
    IPosition ip2(ip1);                       // Copy constructor; a COPY
    

Binary operations must take place either with a conformnat (same size) IPosition or with an integer, which behaves as if it was an IPosition of the same size (i.e., length). All the usual binary arithmetic operations are available, as well as logical operations, which return Booleans. These all operate "element-by-element".

All non-inlined member functions of IPosition check invariants if the preprocessor symbol AIPS_DEBUG is defined. That is, the member functions check that ok() is true (constructors check after construction, other functions on entry to the function). If these tests fail, an AipsError exception is thrown; its message contains the line number and source file of the failure (it is thrown by the lAssert macro defined in aips/Assert.h).

Example

    IPosition blc(5), trc(5,1,2,3,4,5);
    blc = 0;            // OR IPosition blc(5,0);
    //...
    if (blc > trc) {
       IPosition tmp;
       tmp = trc;       // Swap
       trc = blc;
       blc = tmp;
    }
    //...
    trc += 5;           // make the box 5 larger in all dimensions
    

Member Description

enum

IPosition()

explicit IPosition(uInt length)

An IPosition of size "length." The values in the object are undefined.

IPosition(uInt length, Int val)

An IPosition of size "length." The values in the object get initialized to val.

IPosition (uInt length, Int val0, Int val1, Int val2=MIN_INT, Int val3=MIN_INT, Int val4=MIN_INT, Int val5=MIN_INT, Int val6=MIN_INT, Int val7=MIN_INT, Int val8=MIN_INT, Int val9=MIN_INT)

An IPosition of size "length" with defined values. You need to supply a value for each element of the IPosition (up to 10). [Unfortunately varargs might not be sufficiently portable.]

IPosition(const IPosition& other)

Makes a copy (copy, NOT reference, semantics) of other.

~IPosition()

IPosition& operator=(const IPosition& other)

Makes this a copy of other. "this" and "other" must either be conformant (same size) or this must be 0-length, in which case it will resize itself to be the same length as other.

IPosition& operator=(Int value)

Copy "value" into every position of this IPosition.

static IPosition makeAxisPath (uInt nrdim)

Construct a default axis path consisting of the values 0 .. nrdim-1.

static IPosition makeAxisPath (uInt nrdim, const IPosition& partialPath)

Construct a full axis path from a (partially) given axis path. It fills the path with the non-given axis. It is checked if the given axis path is valid (i.e. if the axis are < nrdim and if they are not doubly defined). E.g.: in the 4D case an axis path [0,2] is returned as [0,2,1,3].

static IPosition otherAxes (uInt nrdim, const IPosition& axes)

Make a list of axes which are the axes not given in axes up to the given dimension

IPosition(const Array<Int>& other)
Vector<Int> asVector() const

Convert an IPosition to and from an Array. In either case, the array must be one dimensional.

IPosition nonDegenerate(uInt startingAxis=0) const
IPosition nonDegenerate(const IPosition& ignoreAxes) const

This member functions return an IPosition which has degenerate (length==1) axes removed and the dimensionality reduced appropriately. Only axes greater than startingAxis are considered (normally one wants to remove trailing axes.
The functions with argument ignoreAxes do not consider the axes given in that argument..

void resize(uInt newSize, Bool copy=True)

Old values are copied on resize if copy==True.. If the size increases, values beyond the former size are undefined.

Int& operator[] (uInt index)
Int operator[] (uInt index) const
Int& operator() (uInt index)
Int operator() (uInt index) const

Index into the IPosition. Indices are zero-based. If the preprocessor symbol AIPS_ARRAY_INDEX_CHECK is defined, operator() will check "index" to ensure it is not out of bounds. If this check fails, an AipsError will be thrown.

const Int *storage() const

Get the storage.

void append (const IPosition& other)

Append this IPosition with another one (causing a resize).

void prepend (const IPosition& other)

Prepend this IPosition with another one (causing a resize).

IPosition concatenate (const IPosition& other) const

Return an IPosition as the concetanation of this and another IPosition.

void setFirst (const IPosition& other)

Set the first values of this IPosition to another IPosition. An exception is thrown if the other IPosition is too long.

void setLast (const IPosition& other)

Set the last values of this IPosition to another IPosition. An exception is thrown if the other IPosition is too long.

IPosition getFirst (uInt n) const

Construct an IPosition from the first n values of this IPosition. An exception is thrown if n is too high.

IPosition getLast (uInt n) const

Construct an IPosition from the last n values of this IPosition. An exception is thrown if n is too high.

uInt nelements() const
uInt size() const

The number of elements in this IPosition. Since IPosition objects use zero-based indexing, the maximum available index is nelements() - 1.

Bool conform(const IPosition& other) const

conform returns true if nelements() == other.nelements().

void operator += (const IPosition& other)
void operator -= (const IPosition& other)
void operator *= (const IPosition& other)
void operator /= (const IPosition& other)
void operator += (Int val)
void operator -= (Int val)
void operator *= (Int val)
void operator /= (Int val)

Element-by-element arithmetic.

Int product() const

Returns 0 if nelements() == 0, otherwise it returns the product of its elements.

Bool isEqual (const IPosition& other) const

Element-by-element comparison for equality. It returns True if the lengths and all elements are equal.
Note that an important difference between this function and operator==() is that if the two IPositions have different lengths, this function returns False, instead of throwing an exception as operator==() does.

Bool isEqual (const IPosition& other, Bool skipDegeneratedAxes) const

Element-by-element comparison for equality. It returns True if all elements are equal. When skipDegeneratedAxes is True, axes with length 1 are skipped in both operands.

Bool isEqual (const IPosition& other, uInt nrCompare) const

Element-by-element comparison for (partial) equality. It returns True if the lengths and the first nrCompare elements are equal.

Bool isSubSet (const IPosition& other) const

Is the other IPosition a subset of (or equal to) this IPosition? It is a subset if zero or more axes of this IPosition do not occur or are degenerated in the other and if the remaining axes are in the same order.

friend std::ostream& operator<<(std::ostream& os, const IPosition& ip)

Write an IPosition to an ostream in a simple text form.

friend AipsIO& operator<<(AipsIO& aio, const IPosition& ip)

Write an IPosition to an AipsIO stream in a binary format.

friend LogIO& operator<<(LogIO& io, const IPosition& ip)

Write an IPosition to a LogIO stream.

friend AipsIO& operator>>(AipsIO& aio, IPosition& ip)

Read an IPosition from an AipsIO stream in a binary format. Will throw an AipsError if the current IPosition Version does not match that of the one on disk.

Bool ok() const

Is this IPosition consistent?

iterator begin()
const_iterator begin() const
const_iterator end() const

Define the STL-style iterators. It makes it possible to iterate through all data elements.

  IPosition shp(2,0);
  for (IPosition::iterator iter=shp.begin(); iter!=shp.end(); iter++) {
    *iter += 1;
  }

void allocateBuffer()

void throwIndexError() const

Throw an index error exception.

enum

Arithmetic Operations for IPosition's (source)

Interface

IPosition operator + (const IPosition& left, const IPosition& right)

IPosition operator - (const IPosition& left, const IPosition& right)

IPosition operator * (const IPosition& left, const IPosition& right)

IPosition operator / (const IPosition& left, const IPosition& right)

IPosition operator + (const IPosition& left, Int val)

IPosition operator - (const IPosition& left, Int val)

IPosition operator * (const IPosition& left, Int val)

IPosition operator / (const IPosition& left, Int val)

IPosition operator + (Int val, const IPosition& right)

IPosition operator - (Int val, const IPosition& right)

IPosition operator * (Int val, const IPosition& right)

IPosition operator / (Int val, const IPosition& right)

IPosition max (const IPosition& left, const IPosition& right)

IPosition min (const IPosition& left, const IPosition& right)

Description

Element by element arithmetic on IPositions.

Member Description

IPosition operator + (const IPosition& left, const IPosition& right)
IPosition operator - (const IPosition& left, const IPosition& right)
IPosition operator * (const IPosition& left, const IPosition& right)
IPosition operator / (const IPosition& left, const IPosition& right)

IPosition operator + (const IPosition& left, Int val)
IPosition operator - (const IPosition& left, Int val)
IPosition operator * (const IPosition& left, Int val)
IPosition operator / (const IPosition& left, Int val)

IPosition operator + (Int val, const IPosition& right)
IPosition operator - (Int val, const IPosition& right)
IPosition operator * (Int val, const IPosition& right)
IPosition operator / (Int val, const IPosition& right)

IPosition max (const IPosition& left, const IPosition& right)
IPosition min (const IPosition& left, const IPosition& right)

Returns the element by element minimum or maximum.

Logical operations for IPosition's (source)

Interface

Bool operator == (const IPosition& left, const IPosition& right)

Bool operator != (const IPosition& left, const IPosition& right)

Bool operator < (const IPosition& left, const IPosition& right)

Bool operator <= (const IPosition& left, const IPosition& right)

Bool operator > (const IPosition& left, const IPosition& right)

Bool operator >= (const IPosition& left, const IPosition& right)

Bool operator == (const IPosition& left, Int val)

Bool operator != (const IPosition& left, Int val)

Bool operator < (const IPosition& left, Int val)

Bool operator <= (const IPosition& left, Int val)

Bool operator > (const IPosition& left, Int val)

Bool operator >= (const IPosition& left, Int val)

Bool operator == (Int val, const IPosition& right)

Bool operator != (Int val, const IPosition& right)

Bool operator < (Int val, const IPosition& right)

Bool operator <= (Int val, const IPosition& right)

Bool operator > (Int val, const IPosition& right)

Bool operator >= (Int val, const IPosition& right)

Description

Element by element boolean operations on IPositions. The result is true only if the operation yields true for every element of the IPosition.

Member Description

Bool operator == (const IPosition& left, const IPosition& right)
Bool operator != (const IPosition& left, const IPosition& right)
Bool operator < (const IPosition& left, const IPosition& right)
Bool operator <= (const IPosition& left, const IPosition& right)
Bool operator > (const IPosition& left, const IPosition& right)
Bool operator >= (const IPosition& left, const IPosition& right)

Bool operator == (const IPosition& left, Int val)
Bool operator != (const IPosition& left, Int val)
Bool operator < (const IPosition& left, Int val)
Bool operator <= (const IPosition& left, Int val)
Bool operator > (const IPosition& left, Int val)
Bool operator >= (const IPosition& left, Int val)

Bool operator == (Int val, const IPosition& right)
Bool operator != (Int val, const IPosition& right)
Bool operator < (Int val, const IPosition& right)
Bool operator <= (Int val, const IPosition& right)
Bool operator > (Int val, const IPosition& right)
Bool operator >= (Int val, const IPosition& right)

Indexing functions for IPosition's (source)

Interface

IPosition toIPositionInArray (const uInt offset, const IPosition& shape)

uInt toOffsetInArray (const IPosition& iposition, const IPosition& shape)

Bool isInsideArray (const uInt offset, const IPosition& shape)

Bool isInsideArray (const IPosition& iposition, const IPosition& shape)

Description

Convert between IPosition and offset in an array.

The offset of an element in an array is the number of elements from the origin that the element would be if the array were arranged linearly. The origin of the array has an offset equal to 0, while the "top right corner" of the array has an offset equal to one less than the total number of elements in the array.

Two examples of offset would be the index in a carray and the seek position in a file.

Member Description

IPosition toIPositionInArray (const uInt offset, const IPosition& shape)

uInt toOffsetInArray (const IPosition& iposition, const IPosition& shape)

Convert from IPosition to offset in an array. The second of these functions requires that type T have shape and origin members which return IPositions.

Bool isInsideArray (const uInt offset, const IPosition& shape)
Bool isInsideArray (const IPosition& iposition, const IPosition& shape)

Determine if the given offset or IPosition is inside the array. Returns True if it is inside the Array. The second and fourth of these functions require that type T have shape and origin members which return IPositions.

Thrown Exceptions

ArrayConformanceError: If all the IPositions are not the same length