Component baltzo_zoneinfobinaryheader [Package baltzo]

Provide an attribute class for Zoneinfo binary-file header data. More...

Namespaces
namespace	baltzo

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Attributes
  • Usage
    • Example 1: Creating a baltzo::ZoneinfoBinaryHeader from User Input

Purpose:

Provide an attribute class for Zoneinfo binary-file header data.

Classes:

baltzo::ZoneinfoBinaryHeader

attribute class for Zoneinfo header data

See also:

Component baltzo_zoneinfobinaryreader

Description:

This component provides a simply constrained attribute class, baltzo::ZoneinfoBinaryHeader, representing the header data of a Zoneinfo binary data file.

Attributes:

  Name               Type  Default  Simple Constraints
  -----------------  ----  -------  ------------------
  version            char  '\0'     == '\0' || == '2' || == '3'
  numIsGmt           int    0       >= 0
  numIsStd           int    0       >= 0
  numLeaps           int    0       == 0
  numTransitions     int    0       >= 0
  numLocalTimeTypes  int    1       >= 1
  abbrevDataSize     int    1       >= 1

• version: Zoneinfo file format version, as of 2013, either \0, 2,

or 3.

• numIsGmt: number of encoded UTC/local indicators in the file, indicating whether a transition time was originally specified as UTC in the rule file.
• numIsStd: number of encoded standard/wall indicators in the file, indicating whether a transition time was originally specified as standard time in the rule file.
• numLeaps: number of leap corrections stored in the file.
• numTransitions: number of local-time type transitions stored in the file.
• numLocalTimeTypes: number of local-time types stored in the file.
• abbrevDataSize: length of the sequence of characters containing the (\0-separated) abbreviation strings in the file.

Usage:

This section illustrates intended use of this component.

Example 1: Creating a baltzo::ZoneinfoBinaryHeader from User Input:

We define the getNextZoneinfoBinaryHeader helper function, reads data from a stream, validates the data, and constructs a baltzo::ZoneinfoBinaryHeader object.

  int getNextZoneinfoBinaryHeader(baltzo::ZoneinfoBinaryHeader *object,
                                  bsl::istream&                stream)
      // Set to the specified 'object' the value extracted from the
      // specified 'stream'.  Return 0 on success, and a non-zero value
      // otherwise, with no change to 'object'.  The 'stream' contains
      // white-space separated decimal representations of the attributes
      // of 'baltzo::ZoneinfoBinaryHeader' in the following order: 'version',
      // 'numIsGmt', 'numIsStd', 'numLeaps', 'numTransitions',
      // 'numLocalTimeTypes', and 'abbrevDataSize'.
  {
      int version;  // not 'char'
      int numIsGmt;
      int numIsStd;
      int numLeaps;
      int numTransitions;
      int numLocalTimeTypes;
      int abbrevDataSize;

      if (!(stream >> version
         && stream >> numIsGmt
         && stream >> numIsStd
         && stream >> numLeaps
         && stream >> numTransitions
         && stream >> numLocalTimeTypes
         && stream >> abbrevDataSize)) {
          return 1;                                                 // RETURN
      }

      if (!(baltzo::ZoneinfoBinaryHeader::isValidVersion(version)
         && baltzo::ZoneinfoBinaryHeader::isValidNumIsGmt(numIsGmt)
         && baltzo::ZoneinfoBinaryHeader::isValidNumIsStd(numIsStd)
         && baltzo::ZoneinfoBinaryHeader::isValidNumLeaps(numLeaps)
         && baltzo::ZoneinfoBinaryHeader::isValidNumTransitions(
                                                              numTransitions)
         && baltzo::ZoneinfoBinaryHeader::isValidNumLocalTimeTypes(
                                                           numLocalTimeTypes)
         && baltzo::ZoneinfoBinaryHeader::isValidAbbrevDataSize(
                                                          abbrevDataSize))) {
          return 2;                                                 // RETURN
      }

      object->setVersion(version);
      object->setNumIsGmt(numIsGmt);
      object->setNumIsStd(numIsStd);
      object->setNumLeaps(numLeaps);
      object->setNumTransitions(numTransitions);
      object->setNumLocalTimeTypes(numLocalTimeTypes);
      object->setAbbrevDataSize(abbrevDataSize);

      return 0;
  }

To use our helper function, we supply it with a stream of (decimal, whitespace-separated values). The resulting object has the expected value.

  bsl::stringstream           input("50 1 2 0 3 4 5");
  baltzo::ZoneinfoBinaryHeader header;
  int rc;

  rc = getNextZoneinfoBinaryHeader(&header, input);

  assert( 0  == rc);
  assert('2' == header.version());
  assert( 1  == header.numIsGmt());
  assert( 2  == header.numIsStd());
  assert( 0  == header.numLeaps());
  assert( 3  == header.numTransitions());
  assert( 4  == header.numLocalTimeTypes());
  assert( 5  == header.abbrevDataSize());

Since all of the data in the stream has now been consumed, another call to the function returns an error and leaves the object unchanged.

  header.setVersion(0);
  header.setNumIsGmt(10);
  header.setNumIsStd(20);
  header.setNumLeaps(0);
  header.setNumTransitions(30);
  header.setNumLocalTimeTypes(40);
  header.setAbbrevDataSize(50);

  rc = getNextZoneinfoBinaryHeader(&header, input);

  assert(  0  != rc);
  assert('\0' == header.version());
  assert( 10  == header.numIsGmt());
  assert( 20  == header.numIsStd());
  assert(  0  == header.numLeaps());
  assert( 30  == header.numTransitions());
  assert( 40  == header.numLocalTimeTypes());
  assert( 50  == header.abbrevDataSize());