baltzo_zoneinfobinaryheader

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

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.

/// 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 getNextZoneinfoBinaryHeader(baltzo::ZoneinfoBinaryHeader *object,
                                bsl::istream&                stream)
{
    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());