ICU-3.13.tar.gz

[apple/icu.git] / icuSources / i18n / tzdat.h

/*
**********************************************************************
*   Copyright (C) 1999-2003, International Business Machines
*   Corporation and others.  All Rights Reserved.
**********************************************************************
*   Date        Name        Description
*   11/24/99    aliu        Creation.
*   12/13/1999  srl         Padded OffsetIndex to 4 byte values
*   02/01/01    aliu        Added country index
**********************************************************************
*/

#ifndef TZDAT_H
#define TZDAT_H

#include "unicode/utypes.h"

/* This file defines the format of the memory-mapped data file
 * containing system time zone data for icu.  See also gentz
 * and tz.pl.
 *
 * The format is designed specifically to allow certain operations:
 *
 * 1. Performing a fast binary search by name, and locating the
 *    corresponding zone data.  This is the most important operation.
 *    It corresponds to the TimeZone::createTimeZone() method.
 *
 * 2. Performing a fast iteration over zones having a specific GMT
 *    offset.  For this operation, the zone data need not be
 *    retrieved, just the IDs.  This corresponds to the
 *    TimeZone::createAvailableIDs(int32_t) method.
 *
 * 3. Iterating over all zone IDs.  This corresponds to the
 *    TimeZone::createAvailableIDs() method.
 *
 * The createAvailableIDs() methods return arrays of pointers to
 * existing static UnicodeString IDs that it owns.  Thus
 * createAvailableIDs() needs a way to reference one of these IDs when
 * iterating.  Note that these IDs are _not_ stored in the
 * memory-mapped data file, so we cannot store offsets.  To solve this
 * problem, we define a canonical index number for each zone.  This
 * index number runs from 0..n-1, where n is the total number of
 * zones.  The name table is stored in index number order, and we
 * provide a table that is sorted by GMT offset with keys being GMT
 * offset values and values being canonical index numbers.
 *
 * (Later, we might change createAvailableIDs() to return char*
 * strings rather than UnicodeString pointers.  In that case, this
 * data structure could be modified to index into the name table
 * directly.)
 *
 * Any field with a name ending in "delta" is an offset value
 * from the first byte of the TZHeader structure, unless otherwise
 * specified.
 *
 * When using the name index table and the offset index table,
 * code can determine whether an indexed zone is a standard
 * zone or a DST zone by examining its delta.  If the delta is
 * less than dstDelta, it is a standard zone.  Otherwise it 
 * is a DST zone.
 */

/* tz.icu data file format
 *
 * Here is the overall structure of the tz.icu file, expressed as a
 * pseudo-C-struct.  Refer to actual struct declarations below for
 * more details on each subelement of tz.icu.  Many of the elements
 * are of variable size.  Padding is used when necessary to align
 * words and longs properly; see structure declarations for details.
 *
 * struct tz.icu {
 *
 *  // The header gives offsets to various tables within tz.icu.
 *
 *  struct TZHeader            header;
 * 
 *  // The equivalency groups; repeated; one element for each
 *  // equivalency group.  Each one is of variable size.  Typically,
 *  // an equivalency group is found given an ID index.  The index is
 *  // used to find an entry of nameToEquiv[].  That entry is added to
 *  // the start of the header to obtain a pointer to one of the
 *  // entries equivTable[i].  The number of equivalency groups (n1)
 *  // is not stored anywhere; it can be discovered by walking the
 *  // table.
 *
 *  struct TZEquivalencyGroup  equivTable[n1];
 * 
 *  // An index which groups timezones having the same raw offset
 *  // together; repeated; one element for each raw offset struct.
 *  // Typically the code walks through this table starting at the
 *  // beginning until the desired index is found or the end of the
 *  // table is reached.  The number of offset groups (n2) is not
 *  // stored anywhere; it can be discovered by walking the table.
 *
 *  struct OffsetIndex         offsetIndex[n2];
 * 
 *  // An index which groups timezones having the same country
 *  // together; repeated; one element for each country.  Typically
 *  // the code walks through this table starting at the beginning
 *  // until the desired country is found or the end of the table is
 *  // reached.  The number of offset groups (n3) is not stored
 *  // anywhere; it can be discovered by walking the table.
 *
 *  struct CountryIndex        countryIndex[n3];
 * 
 *  // An array of offsets, one for each name.  Each offset, when
 *  // added to the start of the header, gives a pointer to an entry
 *  // equivTable[i], the equivalency group struct for the given zone.
 *  // The nubmer of names is given by TZHeader.count.  The order of
 *  // entries is the same as nameTable[].
 *
 *  uint32                     nameToEquiv[header.count];
 * 
 *  // All the time zone IDs, in sorted order, with 0 termination.
 *  // The number of entries is given by TZHeader.count.  The total
 *  // number of characters in this table (n4) is not stored anywhere;
 *  // it can be discovered by walking the table.  The order of
 *  // entries is the same as nameToEquiv[].
 *
 *  char                       nameTable[n4];
 * };
 */

// Information used to identify and validate the data

#define TZ_DATA_NAME "tz"
#define TZ_DATA_TYPE "icu"

#if !UCONFIG_NO_FORMATTING

// Fields in UDataInfo:

// TZ_SIG[] is encoded as numeric literals for compatibility with the HP compiler
static const uint8_t TZ_SIG_0 = 0x7a; // z
static const uint8_t TZ_SIG_1 = 0x6f; // o
static const uint8_t TZ_SIG_2 = 0x6e; // n
static const uint8_t TZ_SIG_3 = 0x65; // e

// This must match the version number at the top of tz.txt as
// well as the version number in the udata header.
static const int8_t TZ_FORMAT_VERSION = 4; // formatVersion[0]

struct TZHeader {    
    uint16_t versionYear;     // e.g. "1999j" -> 1999
    uint16_t versionSuffix;   // e.g. "1999j" -> 10

    uint32_t count;           // standardCount + dstCount

    uint32_t equivTableDelta;  // delta to equivalency group table
    uint32_t offsetIndexDelta; // delta to gmtOffset index table

    uint32_t countryIndexDelta; // delta to country code index table

    uint32_t nameIndexDelta;   // delta to name index table
    // The name index table is an array of 'count' 32-bit offsets from
    // the start of this header to equivalency group table entries.

    uint32_t nameTableDelta;   // delta to name (aka ID) table
    // The name table contains all zone IDs, in sort order, each name
    // terminated by a zero byte.
};

struct StandardZone {
    int32_t  gmtOffset;   // gmt offset in milliseconds
};

struct TZRule {
    uint8_t  month;  // month
    int8_t   dowim;  // dowim
    int8_t   dow;    // dow
    uint16_t time;   // time in minutes
    int8_t   mode;   // (w/s/u) == TimeZone::TimeMode enum as int
};

struct DSTZone {
    int32_t  gmtOffset;   // gmtoffset in milliseconds
    uint16_t dstSavings;  // savings in minutes
    TZRule   onsetRule;   // onset rule
    TZRule   ceaseRule;   // cease rule
};

/**
 * This variable-sized struct represents a time zone equivalency group.
 * This is a set of one or more zones that are identical in GMT offset
 * and rules, but differ in ID.  The struct has a variable size because
 * the standard zone has no rule data, and also because it contains a
 * variable number of index values listing the zones in the group.
 * The struct is padded to take up 4n bytes so that 4-byte integers
 * within the struct stay 4-aligned (namely, the gmtOffset members of
 * the zone structs).
 */
struct TZEquivalencyGroup {
    uint16_t nextEntryDelta;    // 0 for last entry
    uint8_t  isDST;             // != 0 for DSTZone
    uint8_t  reserved;
    union {
        struct {
            StandardZone zone;
            uint16_t     count;
            uint16_t     index; // There are actually 'count' uint16_t's here
        } s;
        struct {
            DSTZone      zone;
            uint16_t     count;
            uint16_t     index; // There are actually 'count' uint16_t's here
        } d;
    } u;
    // There may be two bytes of padding HERE to make the whole struct
    // have size 4n bytes.
};

/**
 * This variable-sized struct makes up the offset index table.  To get
 * from one table entry to the next, add the nextEntryDelta.  If the
 * nextEntryDelta is zero then this is the last entry.  The offset
 * index table is designed for sequential access, not random access.
 * Given the small number of distinct offsets (39 in 1999j), this
 * suffices.
 *
 * The value of default is the zone within this list that should be
 * selected as the default zone in the absence of any other
 * discriminating information.  This information comes from the file
 * tz.default.  Note that this is itself a zone number, like
 * those in the array starting at &zoneNumber.
 *
 * The gmtOffset field must be 4-aligned for some architectures.  To
 * ensure this, we do two things: 1. The entire struct is 4-aligned.
 * 2. The gmtOffset is placed at a 4-aligned position within the
 * struct.  3. The size of the whole structure is padded out to 4n
 * bytes.  We achieve this last condition by adding two bytes of
 * padding after the last zoneNumber, if count is _even_.  That is,
 * the struct size is 10+2count+padding, where padding is (count%2==0
 * ? 2:0).  See gentz for implementation.
 */
struct OffsetIndex {
    int32_t   gmtOffset;  // in ms - 4-aligned
    uint16_t  nextEntryDelta;
    uint16_t  defaultZone; // a zone number from 0..TZHeader.count-1
    uint16_t  count;
    uint16_t  zoneNumber; // There are actually 'count' uint16_t's here
    // Following the 'count' uint16_t's starting with zoneNumber,
    // there may be two bytes of padding to make the whole struct have
    // a size of 4n.  nextEntryDelta skips over any padding.
};

/**
 * This variable-sized struct makes up the country index table.  To get
 * from one table entry to the next, add the nextEntryDelta.  If the
 * nextEntryDelta is zero then this is the last entry.  The country
 * index table is designed for sequential access, not random access.
 *
 * The intcode is an integer representation of the two-letter country
 * code.  It is computed as (c1-'A')*32 + (c0-'A') where the country
 * code is a two-character string c1 c0, 'A' <= ci <= 'Z'.
 *
 * There are no 4-byte integers in this table, so we don't 4-align the
 * entries.
 */
struct CountryIndex {
    uint16_t  intcode; // see above
    uint16_t  nextEntryDelta;
    uint16_t  count;
    uint16_t  zoneNumber; // There are actually 'count' uint16_t's here
};

#endif /* #if !UCONFIG_NO_FORMATTING */

#endif