ARROW-14230: [C++] Deprecate ArrayBuilder::Advance

Closes #11326 from pitrou/ARROW-14230-array-builder-advance

Authored-by: Antoine Pitrou <antoine@python.org>
Signed-off-by: Antoine Pitrou <antoine@python.org>

cpp/src/arrow/array/array_test.cc

@@ -1577,6 +1577,7 @@ TYPED_TEST(TestPrimitiveBuilder, TestAppendValuesStdBool) {
 }
 
 TYPED_TEST(TestPrimitiveBuilder, TestAdvance) {
+  ARROW_SUPPRESS_DEPRECATION_WARNING
   int64_t n = 1000;
   ASSERT_OK(this->builder_->Reserve(n));
 
@@ -1587,6 +1588,7 @@ TYPED_TEST(TestPrimitiveBuilder, TestAdvance) {
 
   int64_t too_many = this->builder_->capacity() - 1000 + 1;
   ASSERT_RAISES(Invalid, this->builder_->Advance(too_many));
+  ARROW_UNSUPPRESS_DEPRECATION_WARNING
 }
 
 TYPED_TEST(TestPrimitiveBuilder, TestResize) {
@@ -1604,7 +1606,9 @@ TYPED_TEST(TestPrimitiveBuilder, TestReserve) {
   ASSERT_OK(this->builder_->Reserve(100));
   ASSERT_EQ(0, this->builder_->length());
   ASSERT_GE(100, this->builder_->capacity());
+  ARROW_SUPPRESS_DEPRECATION_WARNING
   ASSERT_OK(this->builder_->Advance(100));
+  ARROW_UNSUPPRESS_DEPRECATION_WARNING
   ASSERT_EQ(100, this->builder_->length());
   ASSERT_GE(100, this->builder_->capacity());
 

cpp/src/arrow/array/builder_base.h

@@ -134,6 +134,10 @@ class ARROW_EXPORT ArrayBuilder {
   /// For cases where raw data was memcpy'd into the internal buffers, allows us
   /// to advance the length of the builder. It is your responsibility to use
   /// this function responsibly.
+  ARROW_DEPRECATED(
+      "Deprecated in 6.0.0. ArrayBuilder::Advance is poorly supported and mostly "
+      "untested.\nFor low-level control over buffer construction, use BufferBuilder "
+      "or TypedBufferBuilder directly.")
   Status Advance(int64_t elements);
 
   /// \brief Return result of builder as an internal generic ArrayData

cpp/src/arrow/ipc/read_write_test.cc

@@ -28,6 +28,7 @@
 
 #include "arrow/array.h"
 #include "arrow/array/builder_primitive.h"
+#include "arrow/buffer_builder.h"
 #include "arrow/io/file.h"
 #include "arrow/io/memory.h"
 #include "arrow/io/test_common.h"
@@ -1654,12 +1655,13 @@ TEST(TestIpcFileFormat, FooterMetaData) {
 TEST_F(TestIpcRoundTrip, LargeRecordBatch) {
   const int64_t length = static_cast<int64_t>(std::numeric_limits<int32_t>::max()) + 1;
 
-  BooleanBuilder builder(default_memory_pool());
-  ASSERT_OK(builder.Reserve(length));
-  ASSERT_OK(builder.Advance(length));
+  TypedBufferBuilder<bool> data_builder;
+  ASSERT_OK(data_builder.Reserve(length));
+  ASSERT_OK(data_builder.Advance(length));
+  ASSERT_EQ(data_builder.length(), length);
+  ASSERT_OK_AND_ASSIGN(auto data, data_builder.Finish());
 
-  std::shared_ptr<Array> array;
-  ASSERT_OK(builder.Finish(&array));
+  auto array = std::make_shared<BooleanArray>(length, data, nullptr, /*null_count=*/0);
 
   auto f0 = arrow::field("f0", array->type());
   std::vector<std::shared_ptr<Field>> fields = {f0};