ADD: Add StatMsg v3

Author: threecgreen

CHANGELOG.md

@@ -1,8 +1,15 @@
 # Changelog
 
+## 0.35.0 - TBD
+
+### Enhancements
+- Added a `v3::StatMsg` record with an expanded 64-bit `quantity` field
+- Added `kDbnVersion` constants to each version namespace: `v1`, `v2`, and `v3`
+- Added `kUndefStatQuantity` constants to each version namespace
+
 ## 0.34.2 - 2025-05-06
 
-#### Bug fixes
+### Bug fixes
 - Fixed potential for unaligned records in live and historical streaming requests
 
 ## 0.34.1 - 2025-04-29

include/databento/record.hpp

@@ -20,7 +20,8 @@ namespace databento {
 // Forward declare
 namespace v3 {
 struct InstrumentDefMsg;
-}
+struct StatMsg;
+}  // namespace v3
 
 // Common data for all Databento Records.
 struct RecordHeader {
@@ -501,6 +502,7 @@ static_assert(alignof(ImbalanceMsg) == 8, "Must have 8-byte alignment");
 struct StatMsg {
   static bool HasRType(RType rtype) { return rtype == RType::Statistics; }
 
+  v3::StatMsg ToV3() const;
   UnixNanos IndexTs() const { return ts_recv; }
 
   RecordHeader hd;

include/databento/v1.hpp

@@ -1,7 +1,7 @@
 #pragma once
 
-#include "databento/constants.hpp"  // kSymbolCstrLen
-#include "databento/datetime.hpp"   // UnixNanos
+#include "databento/constants.hpp"  // kAssetCstrLen, kSymbolCstrLen, kUndefStatQuantity
+#include "databento/datetime.hpp"  // UnixNanos
 #include "databento/enums.hpp"
 #include "databento/record.hpp"
 #include "databento/v2.hpp"
@@ -13,8 +13,11 @@ struct InstrumentDefMsg;
 }
 
 namespace v1 {
+static constexpr std::uint8_t kDbnVersion = 1;
 static constexpr std::size_t kSymbolCstrLen = 22;
 static constexpr std::size_t kAssetCstrLen = databento::kAssetCstrLen;
+static constexpr std::int32_t kUndefStatQuantity =
+    databento::kUndefStatQuantity;
 
 using MboMsg = databento::MboMsg;
 using TradeMsg = databento::TradeMsg;

include/databento/v2.hpp

@@ -1,11 +1,14 @@
 #pragma once
 
-#include "databento/constants.hpp"  // kSymbolCstrLen
+#include "databento/constants.hpp"  // kAssetCstrLen, kSymbolCstrLen, kUndefStatQuantity
 #include "databento/record.hpp"
 
 namespace databento::v2 {
+static constexpr std::uint8_t kDbnVersion = 2;
 static constexpr std::size_t kSymbolCstrLen = databento::kSymbolCstrLen;
 static constexpr std::size_t kAssetCstrLen = databento::kAssetCstrLen;
+static constexpr std::int32_t kUndefStatQuantity =
+    databento::kUndefStatQuantity;
 
 using MboMsg = databento::MboMsg;
 using TradeMsg = databento::TradeMsg;

include/databento/v3.hpp

@@ -2,15 +2,19 @@
 
 #include <cstddef>
 #include <cstdint>
+#include <limits>
 
 #include "databento/constants.hpp"  // kSymbolCstrLen
 #include "databento/datetime.hpp"   // UnixNanos
 #include "databento/enums.hpp"  // InstrumentClass, MatchingAlgorithm, RType, SecurityUpdateAction, Side, UserDefinedInstrument
 #include "databento/record.hpp"  // RecordHeader
 
 namespace databento::v3 {
+static constexpr std::uint8_t kDbnVersion = 3;
 static constexpr std::size_t kSymbolCstrLen = databento::kSymbolCstrLen;
 static constexpr std::size_t kAssetCstrLen = 11;
+static constexpr std::int64_t kUndefStatQuantity =
+    std::numeric_limits<int64_t>::max();
 
 using MboMsg = databento::MboMsg;
 using TradeMsg = databento::TradeMsg;
@@ -28,7 +32,6 @@ using Cbbo1MMsg = databento::Cbbo1MMsg;
 using OhlcvMsg = databento::OhlcvMsg;
 using StatusMsg = databento::StatusMsg;
 using ImbalanceMsg = databento::ImbalanceMsg;
-using StatMsg = databento::StatMsg;
 using ErrorMsg = databento::ErrorMsg;
 using SymbolMappingMsg = databento::SymbolMappingMsg;
 using SystemMsg = databento::SystemMsg;
@@ -133,13 +136,50 @@ static_assert(alignof(InstrumentDefMsg) == 8, "Must have 8-byte alignment");
 static_assert(kMaxRecordLen == sizeof(InstrumentDefMsg) + sizeof(UnixNanos),
               "v3 definition with ts_out should be the largest record");
 
+/// A statistics message. A catchall for various data disseminated by
+/// publishers. The `stat_type` indicates the statistic contained in the
+/// message.
+struct StatMsg {
+  static bool HasRType(RType rtype) { return rtype == RType::Statistics; }
+
+  UnixNanos IndexTs() const { return ts_recv; }
+
+  RecordHeader hd;
+  UnixNanos ts_recv;
+  UnixNanos ts_ref;
+  std::int64_t price;
+  std::int64_t quantity;
+  std::uint32_t sequence;
+  TimeDeltaNanos ts_in_delta;
+  StatType stat_type;
+  std::uint16_t channel_id;
+  StatUpdateAction update_action;
+  std::uint8_t stat_flags;
+  std::array<char, 18> reserved;
+};
+static_assert(sizeof(StatMsg) == 80, "StatMsg size must match Rust");
+static_assert(alignof(StatMsg) == 8, "Must have 8-byte alignment");
+
 bool operator==(const InstrumentDefMsg& lhs, const InstrumentDefMsg& rhs);
 inline bool operator!=(const InstrumentDefMsg& lhs,
                        const InstrumentDefMsg& rhs) {
   return !(lhs == rhs);
 }
+inline bool operator==(const StatMsg& lhs, const StatMsg& rhs) {
+  return std::tie(lhs.hd, lhs.ts_recv, lhs.ts_ref, lhs.price, lhs.quantity,
+                  lhs.sequence, lhs.ts_in_delta, lhs.stat_type, lhs.channel_id,
+                  lhs.update_action, lhs.stat_flags) ==
+         std::tie(rhs.hd, rhs.ts_recv, rhs.ts_ref, rhs.price, rhs.quantity,
+                  rhs.sequence, rhs.ts_in_delta, rhs.stat_type, rhs.channel_id,
+                  rhs.update_action, rhs.stat_flags);
+}
+inline bool operator!=(const StatMsg& lhs, const StatMsg& rhs) {
+  return !(lhs == rhs);
+}
 
 std::string ToString(const InstrumentDefMsg& instr_def_msg);
 std::ostream& operator<<(std::ostream& stream,
                          const InstrumentDefMsg& instr_def_msg);
+std::string ToString(const StatMsg& stat_msg);
+std::ostream& operator<<(std::ostream& stream, const StatMsg& stat_msg);
 }  // namespace databento::v3

src/record.cpp

@@ -2,6 +2,7 @@
 
 #include <string>
 
+#include "databento/constants.hpp"
 #include "databento/enums.hpp"
 #include "databento/exceptions.hpp"  // InvalidArgumentError
 #include "databento/fixed_price.hpp"
@@ -200,6 +201,26 @@ databento::v3::InstrumentDefMsg InstrumentDefMsg::ToV3() const {
   return ret;
 }
 
+using databento::StatMsg;
+
+databento::v3::StatMsg StatMsg::ToV3() const {
+  return databento::v3::StatMsg{
+      RecordHeader{sizeof(v3::StatMsg) / RecordHeader::kLengthMultiplier,
+                   RType::Statistics, hd.publisher_id, hd.instrument_id,
+                   hd.ts_event},
+      ts_recv,
+      ts_ref,
+      price,
+      quantity == kUndefStatQuantity ? v3::kUndefStatQuantity : quantity,
+      sequence,
+      ts_in_delta,
+      stat_type,
+      channel_id,
+      update_action,
+      stat_flags,
+      {}};
+}
+
 bool databento::operator==(const InstrumentDefMsg& lhs,
                            const InstrumentDefMsg& rhs) {
   return lhs.hd == rhs.hd && lhs.ts_recv == rhs.ts_recv &&

src/v3.cpp

@@ -157,4 +157,24 @@ std::ostream& operator<<(std::ostream& stream,
       .AddField("leg_side", instr_def_msg.leg_side)
       .Finish();
 }
+
+std::string ToString(const StatMsg& stat_msg) { return MakeString(stat_msg); }
+std::ostream& operator<<(std::ostream& stream, const StatMsg& stat_msg) {
+  return StreamOpBuilder{stream}
+      .SetSpacer("\n    ")
+      .SetTypeName("StatMsg")
+      .Build()
+      .AddField("hd", stat_msg.hd)
+      .AddField("ts_recv", stat_msg.ts_recv)
+      .AddField("ts_ref", stat_msg.ts_ref)
+      .AddField("price", FixPx{stat_msg.price})
+      .AddField("quantity", stat_msg.quantity)
+      .AddField("sequence", stat_msg.sequence)
+      .AddField("ts_in_delta", stat_msg.ts_in_delta)
+      .AddField("stat_type", stat_msg.stat_type)
+      .AddField("channel_id", stat_msg.channel_id)
+      .AddField("update_action", stat_msg.update_action)
+      .AddField("stat_flags", stat_msg.stat_flags)
+      .Finish();
+}
 }  // namespace databento::v3