casacore
SSMStringHandler.h
Go to the documentation of this file.
1//# SSMStringHandler.h: Store strings 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_SSMSTRINGHANDLER_H
29#define TABLES_SSMSTRINGHANDLER_H
30
31
32//# Includes
33#include <casacore/casa/aips.h>
34#include <casacore/casa/OS/Conversion.h>
35#include <casacore/casa/BasicSL/String.h>
36#include <casacore/casa/Arrays/Array.h>
37
38namespace casacore { //# NAMESPACE CASACORE - BEGIN
39
40//# Forward Declarations.
41class SSMBase;
42
43
44// <summary>
45// Store strings in the Standard Storage Manager.
46// </summary>
47
48// <use visibility=local>
49
50// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tSSMStringHandler.cc">
51// </reviewed>
52
53// <prerequisite>
54//# Classes you should understand before using this one.
55// <li> <linkto class=SSMBase>SSMBase</linkto>
56// </prerequisite>
57
58// <etymology>
59// SSMStringHandler handles strings for the Standard Storage Manager.
60// </etymology>
61
62// <synopsis>
63// Variable length strings cannot be stored in the data bucket.
64// Only short (<8 characters) strings can be stored directly.
65// Class SSMStringhandler is used by the SSM to store strings in
66// so-called string buckets.
67// A string bucket has the following layout:
68// <ul>
69// <li> The first Int is reserved to be used for the free bucket list.
70// <li> <src>itsUsedLength</src> tells how many bytes have been used.
71// Thus it tells the next free byte in the string part.
72// In principle it always increases. Only if data are removed
73// from the last part of the string part, it is decreased, thus
74// the deleted part can be reused again.
75// <li> <src>itsNDeleted</src> tells how many bytes of the string part
76// are deleted (i.e. not used). Initially it is the length of the
77// string part of the bucket (i.e. bucketsize minus 4 Ints).
78// When a string is stored, its length is subtracted from itsNDeleted.
79// When a string is removed, its length is added again.
80// When the string part is deleted, the bucket is added to the
81// free bucket list.
82// <li> <src>itsNextBucket</src> tells the next bucket if the last
83// entry in the bucket is continued in another bucket.
84// Normally this field is -1 (meaning not continued), but long
85// strings or string arrays might be continued in another bucket
86// (and continued from there again).
87// <li> The string part is a sequence of bytes containing the string
88// data. When a value is to be stored, it will replace the current
89// value if the new value is not longer. Otherwise the current
90// value (if any) is deleted and the new value is appended to
91// the end of the string part in the last bucket used.
92// <p>
93// For a scalar string only its characters are stored. Its length
94// (and bucketnr and offset in string bucket) are stored in the data
95// bucket.
96// <br>
97// A fixed length array is stored as an array of bytes. That byte
98// array contains length-value pairs for each element of the array.
99// The total length (and bucketnr and offset) are stored in the data
100// bucket.
101// <br>
102// A variable length array is stored as the shape, a flag, optionally
103// followed by the string array as length-value pairs (as above).
104// The shape consists of the nr of dimensions followed by the
105// length of each dimension. The flag indicates if a string array
106// is actually stored. It is not if only the shape of the array
107// is set, but no data put yet.
108// </ul>
109// SSMStringHandler keeps a copy of the current bucket in use to reduce
110// the number of accesses to the bucket cache.
111// <p>
112// It also keeps the bucket number of the last bucket where data were
113// added to. It tells which bucket to use when new data has to be stored.
114// </synopsis>
115
116//# <todo asof="$DATE:$">
117//# A List of bugs, limitations, extensions or planned refinements.
118//# </todo>
119
121{
122public:
123 // Default constructor initializes last string bucket to -1.
125
127
128 // Set or get last string bucketnr.
129 // Setting is needed when an existing table is opened.
130 // <group>
132 Int lastStringBucket() const;
133 // </group>
134
135 // Put a single string or an array of strings into a bucket.
136 // If its length does not exceed the given length, it reuses
137 // the currently used space (given by bucketnr and offset).
138 // Otherwise it adds the data to the last string bucket.
139 // It fills the offset and bucketnr where the data are stored and the
140 // length occupied in the buckets.
141 // An array of strings is flattened first (a la SSMColumn::writeString).
142 // <br>
143 // If <src>handleShape</src> is True (for variable shaped arrays), the
144 // shape will be put first.
145 // <group>
146 void put (Int& bucketNr, Int& offset, Int& length,
147 const String& string);
148 void put (Int& bucketNr, Int& offset, Int& length,
149 const Array<String>& string, Bool handleShape);
150 // </group>
151
152 // Put a single string or an array of strings into a bucket.
153 // If its length does not exceed the given length, it reuses
154 // the currently used space (given by bucketnr and offset).
155 // Otherwise it adds the data to the last string bucket.
156 // It fills the offset and bucketnr where stored and the
157 // length occupied in the buckets.
158 void putShape (Int& bucketNr, Int& offset, Int& length,
159 const IPosition& aShape);
160
161 // Get the shape in the given bucket and offset.
162 // It sets the offset to the data right after the shape.
163 // The IPosition object is resized as needed.
164 void getShape (IPosition& aShape, Int bucket, Int& offset, Int length);
165
166 // Remove data with the given length from a bucket.
167 // If the data are continued in next bucket(s), they will be
168 // removed there as well.
169 void remove (Int bucketNr, Int offset, Int length);
170
171 // Get a string or an array of strings.
172 // The array must have the correct shape.
173 // <src>handleShape</src> will be True for variable shaped arrays
174 // indicating that the data are preceeded by the shape.
175 // <group>
176 void get (String& string, Int bucket, Int offset, Int length);
177 void get (Array<String>& string, Int bucket, Int offset,
178 Int length, Bool handleShape);
179 // </group>
180
181 // Flush the currently used string bucket.
182 void flush();
183
184 // Initialize the StringHandler
185 void init();
186
187 // Resynchronize (after a table lock was acquired).
188 // It clears the itsCurrentBucket variable to assure that buckets
189 // are reread.
190 void resync();
191
192private:
193 // Forbid copy constructor and assignment.
194 // <group>
197 // </group>
198
199 // Get the given bucket and make it current.
200 // It first writes the current bucket if it has changed.
201 // <br>
202 // If <src>isNew</src> is True the bucket is new,
203 // so the Ints at its beginning do not have to be interpreted.
204 void getBucket (uInt bucketNr, Bool isNew=False);
205
206 // Get a new bucket and make it current.
207 // If <src>doConcat</src> is True, the new bucket is a continuation,
208 // so <src>itsNextBucket</src> in the currently used bucket is filled
209 // with the new bucket number.
210 void getNewBucket (Bool doConcat);
211
212 // Put the data with the given length at the end of the current bucket.
213 // If they do not fit, they are continued in a new bucket.
214 void putData (Int length, const Char* data);
215
216 // Get the data with the given length from the curent bucket at the
217 // given offset. If sets the offset to the byte after the data read.
218 // Continuation buckets are followed (and made current).
219 void getData (Int length, Char* data, Int& offset);
220
221 // Replace the current data with the new data.
222 // It is used by <src>put</src> after having assured that the
223 // new length does not exceed the current one.
224 // It follows continuation buckets as needed.
225 // <group>
226 void replace (Int bucketNr, Int offset, Int length,
227 const String& string);
228 void replace (Int bucketNr, Int offset, Int length, Int totalLength,
229 const IPosition& aShape);
230 void replace (Int bucketNr, Int offset, Int length, Int totalLength,
231 const Array<String>& string, Bool handleShape);
232 void replaceData (Int& offset,Int length, const Char* data);
233 // </group>
234
235
236 SSMBase* itsSSMPtr; // Pointer to SSMBase stucture
237 Int itsCurrentBucket; // bucketnr of current string bucket (-1 is none)
238 Int itsLength; // length of bucket in use (only the string part)
239 Int itsNDeleted; // #bytes deleted from the string part of the bucket
240 Int itsUsedLength; // #bytes used from the string part of the bucket
241 Int itsNextBucket; // next bucket for long strings
242 char* itsData; // bucket string data
243 char* itsIntBuf; // buffer for initialisation params
244 Bool isChanged; // has current bucket been changed?
245 uInt itsIntSize; // size of integers in this system
246 Int itsLastBucket; // last string bucket used
247 uInt itsStart; // Start position of actual data in bucket
248};
249
250
251inline void SSMStringHandler::setLastStringBucket (Int lastStringBucket)
252{
254}
255
257{
258 return itsLastBucket;
259}
260
261
262
263} //# NAMESPACE CASACORE - END
264
265#endif
SSMStringHandler(SSMBase *aBase)
Default constructor initializes last string bucket to -1.
SSMStringHandler(const SSMStringHandler &)
Forbid copy constructor and assignment.
void get(String &string, Int bucket, Int offset, Int length)
Get a string or an array of strings.
void init()
Initialize the StringHandler.
void replaceData(Int &offset, Int length, const Char *data)
void setLastStringBucket(Int lastStringBucket)
Set or get last string bucketnr.
void remove(Int bucketNr, Int offset, Int length)
Remove data with the given length from a bucket.
void get(Array< String > &string, Int bucket, Int offset, Int length, Bool handleShape)
void getData(Int length, Char *data, Int &offset)
Get the data with the given length from the curent bucket at the given offset.
void replace(Int bucketNr, Int offset, Int length, Int totalLength, const Array< String > &string, Bool handleShape)
void resync()
Resynchronize (after a table lock was acquired).
void flush()
Flush the currently used string bucket.
void replace(Int bucketNr, Int offset, Int length, const String &string)
Replace the current data with the new data.
void replace(Int bucketNr, Int offset, Int length, Int totalLength, const IPosition &aShape)
void putData(Int length, const Char *data)
Put the data with the given length at the end of the current bucket.
void getNewBucket(Bool doConcat)
Get a new bucket and make it current.
void getBucket(uInt bucketNr, Bool isNew=False)
Get the given bucket and make it current.
void put(Int &bucketNr, Int &offset, Int &length, const String &string)
Put a single string or an array of strings into a bucket.
void getShape(IPosition &aShape, Int bucket, Int &offset, Int length)
Get the shape in the given bucket and offset.
SSMStringHandler & operator=(const SSMStringHandler &)
void putShape(Int &bucketNr, Int &offset, Int &length, const IPosition &aShape)
Put a single string or an array of strings into a bucket.
void put(Int &bucketNr, Int &offset, Int &length, const Array< String > &string, Bool handleShape)
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
const Bool False
Definition: aipstype.h:44
unsigned int uInt
Definition: aipstype.h:51
LatticeExprNode length(const LatticeExprNode &expr, const LatticeExprNode &axis)
2-argument function to get the length of an axis.
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
char Char
Definition: aipstype.h:46