Describe how the contents of a PackedContainer are to be saved. More...

#include <PackedParameters.h>

Collaboration diagram for SG::PackedParameters:

Public Types
enum	{ FLAG_IS_SIGNED = (1<<0) , FLAG_IS_FLOAT = (1<<1) , FLAG_HAS_SCALE = (1<<2) , FLAG_ROUNDING = (1<<3) }
	Define bit assignments for the flags field. More...

Public Member Functions
	PackedParameters ()
	Default constructor.
	PackedParameters (uint8_t nbits, uint8_t flags)
	Constructor from nbits and flags.
template<class T>
	PackedParameters (T)
	Initialize with default packing parameters for type `T`.
uint8_t	nbits () const
	The number of bits used to store each element.
uint8_t	nmantissa () const
	The number of bits used for the mantissa portion of a float-point representation, excluding a sign bit (if any).
uint8_t	flags () const
	Additional flags describing the packing.
float	scale () const
	Return the scale for floating-point numbers.
bool	isSigned () const
	Are elements being written as signed numbers?
bool	isFloat () const
	Are elements being written as floating-point numbers?
bool	hasScale () const
	Should floats be rescaled before writing?
bool	rounding () const
	Should floats be rounded during writing?
bool	setNbits (uint8_t nbits)
	Set the number of bits to be used for each element.
bool	setNmantissa (uint8_t nmantissa)
	Set the number of mantissa bits used in the packed representation.
bool	setScale (float scale)
	Set the scale to use when packing floating-point data.
bool	setSigned (bool flag)
	Set the signedness flag for the packed representation.
bool	setRounding (bool flag)
	Set the rounding mode.
bool	setFloat (bool flag)
	Set the floating-point flag.
bool	setOption (const AuxDataOption &option)
	Set a packing option.

Static Public Member Functions
static bool	isValidOption (const AuxDataOption &option)
	Test to see if `option` is a recognized packing option.

Private Attributes
uint8_t	m_nbits
	The number of bits to use for each element.
uint8_t	m_nmantissa
	The number of bits for the mantissa of floating-point representations.
float	m_scale
	If nonzero, divide floating-point numbers by this before writing.
uint8_t	m_flags
	Additional flags.

Detailed Description

Describe how the contents of a PackedContainer are to be saved.

When a PackedContainer is saved to a root file, the contents may be stored with reduced precision. How this packing is done is described by the parameters held in this structure. These include:

nbits: This is the overall number of bits used to hold one container element. May be in the range 1-32, inclusive.
isSigned: If true, then the elements are saved as signed numbers; otherwise as unsigned numbers. If this is set, then one bit is used for the sign; nbits must therefore be at least 2.
isFloat: If true, the elements are saved as floating-point numbers; otherwise as integers. It may occasionally be useful to save floating-point values as integers. The converse should also work, but is likely to be less useful.

The remaining parameters are only used when elements are being saved as floating-point.

nmantissa: The number of bits to be used for the mantissa part of the representation. Does not include a sign bit. Any bits left out of nbits after removing nmantissa bits and (optionally) the sign bit are used as the exponent. If fewer than 2 bits are available for the exponent, then the number is saved using a fixed-point representation, with a range [0, 1).
scale: If set, then numbers will be divided by this value before being saved. This allows extending a fixed-point format to an arbitrary range.
rounding: If true, numbers will be rounded to the nearest value when written. Otherwise (the default), they will be truncated.

User code will should usually not interact with this class directly. Use the setOption interfaces instead.

Definition at line 65 of file PackedParameters.h.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

Define bit assignments for the flags field.

Existing flag assignments should never be changed, as the persistent format may depend on them.

Enumerator
FLAG_IS_SIGNED
FLAG_IS_FLOAT
FLAG_HAS_SCALE
FLAG_ROUNDING

Definition at line 266 of file PackedParameters.h.

       {
    FLAG_IS_SIGNED = (1<<0),
    FLAG_IS_FLOAT  = (1<<1),
    FLAG_HAS_SCALE = (1<<2),
    FLAG_ROUNDING  = (1<<3),
  };

Constructor & Destructor Documentation

◆ PackedParameters() [1/3]

SG::PackedParameters::PackedParameters ( )

Default constructor.

Set up to write unsigned integers with 32 bits.

Definition at line 25 of file PackedParameters.cxx.

  : m_nbits(8 * sizeof(uint32_t)),
    m_nmantissa(23),
    m_scale(0),
    m_flags(0)
{
}

◆ PackedParameters() [2/3]

SG::PackedParameters::PackedParameters	(	uint8_t	nbits,
		uint8_t	flags )

Constructor from nbits and flags.

Parameters

nbits	The number of bits for each element.
flags	Extra flags describing the packing.

Additionally nmantissa is set to correspond to a fixed-point representation and the scale is cleared.

This is meant to be used by the read converter.

Definition at line 44 of file PackedParameters.cxx.

  : m_nbits(nbits),
    m_flags(flags)
{
  m_nmantissa = nbits;
  if (isSigned() && m_nmantissa > 0) --m_nmantissa;
  if (hasScale())
    m_scale = 1;
  else
    m_scale = 0;
}

◆ PackedParameters() [3/3]

template<class T>

SG::PackedParameters::PackedParameters ( T )

Initialize with default packing parameters for type T.

For integer types, the number of bits and signedness is set to match T. For floating types, nbits is set to 32, nmantissa to 23, isSigned to true, and the scale is cleared.

Member Function Documentation

◆ flags()

uint8_t SG::PackedParameters::flags ( ) const

Additional flags describing the packing.

(This should really only be used by converters.)

◆ hasScale()

bool SG::PackedParameters::hasScale ( ) const

Should floats be rescaled before writing?

◆ isFloat()

bool SG::PackedParameters::isFloat ( ) const

Are elements being written as floating-point numbers?

◆ isSigned()

bool SG::PackedParameters::isSigned ( ) const

Are elements being written as signed numbers?

◆ isValidOption()

bool SG::PackedParameters::isValidOption ( const AuxDataOption & option )

static

Test to see if option is a recognized packing option.

Parameters

option The option to test.

Returns true if the name of option is recognized as a valid packing option; false otherwise.

Definition at line 197 of file PackedParameters.cxx.

{
  if (option.name() == "nbits" ||
      option.name() == "nmantissa" ||
      option.name() == "scale" ||
      option.name() == "signed" ||
      option.name() == "rounding" ||
      option.name() == "float")
  {
    return true;
  }
  return false;
}

◆ nbits()

uint8_t SG::PackedParameters::nbits ( ) const

The number of bits used to store each element.

◆ nmantissa()

uint8_t SG::PackedParameters::nmantissa ( ) const

The number of bits used for the mantissa portion of a float-point representation, excluding a sign bit (if any).

If there are at least two bits left over after accounting for the mantissa and sign bits, then numbers will be saved in a floating-point format; otherwise, fixed-point.

◆ rounding()

bool SG::PackedParameters::rounding ( ) const

Should floats be rounded during writing?

◆ scale()

float SG::PackedParameters::scale ( ) const

Return the scale for floating-point numbers.

If enabled, float-point numbers will be divided by this value before being saved. If not enabled, this may return 0.

◆ setFloat()

bool SG::PackedParameters::setFloat ( bool flag )

Set the floating-point flag.

Parameters

flag	Should numbers be written as floating-point?

If true, numbers will be written in a floating/fixed point representation; otherwise, they will be written as integers.

Returns true to indicate success.

Definition at line 180 of file PackedParameters.cxx.

{
  if (flag)
    m_flags |= FLAG_IS_FLOAT;
  else
    m_flags &= ~FLAG_IS_FLOAT;
  return true;
}

◆ setNbits()

bool SG::PackedParameters::setNbits ( uint8_t nbits )

Set the number of bits to be used for each element.

nbits The desired number of bits.

nbits must be in the range 1-32 for unsigned numbers, 2-32 for signed numbers.

If necessary, nmantissa will be adjusted so that it still fits within the requested number of bits.

Returns true if successful, false otherwise.

Definition at line 69 of file PackedParameters.cxx.

{
  if (nbits <= 0 || nbits > 32) return false;
  uint8_t navail = nbits;
  if (isSigned()) --navail;
  if (navail == 0) return false;
  m_nbits = nbits;
  if (m_nmantissa > navail)
    m_nmantissa = navail;
  return true;
}

◆ setNmantissa()

bool SG::PackedParameters::setNmantissa ( uint8_t nmantissa )

Set the number of mantissa bits used in the packed representation.

nmantissa The desired number of mantissa bits.

This has an effect only when saving floating-point types.

nmantissa must fit within the requested number of bits. nmantissa does not include the sign bit. If there are at least two bits left over, then numbers will be saved in a floating-point format; otherwise, fixed point will be used.

Returns true if successful, false otherwise.

Definition at line 95 of file PackedParameters.cxx.

{
  uint8_t navail = m_nbits;
  if (isSigned()) --navail;
  if (nmantissa <= 0 || nmantissa > navail) return false;
  m_nmantissa = nmantissa;
  return true;
}

◆ setOption()

bool SG::PackedParameters::setOption ( const AuxDataOption & option )

Set a packing option.

Parameters

option The option to set.

Recognized options are ‘nbits’, ‘nmantissa’, ‘scale’, ‘signed’, ‘rounding’, and ‘float’. See the setter functions above for details on their semantics.

Returns true on success; false otherwise.

Definition at line 222 of file PackedParameters.cxx.

{
  if (option.name() == "nbits")
    return setNbits (option.intVal());
 
  else if (option.name() == "nmantissa")
    return setNmantissa (option.intVal());
 
  else if (option.name() == "scale")
    return setScale (option.floatVal());
 
  else if (option.name() == "signed")
    return setSigned (option.intVal() != 0);
  
  else if (option.name() == "rounding")
    return setRounding (option.intVal() != 0);
  
  else if (option.name() == "float")
    return setFloat (option.intVal() != 0);
  
  return false;
}

◆ setRounding()

bool SG::PackedParameters::setRounding ( bool flag )

Set the rounding mode.

Parameters

flag	Should numbers be rounded when being written?

This has an effect only when saving floating-point types.

Returns true to indicate success.

Definition at line 161 of file PackedParameters.cxx.

{
  if (flag)
    m_flags |= FLAG_ROUNDING;
  else
    m_flags &= ~FLAG_ROUNDING;
  return true;
}

◆ setScale()

bool SG::PackedParameters::setScale ( float scale )

Set the scale to use when packing floating-point data.

Parameters

scale The new scale, or 0 to disable.

This has an effect only when saving floating-point types.

If set to something non-zero, then floating-point numbers will be divided by this value before being written.

Returns true to indicate success.

Definition at line 116 of file PackedParameters.cxx.

{
  m_scale = scale;
  if (m_scale == 0 || m_scale == 1)
    m_flags &= ~FLAG_HAS_SCALE;
  else
    m_flags |= FLAG_HAS_SCALE;
  return true;
}

◆ setSigned()

bool SG::PackedParameters::setSigned ( bool flag )

Set the signedness flag for the packed representation.

Parameters

flag	Should elements be saved as signed numbers?

If the flag is false (unsigned), this always succeeds. If the flag is true (signed), then this fails if nbits is 1. nmantissa will be adjusted if there are now insufficient bits for it.

Returns true if successful, false otherwise.

Definition at line 138 of file PackedParameters.cxx.

{
  if (!flag) {
    m_flags &= ~FLAG_IS_SIGNED;
    return true;
  }
 
  if (m_nbits == 1) return false;
  if (m_nmantissa + 1 > m_nbits)
    m_nmantissa = m_nbits - 1;
  m_flags |= FLAG_IS_SIGNED;
  return true;
}

Member Data Documentation

◆ m_flags

uint8_t SG::PackedParameters::m_flags

private

Additional flags.

Definition at line 286 of file PackedParameters.h.

◆ m_nbits

uint8_t SG::PackedParameters::m_nbits

private

The number of bits to use for each element.

Definition at line 276 of file PackedParameters.h.

◆ m_nmantissa

uint8_t SG::PackedParameters::m_nmantissa

private

The number of bits for the mantissa of floating-point representations.

Does not include the sign bit.

Definition at line 280 of file PackedParameters.h.

◆ m_scale

float SG::PackedParameters::m_scale

private

If nonzero, divide floating-point numbers by this before writing.

Definition at line 283 of file PackedParameters.h.

The documentation for this class was generated from the following files:

Public Types

Public Member Functions

Static Public Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ anonymous enum

Constructor & Destructor Documentation

◆ PackedParameters() [1/3]

◆ PackedParameters() [2/3]

◆ PackedParameters() [3/3]

Member Function Documentation

◆ flags()

◆ hasScale()

◆ isFloat()

◆ isSigned()

◆ isValidOption()

◆ nbits()

◆ nmantissa()

◆ rounding()

◆ scale()

◆ setFloat()

◆ setNbits()

◆ setNmantissa()

◆ setOption()

◆ setRounding()

◆ setScale()

◆ setSigned()

Member Data Documentation

◆ m_flags

◆ m_nbits

◆ m_nmantissa

◆ m_scale