Class RleBitPackedParser

cpp/src/arrow/util/rle_encoding_internal.h:195–255

A parser that emits either a ``BitPackedRun`` or a ``RleRun``.

/// A parser that emits either a ``BitPackedRun`` or a ``RleRun``.
class RleBitPackedParser {
 public:
  /// The different types of runs emitted by the parser
  using dynamic_run_type = std::variant<RleRun, BitPackedRun>;

  constexpr RleBitPackedParser() noexcept = default;

  constexpr RleBitPackedParser(const uint8_t* data, rle_size_t data_size,
                               rle_size_t value_bit_width) noexcept
      : data_(data), data_size_(data_size), value_bit_width_(value_bit_width) {}

  constexpr void Reset(const uint8_t* data, rle_size_t data_size,
                       rle_size_t value_bit_width) noexcept {
    *this = {data, data_size, value_bit_width};
  }

  /// Whether there is still runs to iterate over.
  ///
  /// WARN: Due to simplistic error handling, iteration with Next and Peek could
  /// fail to return data while the parser is not exhausted.
  /// This is how one can check for errors.
  bool exhausted() const { return data_size_ == 0; }

  /// Enum to return from an ``Parse`` handler.
  ///
  /// Since a callback has no way to know when to stop, the handler must return
  /// a value indicating to the ``Parse`` function whether to stop or continue.
  enum class ControlFlow {
    Continue,
    Break,
  };

  /// A callback approach to parsing.
  ///
  /// This approach is used to reduce the number of dynamic lookups involved with using a
  /// variant.
  ///
  /// The handler must be of the form
  /// ```cpp
  /// struct Handler {
  ///   ControlFlow OnBitPackedRun(BitPackedRun run);
  ///
  ///   ControlFlow OnRleRun(RleRun run);
  /// };
  /// ```
  template <typename Handler>
  void Parse(Handler&& handler);

 private:
  /// The pointer to the beginning of the run
  const uint8_t* data_ = nullptr;
  /// Size in bytes of the run.
  rle_size_t data_size_ = 0;
  /// The size in bit of a packed value in the run
  rle_size_t value_bit_width_ = 0;

  /// Run the handler on the run read and return the number of values read.
  /// Does not advance the parser.