This is an automated email from the ASF dual-hosted git repository.
wesm pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/master by this push:
new 10a571b ARROW-5545: [C++][Docs] Clarify expectation of UTC values for
timestamps with time zones
10a571b is described below
commit 10a571b4334da95f00411a64959170fd08e0dba1
Author: TP Boudreau <[email protected]>
AuthorDate: Fri Jun 14 07:59:40 2019 -0500
ARROW-5545: [C++][Docs] Clarify expectation of UTC values for timestamps
with time zones
Doxygen comments only. No code changes.
Author: TP Boudreau <[email protected]>
Closes #4555 from tpboudreau/ARROW-5545 and squashes the following commits:
305b0d84d <TP Boudreau> Add comments for three temporal DataTypes
---
cpp/src/arrow/type.h | 36 ++++++++++++++++++++++++++++++++++++
1 file changed, 36 insertions(+)
diff --git a/cpp/src/arrow/type.h b/cpp/src/arrow/type.h
index 98d2e4e..b581739 100644
--- a/cpp/src/arrow/type.h
+++ b/cpp/src/arrow/type.h
@@ -769,6 +769,8 @@ class ARROW_EXPORT TimeType : public TemporalType, public
ParametricType {
TimeUnit::type unit_;
};
+/// Concrete type class for 32-bit time data (as number of seconds or
milliseconds
+/// since midnight)
class ARROW_EXPORT Time32Type : public TimeType {
public:
static constexpr Type::type type_id = Type::TIME32;
@@ -783,6 +785,8 @@ class ARROW_EXPORT Time32Type : public TimeType {
std::string name() const override { return "time32"; }
};
+/// Concrete type class for 64-bit time data (as number of microseconds or
nanoseconds
+/// since midnight)
class ARROW_EXPORT Time64Type : public TimeType {
public:
static constexpr Type::type type_id = Type::TIME64;
@@ -797,6 +801,38 @@ class ARROW_EXPORT Time64Type : public TimeType {
std::string name() const override { return "time64"; }
};
+/// \brief Concrete type class for datetime data (as number of seconds,
milliseconds,
+/// microseconds or nanoseconds since UNIX epoch)
+///
+/// If supplied, the timezone string should take either the form (i)
"Area/Location",
+/// with values drawn from the names in the IANA Time Zone Database (such as
+/// "Europe/Zurich"); or (ii) "(+|-)HH:MM" indicating an absolute offset from
GMT
+/// (such as "-08:00"). To indicate a native UTC timestamp, one of the
strings "UTC",
+/// "Etc/UTC" or "+00:00" should be used.
+///
+/// If any non-empty string is supplied as the timezone for a TimestampType,
then the
+/// Arrow field containing that timestamp type (and by extension the column
associated
+/// with such a field) is considered "timezone-aware". The integer arrays
that comprise
+/// a timezone-aware column must contain UTC normalized datetime values,
regardless of
+/// the contents of their timezone string. More precisely, (i) the producer
of a
+/// timezone-aware column must populate its constituent arrays with valid UTC
values
+/// (performing offset conversions from non-UTC values if necessary); and (ii)
the
+/// consumer of a timezone-aware column may assume that the column's values
are directly
+/// comparable (that is, with no offset adjustment required) to the values of
any other
+/// timezone-aware column or to any other valid UTC datetime value (provided
all values
+/// are expressed in the same units).
+///
+/// If a TimestampType is constructed without a timezone (or, equivalently, if
the
+/// timezone supplied is an empty string) then the resulting Arrow field
(column) is
+/// considered "timezone-naive". The producer of a timezone-naive column may
populate
+/// its constituent integer arrays with datetime values from any timezone; the
consumer
+/// of a timezone-naive column should make no assumptions about the
interoperability or
+/// comparability of the values of such a column with those of any other
timestamp
+/// column or datetime value.
+///
+/// If a timezone-aware field contains a recognized timezone, its values may be
+/// localized to that locale upon display; the values of timezone-naive fields
must
+/// always be displayed "as is", with no localization performed on them.
class ARROW_EXPORT TimestampType : public TemporalType, public ParametricType {
public:
using Unit = TimeUnit;
