GH-34535: [C++] Move ChunkResolver to the public API

cpp/src/arrow/chunk_resolver.cc

@@ -26,7 +26,7 @@
 #include "arrow/array.h"
 #include "arrow/record_batch.h"
 
-namespace arrow::internal {
+namespace arrow {
 
 namespace {
 template <typename T>
@@ -167,4 +167,4 @@ void ChunkResolver::ResolveManyImpl(int64_t n_indices, const uint64_t* logical_i
                     logical_index_vec, out_chunk_location_vec, chunk_hint);
 }
 
-}  // namespace arrow::internal
+}  // namespace arrow

cpp/src/arrow/chunk_resolver.h

@@ -27,12 +27,12 @@
 #include "arrow/type_fwd.h"
 #include "arrow/util/macros.h"
 
-namespace arrow::internal {
+namespace arrow {
 
-struct ChunkResolver;
+class ChunkResolver;
 
 template <typename IndexType>
-struct TypedChunkLocation {
+struct ARROW_EXPORT TypedChunkLocation {
   /// \brief Index of the chunk in the array of chunks
   ///
   /// The value is always in the range `[0, chunks.size()]`. `chunks.size()` is used
@@ -41,7 +41,7 @@ struct TypedChunkLocation {
 
   /// \brief Index of the value in the chunk
   ///
-  /// The value is UNDEFINED if chunk_index >= chunks.size()
+  /// The value is UNDEFINED if `chunk_index >= chunks.size()`
   IndexType index_in_chunk = 0;
 
   TypedChunkLocation() = default;
@@ -61,7 +61,7 @@ using ChunkLocation = TypedChunkLocation<int64_t>;
 
 /// \brief An utility that incrementally resolves logical indices into
 /// physical indices in a chunked array.
-struct ARROW_EXPORT ChunkResolver {
+class ARROW_EXPORT ChunkResolver {
  private:
   /// \brief Array containing `chunks.size() + 1` offsets.
   ///
@@ -75,8 +75,16 @@ struct ARROW_EXPORT ChunkResolver {
   mutable std::atomic<int32_t> cached_chunk_;
 
  public:
+  /// \brief Initialize from an `ArrayVector`.
   explicit ChunkResolver(const ArrayVector& chunks) noexcept;
+
+  /// \brief Initialize from a vector of raw `Array` pointers.
   explicit ChunkResolver(const std::vector<const Array*>& chunks) noexcept;
+
+  /// \brief Initialize from a `RecordBatchVector`.
+  ///
+  /// Because all `Array`s in a `RecordBatch` must have the same length, this
+  /// can be useful for iterating over multiple columns simultaneously.
   explicit ChunkResolver(const RecordBatchVector& batches) noexcept;
 
   /// \brief Construct a ChunkResolver from a vector of chunks.size() + 1 offsets.
@@ -115,11 +123,11 @@ struct ARROW_EXPORT ChunkResolver {
   /// The returned ChunkLocation contains the chunk index and the within-chunk index
   /// equivalent to the logical index.
   ///
-  /// \pre index >= 0
-  /// \post location.chunk_index in [0, chunks.size()]
+  /// \pre `index >= 0`
+  /// \post `location.chunk_index` in `[0, chunks.size()]`
   /// \param index The logical index to resolve
   /// \return ChunkLocation with a valid chunk_index if index is within
-  ///         bounds, or with chunk_index == chunks.size() if logical index is
+  ///         bounds, or with `chunk_index == chunks.size()` if logical index is
   ///         `>= chunked_array.length()`.
   inline ChunkLocation Resolve(int64_t index) const {
     const auto cached_chunk = cached_chunk_.load(std::memory_order_relaxed);
@@ -133,13 +141,13 @@ struct ARROW_EXPORT ChunkResolver {
   /// The returned ChunkLocation contains the chunk index and the within-chunk index
   /// equivalent to the logical index.
   ///
-  /// \pre index >= 0
-  /// \post location.chunk_index in [0, chunks.size()]
+  /// \pre `index >= 0`
+  /// \post `location.chunk_index` in `[0, chunks.size()]`
   /// \param index The logical index to resolve
   /// \param hint ChunkLocation{} or the last ChunkLocation returned by
   ///             this ChunkResolver.
   /// \return ChunkLocation with a valid chunk_index if index is within
-  ///         bounds, or with chunk_index == chunks.size() if logical index is
+  ///         bounds, or with `chunk_index == chunks.size()` if logical index is
   ///         `>= chunked_array.length()`.
   inline ChunkLocation ResolveWithHint(int64_t index, ChunkLocation hint) const {
     assert(hint.chunk_index < static_cast<uint32_t>(offsets_.size()));
@@ -281,4 +289,13 @@ struct ARROW_EXPORT ChunkResolver {
   }
 };
 
-}  // namespace arrow::internal
+// Explicitly instantiate template base struct, for DLL linking on Windows
+template struct arrow::TypedChunkLocation<int32_t>;
+template struct arrow::TypedChunkLocation<int16_t>;
+template struct arrow::TypedChunkLocation<int8_t>;
+template struct arrow::TypedChunkLocation<uint8_t>;
+template struct arrow::TypedChunkLocation<uint16_t>;
+template struct arrow::TypedChunkLocation<uint32_t>;
+template struct arrow::TypedChunkLocation<int64_t>;
+template struct arrow::TypedChunkLocation<uint64_t>;
+}  // namespace arrow

cpp/src/arrow/chunk_resolver_benchmark.cc

@@ -28,8 +28,8 @@
 
 namespace arrow {
 
-using internal::ChunkResolver;
-using internal::TypedChunkLocation;
+using arrow::ChunkResolver;
+using arrow::TypedChunkLocation;
 
 namespace {
 

cpp/src/arrow/chunked_array.h

@@ -199,7 +199,7 @@ class ARROW_EXPORT ChunkedArray {
  private:
   template <typename T, typename V>
   friend class ::arrow::stl::ChunkedArrayIterator;
-  internal::ChunkResolver chunk_resolver_;
+  ChunkResolver chunk_resolver_;
   ARROW_DISALLOW_COPY_AND_ASSIGN(ChunkedArray);
 };
 

cpp/src/arrow/chunked_array_test.cc

@@ -36,9 +36,9 @@
 
 namespace arrow {
 
-using internal::ChunkLocation;
-using internal::ChunkResolver;
-using internal::TypedChunkLocation;
+using arrow::ChunkLocation;
+using arrow::ChunkResolver;
+using arrow::TypedChunkLocation;
 
 class TestChunkedArray : public ::testing::Test {
  protected:

cpp/src/arrow/compute/kernels/chunked_internal.h

@@ -52,7 +52,7 @@ struct ResolvedChunk {
 
 class ChunkedArrayResolver {
  private:
-  ::arrow::internal::ChunkResolver resolver_;
+  ChunkResolver resolver_;
   std::vector<const Array*> chunks_;
 
  public:

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

@@ -23,8 +23,8 @@
 
 namespace arrow {
 
+using arrow::ChunkLocation;
 using internal::checked_cast;
-using internal::ChunkLocation;
 
 namespace compute {
 namespace internal {
@@ -852,7 +852,7 @@ class TableSorter {
   const RecordBatchVector batches_;
   const SortOptions& options_;
   const NullPlacement null_placement_;
-  const ::arrow::internal::ChunkResolver left_resolver_, right_resolver_;
+  const ::arrow::ChunkResolver left_resolver_, right_resolver_;
   const std::vector<ResolvedSortKey> sort_keys_;
   uint64_t* indices_begin_;
   uint64_t* indices_end_;

cpp/src/arrow/compute/kernels/vector_sort_internal.h

@@ -749,9 +749,9 @@ struct ResolvedTableSortKey {
         order(order),
         null_count(null_count) {}
 
-  using LocationType = ::arrow::internal::ChunkLocation;
+  using LocationType = ::arrow::ChunkLocation;
 
-  ResolvedChunk GetChunk(::arrow::internal::ChunkLocation loc) const {
+  ResolvedChunk GetChunk(::arrow::ChunkLocation loc) const {
     return {chunks[loc.chunk_index], loc.index_in_chunk};
   }
 

cpp/src/arrow/stl_iterator.h

@@ -237,7 +237,7 @@ class ChunkedArrayIterator {
   }
 
  private:
-  arrow::internal::ChunkLocation GetChunkLocation(int64_t index) const {
+  arrow::ChunkLocation GetChunkLocation(int64_t index) const {
     assert(chunked_array_);
     return chunked_array_->chunk_resolver_.Resolve(index);
   }

docs/source/cpp/api/array.rst

@@ -19,6 +19,9 @@
 Arrays
 ======
 
+Base classes
+============
+
 .. doxygenclass:: arrow::ArrayData
    :project: arrow_cpp
    :members:
@@ -85,6 +88,17 @@ Chunked Arrays
    :project: arrow_cpp
    :members:
 
+.. doxygenstruct:: arrow::ChunkLocation
+   :project: arrow_cpp
+   :members:
+
+.. doxygenstruct:: arrow::TypedChunkLocation
+   :project: arrow_cpp
+   :members:
+
+.. doxygenclass:: arrow::ChunkResolver
+   :project: arrow_cpp
+   :members:
 
 Utilities
 =========

r/src/altrep.cpp

@@ -87,13 +87,11 @@ class ArrowAltrepData {
 
   const std::shared_ptr<ChunkedArray>& chunked_array() { return chunked_array_; }
 
-  arrow::internal::ChunkLocation locate(int64_t index) {
-    return resolver_.Resolve(index);
-  }
+  arrow::ChunkLocation locate(int64_t index) { return resolver_.Resolve(index); }
 
  private:
   std::shared_ptr<ChunkedArray> chunked_array_;
-  arrow::internal::ChunkResolver resolver_;
+  arrow::ChunkResolver resolver_;
 };
 
 // the ChunkedArray that is being wrapped by the altrep object