GH-45908: [C++][Docs] Rename and expose basic {Array,...}FromJSON helpers as public APIs

cpp/examples/arrow/CMakeLists.txt

@@ -19,6 +19,7 @@ add_arrow_example(row_wise_conversion_example)
 
 if(ARROW_WITH_RAPIDJSON)
  add_arrow_example(rapidjson_row_converter EXTRA_LINK_LIBS RapidJSON)
+ add_arrow_example(from_json_string_example EXTRA_LINK_LIBS RapidJSON)
 endif()
 
 if(ARROW_ACERO)

cpp/examples/arrow/from_json_string_example.cc

@@ -0,0 +1,91 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+// This example shows how to use some of the *FromJSONString helpers.
+
+#include <iostream>
+#include <memory>
+
+#include <arrow/api.h>
+#include <arrow/array/array_base.h>
+#include <arrow/json/from_string.h>
+#include <arrow/status.h>
+
+using arrow::json::ArrayFromJSONString;
+using arrow::json::ChunkedArrayFromJSONString;
+using arrow::json::DictArrayFromJSONString;
+
+/**
+ * \brief Run Example
+ *
+ * ./debug/from-json-string-example
+ */
+arrow::Status RunExample() {
+ // Simple types
+ ARROW_ASSIGN_OR_RAISE(auto int32_array,
+ ArrayFromJSONString(arrow::int32(), "[1, 2, 3]"));
+ ARROW_ASSIGN_OR_RAISE(auto float64_array,
+ ArrayFromJSONString(arrow::float64(), "[4.0, 5.0, 6.0]"));
+ ARROW_ASSIGN_OR_RAISE(auto bool_array,
+ ArrayFromJSONString(arrow::boolean(), "[true, false, true]"));
+ ARROW_ASSIGN_OR_RAISE(
+ auto string_array,
+ ArrayFromJSONString(arrow::utf8(), R"(["Hello", "World", null])"));
+
+ // Timestamps can be created from string representations
+ ARROW_ASSIGN_OR_RAISE(
+ auto ts_array,
+ ArrayFromJSONString(timestamp(arrow::TimeUnit::SECOND),
+ R"(["1970-01-01", "2000-02-29","3989-07-14","1900-02-28"])"));
+
+ // List, Map, Struct
+ ARROW_ASSIGN_OR_RAISE(
+ auto list_array,
+ ArrayFromJSONString(list(arrow::int64()),
+ "[[null], [], null, [4, 5, 6, 7, 8], [2, 3]]"));
+ ARROW_ASSIGN_OR_RAISE(
+ auto map_array,
+ ArrayFromJSONString(map(arrow::utf8(), arrow::int32()),
+ R"([[["joe", 0], ["mark", null]], null, [["cap", 8]], []])"));
+ ARROW_ASSIGN_OR_RAISE(
+ auto struct_array,
+ ArrayFromJSONString(
+ arrow::struct_({field("one", arrow::int32()), field("two", arrow::int32())}),
+ "[[11, 22], null, [null, 33]]"));
+
+ // ChunkedArrayFromJSONString
+ std::shared_ptr<arrow::ChunkedArray> chunked_array;
+ ARROW_RETURN_NOT_OK(ChunkedArrayFromJSONString(
+ arrow::int32(), {"[5, 10]", "[null]", "[16]"}, &chunked_array));
+
+ // DictArrayFromJSONString
+ std::shared_ptr<arrow::Array> dict_array;
+ ARROW_RETURN_NOT_OK(DictArrayFromJSONString(
+ dictionary(arrow::int32(), arrow::utf8()), "[0, 1, 0, 2, 0, 3]",
+ R"(["k1", "k2", "k3", "k4"])", &dict_array));
+
+ return arrow::Status::OK();
+}
+
+int main(int argc, char** argv) {
+ auto status = RunExample();
+ if (!status.ok()) {
+ std::cerr << status.ToString() << std::endl;
+ return EXIT_FAILURE;
+ }
+ return EXIT_SUCCESS;
+}

cpp/src/arrow/CMakeLists.txt

@@ -620,6 +620,11 @@ if(ARROW_WITH_OPENTELEMETRY)
  target_link_libraries(${ARROW_UTIL_TARGET} PRIVATE ${ARROW_OPENTELEMETRY_LIBS})
  endforeach()
 endif()
+if(ARROW_WITH_RAPIDJSON)
+ foreach(ARROW_UTIL_TARGET ${ARROW_UTIL_TARGETS})
+ target_link_libraries(${ARROW_UTIL_TARGET} PRIVATE RapidJSON)
+ endforeach()
+endif()
 if(ARROW_WITH_ZLIB)
  foreach(ARROW_UTIL_TARGET ${ARROW_UTIL_TARGETS})
  target_link_libraries(${ARROW_UTIL_TARGET} PRIVATE ZLIB::ZLIB)
@@ -914,18 +919,10 @@ if(ARROW_IPC)
  ipc/options.cc
  ipc/reader.cc
  ipc/writer.cc)
- if(ARROW_JSON)
- list(APPEND ARROW_IPC_SRCS ipc/json_simple.cc)
- endif()
  arrow_add_object_library(ARROW_IPC ${ARROW_IPC_SRCS})
  foreach(ARROW_IPC_TARGET ${ARROW_IPC_TARGETS})
  target_link_libraries(${ARROW_IPC_TARGET} PRIVATE arrow::flatbuffers)
  endforeach()
- if(ARROW_JSON)
- foreach(ARROW_IPC_TARGET ${ARROW_IPC_TARGETS})
- target_link_libraries(${ARROW_IPC_TARGET} PRIVATE RapidJSON)
- endforeach()
- endif()
 else()
  set(ARROW_IPC_TARGET_SHARED)
  set(ARROW_IPC_TARGET_STATIC)
@@ -939,6 +936,7 @@ if(ARROW_JSON)
  json/chunked_builder.cc
  json/chunker.cc
  json/converter.cc
+ json/from_string.cc
  json/object_parser.cc
  json/object_writer.cc
  json/parser.cc

cpp/src/arrow/c/bridge_benchmark.cc

@@ -22,7 +22,7 @@
 #include "arrow/array.h"
 #include "arrow/c/bridge.h"
 #include "arrow/c/helpers.h"
-#include "arrow/ipc/json_simple.h"
+#include "arrow/json/from_string.h"
 #include "arrow/record_batch.h"
 #include "arrow/testing/gtest_util.h"
 #include "arrow/type.h"
@@ -79,7 +79,7 @@ static void ExportSchema(benchmark::State& state) { // NOLINT non-const referen
 
 static void ExportArray(benchmark::State& state) { // NOLINT non-const reference
  struct ArrowArray c_export;
- auto array = ArrayFromJSON(utf8(), R"(["foo", "bar", null])");
+ auto array = arrow::ArrayFromJSON(utf8(), R"(["foo", "bar", null])");
 
  for (auto _ : state) {
  ABORT_NOT_OK(::arrow::ExportArray(*array, &c_export));
@@ -123,7 +123,7 @@ static void ExportImportSchema(benchmark::State& state) { // NOLINT non-const r
 
 static void ExportImportArray(benchmark::State& state) { // NOLINT non-const reference
  struct ArrowArray c_export;
- auto array = ArrayFromJSON(utf8(), R"(["foo", "bar", null])");
+ auto array = arrow::ArrayFromJSON(utf8(), R"(["foo", "bar", null])");
  auto type = array->type();
 
  for (auto _ : state) {

cpp/src/arrow/c/bridge_test.cc

@@ -31,7 +31,6 @@
 #include "arrow/c/bridge.h"
 #include "arrow/c/helpers.h"
 #include "arrow/c/util_internal.h"
-#include "arrow/ipc/json_simple.h"
 #include "arrow/memory_pool.h"
 #include "arrow/testing/builder.h"
 #include "arrow/testing/extension_type.h"

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

@@ -43,8 +43,6 @@
 #include "arrow/compute/api.h"
 #include "arrow/compute/kernels/test_util_internal.h"
 
-#include "arrow/ipc/json_simple.h"
-
 namespace arrow {
 
 using internal::checked_cast;

cpp/src/arrow/dataset/test_util_internal.h

@@ -2140,8 +2140,8 @@ class WriteFileSystemDatasetMixin : public MakeFileSystemDatasetMixin {
  actual_struct = std::dynamic_pointer_cast<Array>(struct_array);
  }
 
- auto expected_struct = ArrayFromJSON(struct_(expected_physical_schema_->fields()),
- file_contents->second);
+ auto expected_struct = arrow::ArrayFromJSON(
+struct_(expected_physical_schema_->fields()), file_contents->second);
 
  AssertArraysEqual(*expected_struct, *actual_struct, /*verbose=*/true);
  }

cpp/src/arrow/ipc/CMakeLists.txt

@@ -38,7 +38,6 @@ function(ADD_ARROW_IPC_TEST REL_TEST_NAME)
 endfunction()
 
 add_arrow_test(feather_test)
-add_arrow_ipc_test(json_simple_test)
 add_arrow_ipc_test(message_internal_test)
 add_arrow_ipc_test(read_write_test)
 add_arrow_ipc_test(tensor_test)

cpp/src/arrow/ipc/api.h

@@ -19,7 +19,6 @@
 
 #include "arrow/ipc/dictionary.h"
 #include "arrow/ipc/feather.h"
-#include "arrow/ipc/json_simple.h"
 #include "arrow/ipc/message.h"
 #include "arrow/ipc/reader.h"
 #include "arrow/ipc/writer.h"

cpp/src/arrow/ipc/generate_fuzz_corpus.cc

@@ -27,9 +27,9 @@
 
 #include "arrow/io/file.h"
 #include "arrow/io/memory.h"
-#include "arrow/ipc/json_simple.h"
 #include "arrow/ipc/test_common.h"
 #include "arrow/ipc/writer.h"
+#include "arrow/json/from_string.h"
 #include "arrow/record_batch.h"
 #include "arrow/result.h"
 #include "arrow/testing/extension_type.h"
@@ -41,7 +41,7 @@ namespace arrow::ipc {
 
 using ::arrow::internal::CreateDir;
 using ::arrow::internal::PlatformFilename;
-using internal::json::ArrayFromJSON;
+using ::arrow::json::ArrayFromJSONString;
 
 Result<std::shared_ptr<RecordBatch>> MakeExtensionBatch() {
  auto array = ExampleUuid();
@@ -60,7 +60,7 @@ Result<std::shared_ptr<RecordBatch>> MakeMapBatch() {
  []
  ]
 )";
- ARROW_ASSIGN_OR_RAISE(array, ArrayFromJSON(map(int16(), int32()), json_input));
+ ARROW_ASSIGN_OR_RAISE(array, ArrayFromJSONString(map(int16(), int32()), json_input));
  auto schema = ::arrow::schema({field("f0", array->type())});
  return RecordBatch::Make(schema, array->length(), {array});
 }

cpp/src/arrow/json/CMakeLists.txt

@@ -20,6 +20,7 @@ add_arrow_test(test
  chunked_builder_test.cc
  chunker_test.cc
  converter_test.cc
+ from_string_test.cc
  parser_test.cc
  reader_test.cc
  PREFIX