casacore
SSMColumn.h
Go to the documentation of this file.
1 //# SSMColumn.h: A Column in the Standard Storage Manager
2 //# Copyright (C) 2000
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 //# $Id$
27 
28 #ifndef TABLES_SSMCOLUMN_H
29 #define TABLES_SSMCOLUMN_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/tables/DataMan/StManColumn.h>
35 #include <casacore/tables/DataMan/SSMBase.h>
36 #include <casacore/casa/Arrays/IPosition.h>
37 #include <casacore/casa/Containers/Block.h>
38 #include <casacore/casa/OS/Conversion.h>
39 
40 namespace casacore { //# NAMESPACE CASACORE - BEGIN
41 
42 //# Forward declarations
43 
44 
45 // <summary>
46 // A Column in the Standard Storage Manager.
47 // </summary>
48 
49 // <use visibility=local>
50 
51 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tStandardStMan.cc">
52 // </reviewed>
53 
54 // <prerequisite>
55 //# Classes you should understand before using this one.
56 // <li> <linkto class=SSMBase>SSMBase</linkto>
57 // <li> <linkto class=SSMStringHandler>SSMStringHandler</linkto>
58 // </prerequisite>
59 
60 // <etymology>
61 // SSMColumn represents a Column in the Standard Storage Manager.
62 // </etymology>
63 
64 // <synopsis>
65 // SSMColumn is the base class for access to a column stored with
66 // the Standard Storage manager. It provides some basic functionality
67 // for the derived classes handling direct and indirect arrays.
68 // <p>
69 // The main task of SSMColumn is handling the access to a column
70 // containing scalars of the various data types. The data is stored
71 // in buckets. The classes <linkto class=SSMBase>SSMBase</linkto>
72 // and <linkto class=SSMIndex>SSMIndex</linkto> keep track in which data
73 // bucket a given row is stored and at which offset the column starts.
74 // Using that information SSMColumn can access its data easily.
75 // <p>
76 // Almost all data types have a fixed length and can be handled easily.
77 // However, strings are a special case.
78 // <br>If the string is fixed length (which means it has a maximum length),
79 // the string is stored directly in the data bucket. If the string is
80 // shorter than the maximum length, its length is indicated by a
81 // trailing 0.
82 // <br>Variable strings are in principle stored in a special string bucket.
83 // The data bucket contains 3 integers telling the bucketnr, offset, and
84 // length of the string. However, it the string is short enough (ie. <=
85 // 8 characters), the string is stored directly in data bucket using
86 // the space for bucketnr and offset.
87 // <p>
88 // The class maintains a cache of the data in the bucket last read.
89 // This cache is used by the higher level table classes to get faster
90 // read access to the data.
91 // The cache is not used for strings, because they are stored differently.
92 // </synopsis>
93 
94 //# <todo asof="$DATE:$">
95 //# A List of bugs, limitations, extensions or planned refinements.
96 //# </todo>
97 
98 
99 class SSMColumn : public StManColumn
100 {
101 public:
102  // Create a SSMColumn object with the given parent.
103  // It initializes the various variables.
104  // It keeps the pointer to its parent (but does not own it).
105  SSMColumn (SSMBase* aParent, int aDataType, uInt aColNr);
106 
107  virtual ~SSMColumn();
108 
109  // Set the shape of an array in the column.
110  // It is only called (right after the constructor) if the array has
111  // a fixed shape.
112  virtual void setShapeColumn (const IPosition& aShape);
113 
114  // Set the maximum length of a 'fixed length' string.
115  // It is only called (right after the constructor) if the string has
116  // a fixed length
117  virtual void setMaxLength (uInt maxLength);
118 
119  // Get the dimensionality of the item in the given row.
120  virtual uInt ndim (uInt aRowNr);
121 
122  // Get the shape of the array in the given row.
123  virtual IPosition shape (uInt aRowNr);
124 
125  // Let the object initialize itself for a newly created table.
126  // It is meant for a derived class.
127  virtual void doCreate (uInt aNrRows);
128 
129  // Let the column object initialize itself for an existing table
130  virtual void getFile (uInt aNrRows);
131 
132  // Resync the storage manager with the new file contents.
133  // It resets the last rownr put.
134  void resync (uInt aNrRow);
135 
136  // Get the scalar value in the given row.
137  // <group>
138  virtual void getBoolV (uInt aRowNr, Bool* aDataPtr);
139  virtual void getuCharV (uInt aRowNr, uChar* aDataPtr);
140  virtual void getShortV (uInt aRowNr, Short* aDataPtr);
141  virtual void getuShortV (uInt aRowNr, uShort* aDataPtr);
142  virtual void getIntV (uInt aRowNr, Int* aDataPtr);
143  virtual void getuIntV (uInt aRowNr, uInt* aDataPtr);
144  virtual void getfloatV (uInt aRowNr, float* aDataPtr);
145  virtual void getdoubleV (uInt aRowNr, double* aDataPtr);
146  virtual void getComplexV (uInt aRowNr, Complex* aDataPtr);
147  virtual void getDComplexV (uInt aRowNr, DComplex* aDataPtr);
148  virtual void getStringV (uInt aRowNr, String* aDataPtr);
149  // </group>
150 
151  // Put the scalar value in the given row.
152  // It updates the cache if the row is contained in the cache.
153  // <group>
154  virtual void putBoolV (uInt aRowNr, const Bool* aDataPtr);
155  virtual void putuCharV (uInt aRowNr, const uChar* aDataPtr);
156  virtual void putShortV (uInt aRowNr, const Short* aDataPtr);
157  virtual void putuShortV (uInt aRowNr, const uShort* aDataPtr);
158  virtual void putIntV (uInt aRowNr, const Int* aDataPtr);
159  virtual void putuIntV (uInt aRowNr, const uInt* aDataPtr);
160  virtual void putfloatV (uInt aRowNr, const float* aDataPtr);
161  virtual void putdoubleV (uInt aRowNr, const double* aDataPtr);
162  virtual void putComplexV (uInt aRowNr, const Complex* aDataPtr);
163  virtual void putDComplexV (uInt aRowNr, const DComplex* aDataPtr);
164  virtual void putStringV (uInt aRowNr, const String* aDataPtr);
165  // </group>
166 
167  // Get the scalar values of the entire column.
168  // <group>
169  virtual void getScalarColumnBoolV (Vector<Bool>* aDataPtr);
170  virtual void getScalarColumnuCharV (Vector<uChar>* aDataPtr);
171  virtual void getScalarColumnShortV (Vector<Short>* aDataPtr);
172  virtual void getScalarColumnuShortV (Vector<uShort>* aDataPtr);
173  virtual void getScalarColumnIntV (Vector<Int>* aDataPtr);
174  virtual void getScalarColumnuIntV (Vector<uInt>* aDataPtr);
175  virtual void getScalarColumnfloatV (Vector<float>* aDataPtr);
176  virtual void getScalarColumndoubleV (Vector<double>* aDataPtr);
177  virtual void getScalarColumnComplexV (Vector<Complex>* aDataPtr);
178  virtual void getScalarColumnDComplexV (Vector<DComplex>* aDataPtr);
179  virtual void getScalarColumnStringV (Vector<String>* aDataPtr);
180  // </group>
181 
182  // Put the scalar values of the entire column.
183  // It invalidates the cache.
184  // <group>
185  virtual void putScalarColumnBoolV (const Vector<Bool>* aDataPtr);
186  virtual void putScalarColumnuCharV (const Vector<uChar>* aDataPtr);
187  virtual void putScalarColumnShortV (const Vector<Short>* aDataPtr);
188  virtual void putScalarColumnuShortV (const Vector<uShort>* aDataPtr);
189  virtual void putScalarColumnIntV (const Vector<Int>* aDataPtr);
190  virtual void putScalarColumnuIntV (const Vector<uInt>* aDataPtr);
191  virtual void putScalarColumnfloatV (const Vector<float>* aDataPtr);
192  virtual void putScalarColumndoubleV (const Vector<double>* aDataPtr);
193  virtual void putScalarColumnComplexV (const Vector<Complex>* aDataPtr);
194  virtual void putScalarColumnDComplexV (const Vector<DComplex>* aDataPtr);
195  virtual void putScalarColumnStringV (const Vector<String>* aDataPtr);
196  // </group>
197 
198  // Add (NewNrRows-OldNrRows) rows to the Column and initialize
199  // the new rows when needed.
200  virtual void addRow (uInt aNewNrRows, uInt anOldNrRows, Bool doInit);
201 
202  // Remove the given row from the data bucket and possibly string bucket.
203  // If needed, it also removes it from the cache.
204  virtual void deleteRow (uInt aRowNr);
205 
206  // Get the size of the dataType in bytes!!
207  uInt getExternalSizeBytes() const;
208 
209  // Get the size of the dataType in bits!!
210  uInt getExternalSizeBits() const;
211 
212  // get the sequence number of this column.
213  uInt getColNr();
214 
215  // set the sequence number of this column.
216  void setColNr (uInt aColNr);
217 
218  // If something special has to be done before removing the Column,
219  // as is the case with Strings, it can be done here.
220  void removeColumn();
221 
222 protected:
223  // Shift the rows in the bucket one to the left when removing the given row.
224  void shiftRows (char* aValue, uInt rowNr, uInt startRow, uInt endRow);
225 
226  // Fill the cache with data of the bucket containing the given row.
227  void getValue (uInt aRowNr);
228 
229  // Get the bucketnr, offset, and length of a variable length string.
230  // <src>data</src> must have 3 Ints to hold the values.
231  // It returns a pointer to the data in the bucket, which can be used
232  // for the case that the data bucket contains the (short) string.
233  Char* getRowValue (Int* data, uInt aRowNr);
234 
235  // Put the given value for the row into the correct data bucket.
236  void putValue (uInt aRowNr, const void* aValue);
237 
238  // Put the given string for the row into the correct data bucket.
239  // The argument <src>aValue></src> must be 3 Ints (for bucketnr, offset,
240  // and length). Only the length is actually used.
241  void putValueShortString (uInt aRowNr, const void* aValue,
242  const String& string);
243 
244  // Get the values for the entire column.
245  // The data from all buckets is copied to the array.
246  void getColumnValue (void* anArray, uInt aNrRows);
247 
248  // Put the values from the array in the entire column.
249  // Each data bucket is filled with the the appropriate part of the array.
250  void putColumnValue (const void* anArray, uInt aNrRows);
251 
252 
253  // Pointer to the parent storage manager.
255  // Length of column cell value in storage format (0 = variable length).
258  // Column sequence number of this column.
260  // The shape of the column.
262  // The maximum length of a 'fixed length' string.
264  // Number of elements in a value for this column.
266  // Number of values to be copied.
267  // Normally this is itsNrElem, but for complex types it is 2*itsNrElem.
268  // When local format is used, it is the number of bytes.
270  // The sizeof the datatype in local format
272  // The data in local format.
273  void* itsData;
274  // Pointer to a convert function for writing.
276  // Pointer to a convert function for reading.
278 
279 private:
280  // Forbid copy constructor.
281  SSMColumn (const SSMColumn&);
282 
283  // Forbid assignment.
284  SSMColumn& operator= (const SSMColumn&);
285 
286  // Initialize part of the object.
287  // It determines the nr of elements, the function to use to convert
288  // from local to file format, etc..
289  void init();
290 
291  // Get the pointer to the cache. It is created if not done yet.
292  char* getDataPtr();
293 };
294 
295 
297 {
298  return itsExternalSizeBytes;
299 }
300 
302 {
303  return itsExternalSizeBits;
304 }
305 
306 inline char* SSMColumn::getDataPtr()
307 {
308  if (itsData == 0) {
310  }
311  return static_cast<char*>(itsData);
312 }
313 
315 {
316  return itsColNr;
317 }
318 
319 inline void SSMColumn::setColNr (uInt aColNr)
320 {
321  itsColNr = aColNr;
322 }
323 
324 
325 
326 } //# NAMESPACE CASACORE - END
327 
328 #endif
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:119
uInt itsLocalSize
The sizeof the datatype in local format.
Definition: SSMColumn.h:271
Char * getRowValue(Int *data, uInt aRowNr)
Get the bucketnr, offset, and length of a variable length string.
int Int
Definition: aipstype.h:47
virtual void putStringV(uInt aRowNr, const String *aDataPtr)
virtual void getIntV(uInt aRowNr, Int *aDataPtr)
uInt getExternalSizeBytes() const
Get the size of the dataType in bytes!!
Definition: SSMColumn.h:296
virtual void getScalarColumnStringV(Vector< String > *aDataPtr)
virtual void putScalarColumnStringV(const Vector< String > *aDataPtr)
virtual void putIntV(uInt aRowNr, const Int *aDataPtr)
void init()
Initialize part of the object.
unsigned char uChar
Definition: aipstype.h:44
virtual void addRow(uInt aNewNrRows, uInt anOldNrRows, Bool doInit)
Add (NewNrRows-OldNrRows) rows to the Column and initialize the new rows when needed.
virtual void getStringV(uInt aRowNr, String *aDataPtr)
virtual void getScalarColumnuShortV(Vector< uShort > *aDataPtr)
uInt getExternalSizeBits() const
Get the size of the dataType in bits!!
Definition: SSMColumn.h:301
char * getDataPtr()
Get the pointer to the cache.
Definition: SSMColumn.h:306
SSMColumn(SSMBase *aParent, int aDataType, uInt aColNr)
Create a SSMColumn object with the given parent.
void getValue(uInt aRowNr)
Fill the cache with data of the bucket containing the given row.
char Char
Definition: aipstype.h:43
virtual void getScalarColumnShortV(Vector< Short > *aDataPtr)
uInt itsNrElem
Number of elements in a value for this column.
Definition: SSMColumn.h:265
virtual void putdoubleV(uInt aRowNr, const double *aDataPtr)
void putColumnValue(const void *anArray, uInt aNrRows)
Put the values from the array in the entire column.
void setColNr(uInt aColNr)
set the sequence number of this column.
Definition: SSMColumn.h:319
Base class of the Standard Storage Manager.
Definition: SSMBase.h:158
uInt itsMaxLen
The maximum length of a &#39;fixed length&#39; string.
Definition: SSMColumn.h:263
virtual void putDComplexV(uInt aRowNr, const DComplex *aDataPtr)
void putValueShortString(uInt aRowNr, const void *aValue, const String &string)
Put the given string for the row into the correct data bucket.
virtual void doCreate(uInt aNrRows)
Let the object initialize itself for a newly created table.
virtual void getScalarColumnComplexV(Vector< Complex > *aDataPtr)
virtual void setShapeColumn(const IPosition &aShape)
Set the shape of an array in the column.
virtual void getScalarColumnDComplexV(Vector< DComplex > *aDataPtr)
virtual uInt ndim(uInt aRowNr)
Get the dimensionality of the item in the given row.
void removeColumn()
If something special has to be done before removing the Column, as is the case with Strings...
virtual void getfloatV(uInt aRowNr, float *aDataPtr)
short Short
Definition: aipstype.h:45
virtual void getuShortV(uInt aRowNr, uShort *aDataPtr)
virtual void getFile(uInt aNrRows)
Let the column object initialize itself for an existing table.
virtual void getScalarColumnuIntV(Vector< uInt > *aDataPtr)
Conversion::ValueFunction * itsWriteFunc
Pointer to a convert function for writing.
Definition: SSMColumn.h:275
virtual void getScalarColumnuCharV(Vector< uChar > *aDataPtr)
virtual void getScalarColumnBoolV(Vector< Bool > *aDataPtr)
Get the scalar values of the entire column.
virtual void getScalarColumndoubleV(Vector< double > *aDataPtr)
virtual void getuIntV(uInt aRowNr, uInt *aDataPtr)
virtual void putfloatV(uInt aRowNr, const float *aDataPtr)
virtual void getuCharV(uInt aRowNr, uChar *aDataPtr)
virtual IPosition shape(uInt aRowNr)
Get the shape of the array in the given row.
void putValue(uInt aRowNr, const void *aValue)
Put the given value for the row into the correct data bucket.
void shiftRows(char *aValue, uInt rowNr, uInt startRow, uInt endRow)
Shift the rows in the bucket one to the left when removing the given row.
uInt getColNr()
get the sequence number of this column.
Definition: SSMColumn.h:314
SSMColumn & operator=(const SSMColumn &)
Forbid assignment.
uInt itsNrCopy
Number of values to be copied.
Definition: SSMColumn.h:269
virtual void getShortV(uInt aRowNr, Short *aDataPtr)
virtual void getScalarColumnIntV(Vector< Int > *aDataPtr)
uInt itsColNr
Column sequence number of this column.
Definition: SSMColumn.h:259
virtual void putScalarColumnIntV(const Vector< Int > *aDataPtr)
virtual void setMaxLength(uInt maxLength)
Set the maximum length of a &#39;fixed length&#39; string.
virtual void putScalarColumnuCharV(const Vector< uChar > *aDataPtr)
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:39
virtual void putuCharV(uInt aRowNr, const uChar *aDataPtr)
virtual void putScalarColumnDComplexV(const Vector< DComplex > *aDataPtr)
virtual void putScalarColumnuIntV(const Vector< uInt > *aDataPtr)
virtual void putScalarColumnfloatV(const Vector< float > *aDataPtr)
A Column in the Standard Storage Manager.
Definition: SSMColumn.h:99
virtual void putScalarColumndoubleV(const Vector< double > *aDataPtr)
virtual void getBoolV(uInt aRowNr, Bool *aDataPtr)
Get the scalar value in the given row.
virtual void putScalarColumnuShortV(const Vector< uShort > *aDataPtr)
virtual void putuIntV(uInt aRowNr, const uInt *aDataPtr)
virtual void deleteRow(uInt aRowNr)
Remove the given row from the data bucket and possibly string bucket.
IPosition itsShape
The shape of the column.
Definition: SSMColumn.h:261
void * itsData
The data in local format.
Definition: SSMColumn.h:273
Conversion::ValueFunction * itsReadFunc
Pointer to a convert function for reading.
Definition: SSMColumn.h:277
virtual void putScalarColumnShortV(const Vector< Short > *aDataPtr)
virtual void getScalarColumnfloatV(Vector< float > *aDataPtr)
uInt itsExternalSizeBytes
Length of column cell value in storage format (0 = variable length).
Definition: SSMColumn.h:256
virtual void putBoolV(uInt aRowNr, const Bool *aDataPtr)
Put the scalar value in the given row.
virtual void putShortV(uInt aRowNr, const Short *aDataPtr)
void getColumnValue(void *anArray, uInt aNrRows)
Get the values for the entire column.
uInt getRowsPerBucket(uInt aColumn) const
Get rows per bucket for the given column.
virtual void putScalarColumnComplexV(const Vector< Complex > *aDataPtr)
String: the storage and methods of handling collections of characters.
Definition: String.h:223
virtual void putComplexV(uInt aRowNr, const Complex *aDataPtr)
virtual void getdoubleV(uInt aRowNr, double *aDataPtr)
Base table column storage manager class.
Definition: StManColumn.h:102
virtual void putScalarColumnBoolV(const Vector< Bool > *aDataPtr)
Put the scalar values of the entire column.
virtual void getDComplexV(uInt aRowNr, DComplex *aDataPtr)
void resync(uInt aNrRow)
Resync the storage manager with the new file contents.
virtual void putuShortV(uInt aRowNr, const uShort *aDataPtr)
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:48
size_t ValueFunction(void *to, const void *from, size_t nvalues)
Define the signature of a function converting nvalues values from internal to external format or vice...
Definition: Conversion.h:100
SSMBase * itsSSMPtr
Pointer to the parent storage manager.
Definition: SSMColumn.h:254
unsigned short uShort
Definition: aipstype.h:46
virtual void getComplexV(uInt aRowNr, Complex *aDataPtr)