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/StManColumnBase.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 StManColumnBase
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 (rownr_t aRowNr);
121 
122  // Get the shape of the array in the given row.
123  virtual IPosition shape (rownr_t 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 (rownr_t aNrRows);
128 
129  // Let the column object initialize itself for an existing table
130  virtual void getFile (rownr_t aNrRows);
131 
132  // Resync the storage manager with the new file contents.
133  // It resets the last rownr put.
134  void resync (rownr_t aNrRow);
135 
136  // Get the scalar value in the given row.
137  // <group>
138  virtual void getBool (rownr_t aRowNr, Bool* aDataPtr);
139  virtual void getuChar (rownr_t aRowNr, uChar* aDataPtr);
140  virtual void getShort (rownr_t aRowNr, Short* aDataPtr);
141  virtual void getuShort (rownr_t aRowNr, uShort* aDataPtr);
142  virtual void getInt (rownr_t aRowNr, Int* aDataPtr);
143  virtual void getuInt (rownr_t aRowNr, uInt* aDataPtr);
144  virtual void getInt64 (rownr_t aRowNr, Int64* aDataPtr);
145  virtual void getfloat (rownr_t aRowNr, float* aDataPtr);
146  virtual void getdouble (rownr_t aRowNr, double* aDataPtr);
147  virtual void getComplex (rownr_t aRowNr, Complex* aDataPtr);
148  virtual void getDComplex (rownr_t aRowNr, DComplex* aDataPtr);
149  virtual void getString (rownr_t aRowNr, String* aDataPtr);
150  // </group>
151 
152  // Put the scalar value in the given row.
153  // It updates the cache if the row is contained in the cache.
154  // <group>
155  virtual void putBool (rownr_t aRowNr, const Bool* aDataPtr);
156  virtual void putuChar (rownr_t aRowNr, const uChar* aDataPtr);
157  virtual void putShort (rownr_t aRowNr, const Short* aDataPtr);
158  virtual void putuShort (rownr_t aRowNr, const uShort* aDataPtr);
159  virtual void putInt (rownr_t aRowNr, const Int* aDataPtr);
160  virtual void putuInt (rownr_t aRowNr, const uInt* aDataPtr);
161  virtual void putInt64 (rownr_t aRowNr, const Int64* aDataPtr);
162  virtual void putfloat (rownr_t aRowNr, const float* aDataPtr);
163  virtual void putdouble (rownr_t aRowNr, const double* aDataPtr);
164  virtual void putComplex (rownr_t aRowNr, const Complex* aDataPtr);
165  virtual void putDComplex (rownr_t aRowNr, const DComplex* aDataPtr);
166  virtual void putString (rownr_t aRowNr, const String* aDataPtr);
167  // </group>
168 
169  // Get the scalar values of the entire column.
170  virtual void getScalarColumnV (ArrayBase& aDataPtr);
171 
172  // Put the scalar values of the entire column.
173  // It invalidates the cache.
174  virtual void putScalarColumnV (const ArrayBase& aDataPtr);
175 
176  // Add (NewNrRows-OldNrRows) rows to the Column and initialize
177  // the new rows when needed.
178  virtual void addRow (rownr_t aNewNrRows, rownr_t anOldNrRows, Bool doInit);
179 
180  // Remove the given row from the data bucket and possibly string bucket.
181  // If needed, it also removes it from the cache.
182  virtual void deleteRow (rownr_t aRowNr);
183 
184  // Get the size of the dataType in bytes!!
185  uInt getExternalSizeBytes() const;
186 
187  // Get the size of the dataType in bits!!
188  uInt getExternalSizeBits() const;
189 
190  // get the sequence number of this column.
191  uInt getColNr();
192 
193  // set the sequence number of this column.
194  void setColNr (uInt aColNr);
195 
196  // If something special has to be done before removing the Column,
197  // as is the case with Strings, it can be done here.
198  void removeColumn();
199 
200 protected:
201  // Shift the rows in the bucket one to the left when removing the given row.
202  void shiftRows (char* aValue, rownr_t rowNr, rownr_t startRow, rownr_t endRow);
203 
204  // Fill the cache with data of the bucket containing the given row.
205  void getValue (rownr_t aRowNr);
206 
207  // Get the bucketnr, offset, and length of a variable length string.
208  // <src>data</src> must have 3 Ints to hold the values.
209  // It returns a pointer to the data in the bucket, which can be used
210  // for the case that the data bucket contains the (short) string.
211  Char* getRowValue (Int* data, rownr_t aRowNr);
212 
213  // Put the given value for the row into the correct data bucket.
214  void putValue (rownr_t aRowNr, const void* aValue);
215 
216  // Put the given string for the row into the correct data bucket.
217  // The argument <src>aValue></src> must be 3 Ints (for bucketnr, offset,
218  // and length). Only the length is actually used.
219  void putValueShortString (rownr_t aRowNr, const void* aValue,
220  const String& string);
221 
222  // Get the values for the entire column.
223  // The data from all buckets is copied to the array.
224  void getColumnValue (void* anArray, rownr_t aNrRows);
225 
226  // Put the values from the array in the entire column.
227  // Each data bucket is filled with the the appropriate part of the array.
228  void putColumnValue (const void* anArray, rownr_t aNrRows);
229 
230 
231  // Pointer to the parent storage manager.
233  // Length of column cell value in storage format (0 = variable length).
236  // Column sequence number of this column.
238  // The shape of the column.
240  // The maximum length of a 'fixed length' string.
242  // Number of elements in a value for this column.
244  // Number of values to be copied.
245  // Normally this is itsNrElem, but for complex types it is 2*itsNrElem.
246  // When local format is used, it is the number of bytes.
248  // The sizeof the datatype in local format
250  // The data in local format.
251  void* itsData;
252  // Pointer to a convert function for writing.
254  // Pointer to a convert function for reading.
256 
257 private:
258  // Forbid copy constructor.
260 
261  // Forbid assignment.
263 
264  // Initialize part of the object.
265  // It determines the nr of elements, the function to use to convert
266  // from local to file format, etc..
267  void init();
268 
269  // Get the pointer to the cache. It is created if not done yet.
270  char* getDataPtr();
271 };
272 
273 
275 {
276  return itsExternalSizeBytes;
277 }
278 
280 {
281  return itsExternalSizeBits;
282 }
283 
284 inline char* SSMColumn::getDataPtr()
285 {
286  if (itsData == 0) {
288  }
289  return static_cast<char*>(itsData);
290 }
291 
293 {
294  return itsColNr;
295 }
296 
297 inline void SSMColumn::setColNr (uInt aColNr)
298 {
299  itsColNr = aColNr;
300 }
301 
302 
303 
304 } //# NAMESPACE CASACORE - END
305 
306 #endif
Non-templated base class for templated Array class.
Definition: ArrayBase.h:73
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
uInt getRowsPerBucket(uInt aColumn) const
Get rows per bucket for the given column.
uInt itsLocalSize
The sizeof the datatype in local format.
Definition: SSMColumn.h:249
uInt getExternalSizeBytes() const
Get the size of the dataType in bytes!!
Definition: SSMColumn.h:274
uInt itsExternalSizeBytes
Length of column cell value in storage format (0 = variable length).
Definition: SSMColumn.h:234
virtual uInt ndim(rownr_t aRowNr)
Get the dimensionality of the item in the given row.
uInt itsNrCopy
Number of values to be copied.
Definition: SSMColumn.h:247
SSMBase * itsSSMPtr
Pointer to the parent storage manager.
Definition: SSMColumn.h:232
virtual void getShort(rownr_t aRowNr, Short *aDataPtr)
virtual void putInt64(rownr_t aRowNr, const Int64 *aDataPtr)
virtual void deleteRow(rownr_t aRowNr)
Remove the given row from the data bucket and possibly string bucket.
virtual void getFile(rownr_t aNrRows)
Let the column object initialize itself for an existing table.
void removeColumn()
If something special has to be done before removing the Column, as is the case with Strings,...
SSMColumn(SSMBase *aParent, int aDataType, uInt aColNr)
Create a SSMColumn object with the given parent.
virtual void putScalarColumnV(const ArrayBase &aDataPtr)
Put the scalar values of the entire column.
virtual void putdouble(rownr_t aRowNr, const double *aDataPtr)
char * getDataPtr()
Get the pointer to the cache.
Definition: SSMColumn.h:284
virtual void putDComplex(rownr_t aRowNr, const DComplex *aDataPtr)
Char * getRowValue(Int *data, rownr_t aRowNr)
Get the bucketnr, offset, and length of a variable length string.
uInt itsColNr
Column sequence number of this column.
Definition: SSMColumn.h:237
void init()
Initialize part of the object.
virtual void putBool(rownr_t aRowNr, const Bool *aDataPtr)
Put the scalar value in the given row.
virtual void getBool(rownr_t aRowNr, Bool *aDataPtr)
Get the scalar value in the given row.
uInt getColNr()
get the sequence number of this column.
Definition: SSMColumn.h:292
virtual void putInt(rownr_t aRowNr, const Int *aDataPtr)
virtual void getDComplex(rownr_t aRowNr, DComplex *aDataPtr)
virtual void setMaxLength(uInt maxLength)
Set the maximum length of a 'fixed length' string.
void * itsData
The data in local format.
Definition: SSMColumn.h:251
virtual void setShapeColumn(const IPosition &aShape)
Set the shape of an array in the column.
void putValue(rownr_t aRowNr, const void *aValue)
Put the given value for the row into the correct data bucket.
virtual void putfloat(rownr_t aRowNr, const float *aDataPtr)
virtual void putuShort(rownr_t aRowNr, const uShort *aDataPtr)
void getValue(rownr_t aRowNr)
Fill the cache with data of the bucket containing the given row.
virtual void getInt64(rownr_t aRowNr, Int64 *aDataPtr)
virtual void getuInt(rownr_t aRowNr, uInt *aDataPtr)
uInt itsMaxLen
The maximum length of a 'fixed length' string.
Definition: SSMColumn.h:241
Conversion::ValueFunction * itsWriteFunc
Pointer to a convert function for writing.
Definition: SSMColumn.h:253
virtual void putString(rownr_t aRowNr, const String *aDataPtr)
IPosition itsShape
The shape of the column.
Definition: SSMColumn.h:239
void shiftRows(char *aValue, rownr_t rowNr, rownr_t startRow, rownr_t endRow)
Shift the rows in the bucket one to the left when removing the given row.
uInt itsNrElem
Number of elements in a value for this column.
Definition: SSMColumn.h:243
virtual void putComplex(rownr_t aRowNr, const Complex *aDataPtr)
virtual void getComplex(rownr_t aRowNr, Complex *aDataPtr)
virtual void getInt(rownr_t aRowNr, Int *aDataPtr)
SSMColumn(const SSMColumn &)
Forbid copy constructor.
void putValueShortString(rownr_t aRowNr, const void *aValue, const String &string)
Put the given string for the row into the correct data bucket.
Conversion::ValueFunction * itsReadFunc
Pointer to a convert function for reading.
Definition: SSMColumn.h:255
virtual void getString(rownr_t aRowNr, String *aDataPtr)
virtual void putuInt(rownr_t aRowNr, const uInt *aDataPtr)
virtual void getdouble(rownr_t aRowNr, double *aDataPtr)
virtual void getfloat(rownr_t aRowNr, float *aDataPtr)
virtual void getuShort(rownr_t aRowNr, uShort *aDataPtr)
virtual void addRow(rownr_t aNewNrRows, rownr_t anOldNrRows, Bool doInit)
Add (NewNrRows-OldNrRows) rows to the Column and initialize the new rows when needed.
virtual void getuChar(rownr_t aRowNr, uChar *aDataPtr)
void resync(rownr_t aNrRow)
Resync the storage manager with the new file contents.
virtual void putShort(rownr_t aRowNr, const Short *aDataPtr)
virtual void getScalarColumnV(ArrayBase &aDataPtr)
Get the scalar values of the entire column.
virtual void putuChar(rownr_t aRowNr, const uChar *aDataPtr)
SSMColumn & operator=(const SSMColumn &)
Forbid assignment.
virtual void doCreate(rownr_t aNrRows)
Let the object initialize itself for a newly created table.
void putColumnValue(const void *anArray, rownr_t 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:297
virtual IPosition shape(rownr_t aRowNr)
Get the shape of the array in the given row.
void getColumnValue(void *anArray, rownr_t aNrRows)
Get the values for the entire column.
uInt getExternalSizeBits() const
Get the size of the dataType in bits!!
Definition: SSMColumn.h:279
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
unsigned char uChar
Definition: aipstype.h:47
short Short
Definition: aipstype.h:48
unsigned int uInt
Definition: aipstype.h:51
unsigned short uShort
Definition: aipstype.h:49
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
uInt64 rownr_t
Define the type of a row number in a table.
Definition: aipsxtype.h:46
char Char
Definition: aipstype.h:46