{"id":13418830,"url":"https://github.com/google/cctz","last_synced_at":"2026-02-25T08:41:47.598Z","repository":{"id":1613595,"uuid":"42454583","full_name":"google/cctz","owner":"google","description":"CCTZ is a C++ library for translating between absolute and civil times using the rules of a time zone.","archived":false,"fork":false,"pushed_at":"2024-11-19T19:13:30.000Z","size":1593,"stargazers_count":598,"open_issues_count":6,"forks_count":167,"subscribers_count":40,"default_branch":"master","last_synced_at":"2025-01-07T16:07:29.686Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/google.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-09-14T14:42:18.000Z","updated_at":"2025-01-02T13:35:44.000Z","dependencies_parsed_at":"2023-10-11T18:58:36.375Z","dependency_job_id":"dab0a498-2d4f-4a64-b25e-141aeafd9056","html_url":"https://github.com/google/cctz","commit_stats":{"total_commits":470,"total_committers":53,"mean_commits":8.867924528301886,"dds":0.5234042553191489,"last_synced_commit":"3803b96130934f48b1fc1d47c5da5f542949c4b0"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fcctz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fcctz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fcctz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fcctz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/google","download_url":"https://codeload.github.com/google/cctz/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243685505,"owners_count":20330980,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T22:01:07.620Z","updated_at":"2025-10-21T04:03:54.869Z","avatar_url":"https://github.com/google.png","language":"C++","readme":"This is not an official Google product.\n\n# Overview\n\nCCTZ contains two libraries that cooperate with `\u003cchrono\u003e` to give C++\nprogrammers all the necessary tools for computing with dates, times, and time\nzones in a simple and correct manner. The libraries in CCTZ are:\n\n*   **The Civil-Time Library** \u0026mdash; This is a header-only library that\n    supports computing with human-scale time, such as dates (which are\n    represented by the `cctz::civil_day` class). This library is declared in\n    [`include/cctz/civil_time.h`](https://github.com/google/cctz/blob/master/include/cctz/civil_time.h).\n*   **The Time-Zone Library** \u0026mdash; This library uses the IANA time zone\n    database that is installed on the system to convert between *absolute time*\n    and *civil time*. This library is declared in\n    [`include/cctz/time_zone.h`](https://github.com/google/cctz/blob/master/include/cctz/time_zone.h).\n\nThese libraries are currently known to work on **Linux**, **Mac OS X**, and\n**Android**.\n\nThey will also work on **Windows** if you install the zoneinfo files. We are\ninterested, though, in an implementation of the cctz::TimeZoneIf interface that\ncalls the Windows time APIs instead. Please contact us if you're interested in\ncontributing.\n\n# Getting Started\n\nCCTZ is best built and tested using the [Bazel](https://bazel.io) build system\nand the [Google Test](https://github.com/google/googletest) framework. (There is\nalso a simple [`Makefile`](https://github.com/google/cctz/blob/master/Makefile)\nand a\n[`CMakeLists.txt`](https://github.com/google/cctz/blob/master/CMakeLists.txt)\nthat should work if you're unable to use Bazel.)\n\n1.  Download/install\n    [Bazel](https://docs.bazel.build/versions/master/install.html)\n2.  Get the cctz source: `git clone https://github.com/google/cctz.git` then `cd\n    cctz`\n3.  Build cctz and run the tests: `bazel test :all`\n\nWith CMake:\n\n1.  Make sure you have CMake \u003e= 3.16 installed.\n2.  Get the cctz source: `git clone https://github.com/google/cctz.git` then `cd\n    cctz`.\n3.  Build cctz so that is can be used by shared libraries and run the tests (use\n    `-DBUILD_TESTING=OFF` to skip the tests):\n\n        mkdir mybuild\n        cd mybuild\n        cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_POSITION_INDEPENDENT_CODE=ON ..\n        cmake --build . --config Release\n        ctest\n        cmake --build . --config Release --target install\n\n4.  Use in your CMake-based project with:\n\n    ```cmake\n    find_package(cctz REQUIRED)\n    add_executable(mytarget file.cc)\n    target_link_libraries(mytarget cctz::cctz)\n    ```\n\nNote: When using CCTZ in your own project, you might find it easiest to compile\nthe sources using your existing build system.\n\nNext Steps:\n\n1.  See the documentation for the libraries in CCTZ:\n    *   Civil Time:\n        [`include/cctz/civil_time.h`](https://github.com/google/cctz/blob/master/include/cctz/civil_time.h)\n    *   Time Zone:\n        [`include/cctz/time_zone.h`](https://github.com/google/cctz/blob/master/include/cctz/time_zone.h)\n2.  Look at the examples in https://github.com/google/cctz/tree/master/examples\n3.  Join our mailing list to ask questions and keep informed of changes:\n    *   https://groups.google.com/forum/#!forum/cctz\n\n# Fundamental Concepts\n\n*[The concepts presented here describe general truths about the problem domain\nand are library and language agnostic. An understanding of these concepts helps\nthe programmer correctly reason about even the most-complicated time-programming\nchallenges and produce the simplest possible solutions.]*\n\nThere are two main ways to think about time in a computer program: as *absolute\ntime*, and as *civil time*. Both have their uses and it is important to\nunderstand when each is appropriate. Absolute and civil times may be converted\nback and forth using a *time zone* \u0026mdash; this is the only way to correctly\nconvert between them. Let us now look more deeply at the three main concepts of\ntime programming: Absolute Time, Civil Time, and Time Zone.\n\n*Absolute time* uniquely and universally represents a specific instant in time.\nIt has no notion of calendars, or dates, or times of day. Instead, it is a\nmeasure of the passage of real time, typically as a simple count of ticks since\nsome epoch. Absolute times are independent of all time zones and do not suffer\nfrom human-imposed complexities such as daylight-saving time (DST). Many C++\ntypes exist to represent absolute times, classically `time_t` and more recently\n`std::chrono::time_point`.\n\n*Civil time* is the legally recognized representation of time for ordinary\naffairs (cf. https://www.merriam-webster.com/dictionary/civil). It is a\nhuman-scale representation of time that consists of the six fields \u0026mdash; year,\nmonth, day, hour, minute, and second (sometimes shortened to \"YMDHMS\") \u0026mdash;\nand it follows the rules of the Proleptic Gregorian Calendar, with 24-hour days\ndivided into 60-minute hours and 60-second minutes. Like absolute times, civil\ntimes are also independent of all time zones and their related complexities\n(e.g., DST). While `std::tm` contains the six civil-time fields (YMDHMS), plus a\nfew more, it does not have behavior to enforce the rules of civil time.\n\n*Time zones* are geo-political regions within which human-defined rules are\nshared to convert between the absolute-time and civil-time domains. A time\nzone's rules include things like the region's offset from the UTC time standard,\ndaylight-saving adjustments, and short abbreviation strings. Time zones often\nhave a history of disparate rules that apply only for certain periods, because\nthe rules may change at the whim of a region's local government. For this\nreason, time-zone rules are usually compiled into data snapshots that are used\nat runtime to perform conversions between absolute and civil times. There is\ncurrently no C++ standard library supporting arbitrary time zones.\n\nIn order for programmers to reason about and program applications that correctly\ndeal with these concepts, they must have a library that correctly implements the\nabove concepts. CCTZ adds to the existing C++11 `\u003cchrono\u003e` library to fully\nimplement the above concepts.\n\n*   Absolute time \u0026mdash; This is implemented by the existing C++11\n    [`\u003cchrono\u003e`](https://en.cppreference.com/w/cpp/chrono) library without\n    modification. For example, an absolute point in time is represented by a\n    `std::chrono::time_point`.\n*   Civil time \u0026mdash; This is implemented by the\n    [`include/cctz/civil_time.h`](https://github.com/google/cctz/blob/master/include/cctz/civil_time.h)\n    library that is provided as part of CCTZ. For example, a \"date\" is\n    represented by a `cctz::civil_day`.\n*   Time zone \u0026mdash; This is implemented by the\n    [`include/cctz/time_zone.h`](https://github.com/google/cctz/blob/master/include/cctz/time_zone.h)\n    library that is provided as part of CCTZ. For example, a time zone is\n    represented by an instance of the class `cctz::time_zone`.\n\n# Examples\n\n## Hello February 2016\n\nThis \"hello world\" example uses a for-loop to iterate the days from the first of\nFebruary until the month of March. Each day is streamed to output, and if the\nday happens to be the 29th, we also output the day of the week.\n\n```\n#include \u003ciostream\u003e\n#include \"cctz/civil_time.h\"\n\nint main() {\n  for (cctz::civil_day d(2016, 2, 1); d \u003c cctz::civil_month(2016, 3); ++d) {\n    std::cout \u003c\u003c \"Hello \" \u003c\u003c d;\n    if (d.day() == 29) {\n      std::cout \u003c\u003c \" \u003c- leap day is a \" \u003c\u003c cctz::get_weekday(d);\n    }\n    std::cout \u003c\u003c \"\\n\";\n  }\n}\n```\n\nThe output of the above program is\n\n```\nHello 2016-02-01\nHello 2016-02-02\nHello 2016-02-03\n[...]\nHello 2016-02-27\nHello 2016-02-28\nHello 2016-02-29 \u003c- leap day is a Monday\n```\n\n## One giant leap\n\nThis example shows how to use all three libraries (`\u003cchrono\u003e`, civil time, and\ntime zone) together. In this example, we know that viewers in New York watched\nNeil Armstrong's first walk on the moon on July 20, 1969 at 10:56 PM. But we'd\nlike to see what time it was for our friend watching in Sydney, Australia.\n\n```\n#include \u003ciostream\u003e\n#include \"cctz/civil_time.h\"\n#include \"cctz/time_zone.h\"\n\nint main() {\n  cctz::time_zone nyc;\n  cctz::load_time_zone(\"America/New_York\", \u0026nyc);\n\n  // Converts the input civil time in NYC to an absolute time.\n  const auto moon_walk =\n    cctz::convert(cctz::civil_second(1969, 7, 20, 22, 56, 0), nyc);\n\n  std::cout \u003c\u003c \"Moon walk in NYC: \"\n            \u003c\u003c cctz::format(\"%Y-%m-%d %H:%M:%S %Ez\\n\", moon_walk, nyc);\n\n  cctz::time_zone syd;\n  if (!cctz::load_time_zone(\"Australia/Sydney\", \u0026syd)) return -1;\n  std::cout \u003c\u003c \"Moon walk in SYD: \"\n            \u003c\u003c cctz::format(\"%Y-%m-%d %H:%M:%S %Ez\\n\", moon_walk, syd);\n}\n```\n\nThe output of the above program is\n\n```\nMoon walk in NYC: 1969-07-20 22:56:00 -04:00\nMoon walk in SYD: 1969-07-21 12:56:00 +10:00\n```\n\nThis example shows that the absolute time (the `std::chrono::time_point`) of the\nfirst walk on the moon is the same no matter the time zone of the viewer (the\nsame time point is used in both calls to `format()`). The only difference is the\ntime zone in which the `moon_walk` time point is rendered. And in this case we\ncan see that our friend in Sydney was probably eating lunch while watching that\nhistoric event.\n\n# References\n\n*   CCTZ [FAQ](https://github.com/google/cctz/wiki/FAQ)\n*   See also the [Time Programming Fundamentals](https://youtu.be/2rnIHsqABfM)\n    talk from CppCon 2015 ([slides available here](https://goo.gl/ofof4N)). This\n    talk mostly describes the older CCTZ v1 API, but the *concepts* are the\n    same.\n*   ISO C++ proposal to standardize the Civil-Time Library:\n    https://github.com/devjgm/papers/blob/master/d0215r1.md\n*   ISO C++ proposal to standardize the Time-Zone Library:\n    https://github.com/devjgm/papers/blob/master/d0216r1.md\n","funding_links":[],"categories":["TODO scan for Android support in followings","Miscellaneous","C++ (70)","Projects built with Bazel"],"sub_categories":["Google projects"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle%2Fcctz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoogle%2Fcctz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle%2Fcctz/lists"}