casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
ScaColDesc.h
Go to the documentation of this file.
00001 //# ScaColDesc.h: Templated class for description of table scalar columns
00002 //# Copyright (C) 1994,1995,1996,1997,1998,2000
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: ScaColDesc.h 21051 2011-04-20 11:46:29Z gervandiepen $
00027 
00028 #ifndef TABLES_SCACOLDESC_H
00029 #define TABLES_SCACOLDESC_H
00030 
00031 
00032 //# Includes
00033 #include <casa/aips.h>
00034 #include <tables/Tables/BaseColDesc.h>
00035 #include <casa/Containers/SimOrdMap.h>
00036 
00037 namespace casa { //# NAMESPACE CASA - BEGIN
00038 
00039 //# Forward Declarations
00040 class PlainColumn;
00041 class ColumnSet;
00042 
00043 
00044 // <summary>
00045 // Templated class to define columns of scalars in tables
00046 // </summary>
00047 
00048 // <reviewed reviewer="Gareth Hunt" date="94Nov17" tests="">
00049 // </reviewed>
00050 
00051 // <use visibility=export>
00052 
00053 // <prerequisite>
00054 //   <li> BaseColumnDesc
00055 //   <li> TableDesc
00056 // </prerequisite>
00057 
00058 // <etymology>
00059 //  This class builds descriptions of table columns where each cell (which
00060 //  may also be called a row) will hold a scalar value.
00061 // </etymology>
00062 
00063 // <synopsis> 
00064 // ScalarColumnDesc is a templated class for defining a
00065 // table column containing scalar values.
00066 // Note that class
00067 // <linkto class=ScalarRecordColumnDesc>ScalarRecordColumnDesc</linkto>
00068 // has to be used to define the description of a column containing records.
00069 // <p>
00070 // The table values are handled by a data manager. This can be
00071 // a storage manager to store the values in a file or it can be
00072 // a virtual column engine to calculate them on-the-fly.
00073 // Only the basic data types are allowed when storing in a file. These are:
00074 //  Bool, uChar, Short, uShort, Int, uInt, float, double,
00075 //  Complex, DComplex and String.
00076 // <p>
00077 // At table creation time (when a table gets created from a table
00078 // description), each column needs to be bound to a data manager.
00079 // If not done explicitly, the table system will bind a column to the
00080 // default data manager defined in the column description.
00081 // <p>
00082 // A scalar column description consists of the following attributes:
00083 // <ul>
00084 //  <li> Name, which has to be unique and must also be different
00085 //         from possible table keyword names.
00086 //  <li> Data type, which is determined by the template parameter
00087 //         (e.g. ArrayColumnDesc<Int>).
00088 //  <li> A data type id, which tells the unique name of non-standard
00089 //         data types (i.e. for data type == TpOther).
00090 //  <li> Comment, which defaults to an empty string.
00091 //         This serves purely as an informational string for the user.
00092 //  <li> Default value, which is only possible for the standard data types.
00093 //         It defaults to the undefined value defined in ValType.h.
00094 //         When a row gets added to a table, it is possible to
00095 //         initialize the column fields in the row with this default value.
00096 //  <li> Default data manager, which will be used if a column
00097 //         for a newly created table is not explicitly bound to a
00098 //         data manager.
00099 //  <li> Data manager group, which serves 2 purposes.
00100 //         Firstly it can be used in class SetupNewTable to bind a group
00101 //         of columns.
00102 //         Secondly, when the default data managers are used, it
00103 //         allows, for example, to have 2 StandardStMan storage managers.
00104 //         One for one group of columns and one for another group of columns.
00105 //  <li> Options. These are defined in ColumnDesc.h and can be combined
00106 //         by or-ing them.
00107 //         Currently only the Undefined flag applies to scalars.
00108 //  <li> Default keyword set, which defaults to an empty set.
00109 //         When a table column gets created from the description, it gets
00110 //         a copy of this keyword set as its initial keyword set.
00111 // </ul>
00112 //
00113 // There are several constructors, which allow to define most
00114 // of the above mentioned attributes. Others, like the default keyword
00115 // set, have to be defined explicitly.
00116 // <p>
00117 // This class is derived from BaseColumnDesc, thus the functions
00118 // in there also apply to this class.
00119 // <br>
00120 // Once a column description is setup satisfactorily, it must be added
00121 // to a table description before it can be used by the table system.
00122 // </synopsis>
00123 
00124 // <example>
00125 // <srcblock>
00126 //     TableDesc tabDesc("tTableDesc", "1", TableDesc::New);
00127 //
00128 //     // Add a scalar integer column ac, define keywords for it
00129 //     // and define a default value 0.
00130 //     ScalarColumnDesc<Int> acColumn("ac");
00131 //     acColumn.rwKeywordSet().define ("scale", Complex(0));
00132 //     acColumn.rwKeywordSet().define ("unit", "");
00133 //     acColumn.setDefault (0);
00134 //     tabDesc.addColumn (acColumn);
00135 //
00136 //     // Add another column, now with data type String..
00137 //     // This can be added directly, because no special things like
00138 //     // keywords or default values have to be set.
00139 //     tabDesc.addColumn (ScalarColumnDesc<String>("name", "comments"));
00140 // </srcblock>
00141 // </example>
00142 
00143 // <motivation>
00144 // Several column description classes are needed to allow the user
00145 // to define attributes which are special for each column type.
00146 // For scalars the special attribute is the default value.
00147 // They all have to be templated to support arbitrary data types.
00148 // </motivation>
00149 
00150 // <templating arg=T>
00151 //  <li> Default constructor
00152 //  <li> Copy constructor
00153 //  <li> Assignment operator
00154 //  <li> <src>static String dataTypeId();  // (not needed for builtin types)</src>
00155 //       This should return the unique "name" of the class.
00156 // </templating>
00157 
00158 // <todo asof="$DATE:$">
00159 //# A List of bugs, limitations, extensions or planned refinements.
00160 // </todo>
00161 
00162 
00163 template<class T>
00164 class ScalarColumnDesc : public BaseColumnDesc
00165 {
00166 friend class ColumnDesc;
00167 
00168 public:
00169     // Construct the column with the given name.
00170     // The data manager type defaults to the StandardStMan storage manager.
00171     // The data manager group defaults to the data manager type.
00172     // The possible options are defined in ColumnDesc.h.
00173     explicit ScalarColumnDesc (const String& name, int options = 0);
00174 
00175     // Construct the column with the given name and comment.
00176     // The data manager type defaults to the StandardStMan storage manager.
00177     // The data manager group defaults to the data manager type.
00178     // The possible options are defined in ColumnDesc.h.
00179     ScalarColumnDesc (const String& name, const String& comment,
00180                       int options = 0);
00181 
00182     // Construct the column with the given name, comment, and
00183     // default data manager type and group.
00184     // A blank data manager group defaults to the data manager type.
00185     // The possible options are defined in ColumnDesc.h.
00186     ScalarColumnDesc (const String& name, const String& comment,
00187                       const String& dataManName, const String& dataManGroup,
00188                       int options = 0);
00189 
00190     // Construct the column with the given name, comment, default
00191     // data manager type and group, and default value.
00192     // A blank data manager group defaults to the data manager type.
00193     // The possible options are defined in ColumnDesc.h.
00194     ScalarColumnDesc (const String& name, const String& comment,
00195                       const String& dataManName, const String& dataManGroup,
00196                       const T& defaultValue, int options = 0);
00197 
00198     // Copy constructor (copy semantics);
00199     ScalarColumnDesc (const ScalarColumnDesc<T>&);
00200 
00201     ~ScalarColumnDesc();
00202 
00203     // Assignment (copy semantics);
00204     ScalarColumnDesc<T>& operator= (const ScalarColumnDesc<T>&);
00205 
00206     // Clone this column description.
00207     BaseColumnDesc* clone() const;
00208 
00209     // Get the name of this class. It is used by the registration process.
00210     // The template argument gets part of the name.
00211     String className() const;
00212 
00213     // Set the default value.
00214     void setDefault (const T& defaultValue)
00215         { defaultVal_p = defaultValue; }
00216 
00217     // Get the default value.
00218     const T& defaultValue() const
00219         { return defaultVal_p; }
00220 
00221     // Create a Column object out of this.
00222     // This is used by class ColumnSet to construct a table column object.
00223     virtual PlainColumn* makeColumn (ColumnSet*) const;
00224 
00225     // Make a ConcatColumn object out of the description.
00226     virtual ConcatColumn* makeConcatColumn (ConcatTable*) const;
00227 
00228     // Show the column.
00229     void show (ostream& os) const;
00230 
00231     // Register the construction function of this class.
00232     void registerClass() const;
00233 
00234     // Create the object from AipsIO (this function is registered).
00235     static BaseColumnDesc* makeDesc (const String& name);
00236 
00237 private:
00238     T  defaultVal_p;                        //# default value
00239 
00240     // Put the object.
00241     virtual void putDesc (AipsIO&) const;
00242 
00243     // Get the object.
00244     virtual void getDesc (AipsIO&);
00245 };
00246 
00247 
00248 
00249 } //# NAMESPACE CASA - END
00250 
00251 #ifndef CASACORE_NO_AUTO_TEMPLATES
00252 #include <tables/Tables/ScaColDesc.tcc>
00253 #endif //# CASACORE_NO_AUTO_TEMPLATES
00254 #endif