casacore
Loading...
Searching...
No Matches
BitFlagsEngine.h
Go to the documentation of this file.
1//# BitFlagsEngine.h: Templated virtual column engine to map bit flags to a Bool
2//# Copyright (C) 2009
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_BITFLAGSENGINE_H
29#define TABLES_BITFLAGSENGINE_H
30
31//# Includes
32#include <casacore/casa/aips.h>
33#include <casacore/tables/DataMan/BaseMappedArrayEngine.h>
34
35namespace casacore { //# NAMESPACE CASACORE - BEGIN
36
37
38 // <summary> Non-templated Helper class to handle the mask. </summary>
39 // <use visibility=local>
40 class BFEngineMask
41 {
42 public:
43 // Form the mask as given.
44 explicit BFEngineMask (uInt mask=0xffffffff);
46 // Form the mask from the given keywords defining the bits.
47 BFEngineMask (const Array<String>& keys, uInt defaultMask);
48
49 // Make the mask from the given keywords defining the bits.
50 void makeMask (const TableColumn& column);
51
52 // Form the read mask from the specification.
53 // If keywords are given, the mask is formed from them.
54 void fromRecord (const RecordInterface& spec, const TableColumn& column,
55 const String& prefix);
56
57 // Store the info in a Record.
58 void toRecord (RecordInterface& spec, const String& prefix) const;
59
60 // Get the mask.
61 uInt getMask() const
62 { return itsMask; }
63
64 // Get the mask keywords.
65 const Array<String>& getKeys() const
66 { return itsMaskKeys; }
67
68 private:
71 };
72
73
74 // <summary>
75 // Templated virtual column engine to map bit flags to a Bool.
76 // </summary>
77
78 // <use visibility=export>
79
80 // <reviewed reviewer="Gareth Hunt" date="94Nov17" tests="">
81 // </reviewed>
82
83 // <prerequisite>
84 //# Classes you should understand before using this one.
85 // <li> VirtualColumnEngine
86 // <li> VirtualArrayColumn
87 // </prerequisite>
88
89 // <synopsis>
90 // BitFlagsEngine is a virtual column engine which maps an integer column
91 // containing flag bits to a Bool column. It can be used in a MeasurementSet
92 // to have multiple flag categories, yet use all existing software that
93 // deals with the Bool FLAG column.
94 //
95 // The engine support read as well as write access.
96 // For both cases a mask can be defined telling which bits have to be taken
97 // into account. For example, when writing to the Bool FLAG column, the data
98 // in the bitflags column twill be or-ed with the bits as defined in the
99 // writemask. Similary when reading FLAG, only the bits of the readmask are
100 // taken into account.
101 //
102 // The masks can be defined in two ways:
103 // <ul>
104 // <li> The mask can be given directly as an integer value.
105 // The default write mask is 1 (thus only bit 0), while the default
106 // read mask is all bits.
107 // <li> Symbolic names for mask bits can be defined as keywords in the
108 // flagbits column. They define the bit value, not the bit number.
109 // It makes it possible to combine bits in a keyword.
110 // The keywords are stored in a subrecord of keyword FLAGSETS.
111 // Example of keyword and their values could be:
112 // <br>RFI=1, CAL=2, CLIP=4, OTHER=8, RFICAL=3
113 // <br>Note that in this example RFICAL is defined such that it
114 // contains RFI and CAL.
115 // </ul>
116 // A mask can be set at construction time, but it can be changed at runtime
117 // using the <src>setProperties</src> function.
118 // The masks are kept in special keywords (which are different from the
119 // keywords defining the flag bits), so it is possible to change a mask
120 // by changing those keywords before opening a table. However, that is
121 // not recommended.
122 //
123 // BitFlagsEngine is known to the table system for data types uChar, Short,
124 // and Int.
125 // </synopsis>
126
127 // <motivation>
128 // The FLAG_CATEGORY defined the Measurement does not work because adding
129 // an extra flag means resizing the entire array which is slow.
130 // This class makes it possible to use an integer column to store flags
131 // and map it directly to a Bool column.
132 // </motivation>
133
134 // <example>
135 // <srcblock>
136 // // Create the table description and 2 columns with indirect arrays in it.
137 // // The Int column will be stored, while the Bool will be used as virtual.
138 // TableDesc tableDesc ("", TableDesc::Scratch);
139 // tableDesc.addColumn (ArrayColumnDesc<Int> ("BitBlags"));
140 // tableDesc.addColumn (ArrayColumnDesc<Bool> ("FLAG"));
141 //
142 // // Create a new table using the table description.
143 // SetupNewTable newtab (tableDesc, "tab.data", Table::New);
144 //
145 // // Create the engine and bind the FLAG column to it.
146 // BitFlagsEngine<Int> flagsEngine("FLAG", "BitFlags");
147 // newtab.bindColumn ("FLAG", flagsEngine);
148 // // Create the table.
149 // Table table (newtab);
150 //
151 // // Store a 3-D array (with dim. 2,3,4) into each row of the column.
152 // // The shape of each array in the column is implicitly set by the put
153 // // function. This will also set the shape of the underlying Int array.
154 // ArrayColumn data (table, "virtualArray");
155 // Array<Bool> someArray(IPosition(4,2,3,4));
156 // someArray = True;
157 // for (rownr_t i=0, i<10; i++) { // table will have 10 rows
158 // table.addRow();
159 // data.put (i, someArray)
160 // }
161 // </srcblock>
162 // The underlying integer array will be stored according to the writemask
163 // which defaults to 1.
164 // </example>
165
166 // <templating arg=StoredType>
167 // <li> only suited for built-in integer data types
168 // </templating>
169
170 template<typename StoredType> class BitFlagsEngine : public BaseMappedArrayEngine<Bool, StoredType>
171 {
172 //# Make members of parent class known.
173 public:
175 protected:
176 using BaseMappedArrayEngine<Bool,StoredType>::storedName;
177 using BaseMappedArrayEngine<Bool,StoredType>::table;
178 using BaseMappedArrayEngine<Bool,StoredType>::column;
179 using BaseMappedArrayEngine<Bool,StoredType>::setNames;
180
181 public:
182 // Construct an engine to map integer arrays in a column to Bool arrays.
183 // StoredColumnName is the name of the column where the integer
184 // data will be put and must have data type StoredType.
185 // The virtual column using this engine must have data type Bool.
186 // <br>A mask can be given that specifies which bits to use in the mapping
187 // from StoredType to Bool. Similarly a mask can be given defining which
188 // bits to set when mapping from Bool to StoredType.
189 BitFlagsEngine (const String& virtualColumnName,
190 const String& storedColumnName,
191 StoredType readMask=StoredType(0xffffffff),
192 StoredType writeMask=1);
193
194 // Construct an engine to map integer arrays in a column to Bool arrays.
195 // StoredColumnName is the name of the column where the scaled
196 // data will be put and must have data type StoredType.
197 // The virtual column using this engine must have data type Bool.
198 // <br>A mask can be given that specifies which bits to use in the mapping
199 // from StoredType to Bool. Similarly a mask can be given defining which
200 // bits to set when mapping from Bool to StoredType.
201 // The masks are given using the values of keywords in the stored column.
202 // Each keyword should be an integer defining one or more bits and can be
203 // seen as a symbolic name. The keyword values are or-ed to form the mask.
204 // The keywords are stored in a subrecord of keyword FLAGSETS.
205 BitFlagsEngine (const String& virtualColumnName,
206 const String& storedColumnName,
207 const Array<String>& readMaskKeys,
208 const Array<String>& writeMaskKeys);
209
210 // Construct from a record specification as created by dataManagerSpec().
211 BitFlagsEngine (const Record& spec);
212
213 // Destructor is mandatory.
215
216 // Return the type name of the engine (i.e. its class name).
217 virtual String dataManagerType() const;
218
219 // Get the name given to the engine (is the virtual column name).
220 virtual String dataManagerName() const;
221
222 // Record a record containing data manager specifications.
223 virtual Record dataManagerSpec() const;
224
225 // Get data manager properties that can be modified.
226 // These are ReadMask, WriteMask, ReadMaskKeys, and WriteMaskKeys.
227 // It is a subset of the data manager specification.
228 virtual Record getProperties() const;
229
230 // Modify data manager properties.
231 // These are ReadMask, WriteMask, ReadMaskKeys, and/or WriteMaskKeys.
232 // Mask keys should be given as an array of strings giving the keyword
233 // names defining mask bits (similar to the constructor). Mask keys are
234 // only used if not empty.
235 virtual void setProperties (const Record& spec);
236
237 // Return the name of the class.
238 // This includes the names of the template arguments.
240
241 // Register the class name and the static makeObject "constructor".
242 // This will make the engine known to the table system.
243 // The automatically invoked registration function in DataManReg.cc
244 // contains BitFlagsEngine<Int>.
245 // Any other instantiation of this class must be registered "manually"
246 // (or added to DataManReg.cc).
247 static void registerClass();
248
249 private:
250 // Copy constructor is only used by clone().
251 // (so it is made private).
253
254 // Assignment is not needed and therefore forbidden
255 // (so it is made private and not implemented).
257
258 // Clone the engine object.
260
261 // Initialize the object for a new table.
262 // It defines the keywords containing the engine parameters.
263 void create64 (rownr_t initialNrrow);
264
265 // Preparing consists of setting the writable switch and
266 // adding the initial number of rows in case of create.
267 // Furthermore it reads the keywords containing the engine parameters.
268 void prepare();
269
270 // Get an array in the given row.
271 // This will scale and offset from the underlying array.
273
274 // Put an array in the given row.
275 // This will scale and offset to the underlying array.
276 void putArray (rownr_t rownr, const Array<Bool>& array);
277
278 // Get a section of the array in the given row.
279 // This will scale and offset from the underlying array.
280 void getSlice (rownr_t rownr, const Slicer& slicer, Array<Bool>& array);
281
282 // Put into a section of the array in the given row.
283 // This will scale and offset to the underlying array.
284 void putSlice (rownr_t rownr, const Slicer& slicer,
285 const Array<Bool>& array);
286
287 // Get an entire column.
288 // This will scale and offset from the underlying array.
290
291 // Put an entire column.
292 // This will scale and offset to the underlying array.
294
295 // Get some array values in the column.
296 // This will scale and offset from the underlying array.
297 virtual void getArrayColumnCells (const RefRows& rownrs,
298 Array<Bool>& data);
299
300 // Put some array values in the column.
301 // This will scale and offset to the underlying array.
302 virtual void putArrayColumnCells (const RefRows& rownrs,
303 const Array<Bool>& data);
304
305 // Get a section of all arrays in the column.
306 // This will scale and offset from the underlying array.
307 void getColumnSlice (const Slicer& slicer, Array<Bool>& array);
308
309 // Put a section of all arrays in the column.
310 // This will scale and offset to the underlying array.
311 void putColumnSlice (const Slicer& slicer, const Array<Bool>& array);
312
313 // Get a section of some arrays in the column.
314 // This will scale and offset from the underlying array.
315 virtual void getColumnSliceCells (const RefRows& rownrs,
316 const Slicer& slicer,
317 Array<Bool>& data);
318
319 // Put into a section of some arrays in the column.
320 // This will scale and offset to the underlying array.
321 virtual void putColumnSliceCells (const RefRows& rownrs,
322 const Slicer& slicer,
323 const Array<Bool>& data);
324
325 // Map bit flags array to Bool array.
326 // This is meant when reading an array from the stored column.
328 const Array<StoredType>& stored);
329
330 // Map Bool array to bit flags array.
331 // This is meant when writing an array into the stored column.
333 Array<StoredType>& stored);
334
335 // Functor to and an array and mask and convert to Bool.
337 {
338 explicit FlagsToBool(StoredType readMask) : itsMask(readMask) {}
339 Bool operator() (StoredType value) const
340 { return (value & itsMask) != 0; }
341 private:
342 StoredType itsMask;
343 };
344 // Functor to convert Bools to flags using a mask.
345 // By default only bit 0 is set.
346 // Flag bits not affected are kept.
348 {
349 explicit BoolToFlags(StoredType writeMask) : itsMask(writeMask) {}
350 StoredType operator() (Bool flag, StoredType value) const
351 { return (flag ? value&itsMask : value); }
352 private:
353 StoredType itsMask;
354 };
355
356 public:
357 // Define the "constructor" to construct this engine when a
358 // table is read back.
359 // This "constructor" has to be registered by the user of the engine.
360 // If the engine is commonly used, its registration can be added
361 // to the registerAllCtor function in DataManReg.cc.
362 // That function gets automatically invoked by the table system.
364 const Record& spec);
365
366 private:
369 StoredType itsReadMask;
370 StoredType itsWriteMask;
371 Bool itsIsNew; //# True = new table
372 };
373
374
375} //# NAMESPACE CASACORE - END
376
377#ifndef CASACORE_NO_AUTO_TEMPLATES
378#include <casacore/tables/DataMan/BitFlagsEngine.tcc>
379#endif //# CASACORE_NO_AUTO_TEMPLATES
380#endif
BFEngineMask(const Array< String > &keys, uInt defaultMask)
Form the mask from the given keywords defining the bits.
BFEngineMask(uInt mask=0xffffffff)
Form the mask as given.
void toRecord(RecordInterface &spec, const String &prefix) const
Store the info in a Record.
uInt getMask() const
Get the mask.
const Array< String > & getKeys() const
Get the mask keywords.
Array< String > itsMaskKeys
void makeMask(const TableColumn &column)
Make the mask from the given keywords defining the bits.
void fromRecord(const RecordInterface &spec, const TableColumn &column, const String &prefix)
Form the read mask from the specification.
ArrayColumn< StoredType > & column()
Give access to the stored column.
void setNames(const String &virtualName, const String &storedName)
Set the virtual and stored column name.
const String & storedName() const
Get the stored column name.
const String & virtualName() const
Get the virtual column name.
Templated virtual column engine to map bit flags to a Bool.
void mapOnGet(Array< Bool > &array, const Array< StoredType > &stored)
Map bit flags array to Bool array.
virtual void getArrayColumnCells(const RefRows &rownrs, Array< Bool > &data)
Get some array values in the column.
BitFlagsEngine(const BitFlagsEngine< StoredType > &)
Copy constructor is only used by clone().
void putArrayColumn(const Array< Bool > &array)
Put an entire column.
void putArray(rownr_t rownr, const Array< Bool > &array)
Put an array in the given row.
BitFlagsEngine(const String &virtualColumnName, const String &storedColumnName, StoredType readMask=StoredType(0xffffffff), StoredType writeMask=1)
Construct an engine to map integer arrays in a column to Bool arrays.
virtual Record getProperties() const
Get data manager properties that can be modified.
void putColumnSlice(const Slicer &slicer, const Array< Bool > &array)
Put a section of all arrays in the column.
void getColumnSlice(const Slicer &slicer, Array< Bool > &array)
Get a section of all arrays in the column.
void mapOnPut(const Array< Bool > &array, Array< StoredType > &stored)
Map Bool array to bit flags array.
static void registerClass()
Register the class name and the static makeObject "constructor".
virtual String dataManagerName() const
Get the name given to the engine (is the virtual column name).
void create64(rownr_t initialNrrow)
Initialize the object for a new table.
void getSlice(rownr_t rownr, const Slicer &slicer, Array< Bool > &array)
Get a section of the array in the given row.
void getArray(rownr_t rownr, Array< Bool > &array)
Get an array in the given row.
virtual void putArrayColumnCells(const RefRows &rownrs, const Array< Bool > &data)
Put some array values in the column.
void putSlice(rownr_t rownr, const Slicer &slicer, const Array< Bool > &array)
Put into a section of the array in the given row.
~BitFlagsEngine()
Destructor is mandatory.
virtual void setProperties(const Record &spec)
Modify data manager properties.
virtual void putColumnSliceCells(const RefRows &rownrs, const Slicer &slicer, const Array< Bool > &data)
Put into a section of some arrays in the column.
BitFlagsEngine(const Record &spec)
Construct from a record specification as created by dataManagerSpec().
virtual Record dataManagerSpec() const
Record a record containing data manager specifications.
DataManager * clone() const
Clone the engine object.
virtual void getColumnSliceCells(const RefRows &rownrs, const Slicer &slicer, Array< Bool > &data)
Get a section of some arrays in the column.
BitFlagsEngine< StoredType > & operator=(const BitFlagsEngine< StoredType > &)
Assignment is not needed and therefore forbidden (so it is made private and not implemented).
static String className()
Return the name of the class.
void getArrayColumn(Array< Bool > &array)
Get an entire column.
static DataManager * makeObject(const String &dataManagerType, const Record &spec)
Define the "constructor" to construct this engine when a table is read back.
virtual String dataManagerType() const
Return the type name of the engine (i.e.
BitFlagsEngine(const String &virtualColumnName, const String &storedColumnName, const Array< String > &readMaskKeys, const Array< String > &writeMaskKeys)
Construct an engine to map integer arrays in a column to Bool arrays.
void prepare()
Preparing consists of setting the writable switch and adding the initial number of rows in case of cr...
Abstract base class for a data manager.
Table & table() const
Get the table this object is associated with.
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 int uInt
Definition aipstype.h:51
TableExprNode array(const TableExprNode &values, const TableExprNodeSet &shape)
Create an array of the given shape and fill it with the values.
Definition ExprNode.h:1929
LatticeExprNode mask(const LatticeExprNode &expr)
This function returns the mask of the given expression.
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:42
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
uInt64 rownr_t
Define the type of a row number in a table.
Definition aipsxtype.h:46
Functor to convert Bools to flags using a mask.
StoredType operator()(Bool flag, StoredType value) const
Functor to and an array and mask and convert to Bool.
Bool operator()(StoredType value) const