casacore
RecordTransformable.h
Go to the documentation of this file.
1 //# RecordTransformable.h: Interface class for converting to/from records
2 //# Copyright (C) 1998,1999,2003
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$
28 
29 #ifndef CASA_RECORDTRANSFORMABLE_H
30 #define CASA_RECORDTRANSFORMABLE_H
31 
32 #include <casacore/casa/aips.h>
33 
34 namespace casacore { //# NAMESPACE CASACORE - BEGIN
35 
36 class String;
37 class RecordInterface;
38 
39 // <summary>Interface class for converting to/from records</summary>
40 
41 // <use visibility=export>
42 
43 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tRecordTransformable">
44 // </reviewed>
45 
46 // <prerequisite>
47 // <li> <linkto class="RecordInterface">RecordInterface</linkto>
48 // </prerequisite>
49 //
50 // <etymology>
51 // This class defines the interface that a class should use if the can be
52 // transformed into a record representation.
53 // </etymology>
54 //
55 // <synopsis>
56 // This abstract base class is intended to be publicly inherited by classes
57 // that contain functions which can represent the object as a record (these
58 // functions should be called <src>toRecord</src> and
59 // <src>fromRecord</src>). Examples of records are:
60 // <ul>
61 // <li> <linkto class="Record">Record</linkto>
62 // <li> <linkto class="TableRecord">TableRecord</linkto>
63 // </ul>
64 //
65 // This interface defines two functions that convert between a RecordInterface
66 // and the class that inherits these functions. These functions are often used
67 // to parse input that is beyond the programs control e.g. user input from
68 // glish or Table records that may have been generated elsewhere. Hence
69 // exceptions should not thrown be thrown by these functions. Instead the
70 // function should return False and append an error message to the supplied
71 // String when the transformation cannot be accomplished.
72 //
73 // <note role=warning>
74 // Converting to/from a GlishRecord requires an extra step.
75 // First a Record should be used which can thereafter be converted to/from
76 // a GlishRecord using the appropriate GlishRecord functions.
77 // </note>
78 // </synopsis>
79 //
80 // <example>
81 // The following example prints out a class using its record representation.
82 // This example is in the file tRecordTransformable.cc
83 // <srcblock>
84 // void printAsRecord(const RecordTransformable & myClass) {
85 // String errorMessage;
86 // Record rec;
87 // if (!myClass.toRecord(errorMessage, rec)) {
88 // cout << "Cannot convert class to a Record. The reason is:" << endl;
89 // cout << errorMessage << endl;
90 // } else {
91 // cout << rec.ndefined() << endl;
92 // }
93 // }
94 // </srcblock>
95 // </example>
96 //
97 // <motivation>
98 // This class was designed to standardise the function interface for converting
99 // between an object and its record representation.
100 // </motivation>
101 //
102 // <todo asof="1998/03/30">
103 // <li> Nothing I hope!
104 // </todo>
105 
107 {
108 public:
109  // The destructor must be virtual so that the destructor of derived classes
110  // is actually used.
112 
113  // Convert the class to an Record representation. The input record may
114  // already contain fields and these fields may be silently overridden. New
115  // fields may be added to the input Record. If the transformation succeeds
116  // then the error String is unchanged and the function returns
117  // True. Otherwise the function returns False and appends an error message to
118  // the supplied String giving the reason why the conversion failed.
119  virtual Bool toRecord(String & error, RecordInterface & outRecord) const = 0;
120 
121  // Initialise the class from a Record representation. The input record should
122  // contain the fields that are required by the class. Other fields will be
123  // ignored. If the transformation succeeds then the error String is unchanged
124  // and the function returns True. Otherwise the function returns False and
125  // appends an error message to the supplied String giving the reason why the
126  // conversion failed.
127  virtual Bool fromRecord(String & error, const RecordInterface & inRecord) =0;
128 
129  // Initialise the class from a String representation. A string cannot
130  // contain enough information for many objects. Hence the default
131  // implementation of this class returns False, indicating that the class
132  // could not be initialised and an error message is appended to the supplied
133  // string. If the class can be initialised from a string then this function
134  // should be overridden.
135  virtual Bool fromString(String & error, const String & inString);
136 
137  // Specify the identification of the record (e.g. 'meas', 'quant'). The
138  // default implementation returns a empty string.
139  virtual const String &ident() const;
140 };
141 
142 
143 } //# NAMESPACE CASACORE - END
144 
145 #endif
virtual Bool fromString(String &error, const String &inString)
Initialise the class from a String representation.
virtual Bool fromRecord(String &error, const RecordInterface &inRecord)=0
Initialise the class from a Record representation.
virtual const String & ident() const
Specify the identification of the record (e.g.
virtual Bool toRecord(String &error, RecordInterface &outRecord) const =0
Convert the class to an Record representation.
virtual ~RecordTransformable()
The destructor must be virtual so that the destructor of derived classes is actually used.
String: the storage and methods of handling collections of characters.
Definition: String.h:225
this file contains all the compiler specific defines
Definition: mainpage.dox:28
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42