ZoneInfoLow.h

Go to the documentation of this file.

/*
 * MIT License
 * Copyright (c) 2023 Brian T. Park
 */
 
#ifndef ACE_TIME_ZONE_INFO_LOW_H
#define ACE_TIME_ZONE_INFO_LOW_H
 
#include <stdint.h>
#include <Arduino.h> // pgm_read_xxx()
#include <AceCommon.h> // KString
#include "compat.h" // ACE_TIME_USE_PROGMEM
#include "BrokerCommon.h"
 
class __FlashStringHelper;
class Print;
 
namespace ace_time{
 
class ZoneInfoLow {
public:
 
struct ZoneContext {
  static const int16_t kInvalidYear = -32768;
 
  static const int8_t kInvalidYearTiny = -128;
 
  static const int16_t kMaxUntilYear = 32767;
 
  static const int8_t kMaxUntilYearTiny = 127;
 
  static const int16_t kMaxYear = kMaxUntilYear - 1;
 
  static const int8_t kMaxYearTiny = kMaxUntilYearTiny - 1;
 
  static const int16_t kMinYear = -32767;
 
  static const int8_t kMinYearTiny = -127;
 
  static const uint8_t kSuffixW = 0x00;
 
  static const uint8_t kSuffixS = 0x10;
 
  static const uint8_t kSuffixU = 0x20;
 
  int16_t const startYear;
 
  int16_t const untilYear;
 
  int16_t const startYearAccurate;
 
  int16_t const untilYearAccurate;
 
  int16_t const baseYear;
 
  int16_t const maxTransitions;
 
  const char* const tzVersion;
 
  uint8_t const numFragments;
 
  uint8_t const numLetters;;
 
  const char* const* const fragments;
 
  const char* const* const letters;
};
 
struct ZoneRule {
  int8_t const fromYear;
 
  int8_t const toYear;
 
  uint8_t const inMonth;
 
  uint8_t const onDayOfWeek;
 
  int8_t const onDayOfMonth;
 
  uint8_t const atTimeCode;
 
  uint8_t const atTimeModifier;
 
  uint8_t const deltaCode;
 
  uint8_t const letterIndex;
};
 
struct ZonePolicy {
  const ZoneRule* const rules;
  uint8_t const numRules;
};
 
struct ZoneEra {
  const ZonePolicy* const zonePolicy;
 
  const char* const format;
 
  int8_t const offsetCode;
 
  uint8_t const deltaCode;
 
  int8_t const untilYear;
 
  uint8_t const untilMonth;
 
  uint8_t const untilDay;
 
  uint8_t const untilTimeCode;
 
  uint8_t const untilTimeModifier;
};
 
struct ZoneInfo {
  const char* const name;
 
  uint32_t const zoneId;
 
  const ZoneContext* const zoneContext;
 
  uint8_t const numEras;
 
  const ZoneEra* const eras;
 
  const ZoneInfo* const targetInfo;
};
 
//-----------------------------------------------------------------------------
// Brokers are wrappers around the above data objects so that outside code
// can use the data objects with a consistent API.
//-----------------------------------------------------------------------------
 
static int16_t toDeltaMinutes(uint8_t deltaCode) {
  return ((int16_t)(deltaCode & 0x0f) - 4) * 15;
}
 
static int16_t toOffsetMinutes(uint8_t offsetCode, uint8_t deltaCode) {
  return ((int8_t)offsetCode * 15) + ((deltaCode & 0xf0) >> 4);
}
 
 
static uint16_t timeCodeToMinutes(uint8_t code, uint8_t modifier) {
  return code * (uint16_t) 15 + (modifier & 0x0f);
}
 
static uint8_t toSuffix(uint8_t modifier) {
  return modifier & 0xf0;
}
 
//-----------------------------------------------------------------------------
 
class ZoneContextBroker {
  public:
    explicit ZoneContextBroker(const ZoneContext* zoneContext = nullptr)
        : mZoneContext(zoneContext)
    {}
 
    // use the default copy constructor
    ZoneContextBroker(const ZoneContextBroker&) = default;
 
    // use the default assignment operator
    ZoneContextBroker& operator=(const ZoneContextBroker&) = default;
 
    bool isNull() const { return mZoneContext == nullptr; }
 
    const ZoneContext* raw() const { return mZoneContext; }
 
    int16_t startYear() const {
      return (int16_t) pgm_read_word(&mZoneContext->startYear);
    }
 
    int16_t untilYear() const {
      return (int16_t) pgm_read_word(&mZoneContext->untilYear);
    }
 
    int16_t startYearAccurate() const {
      return (int16_t) pgm_read_word(&mZoneContext->startYearAccurate);
    }
 
    int16_t untilYearAccurate() const {
      return (int16_t) pgm_read_word(&mZoneContext->untilYearAccurate);
    }
 
    int16_t baseYear() const {
      return (int16_t) pgm_read_word(&mZoneContext->baseYear);
    }
 
    int16_t maxTransitions() const {
      return (int16_t) pgm_read_word(&mZoneContext->maxTransitions);
    }
 
    const __FlashStringHelper* tzVersion() const {
      return (const __FlashStringHelper*)
          pgm_read_ptr(&mZoneContext->tzVersion);
    }
 
    uint8_t numFragments() const {
      return (uint8_t) pgm_read_byte(&mZoneContext->numFragments);
    }
 
    uint8_t numLetters() const {
      return (uint8_t) pgm_read_byte(&mZoneContext->numLetters);
    }
 
    const __FlashStringHelper* const* fragments() const {
      return (const __FlashStringHelper* const*)
          pgm_read_ptr(&mZoneContext->fragments);
    }
 
    const __FlashStringHelper* letter(uint8_t i) const {
      const char * const* letters = (const char* const*)
          pgm_read_ptr(&mZoneContext->letters);
      const char* letter = (const char*) pgm_read_ptr(letters + i);
      return (const __FlashStringHelper*) letter;
    }
 
  private:
    const ZoneContext* mZoneContext;
};
 
//-----------------------------------------------------------------------------
 
class ZoneRuleBroker {
  public:
    explicit ZoneRuleBroker(
        const ZoneContext* zoneContext = nullptr,
        const ZoneRule* zoneRule = nullptr)
        : mZoneContext(zoneContext)
        , mZoneRule(zoneRule)
    {}
 
    // use the default copy constructor
    ZoneRuleBroker(const ZoneRuleBroker&) = default;
 
    // use the default assignment operator
    ZoneRuleBroker& operator=(const ZoneRuleBroker&) = default;
 
    bool isNull() const { return mZoneRule == nullptr; }
 
    int16_t fromYear() const {
      int8_t yearTiny = (int8_t) pgm_read_byte(&mZoneRule->fromYear);
      int16_t baseYear = ZoneContextBroker(mZoneContext).baseYear();
      return toYearFromTiny(yearTiny, baseYear);
    }
 
    int16_t toYear() const {
      int8_t yearTiny = (int8_t) pgm_read_byte(&mZoneRule->toYear);
      int16_t baseYear = ZoneContextBroker(mZoneContext).baseYear();
      return toYearFromTiny(yearTiny, baseYear);
    }
 
    static int16_t toYearFromTiny(int8_t yearTiny, int16_t baseYear) {
      if (yearTiny == ZoneContext::kInvalidYearTiny)
          return ZoneContext::kInvalidYear;
      if (yearTiny == ZoneContext::kMinYearTiny)
          return ZoneContext::kMinYear;
 
      // yearTiny should be a maximum of 126, and should never be as high as
      // 127. But if it does have this value, what should we do? Let's peg the
      // return value at 32766, so that it's always less than the 32767 maximum
      // returned by untilYear().
      if (yearTiny >= ZoneContext::kMaxYearTiny) return ZoneContext::kMaxYear;
 
      return baseYear + yearTiny;
    }
 
    uint8_t inMonth() const {
      return pgm_read_byte(&mZoneRule->inMonth);
    }
 
    uint8_t onDayOfWeek() const {
      return pgm_read_byte(&mZoneRule->onDayOfWeek);
    }
 
    int8_t onDayOfMonth() const {
      return pgm_read_byte(&mZoneRule->onDayOfMonth);
    }
 
    uint32_t atTimeSeconds() const {
      return 60 * timeCodeToMinutes(
          pgm_read_byte(&mZoneRule->atTimeCode),
          pgm_read_byte(&mZoneRule->atTimeModifier));
    }
 
    uint8_t atTimeSuffix() const {
      return toSuffix(pgm_read_byte(&mZoneRule->atTimeModifier));
    }
 
    int32_t deltaSeconds() const {
      return 60 * toDeltaMinutes(pgm_read_byte(&mZoneRule->deltaCode));
    }
 
    const __FlashStringHelper* letter() const {
      uint8_t index = pgm_read_byte(&mZoneRule->letterIndex);
      return ZoneContextBroker(mZoneContext).letter(index);
    }
 
  private:
    const ZoneContext* mZoneContext;
    const ZoneRule* mZoneRule;
};
 
class ZonePolicyBroker {
  public:
    explicit ZonePolicyBroker(
        const ZoneContext* zoneContext,
        const ZonePolicy* zonePolicy)
        : mZoneContext(zoneContext)
        , mZonePolicy(zonePolicy)
    {}
 
    // use default copy constructor
    ZonePolicyBroker(const ZonePolicyBroker&) = default;
 
    // use default assignment operator
    ZonePolicyBroker& operator=(const ZonePolicyBroker&) = default;
 
    bool isNull() const { return mZonePolicy == nullptr; }
 
    uint8_t numRules() const {
      return pgm_read_byte(&mZonePolicy->numRules);
    }
 
    const ZoneRuleBroker rule(uint8_t i) const {
      const ZoneRule* rules =
          (const ZoneRule*) pgm_read_ptr(&mZonePolicy->rules);
      return ZoneRuleBroker(mZoneContext, &rules[i]);
    }
 
  private:
    const ZoneContext* mZoneContext;
    const ZonePolicy* mZonePolicy;
};
 
//-----------------------------------------------------------------------------
 
class ZoneEraBroker {
  public:
    explicit ZoneEraBroker(
        const ZoneContext* zoneContext = nullptr,
        const ZoneEra* zoneEra = nullptr)
        : mZoneContext(zoneContext)
        , mZoneEra(zoneEra)
    {}
 
    // use default copy constructor
    ZoneEraBroker(const ZoneEraBroker&) = default;
 
    // use default assignment operator
    ZoneEraBroker& operator=(const ZoneEraBroker&) = default;
 
    bool isNull() const { return mZoneEra == nullptr; }
 
    bool equals(const ZoneEraBroker& other) const {
      return mZoneEra == other.mZoneEra;
    }
 
    const ZonePolicyBroker zonePolicy() const {
      return ZonePolicyBroker(
          mZoneContext,
          (const ZonePolicy*) pgm_read_ptr(&mZoneEra->zonePolicy));
    }
 
    int32_t offsetSeconds() const {
      return 60 * toOffsetMinutes(
        pgm_read_byte(&mZoneEra->offsetCode),
        pgm_read_byte(&mZoneEra->deltaCode));
    }
 
    int32_t deltaSeconds() const {
      return 60 * toDeltaMinutes(pgm_read_byte(&mZoneEra->deltaCode));
    }
 
    const char* format() const {
      return (const char*) pgm_read_ptr(&mZoneEra->format);
    }
 
    int16_t untilYear() const {
      int8_t yearTiny = (int8_t) pgm_read_byte(&mZoneEra->untilYear);
      int16_t baseYear = ZoneContextBroker(mZoneContext).baseYear();
      return toUntilYearFromTiny(yearTiny, baseYear);
    }
 
    static int16_t toUntilYearFromTiny(int8_t yearTiny, int16_t baseYear) {
      if (yearTiny == ZoneContext::kInvalidYearTiny)
          return ZoneContext::kInvalidYear;
      if (yearTiny == ZoneContext::kMinYearTiny)
          return ZoneContext::kMinYear;
      if (yearTiny == ZoneContext::kMaxUntilYearTiny)
          return ZoneContext::kMaxUntilYear;
      return baseYear + yearTiny;
    }
 
    uint8_t untilMonth() const {
      return pgm_read_byte(&mZoneEra->untilMonth);
    }
 
    uint8_t untilDay() const {
      return pgm_read_byte(&mZoneEra->untilDay);
    }
 
    uint32_t untilTimeSeconds() const {
      return 60 * timeCodeToMinutes(
        pgm_read_byte(&mZoneEra->untilTimeCode),
        pgm_read_byte(&mZoneEra->untilTimeModifier));
    }
 
    uint8_t untilTimeSuffix() const {
      return toSuffix(pgm_read_byte(&mZoneEra->untilTimeModifier));
    }
 
  private:
    const ZoneContext* mZoneContext;
    const ZoneEra* mZoneEra;
};
 
class ZoneInfoBroker {
  public:
    explicit ZoneInfoBroker(const ZoneInfo* zoneInfo = nullptr):
        mZoneInfo(zoneInfo) {}
 
    // use default copy constructor
    ZoneInfoBroker(const ZoneInfoBroker&) = default;
 
    // use default assignment operator
    ZoneInfoBroker& operator=(const ZoneInfoBroker&) = default;
 
    bool equals(uintptr_t zoneKey) const {
      return mZoneInfo == (const ZoneInfo*) zoneKey;
    }
 
    bool equals(const ZoneInfoBroker& zoneInfoBroker) const {
      return mZoneInfo == zoneInfoBroker.mZoneInfo;
    }
 
    bool isNull() const { return mZoneInfo == nullptr; }
 
    const ZoneContextBroker zoneContext() const {
      const ZoneContext* context =
          (const ZoneContext*) pgm_read_ptr(&mZoneInfo->zoneContext);
      return ZoneContextBroker(context);
    }
 
    const __FlashStringHelper* name() const {
      return FPSTR(pgm_read_ptr(&mZoneInfo->name));
    }
 
    uint32_t zoneId() const {
      return pgm_read_dword(&mZoneInfo->zoneId);
    }
 
    uint8_t numEras() const {
      return pgm_read_byte(&mZoneInfo->numEras);
    }
 
    const ZoneEraBroker era(uint8_t i) const {
      auto eras = (const ZoneEra*) pgm_read_ptr(&mZoneInfo->eras);
      return ZoneEraBroker(zoneContext().raw(), &eras[i]);
    }
 
    bool isLink() const {
      return mZoneInfo->targetInfo != nullptr;
    }
 
    ZoneInfoBroker targetInfo() const {
      return ZoneInfoBroker(
          (const ZoneInfo*) pgm_read_ptr(&mZoneInfo->targetInfo));
    }
 
    void printNameTo(Print& printer) const {
      ZoneContextBroker zc = zoneContext();
      ace_common::KString kname(name(), zc.fragments(), zc.numFragments());
      kname.printTo(printer);
    }
 
    void printShortNameTo(Print& printer) const {
      ace_common::printReplaceCharTo(
          printer, zoneinfo::findShortName(name()), '_', ' ');
    }
 
  private:
    const ZoneInfo* mZoneInfo;
};
 
//-----------------------------------------------------------------------------
 
class ZoneRegistryBroker {
  public:
    ZoneRegistryBroker(const ZoneInfo* const* zoneRegistry):
        mZoneRegistry(zoneRegistry) {}
 
    // use default copy constructor
    ZoneRegistryBroker(const ZoneRegistryBroker&) = default;
 
    // use default assignment operator
    ZoneRegistryBroker& operator=(const ZoneRegistryBroker&) = default;
 
    const ZoneInfo* zoneInfo(uint16_t i) const {
      return (const ZoneInfo*) pgm_read_ptr(&mZoneRegistry[i]);
    }
 
  private:
    const ZoneInfo* const* mZoneRegistry;
};
 
//-----------------------------------------------------------------------------
// A factory class for a ZoneInfoBroker.
//-----------------------------------------------------------------------------
 
class ZoneInfoStore {
  public:
    ZoneInfoBroker createZoneInfoBroker(uintptr_t zoneKey) const {
      return ZoneInfoBroker((const ZoneInfo*) zoneKey);
    }
};
 
}; // ZoneInfoLow
 
} // ace_time
 
#endif