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

#include <IPosition.h>

Public Types
enum	{ MIN_INT }

Public Member Functions
	IPosition ()
	A zero-length IPosition. More...

	IPosition (uInt length)
	An IPosition of size "length." The values in the object are undefined. More...

	IPosition (uInt length, ssize_t val)
	An IPosition of size "length." The values in the object get initialized to val. More...

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

	IPosition (const IPosition &other)
	Makes a copy (copy, NOT reference, semantics) of other. More...

	~IPosition ()

IPosition &	operator= (const IPosition &other)
	Makes this a copy of other. More...

IPosition &	operator= (ssize_t value)
	Copy "value" into every position of this IPosition. More...

	IPosition (const Array< Int > &other)
	Convert an IPosition to and from an Array<Int>. More...

Vector< Int >	asVector () const

	IPosition (const std::vector< Int > &other)
	Convert an IPosition to and from an Array<Int>. More...

std::vector< Int >	asStdVector () const

template<typename InputIterator >
void	fill (uInt size, InputIterator iter)
	Resize and fill this IPosition object. More...

template<typename OutputIterator >
void	copy (OutputIterator iter) const
	Copy the contents of this IPosition object to the output iterator. More...

IPosition	nonDegenerate (uInt startingAxis=0) const
	This member functions return an IPosition which has degenerate (length==1) axes removed and the dimensionality reduced appropriately. More...

IPosition	nonDegenerate (const IPosition &ignoreAxes) const

void	resize (uInt newSize, Bool copy=True)
	Old values are copied on resize if copy==True. More...

ssize_t &	operator[] (uInt index)
	Index into the IPosition. More...

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

ssize_t &	last (uInt index=0)
	Index into the IPosition from the end. More...

ssize_t	last (uInt index=0) const

const ssize_t *	storage () const
	Get the storage. More...

void	append (const IPosition &other)
	Append this IPosition with another one (causing a resize). More...

void	prepend (const IPosition &other)
	Prepend this IPosition with another one (causing a resize). More...

IPosition	concatenate (const IPosition &other) const
	Return an IPosition as the concetanation of this and another IPosition. More...

void	setFirst (const IPosition &other)
	Set the first values of this IPosition to another IPosition. More...

void	setLast (const IPosition &other)
	Set the last values of this IPosition to another IPosition. More...

IPosition	getFirst (uInt n) const
	Construct an IPosition from the first `n` values of this IPosition. More...

IPosition	getLast (uInt n) const
	Construct an IPosition from the last `n` values of this IPosition. More...

IPosition	removeAxes (const IPosition &axes) const
	Return an IPosition where the given axes are reoved. More...

IPosition	keepAxes (const IPosition &axes) const
	Return an IPosition containing the given axes only. More...

uInt	nelements () const
	The number of elements in this IPosition. More...

uInt	size () const

Bool	empty () const
	Is the IPosition empty (i.e. More...

Bool	conform (const IPosition &other) const
	conform returns true if nelements() == other.nelements(). More...

void	operator+= (const IPosition &other)
	Element-by-element arithmetic. More...

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

Bool	allOne () const
	Are all elements equal to 1? Useful to check if a given stride is really a stride. More...

Bool	isEqual (const IPosition &other) const
	Element-by-element comparison for equality. More...

Bool	isEqual (const IPosition &other, Bool skipDegeneratedAxes) const
	Element-by-element comparison for equality. More...

Bool	isEqual (const IPosition &other, uInt nrCompare) const
	Element-by-element comparison for (partial) equality. More...

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

String	toString () const
	Write the IPosition into a String. More...

Bool	ok () const
	Is this IPosition consistent? More...

Static Public Member Functions
static IPosition	makeAxisPath (uInt nrdim)
	Construct a default axis path consisting of the values 0. More...

static IPosition	makeAxisPath (uInt nrdim, const IPosition &partialPath)
	Construct a full axis path from a (partially) given axis path. More...

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

Friends
class	IPositionComparator

std::ostream &	operator<< (std::ostream &os, const IPosition &ip)
	Write an IPosition to an ostream in a simple text form. More...

AipsIO &	operator<< (AipsIO &aio, const IPosition &ip)
	Write an IPosition to an AipsIO stream in a binary format. More...

LogIO &	operator<< (LogIO &io, const IPosition &ip)
	Write an IPosition to a LogIO stream. More...

AipsIO &	operator>> (AipsIO &aio, IPosition &ip)
	Read an IPosition from an AipsIO stream in a binary format. More...

typedef ssize_t	value_type
	Define the STL-style iterators. More...

typedef ssize_t *	iterator

typedef const ssize_t *	const_iterator

typedef value_type *	pointer

typedef const value_type *	const_pointer

typedef value_type &	reference

typedef const value_type &	const_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. More...

iterator	begin ()
	Get the begin and end iterator object for this object. More...

const_iterator	begin () const

iterator	end ()

const_iterator	end () const

void	allocateBuffer ()
	Allocate a buffer with length size_p. More...

void	throwIndexError () const
	Throw an index error exception. More...

Detailed Description

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

Intended use:

Public interface

Review Status

Reviewed By:: UNKNOWN
Date Reviewed:: before2004/08/25

Etymology

IPosition is an Index Position in an n-dimensional array.

Synopsis

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.

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

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* casacore::IPosition::const_iterator

Definition at line 383 of file IPosition.h.

typedef const value_type* casacore::IPosition::const_pointer

Definition at line 385 of file IPosition.h.

typedef const value_type& casacore::IPosition::const_reference

Definition at line 387 of file IPosition.h.

typedef ptrdiff_t casacore::IPosition::difference_type

Definition at line 389 of file IPosition.h.

typedef ssize_t* casacore::IPosition::iterator

Definition at line 382 of file IPosition.h.

typedef value_type* casacore::IPosition::pointer

Definition at line 384 of file IPosition.h.

typedef value_type& casacore::IPosition::reference

Definition at line 386 of file IPosition.h.

typedef size_t casacore::IPosition::size_type

Definition at line 388 of file IPosition.h.

typedef ssize_t casacore::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 381 of file IPosition.h.

Member Enumeration Documentation

anonymous enum

Enumerator
MIN_INT

Definition at line 123 of file IPosition.h.

anonymous enum

private

Enumerator
BufferLength

Definition at line 411 of file IPosition.h.

Constructor & Destructor Documentation

casacore::IPosition::IPosition ( )

inline

A zero-length IPosition.

Definition at line 534 of file IPosition.h.

Referenced by makeAxisPath().

casacore::IPosition::IPosition ( uInt length )

explicit

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

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

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

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

casacore::IPosition::IPosition ( const IPosition & other )

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

casacore::IPosition::~IPosition ( )

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

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

In either case, the array must be one dimensional.

casacore::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 casacore::IPosition::allocateBuffer ( )

private

Allocate a buffer with length size_p.

Bool casacore::IPosition::allOne ( ) const

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

void casacore::IPosition::append ( const IPosition & other )

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

Referenced by casacore::TableExprGroupAggr::getArray(), and casacore::TableProxy::record2Array().

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

Vector<Int> casacore::IPosition::asVector ( ) const

Referenced by casa::ProtoVR::DataToGrid(), and casa::CFCell::setStorage().

iterator casacore::IPosition::begin ( )

inline

Get the begin and end iterator object for this object.

Definition at line 393 of file IPosition.h.

References data_p.

const_iterator casacore::IPosition::begin ( ) const

inline

Definition at line 395 of file IPosition.h.

References data_p.

IPosition casacore::IPosition::concatenate ( const IPosition & other ) const

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

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

Bool casacore::IPosition::conform ( const IPosition & other ) const

inline

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

Definition at line 612 of file IPosition.h.

References size_p.

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

template<typename OutputIterator >

void casacore::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 196 of file IPosition.h.

References data_p, and size_p.

Bool casacore::IPosition::empty ( ) const

inline

Is the IPosition empty (i.e.

no elements)?

Definition at line 552 of file IPosition.h.

References size_p.

iterator casacore::IPosition::end ( )

inline

Definition at line 397 of file IPosition.h.

References data_p, and size_p.

const_iterator casacore::IPosition::end ( ) const

inline

Definition at line 399 of file IPosition.h.

References data_p, and size_p.

template<typename InputIterator >

void casacore::IPosition::fill	(	uInt	size,
		InputIterator	iter
	)

inline

Resize and fill this IPosition object.

Definition at line 185 of file IPosition.h.

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

IPosition casacore::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 casacore::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.

Bool casacore::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 casacore::checkArrayShapes(), casacore::LatticeBase::conform(), casacore::ArrayBase::conform2(), and casa::WorldCanvas::ColorIndexedImage_::maskValid().

Bool casacore::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 casacore::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 casacore::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.

IPosition casacore::IPosition::keepAxes ( const IPosition & axes ) const

Return an IPosition containing the given axes only.

ssize_t & casacore::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 587 of file IPosition.h.

References data_p, size_p, and throwIndexError().

Referenced by casa::vi::VbCacheItemArray< casacore::casacore::Vector< casacore::uInt > >::appendRows(), casa::vi::VbCacheItemArray< casacore::casacore::Vector< casacore::uInt > >::resize(), and casa::vi::VbCacheItemArray< casacore::casacore::Vector< casacore::uInt > >::resizeRows().

ssize_t casacore::IPosition::last ( uInt index = 0 ) const

inline

Definition at line 597 of file IPosition.h.

References data_p, size_p, and throwIndexError().

IPosition casacore::IPosition::makeAxisPath ( uInt nrdim )

inlinestatic

Construct a default axis path consisting of the values 0.

. nrdim-1.

Definition at line 539 of file IPosition.h.

References IPosition().

static IPosition casacore::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 casacore::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 544 of file IPosition.h.

References size_p.

Referenced by casa::vi::VbCacheItemArray< casacore::casacore::Vector< casacore::uInt > >::appendRows(), casa::vi::VbCacheItemArray< casacore::casacore::Vector< casacore::uInt > >::copyRowElementAux(), casacore::ArrayPositionIterator::dimIter(), casacore::Adios2StManColumnT< T >::getArrayColumnCellsV(), casacore::ArrayPositionIterator::ndim(), casacore::Slicer::ndim(), operator()(), casacore::Adios2StManColumnT< T >::putArrayColumnCellsV(), casacore::TSMCube::setLastColSlice(), and casa::PixelatedConvFunc< T >::setSize().

IPosition casacore::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 casacore::IPosition::nonDegenerate ( const IPosition & ignoreAxes ) const

Bool casacore::IPosition::ok ( ) const

Is this IPosition consistent?

ssize_t & casacore::IPosition::operator() ( uInt index )

inline

Definition at line 567 of file IPosition.h.

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

ssize_t casacore::IPosition::operator() ( uInt index ) const

inline

Definition at line 577 of file IPosition.h.

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

IPosition casacore::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 casacore::IPosition::operator*= ( const IPosition & other )

void casacore::IPosition::operator*= ( ssize_t val )

void casacore::IPosition::operator+= ( const IPosition & other )

Element-by-element arithmetic.

void casacore::IPosition::operator+= ( ssize_t val )

void casacore::IPosition::operator-= ( const IPosition & other )

void casacore::IPosition::operator-= ( ssize_t val )

void casacore::IPosition::operator/= ( const IPosition & other )

void casacore::IPosition::operator/= ( ssize_t val )

IPosition& casacore::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& casacore::IPosition::operator= ( ssize_t value )

Copy "value" into every position of this IPosition.

ssize_t & casacore::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 557 of file IPosition.h.

References data_p.

ssize_t casacore::IPosition::operator[] ( uInt index ) const

inline

Definition at line 562 of file IPosition.h.

References data_p.

static IPosition casacore::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 casacore::IPosition::prepend ( const IPosition & other )

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

Int64 casacore::IPosition::product ( ) const

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

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

IPosition casacore::IPosition::removeAxes ( const IPosition & axes ) const

Return an IPosition where the given axes are reoved.

void casacore::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(), casa::CFCell::initCache(), casa::ms::CachedPlane< casacore::Complex >::referenceMatrix(), casa::ms::CachedColumn< casacore::Float >::referenceVector(), casacore::TSMCube::setLastColSlice(), and casacore::TableExprNodeSet::toArray().

void casacore::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 casacore::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 casacore::IPosition::size ( ) const

inline

Definition at line 548 of file IPosition.h.

References size_p.

Referenced by casa::vi::VbCacheItemArray< casacore::casacore::Vector< casacore::uInt > >::appendRows(), fill(), casacore::TableExprGroupAggr::getArray(), casacore::python::to_list< casacore::IPosition >::makeobject(), casacore::MArrayBase::ndim(), and casacore::TableExprNodeSet::toArray().

const ssize_t * casacore::IPosition::storage ( ) const

inline

Get the storage.

Definition at line 607 of file IPosition.h.

References data_p.

Referenced by casacore::MArrayMath_global_functions_MArray_mathematical_operations::fractile(), and casacore::MArrayMath_global_functions_MArray_mathematical_operations::median().

void casacore::IPosition::throwIndexError ( ) const

private

Throw an index error exception.

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

String casacore::IPosition::toString ( ) const

Write the IPosition into a String.

Referenced by casa::vi::VbCacheItemArray< casacore::casacore::Vector< casacore::uInt > >::shapeErrorMessage().

Friends And Related Function Documentation

friend class IPositionComparator

friend

Definition at line 121 of file IPosition.h.

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

ssize_t casacore::IPosition::buffer_p[BufferLength]

private

Definition at line 413 of file IPosition.h.

ssize_t* casacore::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 416 of file IPosition.h.

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

uInt casacore::IPosition::size_p

private

Definition at line 412 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:

casa/casacore/casa/Arrays/IPosition.h

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Intended use:

Review Status

Etymology

Synopsis

Example

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Example

Friends And Related Function Documentation

Member Data Documentation