/usr/include/wreport/varinfo.h is in libwreport-dev 2.1-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 | /*
* wreport/varinfo - Variable information
*
* Copyright (C) 2005--2011 ARPA-SIM <urpsim@smr.arpa.emr.it>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
*
* Author: Enrico Zini <enrico@enricozini.com>
*/
#ifndef WREPORT_VARINFO_H
#define WREPORT_VARINFO_H
#include <stdint.h>
#include <string>
namespace wreport {
/** @file
* @ingroup core
* Implement fast access to information about WMO variables.
*
* The measured value of a physical quantity has little meaning without
* specifying what quantity it represents, what units are used to measure it,
* and how many digits are significant for the value.
*
* This module provides access to all this metadata:
*
* \li \b wreport::Varcode represents what is the quantity measured, and takes
* values from the WMO B tables used for BUFR and CREX encodings.
* The ::WR_VAR macro can be used to construct wreport::Varcode values, and the
* ::WR_VAR_F, ::WR_VAR_X and ::WR_VAR_Y macros can be used to access the
* various parts of the dba_varcode.
* \li \b wreport::Varinfo contains all the expanded information about a variable:
* its wreport::Varcode, description, measurement units, significant digits,
* minimum and maximum values it can have and other information useful for
* serialisation and deserialisation of values.
*
* There are many B tables with slight differences used by different
* meteorological centre or equipment. This module allows to access
* different vartables using dba_vartable_create().
*
* wreport::Vartable and wreport::Varinfo have special memory management: they are never
* deallocated. This is a precise design choice to speed up passing and
* copying wreport::Varinfo values, that are used very intensely as they accompany
* all the physical values processed by DB-All.e and its components.
* This behaviour should not be a cause of memory leaks, since a software would
* only need to access a limited amount of B tables during its lifetime.
*
* To construct a wreport::Varcode value one needs to provide three numbers: F, X
* and Y.
*
* \li \b F (2 bits) identifies the type of table entry represented by the
* dba_varcode, and is always 0 for B tables. Different values are only used
* during encoding and decoding of BUFR and CREX messages and are not in use in
* other parts of DB-All.e.
* \li \b X (6 bits) identifies a section of the table.
* \li \b Y (8 bits) identifies the value within the section.
*
* The normal text representation of a wreport::Varcode for a WMO B table uses the
* format Bxxyyy.
*/
/**
* Holds the WMO variable code of a variable
*/
typedef short unsigned int Varcode;
/// Format a varcode into a string
std::string varcode_format(Varcode code);
/**
* Create a WMO variable code from its F, X and Y components.
*/
#define WR_VAR(f, x, y) ((wreport::Varcode)( ((unsigned)(f)<<14) | ((unsigned)(x)<<8) | (unsigned)(y) ))
/**
* Convert a XXYYY string to a WMO variable code.
*
* This is useful only in rare cases, such as when parsing tables; use
* descriptor_code() to parse proper entry names such as "B01003" or "D21301".
*/
#define WR_STRING_TO_VAR(str) ((wreport::Varcode)( \
(( ((str)[0] - '0')*10 + ((str)[1] - '0') ) << 8) | \
( ((str)[2] - '0')*100 + ((str)[3] - '0')*10 + ((str)[4] - '0') ) \
))
/**
* Get the F part of a WMO variable code.
*/
#define WR_VAR_F(code) (((code) >> 14) & 0x3)
/**
* Get the X part of a WMO variable code.
*/
#define WR_VAR_X(code) ((code) >> 8 & 0x3f)
/**
* Get the Y part of a WMO variable code.
*/
#define WR_VAR_Y(code) ((code) & 0xff)
/**
* Convert a FXXYYY string descriptor code into its short integer
* representation.
*
* @param desc
* The 6-byte string descriptor as FXXYYY
*
* @return
* The short integer code that can be queried with the WR_GET_* macros
*/
Varcode descriptor_code(const char* desc);
/**
* Describes how a wreport::Varinfo has been altered: it is used for supporting
* variables coming from BUFR and CREX messages that use C codes to alter
* variable information.
*/
typedef short unsigned int Alteration;
/**
* Varinfo flags
* @{
*/
#define VARINFO_FLAG_STRING 0x01 ///< Mark string variables
#define VARINFO_FLAG_BINARY 0x02 ///< Mark literal binary variables
/**@}*/
/**
* Holds the information about a DBALLE variable.
*
* It never needs to be deallocated, as all the Varinfo returned by DB-ALLe
* are pointers to memory-cached versions that are guaranteed to exist for all
* the lifetime of the program.
*/
struct _Varinfo
{
/** The variable code. See @ref WR_VAR, WR_VAR_X, WR_VAR_Y. */
Varcode var;
/** The variable description. */
char desc[64];
/** The measurement unit of the variable. */
char unit[24];
/** The scale of the variable. When the variable is represented as an
* integer, it is multiplied by 10**scale */
int scale;
/** The reference value for the variable. When the variable is represented
* as an integer, and after scaling, it is added this value */
int ref;
/** The length in digits of the integer representation of this variable
* (after scaling and changing reference value) */
unsigned len;
/** The reference value for bit-encoding. When the variable is encoded in
* a bit string, it is added this value */
int bit_ref;
/** The length in bits of the variable when encoded in a bit string (after
* scaling and changing reference value) */
unsigned bit_len;
/// Variable flags (see VARINFO_FLAG_* constants)
unsigned flags;
/** Minimum unscaled value the field can have */
int imin;
/** Maximum unscaled value the field can have */
int imax;
/** Minimum scaled value the field can have */
double dmin;
/** Maximum scaled value the field can have */
double dmax;
/** C-table alteration that has been applied to this entry (deprecated) */
Alteration alteration;
/** Other altered versions of this Varinfo */
mutable struct _Varinfo* alterations;
/** The measurement unit of the variable when encoded in BUFR. */
char bufr_unit[24];
/** The scale of the variable when encoded in BUFR. */
int bufr_scale;
/// Reference count
mutable int _ref;
_Varinfo();
/// Increment the reference count to this Data object
void do_ref() const { ++_ref; }
/**
* Decrement the reference count to this Data object, and return true
* if the reference count went down to 0
*/
bool do_unref() const { return (--_ref) == 0; }
/// Check if we are a string value
bool is_string() const
{
return (flags & VARINFO_FLAG_STRING) != 0;
}
/// Check if we are a binary value
bool is_binary() const
{
return (flags & VARINFO_FLAG_BINARY) != 0;
}
/**
* Encode a double value into an integer value using Varinfo decimal
* encoding informations (ref and scale)
*
* @param fval
* Value to encode
* @returns
* The double value encoded as an integer
*/
int encode_int(double fval) const throw ();
/**
* Encode a double value into an integer value using Varinfo binary encoding
* informations (bit_ref and bufr_scale)
*
* @param fval
* Value to encode
* @returns
* The double value encoded as an integer
*/
unsigned encode_bit_int(double fval) const;
/**
* Decode a double value from integer value using Varinfo encoding
* informations
*
* @param val
* Value to decode
* @returns
* The decoded double value
*/
double decode_int(int val) const throw ();
/**
* Decode a double value from integer value using Varinfo encoding
* informations for BUFR
*
* @param val
* Value to decode
* @returns
* The decoded double value
*/
double bufr_decode_int(uint32_t val) const throw ();
/**
* Set all fields to 0, except the reference count
*/
void reset();
/**
* Set the values all in one shot.
*
* It also calls compute_range
*/
void set(Varcode var, const char* desc, const char* unit, int scale = 0, int ref = 0, int len = 0, int bit_ref = 0, int bit_len = 0, int flags = 0, const char* bufr_unit = 0, int bufr_scale = 0);
/**
* Initialise the varinfo to represent a string variable
*
* @param var the variable code
* @param desc the variable description
* @param len the maximum string length
*/
void set_string(Varcode var, const char* desc, int len);
/**
* Compute the valid variable range and store it in the *min and *max
* fields
*/
void compute_range();
};
class Varinfo;
/// Smart pointer to handle/use varinfos
class MutableVarinfo
{
protected:
/// Varinfo structure to which the pointer refers
_Varinfo* m_impl;
public:
//@{
/// Create a smart pointer to the given variable information
MutableVarinfo(_Varinfo* impl) : m_impl(impl) { m_impl->do_ref(); }
MutableVarinfo(const MutableVarinfo& vi) : m_impl(vi.m_impl) { m_impl->do_ref(); }
//@}
~MutableVarinfo() { if (m_impl->do_unref()) delete m_impl; }
//@{
/// Standard smart pointer methods
MutableVarinfo& operator=(const MutableVarinfo& vi)
{
vi.m_impl->do_ref();
if (m_impl->do_unref()) delete m_impl;
m_impl = vi.m_impl;
return *this;
}
_Varinfo* operator->() { return m_impl; }
_Varinfo& operator*() { return *m_impl; }
//@}
/// Access the underlying _Varinfo structure
_Varinfo* impl() const { return m_impl; }
/**
* Create a single use varinfo structure.
*
* A single use varinfo structure is not memory managed by a vartable
* and needs to be deallocated explicitly when it is not needed
* anymore.
*
* The various fields of the resulting varinfo will be zeroed.
*/
static MutableVarinfo create_singleuse();
friend class wreport::Varinfo;
};
/// Smart pointer to handle/use varinfos
class Varinfo
{
protected:
/// Varinfo structure to which the pointer refers
const _Varinfo* m_impl;
public:
//@{
/// Create a smart pointer to the given variable information
Varinfo(const _Varinfo* impl) : m_impl(impl) { m_impl->do_ref(); }
Varinfo(const _Varinfo& impl) : m_impl(&impl) { m_impl->do_ref(); }
Varinfo(const Varinfo& vi) : m_impl(vi.m_impl) { m_impl->do_ref(); }
Varinfo(const MutableVarinfo& vi) : m_impl(vi.m_impl) { m_impl->do_ref(); }
//@}
~Varinfo() { if (m_impl->do_unref()) delete m_impl; }
//@{
/// Standard smart pointer methods
const Varinfo& operator=(const Varinfo& vi)
{
vi.m_impl->do_ref();
if (m_impl->do_unref()) delete m_impl;
m_impl = vi.m_impl;
return *this;
}
const _Varinfo& operator*() const { return *m_impl; }
const _Varinfo* operator->() const { return m_impl; }
//@}
/// Access the underlying _Varinfo structure
const _Varinfo* impl() const { return m_impl; }
};
}
#endif
/* vim:set ts=4 sw=4: */
|