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