feat: Adds formatting utilities for Unix microseconds

Author: WZhuo

src/iceberg/test/CMakeLists.txt

@@ -111,6 +111,7 @@ add_iceberg_test(util_test
                  formatter_test.cc
                  location_util_test.cc
                  string_util_test.cc
+                 timepoint_test.cc
                  truncate_util_test.cc
                  url_encoder_test.cc
                  uuid_test.cc

src/iceberg/test/meson.build

@@ -87,6 +87,7 @@ iceberg_tests = {
             'formatter_test.cc',
             'location_util_test.cc',
             'string_util_test.cc',
+            'timepoint_test.cc',
             'truncate_util_test.cc',
             'url_encoder_test.cc',
             'uuid_test.cc',

src/iceberg/test/timepoint_test.cc

@@ -0,0 +1,90 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.
+ */
+
+#include "iceberg/util/timepoint.h"
+
+#include <chrono>
+
+#include <gtest/gtest.h>
+
+#include "iceberg/util/timepoint.h"
+
+namespace iceberg {
+
+TEST(TimePointTest, FormatTimePointMs) {
+  // Unix timestamp for 2026-01-01T00:00:00 is 1767225600000
+  auto time_point = TimePointMsFromUnixMs(1767225600000).value();
+  EXPECT_EQ("2026-01-01T00:00:00.000", FormatTimePointMs(time_point));
+
+  // Unix timestamp for 2026-01-01T12:20:00.123
+  auto time_point2 =
+      TimePointMsFromUnixMs(1767225600123 + (12 * 3600 + 20 * 60) * 1000).value();
+  EXPECT_EQ("2026-01-01T12:20:00.123", FormatTimePointMs(time_point2));
+
+  // Test with a date before 1970 (Unix epoch) - 1969-01-01T00:00:00
+  // Unix timestamp for 1969-01-01T00:00:00 is -31536000000 ms from epoch
+  auto time_point_before_epoch = TimePointMsFromUnixMs(-31536000000).value();
+  EXPECT_EQ("1969-01-01T00:00:00.000", FormatTimePointMs(time_point_before_epoch));
+}
+
+TEST(TimePointTest, FormatUnixMicro) {
+  // Test with whole seconds (micros = 0) - 2026-01-01T00:00:00.000000
+  int64_t unix_micro = 1767225600000000;
+  EXPECT_EQ("2026-01-01T00:00:00", FormatUnixMicro(unix_micro));
+
+  // Test with milliseconds precision (micros ending in 000)
+  int64_t unix_micro_ms = 1767225600001000;
+  EXPECT_EQ("2026-01-01T00:00:00.001", FormatUnixMicro(unix_micro_ms));
+
+  // Test with full microsecond precision
+  int64_t unix_micro_full = 1767225600001234;
+  EXPECT_EQ("2026-01-01T00:00:00.001234", FormatUnixMicro(unix_micro_full));
+
+  // Test with a value that has more micros than a second
+  int64_t unix_micro_over = 1767225661123456;
+  EXPECT_EQ("2026-01-01T00:01:01.123456", FormatUnixMicro(unix_micro_over));
+
+  // Test with a date before 1970
+  int64_t unix_micro_before_epoch = -31536000000000;
+  EXPECT_EQ("1969-01-01T00:00:00", FormatUnixMicro(unix_micro_before_epoch));
+}
+
+TEST(TimePointTest, FormatUnixMicroTz) {
+  // Test with whole seconds (micros = 0)
+  int64_t unix_micro = 1767225600000000;
+  EXPECT_EQ("2026-01-01T00:00:00+00:00", FormatUnixMicroTz(unix_micro));
+
+  // Test with milliseconds precision (micros ending in 000)
+  int64_t unix_micro_ms = 1767225600001000;
+  EXPECT_EQ("2026-01-01T00:00:00.001+00:00", FormatUnixMicroTz(unix_micro_ms));
+
+  // Test with full microsecond precision
+  int64_t unix_micro_full = 1767225600001234;
+  EXPECT_EQ("2026-01-01T00:00:00.001234+00:00", FormatUnixMicroTz(unix_micro_full));
+
+  // Test with a value that has more micros than a second
+  int64_t unix_micro_over = 1767225661123456;
+  EXPECT_EQ("2026-01-01T00:01:01.123456+00:00", FormatUnixMicroTz(unix_micro_over));
+
+  // Test with a date before 1970
+  int64_t unix_micro_before_epoch = -31536000000000;
+  EXPECT_EQ("1969-01-01T00:00:00+00:00", FormatUnixMicroTz(unix_micro_before_epoch));
+}
+
+}  // namespace iceberg

src/iceberg/util/timepoint.cc

@@ -20,8 +20,6 @@
 #include "iceberg/util/timepoint.h"
 
 #include <chrono>
-#include <iomanip>
-#include <sstream>
 
 namespace iceberg {
 
@@ -46,18 +44,35 @@ int64_t UnixNsFromTimePointNs(TimePointNs time_point_ns) {
 }
 
 std::string FormatTimePointMs(TimePointMs time_point_ms) {
-  auto unix_ms = UnixMsFromTimePointMs(time_point_ms);
-  auto time_t = std::chrono::system_clock::to_time_t(time_point_ms);
+  return std::format("{:%FT%T}", time_point_ms);
+}
+
+std::string FormatUnixMicro(int64_t unix_micro) {
+  auto tp = std::chrono::time_point<std::chrono::system_clock, std::chrono::seconds>{
+      std::chrono::seconds(unix_micro / kMicrosPerSecond)};
 
-  // Format as ISO 8601-like string: YYYY-MM-DD HH:MM:SS
-  std::ostringstream oss;
-  oss << std::put_time(std::gmtime(&time_t), "%Y-%m-%d %H:%M:%S");
+  auto micros = unix_micro % kMicrosPerSecond;
+  if (micros == 0) {
+    return std::format("{:%FT%T}", tp);
+  } else if (micros % kMicrosPerMillis == 0) {
+    return std::format("{:%FT%T}.{:03d}", tp, micros / kMicrosPerMillis);
+  } else {
+    return std::format("{:%FT%T}.{:06d}", tp, micros);
+  }
+}
 
-  // Add milliseconds
-  auto ms = unix_ms % 1000;
-  oss << "." << std::setfill('0') << std::setw(3) << ms << " UTC";
+std::string FormatUnixMicroTz(int64_t unix_micro) {
+  auto tp = std::chrono::time_point<std::chrono::system_clock, std::chrono::seconds>{
+      std::chrono::seconds(unix_micro / kMicrosPerSecond)};
 
-  return oss.str();
+  auto micros = unix_micro % kMicrosPerSecond;
+  if (micros == 0) {
+    return std::format("{:%FT%T}+00:00", tp);
+  } else if (micros % kMicrosPerMillis == 0) {
+    return std::format("{:%FT%T}.{:03d}+00:00", tp, micros / kMicrosPerMillis);
+  } else {
+    return std::format("{:%FT%T}.{:06d}+00:00", tp, micros);
+  }
 }
 
 }  // namespace iceberg

src/iceberg/util/timepoint.h

@@ -34,6 +34,10 @@ using TimePointMs =
 using TimePointNs =
     std::chrono::time_point<std::chrono::system_clock, std::chrono::nanoseconds>;
 
+constexpr int64_t kMillisPerSecond = 1000;
+constexpr int64_t kMicrosPerMillis = 1000;
+constexpr int64_t kMicrosPerSecond = 1000000;
+
 /// \brief Returns a TimePointMs from a Unix timestamp in milliseconds
 ICEBERG_EXPORT Result<TimePointMs> TimePointMsFromUnixMs(int64_t unix_ms);
 
@@ -49,4 +53,24 @@ ICEBERG_EXPORT int64_t UnixNsFromTimePointNs(TimePointNs time_point_ns);
 /// \brief Returns a human-readable string representation of a TimePointMs
 ICEBERG_EXPORT std::string FormatTimePointMs(TimePointMs time_point_ms);
 
+/// \brief Returns a human-readable string representation of a Unix timestamp in
+/// microseconds
+///
+/// The output will be one of the following forms, according to the precision of the
+/// timestamp:
+///  - yyyy-MM-dd HH:mm:ss
+///  - yyyy-MM-dd HH:mm:ss.SSS
+///  - yyyy-MM-dd HH:mm:ss.SSSSSS
+ICEBERG_EXPORT std::string FormatUnixMicro(int64_t unix_micro);
+
+/// \brief Returns a human-readable string representation of a Unix timestamp in
+/// microseconds with time zone
+///
+/// The output will be one of the following forms, according to the precision of the
+/// timestamp:
+///  - yyyy-MM-dd HH:mm:ss+00:00
+///  - yyyy-MM-dd HH:mm:ss.SSS+00:00
+///  - yyyy-MM-dd HH:mm:ss.SSSSSS+00:00
+ICEBERG_EXPORT std::string FormatUnixMicroTz(int64_t unix_micro);
+
 }  // namespace iceberg