casacore
ArrayIO.h
Go to the documentation of this file.
1//# ArrayIO.h: text output and binary IO for an array of any dimensionality.
2//# Copyright (C) 1993,1994,1995,1997,1999,2000,2001
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_ARRAYIO_2_H
29#define CASA_ARRAYIO_2_H
30
31//# Includes
32#include <vector>
33#include <ostream>
34#include <regex>
35
36#include <casacore/casa/Arrays/ArrayFwd.h>
37
38namespace casacore { //# NAMESPACE CASACORE - BEGIN
39
40class AipsIO;
41class LogIO;
42class IPosition;
43template<typename T> class Block;
44class String;
45
46// <summary>
47// Input/output operators for Arrays.
48// </summary>
49
50// <use visibility=export>
51
52// <reviewed reviewer="Paul Shannon" date="1995/02/21" tests="" demos="">
53// This header was reviewed and revised with the goal of making it an
54// example for those writing global function header files.
55// </reviewed>
56
57// <prerequisite>
58// <li> <linkto class=Array>Array</linkto>
59// <li> ostream
60// <li> <linkto class=AipsIO>AipsIO</linkto>
61// </prerequisite>
62
63// <etymology>
64// ArrayIO is simply the conventional shorthand for "array input/output".
65// </etymology>
66
67// <synopsis>
68// These global functions provide easy input and output of (possibly)
69// large and (possibly) multi-dimensional arrays. Iteration through
70// entire arrays is done behind the scenes, with no effort required
71// of the client programmer.
72// These functions are global, rather than member functions of the
73// Array class, because of the well-known C++ requirement that the first
74// argument to an operator function (as it is declared) is the
75// left operand when the function is called.
76// </synopsis>
77
78
79// <example>
80// <srcblock>
81// IPosition shape (3,10,10,3);
82// Array <float> array (shape);
83// // ...initialize and manipulate the array...
84// cout << "result: " << array;
85// </srcblock>
86//
87// <motivation>
88// Effortless input/output is clearly a big win.
89// </motivation>
90//
91// <todo asof="1997/01/15">
92// </todo>
93
94// <linkfrom anchor="Array IO" classes="Array Vector Matrix Cube">
95// <here>Array IO</here> -- Input/output operators for Arrays.
96// </linkfrom>
97//
98// <group name="Array IO">
100// Write a formatted copy of the array to the LogIO output object. Merely calls
101// the ostream operator<< in turn.
102template<typename T, typename Alloc>
104
105// Read or write a binary representation of an Array to a file. Very
106// useful for saving arrays and restoring them later.
107// <br>The putArray function is put in for forwards compatibility
108// of images (so new images can be read with old release).
109//
110// <group>
111
112template<typename T, typename Alloc>
114
115template<typename T, typename Alloc>
116void putArray (AipsIO &, const Array<T, Alloc> &, const char* name);
117
118template<typename T, typename Alloc>
120
121// </group>
122
123// </group>
124
125// <summary>
126// Global functions to read/write binary arrays from/to a file.
127// </summary>
128
129// <use visibility=export>
130
131// <reviewed reviewer="Gareth Hunt" date="95Mar31" tests="" demos="">
132// </reviewed>
133
134// <synopsis>
135// These global functions provide disk read/write functions for an Array of
136// binary numbers. The write operation is useful, for example, to dump an
137// image in binary form to disk so that it can be displayed with an external
138// utility such as SAOimage.
139// </synopsis>
140
141// <example>
142// <srcblock>
143// Matrix<float> picture(256, 256); picture = 0.0;
144// String fileName="picture.data";
145//
146// // operations to populate picture
147// // ...
148//
149// write_array (picture, fileName);
150// </srcblock>
151// </example>
152
153// <todo asof="">
154// <li> These functions should eventually be replaced with something
155// more sophisticated.
156// </todo>
157
158// <linkfrom anchor="Array binary IO" classes="Array Vector Matrix Cube">
159// <here>Array binary IO</here> -- Simple binary input/output for Arrays.
160// </linkfrom>
161
162// <group name=Array binary IO>
164// Write the values of an array in binary format into a file with
165// the given name.
166// The values are stored in local format, thus are not converted
167// to a canonical format as
168// <linkto class="AipsIO:description">AipsIO</linkto>
169// does.
170// <note role=warning>
171// This function is only suitable for built-in data types.
172// </note>
173// <group>
174template <typename T, typename Alloc>
175void write_array (const Array<T, Alloc>& the_array, const std::string& fileName);
176
177template <typename T, typename Alloc>
178inline void write_array (const Array<T, Alloc>& the_array, const char* fileName)
179 { write_array (the_array, std::string(fileName)); }
180// </group>
181
182// Read the values of an array in binary format from a file with
183// the given name.
184// The number of values read is the size of the Array, thus the file
185// should at least contain that number of values.
186// <note role=warning>
187// This function is only suitable for built-in data types.
188// </note>
189// <group>
190template <typename T, typename Alloc>
191void read_array (Array<T, Alloc>& the_array, const std::string& fileName);
192
193template <typename T, typename Alloc>
194inline void read_array (Array<T, Alloc>& the_array, const char* fileName)
195 { read_array (the_array, std::string(fileName)); }
196// </group>
197
198// </group>
199
200// These two functions read and write a Vector of data. The input
201// may be arranged in any format (i.e. It may be recorded as one value per
202// line or it may be recorded with all values on a single line).
203// Values must be separated by whitespace.
204
205// <group>
206template <typename T, typename Alloc>
207void readAsciiVector (Vector<T, Alloc>& vec, const char* fileName);
208
209template <typename T, typename Alloc>
210void writeAsciiVector (const Vector<T, Alloc>& vec, const char* fileName);
211// </group>
212
213// </group>
214
215AipsIO& operator<< (AipsIO& aio, const IPosition& ip);
216AipsIO& operator>> (AipsIO& aio, IPosition& ip);
217LogIO& operator<< (LogIO& os, const IPosition& ip);
218
219template<typename T, typename Alloc>
220Block<T> makeBlock(const Array<T, Alloc>& array);
221
222template<typename T>
223Vector<T> makeVector(const Block<T>& block);
224
225Vector<String> stringToVector (const String& string, char delim = ',');
226Vector<String> stringToVector (const String& string, const std::regex& delim);
227
228} //# NAMESPACE CASACORE - END
229
230#include <casacore/casa/IO/ArrayIO.tcc>
231
232#endif
AipsIO & operator<<(AipsIO &aio, const IPosition &ip)
AipsIO & operator>>(AipsIO &aio, IPosition &ip)
Vector< T > makeVector(const Block< T > &block)
Vector< String > stringToVector(const String &string, char delim=',')
Block< T > makeBlock(const Array< T, Alloc > &array)
this file contains all the compiler specific defines
Definition: mainpage.dox:28
AipsIO & operator>>(AipsIO &os, Record &rec)
Definition: Record.h:465
ostream & operator<<(ostream &os, const IComplex &)
Show on ostream.
void readAsciiVector(Vector< T, Alloc > &vec, const char *fileName)
These two functions read and write a Vector of data.
TableExprNode array(const TableExprNode &values, const TableExprNodeSet &shape)
Create an array of the given shape and fill it with the values.
Definition: ExprNode.h:1929
void writeAsciiVector(const Vector< T, Alloc > &vec, const char *fileName)
TableExprNode regex(const TableExprNode &node)
Functions for regular expression matching and pattern matching.
Definition: ExprNode.h:1483
AipsIO & operator>>(AipsIO &, Array< T, Alloc > &)
LogIO & operator<<(LogIO &os, const Array< T, Alloc > &a)
Write a formatted copy of the array to the LogIO output object.
void putArray(AipsIO &, const Array< T, Alloc > &, const char *name)
Global functions to read/write binary arrays from/to a file.
Definition: ArrayIO.h:163
void read_array(Array< T, Alloc > &the_array, const char *fileName)
Definition: ArrayIO.h:194
void write_array(const Array< T, Alloc > &the_array, const char *fileName)
Definition: ArrayIO.h:178
void read_array(Array< T, Alloc > &the_array, const std::string &fileName)
Read the values of an array in binary format from a file with the given name.
void write_array(const Array< T, Alloc > &the_array, const std::string &fileName)
Write the values of an array in binary format into a file with the given name.