Function RunGetSpaced

cpp/src/arrow/util/rle_encoding_internal.h:886–944

/// Overload for GetSpaced for a single run in a RleDecoder
template <typename Converter, typename BitRunReader, typename BitRun, typename value_type>
auto RunGetSpaced(Converter* converter, typename Converter::out_type* out,
                  rle_size_t batch_size, rle_size_t null_count,
                  rle_size_t value_bit_width, BitRunReader* validity_reader,
                  BitRun* validity_run,
                  RleRunDecoder<value_type>* decoder) -> GetSpacedResult<rle_size_t> {
  ARROW_DCHECK_GT(batch_size, 0);
  // The equality case is handled in the main loop in GetSpaced
  ARROW_DCHECK_LT(null_count, batch_size);

  auto batch = BatchCounter::FromBatchSizeAndNulls(batch_size, null_count);

  const rle_size_t values_available = decoder->remaining();
  ARROW_DCHECK_GT(values_available, 0);
  auto values_remaining_run = [&]() {
    auto out = values_available - batch.values_read();
    ARROW_DCHECK_GE(out, 0);
    return out;
  };

  // Consume as much as possible from the repeated run.
  // We only need to count the number of nulls and non-nulls because we can fill in the
  // same value for nulls and non-nulls.
  // This proves to be a big efficiency win.
  while (values_remaining_run() > 0 && !batch.is_done()) {
    ARROW_DCHECK_GE(validity_run->length, 0);
    ARROW_DCHECK_LT(validity_run->length, max_size_for_v<rle_size_t>);
    ARROW_DCHECK_LE(validity_run->length, batch.total_remaining());
    const auto& validity_run_size = static_cast<rle_size_t>(validity_run->length);

    if (validity_run->set) {
      // We may end the current RLE run in the middle of the validity run
      auto update_size = std::min(validity_run_size, values_remaining_run());
      batch.AccrueReadValues(update_size);
      validity_run->length -= update_size;
    } else {
      // We can consume all nulls here because it does not matter if we consume on this
      // RLE run, or an a next encoded run. The value filled does not matter.
      auto update_size = std::min(validity_run_size, batch.null_remaining());
      batch.AccrueReadNulls(update_size);
      validity_run->length -= update_size;
    }

    if (ARROW_PREDICT_TRUE(validity_run->length == 0)) {
      *validity_run = validity_reader->NextRun();
    }
  }

  const value_type value = decoder->value();
  if (ARROW_PREDICT_FALSE(!converter->InputIsValid(value))) {
    return {0, 0};
  }
  converter->WriteRepeated(out, out + batch.total_read(), value);
  const auto actual_values_read = decoder->Advance(batch.values_read());
  // We always cropped the number of values_read by the remaining values in the run.
  // What's more the RLE decoder should not encounter any errors.
  ARROW_DCHECK_EQ(actual_values_read, batch.values_read());

  return {/* .values_read= */ batch.values_read(), /* .null_read= */ batch.null_read()};