GH-50216: [C++][Parquet] Add RleBitPackedToBitmapDecoder (#50217)

### Rationale for this change
Add a `RleBitPackedToBitmapDecoder` capable of decoding a Parquet mixed Rle / BitPacked byte stream directly into a bitmap. This is an optimization to be used when target and source bit_width = 1 that will improve decoding nullable columns in a  follow-up PR.

### What changes are included in this PR?
New classes, that reuse previous Runs and parser.
Their API is slighly different from the existing one as it fits a partilcular case.
  - `RleRunToBitmapDecoder`
  - `BitPackedRunToBitmapDecoder`
  - `RleRunToBitmapDecoder`

### Are these changes tested?
Yes.

### Are there any user-facing changes?
No.

* GitHub Issue: #50216

Authored-by: AntoinePrv <AntoinePrv@users.noreply.github.com>
Signed-off-by: Antoine Pitrou <antoine@python.org>

Author: AntoinePrv

cpp/src/arrow/util/CMakeLists.txt

@@ -99,6 +99,7 @@ add_arrow_test(bit-utility-test
                bit_util_test.cc
                bitmap_test.cc
                bpacking_test.cc
+               rle_bitmap_test.cc
                rle_encoding_test.cc
                test_common.cc)
 

cpp/src/arrow/util/bit_util.h

@@ -18,9 +18,12 @@
 #pragma once
 
 #include <bit>
+#include <cassert>
 #include <cstdint>
+#include <cstring>
 #include <type_traits>
 
+#include "arrow/util/endian.h"
 #include "arrow/util/macros.h"
 #include "arrow/util/visibility.h"
 
@@ -176,6 +179,39 @@ static constexpr bool GetBitFromByte(uint8_t byte, uint8_t i) {
   return byte & kBitmask[i];
 }
 
+template <typename Uint>
+struct CopyBitsParams {
+  Uint src = {};
+  Uint dst = {};
+  int start = {};
+  int end = {};
+};
+
+/// Copy a contiguous span of bits from src into dst.
+///
+/// Copy bits [start, end[ from src into the position [start, end[ in dst
+/// and return the result (inputs are unmodified).
+/// Setting ``kAllowFullCopy`` to false is an optimization when the caller can
+/// guarantee that the range of bits to copy does not cover the whole range.
+template <typename Uint, bool kAllowFullCopy = true>
+[[nodiscard]] constexpr Uint CopyBitsInInteger(const CopyBitsParams<Uint>& params) {
+  constexpr auto kUintSizeBits = static_cast<int>(sizeof(Uint) * 8);
+  assert(params.start <= params.end);
+  assert(params.start < kUintSizeBits);
+  assert(params.end <= kUintSizeBits);
+
+  const int length = params.end - params.start;
+  if constexpr (kAllowFullCopy) {
+    if (length == kUintSizeBits) {
+      return params.src;
+    }
+  }
+  assert(length < kUintSizeBits);
+  const Uint mask =
+      static_cast<Uint>(LeastSignificantBitMask<Uint, false>(length) << params.start);
+  return (~mask & params.dst) | (mask & params.src);
+}
+
 static inline void ClearBit(uint8_t* bits, int64_t i) {
   bits[i / 8] &= kFlippedBitmask[i % 8];
 }

cpp/src/arrow/util/bit_util_test.cc

@@ -1065,4 +1065,47 @@ TEST(SpliceWord, SpliceWord) {
             0xfedc456789abcdef);
 }
 
+TEST(BitUtil, CopyBits) {
+  // Copy bits [start, end[ from src into dst, keeping dst's other bits.
+  using bit_util::CopyBitsInInteger;
+
+  // Empty range: result equals dst.
+  ASSERT_EQ(CopyBitsInInteger<uint8_t>(
+                {.src = 0b11111111, .dst = 0b00010010, .start = 3, .end = 3}),
+            0b00010010);
+  // dst = 0101 0101, src = 1010 1010  ->  0101 1010
+  ASSERT_EQ(CopyBitsInInteger<uint8_t>(
+                {.src = 0b10101010, .dst = 0b01010101, .start = 0, .end = 4}),
+            0b01011010);
+  // Copy a middle span [2, 5[ of all-ones into an all-zeros dst.
+  ASSERT_EQ(CopyBitsInInteger<uint8_t>(
+                {.src = 0b11111111, .dst = 0b00000000, .start = 2, .end = 5}),
+            0b00011100);
+  // Copy a middle span [2, 5[ of all-zeros into an all-ones dst.
+  ASSERT_EQ(CopyBitsInInteger<uint8_t>(
+                {.src = 0b00000000, .dst = 0b11111111, .start = 2, .end = 5}),
+            0b11100011);
+  // Full-word copy returns src unchanged.
+  ASSERT_EQ(CopyBitsInInteger<uint8_t>(
+                {.src = 0b10101011, .dst = 0b00010010, .start = 0, .end = 8}),
+            0b10101011);
+  // uint16_t partial range [4, 12[: dst keeps its bits outside, src fills inside.
+  ASSERT_EQ(
+      CopyBitsInInteger<uint16_t>(
+          {.src = 0b1010101010101010, .dst = 0b0101010101010101, .start = 4, .end = 12}),
+      0b0101101010100101);
+  // uint64_t
+  ASSERT_EQ(CopyBitsInInteger<uint64_t>({
+                .src = 0x0123456789abcdef,
+                .dst = 0xfedcba9876543210,
+                .start = 0,
+                .end = 64,
+            }),
+            0x0123456789abcdef);
+  // constexpr-evaluable.
+  static_assert(CopyBitsInInteger<uint8_t>(
+                    {.src = 0b10101010, .dst = 0b01010101, .start = 0, .end = 4}) ==
+                0b01011010);
+}
+
 }  // namespace arrow