Skip to content

Commit

Permalink
CCTZ Version 2.
Browse files Browse the repository at this point in the history 
Adds civil-time classes and new time-zone interfaces.
These are being proposed for C++ standardization.
  • Loading branch information
@devbww
devbww committed Mar 3, 2016
1 parent 9d4de9f commit 84abf32
Show file tree
Hide file tree
Showing 40 changed files with 3,201 additions and 1,588 deletions.
166 changes: 166 additions & 0 deletions BUILD
View file
@@ -0,0 +1,166 @@
# Copyright 2016 Google Inc. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

### libraries

cc_library(
name = "cctz",
srcs = [
"src/time_zone_format.cc",
"src/time_zone_if.cc",
"src/time_zone_if.h",
"src/time_zone_impl.cc",
"src/time_zone_impl.h",
"src/time_zone_info.cc",
"src/time_zone_info.h",
"src/time_zone_libc.cc",
"src/time_zone_libc.h",
"src/time_zone_lookup.cc",
"src/time_zone_posix.cc",
"src/time_zone_posix.h",
"src/tzfile.h",
],
hdrs = [
"src/civil_time.h",
"src/time_zone.h",
],
includes = ["src"],
linkopts = [
"-lm",
"-lpthread",
],
textual_hdrs = ["src/civil_time_detail.h"],
visibility = ["//visibility:public"],
)

### tests

# Builds the Google Test source that was fetched from another repository.
cc_library(
name = "gtest",
srcs = glob(
[
"google*/src/*.cc",
],
exclude = glob([
"google*/src/*-all.cc",
"googlemock/src/gmock_main.cc",
]),
),
hdrs = glob(["*/include/**/*.h"]),
includes = [
"googlemock/",
"googlemock/include",
"googletest/",
"googletest/include",
],
linkopts = ["-pthread"],
textual_hdrs = ["googletest/src/gtest-internal-inl.h"],
visibility = ["//visibility:public"],
)

cc_test(
name = "civil_time_test",
size = "small",
srcs = ["src/civil_time_test.cc"],
deps = [
"@gtest//:gtest",
":cctz",
],
)

cc_test(
name = "time_zone_format_test",
size = "small",
srcs = ["src/time_zone_format_test.cc"],
deps = [
"@gtest//:gtest",
":cctz",
],
)

cc_test(
name = "time_zone_lookup_test",
size = "small",
srcs = ["src/time_zone_lookup_test.cc"],
deps = [
"@gtest//:gtest",
":cctz",
],
)

### examples

cc_binary(
name = "classic",
srcs = ["examples/classic.cc"],
)

cc_binary(
name = "epoch_shift",
srcs = ["examples/epoch_shift.cc"],
deps = [
":cctz",
],
)

cc_binary(
name = "example1",
srcs = ["examples/example1.cc"],
deps = [
":cctz",
],
)

cc_binary(
name = "example2",
srcs = ["examples/example2.cc"],
deps = [
":cctz",
],
)

cc_binary(
name = "example3",
srcs = ["examples/example3.cc"],
deps = [
":cctz",
],
)

cc_binary(
name = "example4",
srcs = ["examples/example4.cc"],
deps = [
":cctz",
],
)

cc_binary(
name = "hello",
srcs = ["examples/hello.cc"],
deps = [
":cctz",
],
)

### binaries

cc_binary(
name = "time_tool",
srcs = ["src/time_tool.cc"],
deps = [
":cctz",
],
)
37 changes: 21 additions & 16 deletions CONTRIBUTING.md
View file
@@ -1,24 +1,29 @@
Want to contribute? Great! First, read this page (including the small print at the end).
Want to contribute? Great! First, read this page (including the small print at
the end).

### Before you contribute
Before we can use your code, you must sign the
[Google Individual Contributor License Agreement](https://developers.google.com/open-source/cla/individual?csw=1)
(CLA), which you can do online. The CLA is necessary mainly because you own the
copyright to your changes, even after your contribution becomes part of our
codebase, so we need your permission to use and distribute your code. We also
need to be sure of various other things—for instance that you'll tell us if you
know that your code infringes on other people's patents. You don't have to sign
the CLA until after you've submitted your code for review and a member has
approved it, but you must do it before we can put your code into our codebase.
Before you start working on a larger contribution, you should get in touch with
us first through the issue tracker with your idea so that we can help out and
possibly guide you. Coordinating up front makes it much easier to avoid
frustration later on.

Before we can use your code, you must sign the [Google Individual Contributor
License Agreement]
(https://developers.google.com/open-source/cla/individual?csw=1) (CLA), which
you can do online. The CLA is necessary mainly because you own the copyright to
your changes, even after your contribution becomes part of our codebase, so we
need your permission to use and distribute your code. We also need to be sure of
various other things—for instance that you'll tell us if you know that
your code infringes on other people's patents. You don't have to sign the CLA
until after you've submitted your code for review and a member has approved it,
but you must do it before we can put your code into our codebase. Before you
start working on a larger contribution, you should get in touch with us first
through the issue tracker with your idea so that we can help out and possibly
guide you. Coordinating up front makes it much easier to avoid frustration later
on.

### Code reviews

All submissions, including submissions by project members, require review. We
use Github pull requests for this purpose.

### The small print
Contributions made by corporations are covered by a different agreement than
the one above, the Software Grant and Corporate Contributor License Agreement.

Contributions made by corporations are covered by a different agreement than the
one above, the Software Grant and Corporate Contributor License Agreement.
90 changes: 90 additions & 0 deletions Makefile
View file
@@ -0,0 +1,90 @@
# Copyright 2016 Google Inc. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

CC = $(CXX)
OPT = -g
# TEST_FLAGS =
# TEST_LIBS =
CPPFLAGS = -Isrc $(TEST_FLAGS) -Wall -std=c++11 -pthread $(OPT) -fPIC
VPATH = examples:src
LDFLAGS = -pthread
LDLIBS = $(TEST_LIBS) -lm
ARFLAGS = rcs
PREFIX = /usr/local

CCTZ_LIB = libcctz.a

CCTZ_HDRS = \
civil_time.h \
civil_time_detail.h \
time_zone.h

CCTZ_OBJS = \
time_zone_format.o \
time_zone_if.o \
time_zone_impl.o \
time_zone_info.o \
time_zone_libc.o \
time_zone_lookup.o \
time_zone_posix.o

# TESTS = civil_time_test time_zone_lookup_test time_zone_format_test
TOOLS = time_tool
EXAMPLES = classic epoch_shift hello example1 example2 example3 example4

all: $(TESTS) $(TOOLS) $(EXAMPLES)

$(TESTS) $(TOOLS) $(EXAMPLES): $(CCTZ_LIB)

$(CCTZ_LIB): $(CCTZ_OBJS)
$(AR) $(ARFLAGS) $@ $(CCTZ_OBJS)

install: $(CCTZ_HDRS) $(CCTZ_LIB)
sudo cp -p $(CCTZ_HDRS) $(PREFIX)/include
sudo cp -p $(CCTZ_LIB) $(PREFIX)/lib

clean:
@$(RM) $(EXAMPLES:=.o) $(EXAMPLES)
@$(RM) $(TOOLS:=.o) $(TOOLS)
@$(RM) $(TESTS:=.o) $(TESTS)
@$(RM) $(CCTZ_OBJS) $(CCTZ_LIB)

# dependencies

time_zone_format.o: time_zone.h civil_time.h time_zone_if.h
time_zone_if.o: time_zone_if.h time_zone.h civil_time.h \
time_zone_info.h time_zone_libc.h tzfile.h
time_zone_impl.o: time_zone_impl.h time_zone.h civil_time.h \
time_zone_info.h time_zone_if.h tzfile.h
time_zone_info.o: time_zone_info.h time_zone.h civil_time.h \
time_zone_posix.h time_zone_if.h tzfile.h
time_zone_libc.o: time_zone_libc.h time_zone.h civil_time.h \
time_zone_if.h
time_zone_lookup.o: time_zone.h civil_time.h \
time_zone_impl.h time_zone_info.h time_zone_if.h tzfile.h
time_zone_posix.o: time_zone_posix.h

civil_time_test.o: civil_time.h
time_zone_lookup_test.o: time_zone.h civil_time.h
time_zone_format_test.o: time_zone.h civil_time.h

time_tool.o: time_zone.h civil_time.h

hello.o: time_zone.h civil_time.h
example1.o: time_zone.h civil_time.h
example2.o: time_zone.h civil_time.h
example3.o: time_zone.h civil_time.h
example4.o: time_zone.h civil_time.h

civil_time.h: civil_time_detail.h
48 changes: 27 additions & 21 deletions README.md
View file
Expand Up @@ -3,27 +3,29 @@ This is not an official Google product.
# Overview

CCTZ (C++ Time Zone) is a library for translating between absolute times and
civil times (see the [Fundamental Concepts](#fundamental-concepts) section below for an explanation of
these terms) using the rules defined by a time zone.
civil times (see the [Fundamental Concepts](#fundamental-concepts) section below
for an explanation of these terms) using the rules defined by a time zone.

This library currently works on **Linux** and **Mac OS X**,
using the standard IANA time zone data
installed on the system in `/usr/share/zoneinfo`.
This library currently works on **Linux** and **Mac OS X**, using the standard
IANA time zone data installed on the system in `/usr/share/zoneinfo`.

CCTZ is built using http://bazel.io and tested using
https://github.com/google/googletest

# Getting Started

1. Download/install Bazel http://bazel.io/docs/install.html
2. Get the cctz source: `git clone https://github.com/google/cctz.git` then `cd cctz`
3. Build cctz and run the tests: `bazel test ...`
4. See the CCTZ API, which is defined in the header [cctz.h](https://github.com/google/cctz/blob/master/src/cctz.h)
5. Look at the examples in https://github.com/google/cctz/tree/master/examples
1. Download/install Bazel http://bazel.io/docs/install.html
2. Get the cctz source: `git clone https://github.com/google/cctz.git` then `cd
cctz`
3. Build cctz and run the tests: `bazel test :all`
4. See the CCTZ API, which is defined in the header [time_zone.h]
(https://github.com/google/cctz/blob/master/src/time_zone.h)
5. Look at the examples in https://github.com/google/cctz/tree/master/examples

# Fundamental Concepts

[ See also the [Time Programming Fundamentals](https://youtu.be/2rnIHsqABfM) talk from CppCon 2015 ([slides available here](http://goo.gl/ofof4N)) ]
[ See also the [Time Programming Fundamentals](https://youtu.be/2rnIHsqABfM)
talk from CppCon 2015 ([slides available here](http://goo.gl/ofof4N)) ]

There are two ways to represent time: as an *Absolute Time*, and as a *Civil
Time*. An absolute time uniquely and universally represents a specific instant
Expand All @@ -42,10 +44,10 @@ the values shown on the clock hanging on your wall and the Dilbert calendar on
your desk. Your friend living across the country may, at the same moment, have a
different civil time showing on their Far Side calendar and clock. For example,
if you lived in New York on July 20, 1969 you witnessed Neil Armstrong's small
step at 10:56 in the evening, whereas your friend in San Francisco saw the
same thing at 7:56, and your pen pal in Sydney saw it while eating lunch at
12:56 on July 21. You all would agree on the absolute time of the event, but
you'd disagree about the civil time.
step at 10:56 in the evening, whereas your friend in San Francisco saw the same
thing at 7:56, and your pen pal in Sydney saw it while eating lunch at 12:56 on
July 21. You all would agree on the absolute time of the event, but you'd
disagree about the civil time.

Time zones are geo-political regions within which rules are shared to convert
between absolute times and civil times. The geographical nature of time zones is
Expand All @@ -59,8 +61,8 @@ complicated, which is why you should always let a time library do time-zone
calculations for you.

Time zones define the relationship between absolute and civil times. Given an
absolute or civil time and a time zone, you can compute the other, as shown
in the example below.
absolute or civil time and a time zone, you can compute the other, as shown in
the example below.

```
Civil Time = F(Absolute Time, Time Zone)
Expand All @@ -76,8 +78,12 @@ relationships will still exist.

# These concepts in CCTZ

* An *absolute* time is represented by any `std::chrono::time_point` defined on the `std::chrono::system_clock`.
* A *civil* time is represented by a `cctz::Breakdown`, or even separate integers.
* A *time zone* is represented by a `cctz::TimeZone`.
* An *absolute* time is represented by any `std::chrono::time_point` defined
on the `std::chrono::system_clock`.
* A *civil* time is represented by a `cctz::Breakdown`, or even separate
integers.
* A *time zone* is represented by a `cctz::TimeZone`.

For more information, see the full API and documentation are described in the header [cctz.h](https://github.com/google/cctz/blob/master/src/cctz.h).
For more information, see the full API and documentation are described in the
header [time_zone.h]
(https://github.com/google/cctz/blob/master/src/time_zone.h).
2 changes: 1 addition & 1 deletion WORKSPACE
View file
Expand Up @@ -2,5 +2,5 @@ new_git_repository(
name = "gtest",
remote = "https://github.com/google/googletest.git",
commit = "de411c3e80120f8dcc2a3f4f62f3ca692c0431d7",
build_file = "test/BUILD",
build_file = "BUILD",
)

0 comments on commit 84abf32

Please sign in to comment.