GH-45819: [C++] Add OptionalBitmapAnd utility

[Shockp]

Rationale for this change

In Arrow, null bitmaps are optional and represented by nullptr when a column contains no nulls. Previously, conjoining two optional bitmaps required downstream code to manually handle the nullptr checks and memory allocations. This change centralizes that logic into a single, highly optimized utility function.

What changes are included in this PR?

• Added OptionalBitmapAnd to cpp/src/arrow/util/bitmap_ops.h and bitmap_ops.cc.
• The implementation safely handles the four possible memory permutations with minimal allocations:
  1. Both buffers nullptr: Returns nullptr.
  2. Left is nullptr: Returns a copy of the right buffer.
  3. Right is nullptr: Returns a copy of the left buffer.
  4. Both valid: Defers to the low-level BitmapAnd function.

Are these changes tested?

Yes. I added a new test case (OptionalBitmapAnd) to cpp/src/arrow/util/bitmap_test.cc that explicitly verifies the correct buffer allocation and bitwise output for all four memory states.

Are there any user-facing changes?

No. This simply exposes a new C++ utility for internal development.

Closes #45819

• GitHub Issue: [C++] Add OptionalBitmapAnd utility #45819

[pitrou]

Thanks for submitting this @Shockp ! Here are some comments.

Also can you find places in the codebase where this can be put to use?

[Shockp]

Reverted the testing submodule, added the out_offset default, implemented the zero-copy slicing for byte-aligned offsets, and updated the tests to use BitmapFromVector for non-trivial inputs. Let me know how it looks! @pitrou

Quick question on the API: I noticed the other functions in bitmap_ops.h (like BitmapAnd, BitmapOr, etc.) don't currently have out_offset = 0 as a default. Would it be worth unifying those for consistency in a separate, follow-up PR, or is it safer to leave the existing signatures as-is?

[Shockp]

Sorry, I had some conflicts with my local branch while trying to pass the lint CI. I just squashed all the changes of the PR in a single commit.

[pitrou]

Quick question on the API: I noticed the other functions in bitmap_ops.h (like BitmapAnd, BitmapOr, etc.) don't currently have out_offset = 0 as a default. Would it be worth unifying those for consistency in a separate, follow-up PR, or is it safer to leave the existing signatures as-is?

Ah, that's a good point. Well, perhaps we can keep them as they are for now.

[pitrou]

Can we perhaps use this function in

arrow/cpp/src/arrow/compute/kernels/hash_aggregate.cc

Lines 1342 to 1348 in 6198adc

	if (null_bitmap) {
	arrow::internal::BitmapAnd(null_bitmap->data(), /*left_offset=*/0,
	no_nulls->data(), /*right_offset=*/0, num_groups_,
	/*out_offset=*/0, null_bitmap->mutable_data());
	} else {
	null_bitmap = std::move(no_nulls);
	}

?

[Shockp]

I just updated it to use the new OptionalBitmapAnd utility @pitrou. It replaces that manual if/else block with a single, clean macro:

      ARROW_ASSIGN_OR_RAISE(
          null_bitmap,
          arrow::internal::OptionalBitmapAnd(pool_, null_bitmap, /*left_offset=*/0,
                                             no_nulls, /*right_offset=*/0,
                                             num_groups_));

[pitrou]

@github-actions crossbow submit -g cpp

[pitrou]

+1, let's wait for CI

[github-actions]

Revision: 99022c3

Submitted crossbow builds: ursacomputing/crossbow @ actions-4c878a50ea

Task	Status
example-cpp-minimal-build-static
example-cpp-minimal-build-static-system-dependency
example-cpp-tutorial
test-build-cpp-fuzz
test-conda-cpp
test-conda-cpp-valgrind
test-debian-13-cpp-amd64
test-debian-13-cpp-i386
test-debian-experimental-cpp-gcc-15
test-fedora-42-cpp
test-ubuntu-22.04-cpp
test-ubuntu-22.04-cpp-20
test-ubuntu-22.04-cpp-bundled
test-ubuntu-22.04-cpp-emscripten
test-ubuntu-22.04-cpp-no-threading
test-ubuntu-24.04-cpp
test-ubuntu-24.04-cpp-bundled-offline
test-ubuntu-24.04-cpp-gcc-13-bundled
test-ubuntu-24.04-cpp-gcc-14
test-ubuntu-24.04-cpp-minimal-with-formats
test-ubuntu-24.04-cpp-thread-sanitizer

[Shockp]

Thanks so much for the review and the approval, @pitrou!

I'm already looking forward to my next contribution. I am really focused on building a strong foundation in High-Performance Computing. Are there specific issue tags or components you would recommend I search for if I want to tackle very low-level C++ tasks (like SIMD, memory/buffer management) or dive into CUDA/GPU-related issues?

Thanks again for all the guidance!

[raulcd]

Felicidades @Shockp ! 🥳

[Shockp]

Gracias! @raulcd . No estoy seguro de si puedes responder al comentario de arriba, por saber las etiquetas que tengo que buscar para esos problemas.

[conbench-apache-arrow]

After merging your PR, Conbench analyzed the 0 benchmarking runs that have been run so far on merge-commit 9abd6d3.

None of the specified runs were found on the Conbench server.

The full Conbench report has more details.