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 
38 namespace casacore { //# NAMESPACE CASACORE - BEGIN
39 
40 class AipsIO;
41 class LogIO;
42 class IPosition;
43 template<typename T> class Block;
44 class 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">
99 
100 // Write a formatted copy of the array to the LogIO output object. Merely calls
101 // the ostream operator<< in turn.
102 template<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 
112 template<typename T, typename Alloc>
114 
115 template<typename T, typename Alloc>
116 void putArray (AipsIO &, const Array<T, Alloc> &, const char* name);
117 
118 template<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>
163 
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>
174 template <typename T, typename Alloc>
175 void write_array (const Array<T, Alloc>& the_array, const std::string& fileName);
176 
177 template <typename T, typename Alloc>
178 inline 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>
190 template <typename T, typename Alloc>
191 void read_array (Array<T, Alloc>& the_array, const std::string& fileName);
192 
193 template <typename T, typename Alloc>
194 inline 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>
206 template <typename T, typename Alloc>
207 void readAsciiVector (Vector<T, Alloc>& vec, const char* fileName);
208 
209 template <typename T, typename Alloc>
210 void writeAsciiVector (const Vector<T, Alloc>& vec, const char* fileName);
211 // </group>
212 
213 // </group>
214 
215 AipsIO& operator<< (AipsIO& aio, const IPosition& ip);
216 AipsIO& operator>> (AipsIO& aio, IPosition& ip);
217 LogIO& operator<< (LogIO& os, const IPosition& ip);
218 
219 template<typename T, typename Alloc>
220 Block<T> makeBlock(const Array<T, Alloc>& array);
221 
222 template<typename T>
223 Vector<T> makeVector(const Block<T>& block);
224 
225 Vector<String> stringToVector (const String& string, char delim = ',');
226 Vector<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
Block< T > makeBlock(const Array< T, Alloc > &array)
Vector< T > makeVector(const Block< T > &block)
Vector< String > stringToVector(const String &string, char delim=',')
this file contains all the compiler specific defines
Definition: mainpage.dox:28
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
ostream & operator<<(ostream &os, const IComplex &)
Show on ostream.
AipsIO & operator>>(AipsIO &os, Record &rec)
Definition: Record.h:465
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)
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.