AceTime  0.1
Date and time classes for Arduino that supports the TZ DAtabase, and a system clock synchronized from an NTP server or an RTC chip.
Public Member Functions | Static Public Member Functions | Static Public Attributes | Friends | List of all members
ace_time::TimeZone Class Reference

Class that describes a time zone. More...

#include <TimeZone.h>

Collaboration diagram for ace_time::TimeZone:
Collaboration graph
[legend]

Public Member Functions

 TimeZone ()
 Default constructor. More...
 
uint8_t getType () const
 Return the type of TimeZone. More...
 
TimeOffset getUtcOffset (acetime_t epochSeconds) const
 Return the total UTC offset at epochSeconds, including DST offset. More...
 
TimeOffset getDeltaOffset (acetime_t epochSeconds) const
 Return the DST offset from standard UTC offset at epochSeconds. More...
 
TimeOffset getUtcOffsetForDateTime (const LocalDateTime &ldt) const
 Return the best guess of the UTC offset at the given LocalDateTime for the current TimeZone. More...
 
void printTo (Print &printer) const
 Print the human readable representation of the time zone. More...
 
void printAbbrevTo (Print &printer, acetime_t epochSeconds) const
 Print the time zone abbreviation for the given epochSeconds. More...
 
bool isDst () const
 Return the isDst() value of the underlying ManualZoneSpecifier. More...
 
void isDst (bool dst)
 Sets the isDst() flag of the underlying ManualZoneSpecifier. More...
 
 TimeZone (const TimeZone &)=default
 
TimeZoneoperator= (const TimeZone &)=default
 

Static Public Member Functions

static TimeZone forTimeOffset (TimeOffset offset=TimeOffset())
 Factory method to create from a fixed UTC offset. More...
 
static TimeZone forZoneSpecifier (const ZoneSpecifier *zoneSpecifier)
 Factory method to create from a ZoneSpecifier. More...
 

Static Public Attributes

static const uint8_t kTypeFixed = 0
 
static const uint8_t kTypeZoneSpecifier = 1
 

Friends

bool operator== (const TimeZone &a, const TimeZone &b)
 

Detailed Description

Class that describes a time zone.

There are 2 types:

The TimeZone class really really wants to be a reference type. In other words, it would be very convenient if the client code could create this object on the heap, and pass it around using a pointer (or smart pointer) to the ZonedDateTime class and shared among multiple ZonedDateTime objects. This would also allow new TimeZones to be created, while allowing older instances of ZonedDateTime to hold on to the previous versions of TimeZone.

However, in a small memory embedded environment (like Arduino Nano or Micro with only 2kB of RAM), I want to avoid any use of the heap (new operator or malloc()) inside the AceTime library. I separated out the memory intensive or mutable features of the TimeZone class into the separate ZoneSpecifier class. The ZoneSpecifier object should be created once at initialization time of the application (either statically allocated or potentially on the heap early in the application start up).

The TimeZone class becomes a thin wrapper around a ZoneSpecifier object (essentially acting like a smart pointer in some sense). It should be treated as a value type and passed around by value or by const reference.

An alternative implementation would use an inheritance hierarchy for the TimeZone, with 2 subclasses (ManualTimeZone and AutoTimeZone). However this means that the TimeZone object can no longer be passed around by value, and the ZonedDateTime is forced to hold on to the TimeZone object using a pointer. It then becomes very difficult to change the offset and DST fields of the ManualTimeZone. Using a single TimeZone class and implementing it as a value type simplifies a lot of code.

Definition at line 50 of file TimeZone.h.

Constructor & Destructor Documentation

ace_time::TimeZone::TimeZone ( )
inline

Default constructor.

Definition at line 75 of file TimeZone.h.

Member Function Documentation

static TimeZone ace_time::TimeZone::forTimeOffset ( TimeOffset  offset = TimeOffset())
inlinestatic

Factory method to create from a fixed UTC offset.

Parameters
offsetthe fixed UTC offset, default 00:00 offset

Definition at line 60 of file TimeZone.h.

static TimeZone ace_time::TimeZone::forZoneSpecifier ( const ZoneSpecifier zoneSpecifier)
inlinestatic

Factory method to create from a ZoneSpecifier.

Parameters
zoneSpecifieran instance of ManualZoneSpecifier, BasicZoneSpecifier, or ExtendedZoneSpecifier. Cannot be nullptr.

Definition at line 70 of file TimeZone.h.

TimeOffset ace_time::TimeZone::getDeltaOffset ( acetime_t  epochSeconds) const
inline

Return the DST offset from standard UTC offset at epochSeconds.

This is an experimental method that has not been tested thoroughly. Use with caution.

Definition at line 94 of file TimeZone.h.

uint8_t ace_time::TimeZone::getType ( ) const
inline

Return the type of TimeZone.

Definition at line 80 of file TimeZone.h.

TimeOffset ace_time::TimeZone::getUtcOffset ( acetime_t  epochSeconds) const
inline

Return the total UTC offset at epochSeconds, including DST offset.

Definition at line 83 of file TimeZone.h.

TimeOffset ace_time::TimeZone::getUtcOffsetForDateTime ( const LocalDateTime ldt) const
inline

Return the best guess of the UTC offset at the given LocalDateTime for the current TimeZone.

Used by ZonedDateTime::forComponents(), so intended to be used mostly for testing and debugging.

Definition at line 105 of file TimeZone.h.

bool ace_time::TimeZone::isDst ( ) const
inline

Return the isDst() value of the underlying ManualZoneSpecifier.

This is a convenience method that is valid only if the TimeZone was constructed using a ManualZoneSpecifier. Returns false for all other type of TimeZone. This is intended to be used by applications which allows the user to set the UTC offset and DST flag manually (e.g. examples/WorldClock.ino).

Definition at line 125 of file TimeZone.h.

void ace_time::TimeZone::isDst ( bool  dst)
inline

Sets the isDst() flag of the underlying ManualZoneSpecifier.

Does nothing for any other type of TimeZone. This is a convenience method for applications that allow the user to set the DST flag manually (e.g. examples/WorldClock).

Definition at line 137 of file TimeZone.h.

void ace_time::TimeZone::printAbbrevTo ( Print &  printer,
acetime_t  epochSeconds 
) const

Print the time zone abbreviation for the given epochSeconds.

Definition at line 21 of file TimeZone.cpp.

void ace_time::TimeZone::printTo ( Print &  printer) const

Print the human readable representation of the time zone.

Definition at line 7 of file TimeZone.cpp.

Member Data Documentation

TimeOffset ace_time::TimeZone::mOffset

Used if mType == mTypeFixed.

Definition at line 178 of file TimeZone.h.

const ZoneSpecifier* ace_time::TimeZone::mZoneSpecifier

Used if mType == mTypeZoneSpecifier.

Definition at line 181 of file TimeZone.h.


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