Skip to content

Migrating from V1 to V2 interface

Jump to bottom
Bradley White edited this page Dec 6, 2021 · 5 revisions

CCTZ was first announced in September 2015. We refer to that version of the library as v1, and the interface to the v1 library is described in the src/cctz.h file.

In early April 2016 CCTZ v2 was released, which added support for a complete civil-time library as well as a time-zone library. Unfortunately, the interface for v2 is not backward compatible with v1, but the migration to the new v2 interface should not be very difficult. This document exists to help callers with the transition from the v1 interface to the v2 interface.

Which headers should I use?

The complete v1 interface is defined in a single header file: src/cctz.h. CCTZ v2 includes two separate libraries that are each declared in their own header file.

The civil-time library is independent and usable on its own. The time-zone library depends on the civil-time library as well as <chrono>.

The v1 interface still seems to work, what gives?

As a temporary measure to ease the transition to the v2 API, we've included a src/cctz.h file that implements the v1 API in terms of the v2 API. This file will be deleted on October 1, 2016, so please migrate to the new API before then. If that is not possible, just build against a git commit that still has the v1 API that you need.

Can you quickly summarize the differences between the v1 and v2 APIs?

Some differences:

  • One obvious difference is that the v2 API uses the more standard snake case naming style for functions and classes (e.g., cctz::time_zone instead of cctz::TimeZone).
  • Another difference is that the collection of year, month, day, hour, minute, and second arguments are now handled by a standalone civil-time library that is declared in include/civil_time.h. So instead of a function accepting 6 separate integer arguments, it will now accept something like a single cctz::civil_second. Additionally, this civil-time library is usable on its own if time-zone support is not needed.
  • The v1 cctz::MakeTime() and cctz::BreakTime() functions are now both called cctz::convert(). As before, cctz::convert() converts between absolute and civil time using the provided cctz::time_zone.
Clone this wiki locally