casa::ArrayIO_global_functions_Array_IO Struct Reference
[Arrays]

#include <ArrayIO.h>

List of all members.

---

Detailed Description

Input/output operators for Arrays.

Intended use:

Part of API

Review Status

Reviewed By:

Paul Shannon

Date Reviewed:

1995/02/21

This header was reviewed and revised with the goal of making it an example for those writing global function header files.

Prerequisite

• Array
• ostream
• AipsIO

Etymology

ArrayIO is simply the conventional shorthand for "array input/output".

Synopsis

These global functions provide easy input and output of (possibly) large and (possibly) multi-dimensional arrays. Iteration through entire arrays is done behind the scenes, with no effort required of the client programmer. These functions are global, rather than member functions of the Array class, because of the well-known C++ requirement that the first argument to an operator function (as it is declared) is the left operand when the function is called.

Example

    IPosition shape (3,10,10,3);
    Array <Float> array (shape);
    // .\..initialize and manipulate the array.\..
    cout << "result: " << array;

Motivation

Effortless input/output is clearly a big win.

To Do

<linkfrom anchor="Array IO" classes="Array Vector Matrix Cube"> <here>Array IO</here> -- Input/output operators for Arrays. </linkfrom>

Definition at line 102 of file ArrayIO.h.

Public Member Functions
template<class T>
ostream &	operator<< (ostream &, const Array< T > &)
	Write out an ascii representation of an array of any dimensionality.
template<class T>
LogIO &	operator<< (LogIO &os, const Array< T > &a)
	Write a formatted copy of the array to the LogIO output object.
template<class T>
Bool	readArrayBlock (istream &s, Bool &trans, IPosition &p, Block< T > &x, const IPosition *ip=0, Bool it=False)
	General read support function for matrices.
template<class T>
istream &	operator>> (istream &s, Array< T > &x)
	Read an ascii representation of an array.
template<class T>
Bool	read (istream &s, Array< T > &x, const IPosition *ip=0, Bool it=False)
template<class T>
AipsIO &	operator<< (AipsIO &, const Array< T > &)
	Read or write a binary representation of an Array to a file.
template<class T>
void	putArray (AipsIO &, const Array< T > &, const Char *name)
template<class T>
AipsIO &	operator>> (AipsIO &, Array< T > &)

---

Member Function Documentation

template<class T>

ostream& casa::ArrayIO_global_functions_Array_IO::operator<<	(	ostream &	,
		const Array< T > &
	)

Write out an ascii representation of an array of any dimensionality.

Arrays of dimensionality 3 or greater are written out vector by vector, preceeded by the position of the start of the vector. If the origin of the array isn't zero it is printed. The shape of the array is always printed.

template<class T>

LogIO& casa::ArrayIO_global_functions_Array_IO::operator<<	(	LogIO &	os,
		const Array< T > &	a
	)

Write a formatted copy of the array to the LogIO output object.

Merely calls the ostream operator<< in turn.

template<class T>

istream& casa::ArrayIO_global_functions_Array_IO::operator>>	(	istream &	s,
		Array< T > &	x
	)

Read an ascii representation of an array.

All types with an << operator can be handled. The basic format of the input should be:

        [element element element .\..\.] 

Elements are separated by whitespace, or a comma, optionally surrounded by white space.
Warning: Some input routines read fields between blank spaces. This is (at the moment) especially true for Quantities and Strings. In those cases the separator should be blank (or a comma following a blank), and the end ']' should have a blank in front. A crude fix for String arrays having separators , and ] without blanks preceding has been made; but slows routines down The default input is a vector of unspecified length. The input shape can be changed by pre-pending the input with:

        {[shape]}

where shape is an unsigned integer vector. The shape will be used to check the input length; and, depending on the possibility, to resize/reshape the result. However, reshaping of e.g. a Vector to a Matrix cannot be done, and the result will stay in the form asked.
Input order is row major, however by preceding the input with:

        {T[shape]}      

the order will be reversed.
Reshaping of the Array provided will depend on the type of Array and its state. If a general Array, the shape will be as defined by user. If fixed Array (e.g. Matrix, Vector, Cube) the number of dimesnsions will be kept. If the user specified more dimensions then supported (e.g. 3 for Matrix), the last dimesions will be collapsed. If less dimensions are specified, the missing ones will be set to 1. will be kept.
The read() version can be used to force a shape (ip), or an input transpose (it) (which can be undone by the user specifying transpose).

template<class T>

Bool casa::ArrayIO_global_functions_Array_IO::read	(	istream &	s,
		Array< T > &	x,
		const IPosition *	ip = 0,
		Bool	it = False
	)

template<class T>

Bool casa::ArrayIO_global_functions_Array_IO::readArrayBlock	(	istream &	s,
		Bool &	trans,
		IPosition &	p,
		Block< T > &	x,
		const IPosition *	ip = 0,
		Bool	it = False
	)

General read support function for matrices.

In principle these functions will not be used by general user, but could be. They can be used by Array type classes (like Slice, Lattice) to do the work of comparable input functions as the one for Arrays. In these functions p is the shape of the returned Block x. This shape is either deduced from the user specification; made equal to (1, nelements) if no user shape is given; is set to ip if specified. The function will return False (and p = (0)) in the case of an invalid input element; a number of elements input not equal to ip (if specified); the shape given by user as input does not conform to ip (if given) or the number of elements input.
trans will be True if transpose asked by user; or if forced by it.

template<class T>

AipsIO& casa::ArrayIO_global_functions_Array_IO::operator<<	(	AipsIO &	,
		const Array< T > &
	)

Read or write a binary representation of an Array to a file.

Very useful for saving arrays and restoring them later.
The putArray function is put in for forwards compatibility of images (so new images can be read with old release).

template<class T>

void casa::ArrayIO_global_functions_Array_IO::putArray	(	AipsIO &	,
		const Array< T > &	,
		const Char *	name
	)

template<class T>

AipsIO& casa::ArrayIO_global_functions_Array_IO::operator>>	(	AipsIO &	,
		Array< T > &
	)

---

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

• casa/implement/Arrays/ArrayIO.h

---