00001 //# ArrayIO.h: text output and binary IO for an array of any dimensionality. 00002 //# Copyright (C) 1993,1994,1995,1997,1999,2000,2001 00003 //# Associated Universities, Inc. Washington DC, USA. 00004 //# 00005 //# This library is free software; you can redistribute it and/or modify it 00006 //# under the terms of the GNU Library General Public License as published by 00007 //# the Free Software Foundation; either version 2 of the License, or (at your 00008 //# option) any later version. 00009 //# 00010 //# This library is distributed in the hope that it will be useful, but WITHOUT 00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 00012 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public 00013 //# License for more details. 00014 //# 00015 //# You should have received a copy of the GNU Library General Public License 00016 //# along with this library; if not, write to the Free Software Foundation, 00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA. 00018 //# 00019 //# Correspondence concerning AIPS++ should be addressed as follows: 00020 //# Internet email: aips2-request@nrao.edu. 00021 //# Postal address: AIPS++ Project Office 00022 //# National Radio Astronomy Observatory 00023 //# 520 Edgemont Road 00024 //# Charlottesville, VA 22903-2475 USA 00025 //# 00026 //# $Id$ 00027 00028 #ifndef CASA_ARRAYIO_H 00029 #define CASA_ARRAYIO_H 00030 00031 //# Includes 00032 #include <casacore/casa/aips.h> 00033 #include <casacore/casa/BasicSL/String.h> 00034 00035 //# Forward declarations 00036 #include <casacore/casa/iosfwd.h> 00037 00038 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00039 00040 class AipsIO; 00041 class LogIO; 00042 class IPosition; 00043 template<class T> class Array; 00044 template<class T> class Matrix; 00045 template<class T> class Vector; 00046 template<class T> class Cube; 00047 template<class T> class Block; 00048 00049 // <summary> 00050 // Input/output operators for Arrays. 00051 // </summary> 00052 00053 // <use visibility=export> 00054 00055 // <reviewed reviewer="Paul Shannon" date="1995/02/21" tests="" demos=""> 00056 // This header was reviewed and revised with the goal of making it an 00057 // example for those writing global function header files. 00058 // </reviewed> 00059 00060 // <prerequisite> 00061 // <li> <linkto class=Array>Array</linkto> 00062 // <li> ostream 00063 // <li> <linkto class=AipsIO>AipsIO</linkto> 00064 // </prerequisite> 00065 00066 // <etymology> 00067 // ArrayIO is simply the conventional shorthand for "array input/output". 00068 // </etymology> 00069 00070 // <synopsis> 00071 // These global functions provide easy input and output of (possibly) 00072 // large and (possibly) multi-dimensional arrays. Iteration through 00073 // entire arrays is done behind the scenes, with no effort required 00074 // of the client programmer. 00075 // These functions are global, rather than member functions of the 00076 // Array class, because of the well-known C++ requirement that the first 00077 // argument to an operator function (as it is declared) is the 00078 // left operand when the function is called. 00079 // </synopsis> 00080 00081 00082 // <example> 00083 // <srcblock> 00084 // IPosition shape (3,10,10,3); 00085 // Array <Float> array (shape); 00086 // // ...initialize and manipulate the array... 00087 // cout << "result: " << array; 00088 // </srcblock> 00089 // 00090 // <motivation> 00091 // Effortless input/output is clearly a big win. 00092 // </motivation> 00093 // 00094 // <todo asof="1997/01/15"> 00095 // </todo> 00096 00097 // <linkfrom anchor="Array IO" classes="Array Vector Matrix Cube"> 00098 // <here>Array IO</here> -- Input/output operators for Arrays. 00099 // </linkfrom> 00100 // 00101 // <group name="Array IO"> 00102 00103 00104 // Write out an ascii representation of an array of any dimensionality. 00105 // Arrays of dimensionality 3 or greater are written out vector by vector, 00106 // preceeded by the position of the start of the vector. If the origin of 00107 // the array isn't zero it is printed. The shape of the array is always 00108 // printed. 00109 00110 template<class T> ostream &operator << (ostream &, const Array<T> &); 00111 00112 // Write a formatted copy of the array to the LogIO output object. Merely calls 00113 // the ostream operator<< in turn. 00114 template<class T> LogIO &operator<<(LogIO &os, const Array<T> &a); 00115 00116 // Read an ascii representation of an array. All types with an <src><<</src> 00117 // operator can be handled. The basic format of the input should be: 00118 // <srcblock> 00119 // [element element element ....] 00120 // </srcblock> 00121 // Elements are separated by whitespace, or a comma, optionally surrounded 00122 // by white space. <br> 00123 // <note role=warning> Some input routines read fields between blank spaces. This 00124 // is (at the moment) especially true for Quantities and Strings. 00125 // In those cases 00126 // the separator should be blank (or a comma following a blank), and the 00127 // end ']' should have a blank in front. 00128 // A crude fix for String arrays having separators <src>,</src> and <src>]</src> 00129 // without blanks preceding has been made; but slows routines down </note> 00130 // The default input is a vector of unspecified length. The input shape 00131 // can be changed by pre-pending the input with: 00132 // <srcblock> 00133 // {[shape]} 00134 // </srcblock> 00135 // where shape is an unsigned integer vector. The shape will be used to check 00136 // the input length; and, depending on the possibility, to resize/reshape the 00137 // result. However, reshaping of e.g. a Vector to a Matrix cannot be done, and 00138 // the result will stay in the form asked.<br> 00139 // Input order is row major, however by preceding the input with: 00140 // <srcblock> 00141 // {T[shape]} 00142 // </srcblock> 00143 // the order will be reversed.<br> 00144 // Reshaping of the Array provided will depend on the type of Array and its 00145 // state. If a general Array, the shape will be 00146 // as defined by user. If fixed Array (e.g. Matrix, Vector, Cube) the number 00147 // of dimesnsions will be kept. If the user specified more dimensions 00148 // then supported (e.g. 3 for Matrix), the last dimesions will be collapsed. 00149 // If less dimensions are specified, the missing ones will be set to 1. 00150 // will be kept.<br> 00151 // The read() version can be used to force a shape (ip), or an input 00152 // transpose (it) (which can be undone by the user specifying transpose). 00153 // 00154 // <group> 00155 00156 template<class T> istream &operator >> (istream &s, Array<T> &x); 00157 template<class T> Bool read(istream &s, Array<T> &x, 00158 const IPosition *ip=0, Bool it=False); 00159 // </group> 00160 00161 // General read support function for matrices. 00162 // In principle these functions will not be 00163 // used by general user, but could be. They can be used by Array type 00164 // classes (like Slice, Lattice) to do the work of comparable input 00165 // functions as the one for Arrays. 00166 // In these functions p is the shape 00167 // of the returned Block x. This shape is either deduced from the user 00168 // specification; made equal to (1, nelements) if no user shape is 00169 // given; is set to ip if specified. The function will return False (and 00170 // p = (0)) in the case of an invalid input element; a number of elements 00171 // input not equal to ip (if specified); the shape given by user as input 00172 // does not conform to ip (if given) or the number of elements input.<br> 00173 // trans will be True if transpose asked by user; or if forced by it. 00174 00175 00176 template<class T> Bool readArrayBlock(istream &s, Bool &trans, 00177 IPosition &p, 00178 Block<T> &x, 00179 const IPosition *ip=0, Bool it=False); 00180 00181 00182 // Read or write a binary representation of an Array to a file. Very 00183 // useful for saving arrays and restoring them later. 00184 // <br>The putArray function is put in for forwards compatibility 00185 // of images (so new images can be read with old release). 00186 // 00187 // <group> 00188 00189 template<class T> AipsIO &operator<< (AipsIO &, const Array<T> &); 00190 template<class T> void putArray (AipsIO &, const Array<T> &, const Char* name); 00191 template<class T> AipsIO &operator>> (AipsIO &, Array<T> &); 00192 00193 // </group> 00194 00195 // </group> 00196 00197 00198 00199 00200 // <summary> 00201 // Global functions to read/write binary arrays from/to a file. 00202 // </summary> 00203 00204 // <use visibility=export> 00205 00206 // <reviewed reviewer="Gareth Hunt" date="95Mar31" tests="" demos=""> 00207 // </reviewed> 00208 00209 // <synopsis> 00210 // These global functions provide disk read/write functions for an Array of 00211 // binary numbers. The write operation is useful, for example, to dump an 00212 // image in binary form to disk so that it can be displayed with an external 00213 // utility such as SAOimage. 00214 // </synopsis> 00215 00216 // <example> 00217 // <srcblock> 00218 // Matrix<Float> picture(256, 256); picture = 0.0; 00219 // String fileName="picture.data"; 00220 // 00221 // // operations to populate picture 00222 // // ... 00223 // 00224 // write_array (picture, fileName); 00225 // </srcblock> 00226 // </example> 00227 00228 // <todo asof=""> 00229 // <li> These functions should eventually be replaced with something 00230 // more sophisticated. 00231 // </todo> 00232 00233 // <linkfrom anchor="Array binary IO" classes="Array Vector Matrix Cube"> 00234 // <here>Array binary IO</here> -- Simple binary input/output for Arrays. 00235 // </linkfrom> 00236 00237 // <group name=Array binary IO> 00238 00239 // Write the values of an array in binary format into a file with 00240 // the given name. 00241 // The values are stored in local format, thus are not converted 00242 // to a canonical format as 00243 // <linkto class="AipsIO:description">AipsIO</linkto> 00244 // does. 00245 // <note role=warning> 00246 // This function is only suitable for built-in data types. 00247 // </note> 00248 // <group> 00249 template <class T> 00250 void write_array (const Array<T>& the_array, const String& fileName); 00251 00252 template <class T> 00253 inline void write_array (const Array<T>& the_array, const Char* fileName) 00254 { write_array (the_array, String(fileName)); } 00255 // </group> 00256 00257 // Read the values of an array in binary format from a file with 00258 // the given name. 00259 // The number of values read is the size of the Array, thus the file 00260 // should at least contain that number of values. 00261 // <note role=warning> 00262 // This function is only suitable for built-in data types. 00263 // </note> 00264 // <group> 00265 template <class T> 00266 void read_array (Array<T>& the_array, const String& fileName); 00267 00268 template <class T> 00269 inline void read_array (Array<T>& the_array, const Char* fileName) 00270 { read_array (the_array, String(fileName)); } 00271 // </group> 00272 00273 // </group> 00274 00275 00276 00277 // <summary> 00278 // Global functions for Matrix/Vector input/output using ASCII format. 00279 // </summary> 00280 00281 // <use visibility=export> 00282 00283 // <prerequisite> 00284 // <li> <linkto class=Matrix>Matrix</linkto> 00285 // <li> <linkto class=Vector>Vector</linkto> 00286 // </prerequisite> 00287 00288 // <synopsis> 00289 // These global functions support file I/O between ASCII files and 00290 // Matrices or Vectors. 00291 // </synopsis> 00292 00293 // <example> 00294 // <srcblock> 00295 // Matrix<Float> picture(256, 256); picture = 0.0; 00296 // String fileName="picture.data"; 00297 // 00298 // // operations to populate picture 00299 // // ... 00300 // 00301 // writeAsciiMatrix (picture, fileName); 00302 // </srcblock> 00303 // </example> 00304 00305 // <linkfrom anchor="Array Ascii IO" classes="Vector Matrix"> 00306 // <here>Array Ascii IO</here> -- Simple Ascii input/output for Arrays. 00307 // </linkfrom> 00308 00309 // <group name=Array Ascii IO> 00310 00311 // These routines read and write a Matrix of data. The first line of 00312 // input will be examined to determine the number of columns in the matrix. 00313 // The maximum number of columns provided for is 100. Each item may be up 00314 // to 50 characters long. 00315 // 00316 // Each item must be separated from others by one (or more) blank column. 00317 // The "line" may be up to 1024 characters long. Each subsequent line must 00318 // contain the SAME number of items as the first line but may be any length 00319 // (up to 1024 characters). 00320 // 00321 // The matrix need NOT be square. 00322 // 00323 // The matrix should be declared but NOT dimensioned in the calling program. 00324 00325 // <group> 00326 template <class T> 00327 void readAsciiMatrix (Matrix<T>& mat, const Char* fileName); 00328 00329 template <class T> 00330 void writeAsciiMatrix (const Matrix<T>& mat, const Char* fileName); 00331 // </group> 00332 00333 00334 // These two functions read and write a Vector of data. The input 00335 // may be arranged in any format (i.e. It may be recorded as one value per 00336 // line or it may be recorded with all values on a single line). 00337 // Values must be separated by whitespace. 00338 00339 // <group> 00340 template <class T> 00341 void readAsciiVector (Vector<T>& vec, const Char* fileName); 00342 00343 template <class T> 00344 void writeAsciiVector (const Vector<T>& vec, const Char* fileName); 00345 // </group> 00346 00347 // </group> 00348 00349 00350 00351 } //# NAMESPACE CASACORE - END 00352 00353 #ifndef CASACORE_NO_AUTO_TEMPLATES 00354 #include <casacore/casa/Arrays/ArrayIO.tcc> 00355 #endif //# CASACORE_NO_AUTO_TEMPLATES 00356 #endif