AceTime

The AceTime library provides Date, Time, and TimeZone classes which can convert "epoch seconds" from the AceTime Epoch (default 2050-01-01 UTC) to human-readable local date and time fields. Those classes can also convert local date and time between different time zones defined by the IANA TZ database while accurately accounting for DST transitions.

The default AceTime epoch is 2050-01-01, but it can be adjusted by the client application at runtime. The epoch second has the type acetime_t which is a 32-bit signed integer, instead of a 64-bit signed integer. Using the smaller 32-bit integer allows the library to use less CPU and memory resources on 8-bit and 32-bit microcontrollers without native 64-bit integer instructions. The range of a 32-bit integer is about 136 years. To be safe, AceTime timezone functions should be kept well within the bounds of this interval, for example, straddling roughly +/- 60 years of the Epoch::currentEpochYear().

The library provides 5 pre-generated ZoneInfo Databases which are programmatically extracted from the IANA TZ database:

• zonedb ("basic", not usually recommended)
  • accurate over the years [2000,10000)
  • contains a subset of zones and links (~450)
  • compatible with BasicZoneProcessor and BasicZoneManager
• zonedb2025 ("basic", not usually recommended)
  • accurate over the years [2025,10000)
  • contains almost all zones in the TZDB (~600)
  • compatible with BasicZoneProcessor and BasicZoneManager
  • larger than zonedb because it supports more zones
• zonedbx ("extended", recommended for most situations)
  • accurate over the years [2000,10000)
  • contains all zones and links (~600) in the IANA TZ database
  • compatible with ExtendedZoneProcessor and ExtendedZoneManager
• zonedbx2025 ("extended", recommended for most situations)
  • accurate over the years [2025,10000)
  • contains all zones and links (~600) in the IANA TZ database
  • compatible with ExtendedZoneProcessor and ExtendedZoneManager
  • about 10kB smaller than zonedbx because it can ignore transitions before 2025
• zonedbc ("complete", intended for validation testing)
  • accurate over the years [0001,10000)
  • contains all zones and links (~600) the IANA TZ database
  • compatible with CompleteZoneProcessor and CompleteZoneManager

Client applications can choose to incorporate a subset of the zones provided by the above databases to save flash memory size of the application.

Support for Unix time using the Unix epoch of 1970-01-01 is provided through conversion functions of the time_t type. Only the 64-bit version of the time_t type is supported to avoid the Year 2038 Problem.

The library does not support leap seconds and ignores them. Instead it uses UNIX time (aka POSIX time) where the POSIX second is variable in duration compared to the SI second. During a leap second, a POSIX second is conceptually equal to 2 SI seconds, and the POSIX clock changes from 23:59:58 to 23:59:59, then is held for 2 seconds before rolling over to 00:00:00. Most real-time clock (RTC) chips do not support leap seconds either, so the final 23:59:59 second will be held for only one second instead of two, so a clock using AceTime with such an RTC chip will be off by one second after a leap second compared to the atomic UTC clock.

The companion library AceTimeClock provides Clock classes to retrieve the time from more accurate sources, such as an NTP server, or a DS3231 RTC chip. A special version of the Clock class called the SystemClock provides a fast and accurate "epoch seconds" across all Arduino compatible systems. This "epoch seconds" can be given to the classes in this library to convert it into human readable components in different timezones. On the ESP8266 and ESP32, the AceTime library can be used with the SNTP client and the C-library time() function through the 64-bit time_t value. See ESP8266 and ESP32 TimeZones below.

The primordial motivation for creating the AceTime library was to build a digital clock with an OLED or LED display, that would show the date and time of multiple timezones at the same time, while adjusting for any DST changes in the selected timezones automatically. Another major goal of the library is to keep the resource (flash and RAM) consumption as small as practical, to allow substantial portion of this library to run inside the 32kB of flash and 2kB of RAM limits of an Arduino Nano or a SparkFun Pro Micro dev board. To meet that goal, this library does not perform any dynamic allocation of memory. Everything it needs is allocated statically.

This library can be an alternative to the Arduino Time (https://github.com/PaulStoffregen/Time) and Arduino Timezone (https://github.com/JChristensen/Timezone) libraries.

Major Changes in v4.0: Rename LocalDate to PlainDate; LocalTime to PlainTime; LocalDateTime to PlainDateTime. Backwards compatible macros are provided, so most existing programs should still compile. See Migrating to v4.0 for more details. Add zonedb2025 and zonedbx2025 databases which contain DST transitions for year >= 2025, which reduces flash memory size. Replace fold parameter with disambiguate (input) and resolved (output) parameters.

Version: 4.1.0 (2025-11-17, TZDB 2025b)
Changelog: CHANGELOG.md
Migration: MIGRATING.md
User Guide: USER_GUIDE.md

See Also:

• AceTimeClock (https://github.com/bxparks/AceTimeClock)
• acetimec (https://github.com/bxparks/acetimec)
• acetimego (https://github.com/bxparks/acetimego)
• acetimepy (https://github.com/bxparks/acetimepy)

Table of Contents

• Installation
  • Source Code
  • Dependencies
• Documentation
  • HelloDateTime
  • HelloZoneManager
  • WorldClock
• User Guide
• Validation
• Resource Consumption
  • Size Of Classes
  • Zone DB Size
  • Flash And Static Memory
  • CPU Usage
• System Requirements
  • Hardware
  • Tool Chain
  • Operating System
• Motivation and Design Considerations
• Comparison to Other Time Libraries
  • Arduino Time Library
  • C Time Library
  • ESP8266 and ESP32 TimeZones
  • ezTime
  • Micro Time Zone
  • Java Time, Joda-Time, Noda Time
  • Howard Hinnant Date Library
  • Google cctz
• License
• Feedback and Support
• Authors

Installation

The latest stable release is available in the Arduino Library Manager in the IDE. Search for "AceTime". Click install. The Library Manager should automatically install AceTime and its dependent libraries:

• AceTime (https://github.com/bxparks/AceTime)
• AceCommon (https://github.com/bxparks/AceCommon)
• AceSorting (https://github.com/bxparks/AceSorting)

The development version can be installed by cloning the above repos manually. You can copy over the contents to the ./libraries directory used by the Arduino IDE. (The result is a set of directories named ./libraries/AceTime, ./libraries/AceCommon, ./libraries/AceSorting). Or you can create symlinks from ./libraries to these directories. Or you can git clone directly into the ./libraries directory.

The develop branch contains the latest development. The master branch contains the stable releases.

Source Code

The source files are organized as follows:

• src/AceTime.h - main header file
• main library code
  • src/ace_time/ - date and time classes (ace_time:: namespace)
  • src/ace_time/common/ - shared classes and utilities
  • src/ace_time/testing/ - files used in unit tests (ace_time::testing namespace)
  • src/zoneinfo - reading the zone databases, and normalizing the interface for accessing the data records
• zone databases
  • src/zonedb/ - files generated from TZ Database for BasicZoneProcessor (ace_time::zonedb namespace)
  • src/zonedbx/ - files generated from TZ Database for ExtendedZoneProcessor (ace_time::zonedbx namespace)
  • src/zonedbc/ - files generated from TZ Database for CompleteZoneProcessor (ace_time::zonedbc namespace)
  • src/testingzonedb/ - limited subset of zonedb for unit tests
  • src/testingzonedbx/ - limited subset of zonedbx for unit tests
  • src/testingzonedbc/ - limited subset of zonedbc for unit tests
• `tests/
  • unit tests using AUnit
• examples/ - example programs and benchmarks
  • Simple
    • HelloDateTime
      • Simple demo of `Zon