feat: implement literal expressions with binary serialization support (#185)

## Summary
Implements binary serialization and deserialization support for Literal
values, enabling conversion between Literal objects and binary
representations. Adds comprehensive formatting support for date, time,
and timestamp types.

  ## Changes
- Added `Conversions` utility class
(`src/iceberg/util/conversions.cc/h`) with `ToBytes()` and `FromBytes()`
methods for `Literal` binary serialization/deserialization
- Added literal formatting utilities
(`src/iceberg/util/literal_format.cc/h`) for `date`, `time`,
`timestamp`, and `timestamptz` formatting
- Implemented `Literal` serialization methods: Replaced placeholder
implementations of `Serialize()` and `Deserialize()` with full
functionality
- Enhanced `Literal::ToString()`: Added support for `date`, `time`,
`timestamp`, and `timestamptz` types
- Added `TypeId` string conversion: Implemented `ToString(TypeId)`
utility function for type name lookups
- Updated CMake configuration: Added new util source files to build
system

 ## Test Plan
- Comprehensive binary round-trip tests for all primitive types
(boolean, int, long, float, double, string, binary)
- Serialization correctness tests verify exact byte representations
match expected formats
- Date/time formatting tests ensure proper ISO 8601 compatible string
output
- Modify existing test(e.g. manifest_reader_test.cc) to use binary
serialization.

Author: HeartLinked

src/iceberg/CMakeLists.txt

@@ -55,10 +55,11 @@ set(ICEBERG_SOURCES
     manifest_reader_internal.cc
     manifest_writer.cc
     arrow_c_data_guard_internal.cc
+    util/conversions.cc
     util/decimal.cc
+    util/gzip_internal.cc
     util/murmurhash3_internal.cc
     util/timepoint.cc
-    util/gzip_internal.cc
     util/uuid.cc)
 
 set(ICEBERG_STATIC_BUILD_INTERFACE_LIBS)

src/iceberg/expression/literal.cc

@@ -23,6 +23,8 @@
 #include <concepts>
 
 #include "iceberg/exception.h"
+#include "iceberg/util/conversions.h"
+#include "iceberg/util/macros.h"
 
 namespace iceberg {
 
@@ -149,13 +151,18 @@ Literal Literal::Binary(std::vector<uint8_t> value) {
   return {Value{std::move(value)}, binary()};
 }
 
+Literal Literal::Fixed(std::vector<uint8_t> value) {
+  auto length = static_cast<int32_t>(value.size());
+  return {Value{std::move(value)}, fixed(length)};
+}
+
 Result<Literal> Literal::Deserialize(std::span<const uint8_t> data,
                                      std::shared_ptr<PrimitiveType> type) {
-  return NotImplemented("Deserialization of Literal is not implemented yet");
+  return Conversions::FromBytes(std::move(type), data);
 }
 
 Result<std::vector<uint8_t>> Literal::Serialize() const {
-  return NotImplemented("Serialization of Literal is not implemented yet");
+  return Conversions::ToBytes(*this);
 }
 
 // Getters
@@ -189,7 +196,7 @@ bool Literal::operator==(const Literal& other) const { return (*this <=> other)
 // Three-way comparison operator
 std::partial_ordering Literal::operator<=>(const Literal& other) const {
   // If types are different, comparison is unordered
-  if (type_->type_id() != other.type_->type_id()) {
+  if (*type_ != *other.type_) {
     return std::partial_ordering::unordered;
   }
 
@@ -216,6 +223,7 @@ std::partial_ordering Literal::operator<=>(const Literal& other) const {
     }
 
     case TypeId::kLong:
+    case TypeId::kTime:
     case TypeId::kTimestamp:
     case TypeId::kTimestampTz: {
       auto this_val = std::get<int64_t>(value_);
@@ -249,6 +257,12 @@ std::partial_ordering Literal::operator<=>(const Literal& other) const {
       return this_val <=> other_val;
     }
 
+    case TypeId::kFixed: {
+      auto& this_val = std::get<std::vector<uint8_t>>(value_);
+      auto& other_val = std::get<std::vector<uint8_t>>(other.value_);
+      return this_val <=> other_val;
+    }
+
     default:
       // For unsupported types, return unordered
       return std::partial_ordering::unordered;
@@ -294,9 +308,17 @@ std::string Literal::ToString() const {
       }
       return result;
     }
+    case TypeId::kFixed: {
+      const auto& fixed_data = std::get<std::vector<uint8_t>>(value_);
+      std::string result;
+      result.reserve(fixed_data.size() * 2);  // 2 chars per byte
+      for (const auto& byte : fixed_data) {
+        std::format_to(std::back_inserter(result), "{:02X}", byte);
+      }
+      return result;
+    }
     case TypeId::kDecimal:
     case TypeId::kUuid:
-    case TypeId::kFixed:
     case TypeId::kDate:
     case TypeId::kTime:
     case TypeId::kTimestamp:

src/iceberg/expression/literal.h

@@ -72,6 +72,7 @@ class ICEBERG_EXPORT Literal : public util::Formattable {
   static Literal Double(double value);
   static Literal String(std::string value);
   static Literal Binary(std::vector<uint8_t> value);
+  static Literal Fixed(std::vector<uint8_t> value);
 
   /// \brief Create a literal representing a null value.
   static Literal Null(std::shared_ptr<PrimitiveType> type) {
@@ -144,11 +145,76 @@ class ICEBERG_EXPORT Literal : public util::Formattable {
  private:
   Literal(Value value, std::shared_ptr<PrimitiveType> type);
 
+  friend class Conversions;
   friend class LiteralCaster;
 
- private:
   Value value_;
   std::shared_ptr<PrimitiveType> type_;
 };
 
+template <TypeId type_id>
+struct LiteralTraits {
+  using ValueType = void;
+};
+
+template <>
+struct LiteralTraits<TypeId::kBoolean> {
+  using ValueType = bool;
+};
+
+template <>
+struct LiteralTraits<TypeId::kInt> {
+  using ValueType = int32_t;
+};
+
+template <>
+struct LiteralTraits<TypeId::kDate> {
+  using ValueType = int32_t;
+};
+
+template <>
+struct LiteralTraits<TypeId::kLong> {
+  using ValueType = int64_t;
+};
+
+template <>
+struct LiteralTraits<TypeId::kTime> {
+  using ValueType = int64_t;
+};
+
+template <>
+struct LiteralTraits<TypeId::kTimestamp> {
+  using ValueType = int64_t;
+};
+
+template <>
+struct LiteralTraits<TypeId::kTimestampTz> {
+  using ValueType = int64_t;
+};
+
+template <>
+struct LiteralTraits<TypeId::kFloat> {
+  using ValueType = float;
+};
+
+template <>
+struct LiteralTraits<TypeId::kDouble> {
+  using ValueType = double;
+};
+
+template <>
+struct LiteralTraits<TypeId::kString> {
+  using ValueType = std::string;
+};
+
+template <>
+struct LiteralTraits<TypeId::kBinary> {
+  using ValueType = std::vector<uint8_t>;
+};
+
+template <>
+struct LiteralTraits<TypeId::kFixed> {
+  using ValueType = std::vector<uint8_t>;
+};
+
 }  // namespace iceberg