Version 1.9 Build 1556

News	FAQ
Search	Home

Next: The functions Up: Introduction to Programming for AIPS++ Previous: Second Version

Subsections

An advanced example

The following program is meant to illustrate some further features of the AIPS++ system. In particular, we will show a program that was used to test the development of two functions which read and write an ASCII file. The file is expected to contain a 2-dimensional array (of any rectangular dimensions) of numbers and place the values it contains (regardless of type) into a matrix.

The work will be described in three parts - which correspond to the three directories that should be used for this type of work. They are:

1.: The directory in which the main routine is composed and compiled. This is the one that has been used in previous examples. It is: ~/aips/code/aips/test.
2.: A directory in which the .h file is defined. This is: ~/aips/code/aips/include.
3.: A directory in which the functions are composed and compiled. This one also will contain a private library which will be searched automatically by the gmake process. This one is: ~/aips++/code/aips/implement.

The main program

We start with the main program which will simply call a couple of routines to check the coding (The source code for this program is found in $AIPSROOT/code/trial/implement/test/tExample3.cc).

 1  #include <aips/aips.h>
 2  #include <aips/AipsIO.h>
 3  #include <aips/ArrayIO.h>
 4  #include <aips/Input.h>
 5  #include <aips/Math.h>
 6  #include <aips/Matrix.h>
 7  #include <aips/AsciiFileIO.h>
 9  
10  main(int argc, char **argv)
11  {
12   Input inputs(1);
13   inputs.Version("$w{Revision}$");
14   inputs.Usage("Testing Ascii IO routines");
15   inputs.Create("infile1","Input1","Float Input file name?","Infile");
16   inputs.Create("infile2","Input2","Int Input file name?","Infile");
17   inputs.Create("infile3","Input3","Double Input file name?","Infile");
18   inputs.Create("outfile","Output","Output file name?","Outfile");
19   inputs.ReadArguments(argc, argv);
20  
21   const char *filein1 = inputs.GetString("infile1");
22   const char *filein2 = inputs.GetString("infile2");
23   const char *filein3 = inputs.GetString("infile3");
24   const char *fileout = inputs.GetString("outfile");
25  
26   Int rows, cols;
27   try {
28      Matrix <Float> mat1;
29      Matrix <Int> mat2;
30      Matrix <Double> mat3;
31  
32      ReadAsciiFile(filein1, mat1);
33      mat1.shape(rows, cols);
34      cout << "The first Matrix is " << rows << " by " << cols << endl;
35  
36      ReadAsciiFile(filein2, mat2);
37      mat2.shape(rows, cols);
38      cout << "The second Matrix is " << rows << " by " << cols << endl;
39  
40      ReadAsciiFile(filein3, mat3);
41      mat3.shape(rows, cols);
42      cout << "The third Matrix is " << rows << " by " << cols << endl;
43  
44      WriteAsciiFile(fileout, mat1);
45  
46      cout.precision(12);
47      cout << mat1 << mat2 << mat3;
48     }
49  
50   return 0;
51
52    catch (AipsError x) {
53    cerr << "aipserror: error " << x.getMesg() << endl;
54          return 1;
55         }
56
58  }

The following discussion refers to the line numbers which have been prepended to the code above:

7-: This line includes the new routines in the code for AsciiFileIO.
15-17-: The program will read 3 different arrays of differing characteristics.
28-30-: The Matrices are declared to be of three differing types but the sizes of the arrays is not stated. It will be set dynamically by the subroutines.
32-: The ReadAsciiFile function is called to read a matrix of floating point values. The type is specified in the declaration of mat1 which is used as an argument. The size of the array is still unknown. Note that the data in the array may be in integer form but it will be stored as an array of float values.
33-: The member function shape is called to determine the dimensions of the matrix that was just read.
36-: The same new function, ReadAsciiFile, is called to read an array of integers. The data may be specified with decimal points and fractional parts but they will be placed in the matrix as integers.
37-: The member function shape is used to get the dimensions of the matrix mat2. Note that these dimensions are quite independent of the dimesions found for the matrix mat1.
40-41-: The same comments hold for a matrix of doubles.
44-: The routine to write the array, WriteAsciiFile, need not pass the dimensions of the array since they can be determined in the same way as they were in lines 33, 37 and 41.
46-: The property of cout, precision, is used to set the number of decimal places that will appear in the output (where they are not all zero). Other properties of the format state may also be set. For example, one could set the number of decimal places displayed to a constant (regardless of whether or not they were all zeroes) by using the statement cout.setf(ios::showpoint).

The include file

This file containd the .h module. The working part of this file is really only two lines long but the required "boiler-plate" takes up the first 25 lines (approximately). This text must be included with every file that is intended for the AIPS++ system (i.e. that could be distributed outside of NRAO).

This include file may be found in $AIPSROOT/code/trial/implememnt/test/FileIO.h.

  1  //# FileIO.h: this defines ileIO functions, which ...
  2  //# Copyright (C) 1996,1999,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  //#
 27  //# $Id: IntroPrg.tex,v 19.0 2003/07/16 04:18:22 aips2adm Exp $
 28
 29  #if !defined (AIPS_FILEIO_H)
 30  #define AIPS_FILEIO_H
 31
 32  #if defined(_AIX)
 33  #pragma implementation ("AsciiFileIO.cc")
 34  #endif
 35
 36  #include <aips/aips.h>
 37  #include <aips/Arrays/ArrayIO.h>
 38
 39  //# Forward Declarations
 40
 41  // <summary>
 42  Input/output using ASCII format
 43  // </summary>
 44
 45  // <use visibility=local>   or   <use visibility=export>
 46
 47  // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
 48  // </reviewed>
 49
 50  // <prerequisite>
 51  //   <li> SomeClass
 52  //   <li> SomeOtherClass
 53  //   <li> some concept
 54  // </prerequisite>
 55  //
 56  // <etymology>
 57  // </etymology>
 58  //
 59  // <synopsis>
 60  // </synopsis>
 61  //
 62  // <example>
 63  // </example>
 64  //
 65  // <motivation>
 66  // </motivation>
 67  //
 68  // <templating arg=T>
 69  //    <li>
 70  //    <li>
 71  // </templating>
 72  //
 73  // <thrown>
 74  //    <li>
 75  //    <li>
 76  // </thrown>
 77  //
 78  // <todo asof="yyyy/mm/dd">
 79  //   <li> add this feature
 80  //   <li> fix this bug
 81  //   <li> start discussion of this possible extension
 82  // </todo>
 83
 84 template <class T>
 85    void
 86    readAsciiFile(const char *filein, Matrix<T> &mat){
 87       readAsciiMatrix(mat, filein);
 88    }
 89 template <class T>
 90    void
 91    readAsciiFile(const char *filein, Vector<T> &vec){
 92       readAsciiVector(vec, filein);
 93    }
 94 
 95 //
 96 
 97 template <class T>
 98    void
 99    writeAsciiFile(const char *fileout, const Matrix<T> &mat){
100       writeAsciiMatrix(mat, fileout);
101    }
102 template <class T>
103    void
104    writeAsciiFile(const char *fileout, const Vector<T> &vec){
105       writeAsciiVector(vec, fileout);
106    }
107  #endif

1-27-: Boilerplate which is to be included in each module.
29-30-: The code begins with a label that identifies this file. The macros if ! defined and define prevent the code from being loaded more than once in a given program. (Note the endif macro at the end.)
34-: Every header file MUST include this line which, in turn, must NOT be included with the code for the function.
35-: The Matrix class is included because this header file describes functions that take a Matrix as an argument.
39-82-: These lines are the documentation template for each class. Cxx2html will read these lines and produce formated HTML for your class/functions. A more complete description maybe found in the Programmer's Reference Manual If you ever want to check you're code in then you must fill them in.
84-86-: These lines (which, you will note, are a single statement) declare the function ReadsAsciiFile to be a template i.e. to be defined once for multiple types of argument. The symbol uses here to represent the argument type is the letter T (declared in the pointed brackets with the keyword class). The function itself is like any other function declaration except that the Matrix argument is defined for the multiple types represented by the letter T.
The implications of this are important. Since the class is only specified later on (when the routine is called) the compiler cannot create ahead of time a module that will be linked with the calling code. So even though we will place these routines in a library, it really is a source library and every time a module is used it must be compiled at that time!
87-89-: The lines declare the second function WriteAsciiFile.
91-: This matches the test for label declaration on line 31.

Next: The functions Up: Introduction to Programming for AIPS++ Previous: Second Version Contents Index