ArrayIO.h

Go to the documentation of this file.
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
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1