casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
Public Types | Public Member Functions | Static Public Member Functions | Friends
casa::IPosition Class Reference

A Vector of integers, for indexing into Array<T> objects. More...

#include <IPosition.h>

List of all members.

Public Types

enum  { MIN_INT }

Public Member Functions

 IPosition ()
 A zero-length IPosition.
 IPosition (uInt length)
 An IPosition of size "length." The values in the object are undefined.
 IPosition (uInt length, ssize_t val)
 An IPosition of size "length." The values in the object get initialized to val.
 IPosition (uInt length, ssize_t val0, ssize_t val1, ssize_t val2=MIN_INT, ssize_t val3=MIN_INT, ssize_t val4=MIN_INT, ssize_t val5=MIN_INT, ssize_t val6=MIN_INT, ssize_t val7=MIN_INT, ssize_t val8=MIN_INT, ssize_t val9=MIN_INT)
 An IPosition of size "length" with defined values.
 IPosition (const IPosition &other)
 Makes a copy (copy, NOT reference, semantics) of other.
 ~IPosition ()
IPositionoperator= (const IPosition &other)
 Makes this a copy of other.
IPositionoperator= (ssize_t value)
 Copy "value" into every position of this IPosition.
 IPosition (const Array< Int > &other)
 Convert an IPosition to and from an Array<Int>.
Vector< IntasVector () const
 IPosition (const std::vector< Int > &other)
 Convert an IPosition to and from an Array<Int>.
std::vector< IntasStdVector () const
template<typename InputIterator >
void fill (uInt size, InputIterator iter)
 Resize and fill this IPosition object.
template<typename OutputIterator >
void copy (OutputIterator iter) const
 Copy the contents of this IPosition object to the output iterator.
IPosition nonDegenerate (uInt startingAxis=0) const
 This member functions return an IPosition which has degenerate (length==1) axes removed and the dimensionality reduced appropriately.
IPosition nonDegenerate (const IPosition &ignoreAxes) const
void resize (uInt newSize, Bool copy=True)
 Old values are copied on resize if copy==True.
ssize_t & operator[] (uInt index)
 Index into the IPosition.
ssize_t operator[] (uInt index) const
ssize_t & operator() (uInt index)
ssize_t operator() (uInt index) const
IPosition operator() (const IPosition &axes) const
 Make an IPosition by using only the specified elements of the current IPosition.
ssize_t & last (uInt index=0)
 Index into the IPosition from the end.
ssize_t last (uInt index=0) const
const ssize_t * 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.
void setLast (const IPosition &other)
 Set the last values of this IPosition to another IPosition.
IPosition getFirst (uInt n) const
 Construct an IPosition from the first n values of this IPosition.
IPosition getLast (uInt n) const
 Construct an IPosition from the last n values of this IPosition.
IPosition removeAxes (const IPosition &axes) const
 Return an IPosition where the given axes are reoved.
IPosition keepAxes (const IPosition &axes) const
 Return an IPosition containing the given axes only.
uInt nelements () const
 The number of elements in this IPosition.
uInt size () const
Bool empty () const
 Is the IPosition empty (i.e.
Bool conform (const IPosition &other) const
 conform returns true if nelements() == other.nelements().
void operator+= (const IPosition &other)
 Element-by-element arithmetic.
void operator-= (const IPosition &other)
void operator*= (const IPosition &other)
void operator/= (const IPosition &other)
void operator+= (ssize_t val)
void operator-= (ssize_t val)
void operator*= (ssize_t val)
void operator/= (ssize_t val)
Int64 product () const
 Returns 0 if nelements() == 0, otherwise it returns the product of its elements.
Bool allOne () const
 Are all elements equal to 1? Useful to check if a given stride is really a stride.
Bool isEqual (const IPosition &other) const
 Element-by-element comparison for equality.
Bool isEqual (const IPosition &other, Bool skipDegeneratedAxes) const
 Element-by-element comparison for equality.
Bool isEqual (const IPosition &other, uInt nrCompare) const
 Element-by-element comparison for (partial) equality.
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.
String toString () const
 Write the IPosition into a String.
Bool ok () const
 Is this IPosition consistent?

Static Public Member Functions

static IPosition makeAxisPath (uInt nrdim)
 Construct a default axis path consisting of the values 0 .
static IPosition makeAxisPath (uInt nrdim, const IPosition &partialPath)
 Construct a full axis path from a (partially) given axis path.
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.

Friends

std::ostream & operator<< (std::ostream &os, const IPosition &ip)
 Write an IPosition to an ostream in a simple text form.
AipsIOoperator<< (AipsIO &aio, const IPosition &ip)
 Write an IPosition to an AipsIO stream in a binary format.
LogIOoperator<< (LogIO &io, const IPosition &ip)
 Write an IPosition to a LogIO stream.
AipsIOoperator>> (AipsIO &aio, IPosition &ip)
 Read an IPosition from an AipsIO stream in a binary format.
typedef ssize_t value_type
 Define the STL-style iterators.
typedef ssize_t * iterator
typedef const ssize_t * const_iterator
typedef value_typepointer
typedef const value_typeconst_pointer
typedef value_typereference
typedef const value_typeconst_reference
typedef size_t size_type
typedef ptrdiff_t difference_type
enum  { BufferLength }
uInt size_p
ssize_t buffer_p [BufferLength]
ssize_t * data_p
 When the iposition is length BufferSize or less data is just buffer_p, avoiding calls to new and delete.
iterator begin ()
 Get the begin and end iterator object for this object.
const_iterator begin () const
iterator end ()
const_iterator end () const
void allocateBuffer ()
 
      

void throwIndexError () const
 Throw an index error exception.

Detailed Description

A Vector of integers, for indexing into Array<T> objects.

Intended use:

Public interface

 <h3>Review Status</h3><dl><dt>Reviewed By:<dd>UNKNOWN<dt>Date Reviewed:<dd>before2004/08/25</dl> 

<h3>Etymology</h3>
IPosition is an Index Position in an n-dimensional array.

<h3>Synopsis</h3> 
IPosition is "logically" a Vector<Int> constrained so that its origin
is zero-based, and in fact that used to be the way it was implemented.
It was split out into a separate class to make the inheritance from
Arrays simpler (since Arrays use IPositions). The
template instantiation mechanism is complicated enough that this
simplification was felt to be a good idea.
<p>
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.).
<p>
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).

Constructors and functions exist to construct an IPosition directly from a Vector or std::vector object or to convert to it. Furthermore the fill and copy can be used to fill from or copy to any STL-type iterator.

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
    std::vector<Int> vec(trc.toStdVector());

Definition at line 119 of file IPosition.h.


Member Typedef Documentation

typedef const ssize_t* casa::IPosition::const_iterator

Definition at line 382 of file IPosition.h.

Definition at line 384 of file IPosition.h.

Definition at line 386 of file IPosition.h.

Definition at line 388 of file IPosition.h.

typedef ssize_t* casa::IPosition::iterator

Definition at line 381 of file IPosition.h.

Definition at line 383 of file IPosition.h.

Definition at line 385 of file IPosition.h.

Definition at line 387 of file IPosition.h.

typedef ssize_t casa::IPosition::value_type

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;
         }

STL-style typedefs.

Definition at line 380 of file IPosition.h.


Member Enumeration Documentation

anonymous enum
Enumerator:
MIN_INT 

Definition at line 122 of file IPosition.h.

anonymous enum [private]
Enumerator:
BufferLength 

Definition at line 410 of file IPosition.h.


Constructor & Destructor Documentation

A zero-length IPosition.

Definition at line 522 of file IPosition.h.

Referenced by makeAxisPath().

casa::IPosition::IPosition ( uInt  length) [explicit]

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

casa::IPosition::IPosition ( uInt  length,
ssize_t  val 
)

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

casa::IPosition::IPosition ( uInt  length,
ssize_t  val0,
ssize_t  val1,
ssize_t  val2 = MIN_INT,
ssize_t  val3 = MIN_INT,
ssize_t  val4 = MIN_INT,
ssize_t  val5 = MIN_INT,
ssize_t  val6 = MIN_INT,
ssize_t  val7 = MIN_INT,
ssize_t  val8 = MIN_INT,
ssize_t  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.]

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

casa::IPosition::IPosition ( const Array< Int > &  other)

Convert an IPosition to and from an Array<Int>.

In either case, the array must be one dimensional.

casa::IPosition::IPosition ( const std::vector< Int > &  other)

Convert an IPosition to and from an Array<Int>.

In either case, the array must be one dimensional.


Member Function Documentation

void casa::IPosition::allocateBuffer ( ) [private]

      

Allocate a buffer with length size_p.

Are all elements equal to 1? Useful to check if a given stride is really a stride.

void casa::IPosition::append ( const IPosition other)

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

std::vector<Int> casa::IPosition::asStdVector ( ) const

Get the begin and end iterator object for this object.

Definition at line 392 of file IPosition.h.

References data_p.

Definition at line 394 of file IPosition.h.

References data_p.

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

Referenced by casa::ScaledComplexData< VirtualType, StoredType >::storedShape().

Bool casa::IPosition::conform ( const IPosition other) const [inline]

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

Definition at line 600 of file IPosition.h.

References size_p.

Referenced by casa::TSMShape::conform().

template<typename OutputIterator >
void casa::IPosition::copy ( OutputIterator  iter) const [inline]

Copy the contents of this IPosition object to the output iterator.

The size of the output must be sufficient.

Definition at line 195 of file IPosition.h.

References data_p, and size_p.

Bool casa::IPosition::empty ( ) const [inline]

Is the IPosition empty (i.e.

no elements)?

Definition at line 540 of file IPosition.h.

References size_p.

Definition at line 396 of file IPosition.h.

References data_p, and size_p.

Definition at line 398 of file IPosition.h.

References data_p, and size_p.

template<typename InputIterator >
void casa::IPosition::fill ( uInt  size,
InputIterator  iter 
) [inline]

Resize and fill this IPosition object.

Definition at line 184 of file IPosition.h.

References data_p, resize(), and size().

Construct an IPosition from the first n values of this IPosition.

An exception is thrown if n is too high.

Construct an IPosition from the last n values of this IPosition.

An exception is thrown if n is too high.

Bool casa::IPosition::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.

Referenced by casa::ArrayMath_global_functions_Array_mathematical_operations::checkArrayShapes(), casa::LatticeBase::conform(), and casa::ArrayBase::conform2().

Bool casa::IPosition::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 casa::IPosition::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 casa::IPosition::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.

Return an IPosition containing the given axes only.

ssize_t & casa::IPosition::last ( uInt  index = 0) [inline]

Index into the IPosition from the end.

By default the last value is returned. If the preprocessor symbol AIPS_ARRAY_INDEX_CHECK is defined, it will check if the index is not out of bounds.

Definition at line 575 of file IPosition.h.

References data_p, size_p, and throwIndexError().

ssize_t casa::IPosition::last ( uInt  index = 0) const [inline]

Definition at line 585 of file IPosition.h.

References data_p, size_p, and throwIndexError().

IPosition casa::IPosition::makeAxisPath ( uInt  nrdim) [inline, static]

Construct a default axis path consisting of the values 0 .

. nrdim-1.

Definition at line 527 of file IPosition.h.

References IPosition().

static IPosition casa::IPosition::makeAxisPath ( uInt  nrdim,
const IPosition partialPath 
) [static]

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].

uInt casa::IPosition::nelements ( ) const [inline]

The number of elements in this IPosition.

Since IPosition objects use zero-based indexing, the maximum available index is nelements() - 1.

Definition at line 532 of file IPosition.h.

References size_p.

Referenced by casa::ArrayPositionIterator::dimIter(), casa::ArrayPositionIterator::ndim(), casa::Slicer::ndim(), operator()(), casa::TSMCube::setLastColSlice(), and casa::PixelatedConvFunc< T >::setSize().

IPosition casa::IPosition::nonDegenerate ( uInt  startingAxis = 0) 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.

IPosition casa::IPosition::nonDegenerate ( const IPosition ignoreAxes) const

Is this IPosition consistent?

ssize_t & casa::IPosition::operator() ( uInt  index) [inline]

Definition at line 555 of file IPosition.h.

References data_p, nelements(), and throwIndexError().

ssize_t casa::IPosition::operator() ( uInt  index) const [inline]

Definition at line 565 of file IPosition.h.

References data_p, nelements(), and throwIndexError().

IPosition casa::IPosition::operator() ( const IPosition axes) const

Make an IPosition by using only the specified elements of the current IPosition.

All values of axes must be less than the number of elements of the current object.

Example

IPosition ipos(4, 11, 12, 13, 14); ex1 is IPosition(3, 11, 12, 13); IPosition ex1 = ipos(IPosition(3,0,1,2); ex2 is IPosition(3, 12, 11) IPosition ex2 = ipos(IPosition(2,2,1); ex3 is IPosition(4,14,14,14,14) IPosition ex3 = ipos(IPosition(4,3,3,3,3);

void casa::IPosition::operator*= ( const IPosition other)
void casa::IPosition::operator*= ( ssize_t  val)
void casa::IPosition::operator+= ( const IPosition other)

Element-by-element arithmetic.

void casa::IPosition::operator+= ( ssize_t  val)
void casa::IPosition::operator-= ( const IPosition other)
void casa::IPosition::operator-= ( ssize_t  val)
void casa::IPosition::operator/= ( const IPosition other)
void casa::IPosition::operator/= ( ssize_t  val)
IPosition& casa::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& casa::IPosition::operator= ( ssize_t  value)

Copy "value" into every position of this IPosition.

ssize_t & casa::IPosition::operator[] ( uInt  index) [inline]

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.

Definition at line 545 of file IPosition.h.

References data_p.

ssize_t casa::IPosition::operator[] ( uInt  index) const [inline]

Definition at line 550 of file IPosition.h.

References data_p.

static IPosition casa::IPosition::otherAxes ( uInt  nrdim,
const IPosition axes 
) [static]

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

void casa::IPosition::prepend ( const IPosition other)

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

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

Referenced by casa::fieldSize(), casa::fieldType(), casa::isFieldSet(), and casa::LatticeIndexer::nelements().

Return an IPosition where the given axes are reoved.

void casa::IPosition::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.

Referenced by fill(), and casa::TSMCube::setLastColSlice().

void casa::IPosition::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 casa::IPosition::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.

uInt casa::IPosition::size ( ) const [inline]

Definition at line 536 of file IPosition.h.

References size_p.

Referenced by fill().

const ssize_t * casa::IPosition::storage ( ) const [inline]

Get the storage.

Definition at line 595 of file IPosition.h.

References data_p.

void casa::IPosition::throwIndexError ( ) const [private]

Throw an index error exception.

Referenced by last(), and operator()().

Write the IPosition into a String.


Friends And Related Function Documentation

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

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

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

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

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

Write an IPosition to a LogIO stream.

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

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.


Member Data Documentation

Definition at line 412 of file IPosition.h.

ssize_t* casa::IPosition::data_p [private]

When the iposition is length BufferSize or less data is just buffer_p, avoiding calls to new and delete.

Definition at line 415 of file IPosition.h.

Referenced by begin(), copy(), end(), fill(), last(), operator()(), operator[](), and storage().

Definition at line 411 of file IPosition.h.

Referenced by conform(), copy(), empty(), end(), last(), nelements(), and size().


The documentation for this class was generated from the following file: