GH-38369: [MATLAB] Create utility functions for simplifying management of Proxy instances for Arrays (#46907)

### Rationale for this change

This is a follow up to #38357 (comment).

In the C++ code for the MATLAB interface, we frequently `wrap`/`unwrap` Arrow types, like `arrow::Array`, into/from a corresponding `libmexclass` `Proxy` objects. This currently takes several lines of code, leading to lots of code duplication and introduces room for subtle implementation errors.

It would be helpful to abstract away some of the steps involved in `Proxy` creation/management into a set of helper utilities that we can reuse in the C++ code for the MATLAB interface.

### What changes are included in this PR?

1. Added a new utility function that wraps a `std::shared_ptr<arrow::Array>` in a `std::shared_ptr<arrow::matlab::array::proxy::Array>`.  Its function signature is 

```c++
arrow::Result<std::shared_ptr<arrow::matlab::array::proxy::Array>> wrap(const std::shared_ptr<arrow::Array>& array);`
````
2. Added a new utility function that wraps a `std::shared_ptr<arrow::Array>` in a `std::shared_ptr<arrow::matlab::array::proxy::Array>` and adds the proxy to the `libmexclass::proxy::ProxyManager`. Its function signature is 

```c++
arrow::Result<std::shared_ptr<arrow::matlab::array::proxy::Array>> wrap_and_manage(const std::shared_ptr<arrow::Array>& array);
```

3. Added a new utility function that wraps a `std::shared_ptr<arrow::DataType>` in a `std::shared_ptr<arrow::matlab::type::proxy::Type>`. Its function signature is 

```c++
arrow::Result<std::shared_ptr<arrow::matlab::type::proxy::Type>> wrap(const std::shared_ptr<arrow::DataType>& type);
```

4. Added a new utility function that wraps a `std::shared_ptr<arrow::DataType>` in a `std::shared_ptr<arrow::matlab::type::proxy::DataType>` and adds the proxy to the `libmexclass::proxy::ProxyManager`. It's function signature is

```c++
arrow::Result<std::shared_ptr<arrow::matlab::type::proxy::Type>> wrap_and_manage(const std::shared_ptr<arrow::DataType>& type);
```

5. Deleted `arrow::matlab::array::proxy::wrap` and `arrow::matlab::type::proxy::wrap` functions.

### Are these changes tested?

Tested via the existing MATLAB test classes.

### Are there any user-facing changes?

No.

* GitHub Issue: #38369

Lead-authored-by: Sarah Gilmore <sgilmore@mathworks.com>
Co-authored-by: Sarah Gilmore <74676073+sgilmore10@users.noreply.github.com>
Co-authored-by: Kevin Gurney <kevin.p.gurney@gmail.com>
Signed-off-by: Sarah Gilmore <sgilmore@mathworks.com>

Author: sgilmore10

matlab/src/cpp/arrow/matlab/array/proxy/array.cc

@@ -19,11 +19,10 @@
 #include "arrow/util/utf8.h"
 
 #include "arrow/matlab/array/proxy/array.h"
-#include "arrow/matlab/array/proxy/wrap.h"
 #include "arrow/matlab/bit/unpack.h"
 #include "arrow/matlab/error/error.h"
 #include "arrow/matlab/index/validate.h"
-#include "arrow/matlab/type/proxy/wrap.h"
+#include "arrow/matlab/proxy/wrap.h"
 #include "arrow/pretty_print.h"
 #include "arrow/type_traits.h"
 
@@ -110,20 +109,9 @@ void Array::getValid(libmexclass::proxy::method::Context& context) {
 }
 
 void Array::getType(libmexclass::proxy::method::Context& context) {
-  namespace mda = ::matlab::data;
-
-  mda::ArrayFactory factory;
-
-  MATLAB_ASSIGN_OR_ERROR_WITH_CONTEXT(auto type_proxy, type::proxy::wrap(array->type()),
-                                      context, error::ARRAY_FAILED_TO_CREATE_TYPE_PROXY);
-
-  const auto type_id = static_cast<int32_t>(type_proxy->unwrap()->id());
-  const auto proxy_id = libmexclass::proxy::ProxyManager::manageProxy(type_proxy);
-
-  mda::StructArray output = factory.createStructArray({1, 1}, {"ProxyID", "TypeID"});
-  output[0]["ProxyID"] = factory.createScalar(proxy_id);
-  output[0]["TypeID"] = factory.createScalar(type_id);
-  context.outputs[0] = output;
+  MATLAB_ASSIGN_OR_ERROR_WITH_CONTEXT(
+      context.outputs[0], arrow::matlab::proxy::wrap_and_manage(array->type()), context,
+      error::ARRAY_FAILED_TO_CREATE_TYPE_PROXY);
 }
 
 void Array::isEqual(libmexclass::proxy::method::Context& context) {
@@ -167,18 +155,9 @@ void Array::slice(libmexclass::proxy::method::Context& context) {
                                       context, error::ARRAY_SLICE_NEGATIVE_LENGTH);
 
   auto sliced_array = array->Slice(offset, length);
-  const auto type_id = static_cast<int32_t>(sliced_array->type_id());
-  MATLAB_ASSIGN_OR_ERROR_WITH_CONTEXT(auto sliced_array_proxy,
-                                      array::proxy::wrap(sliced_array), context,
-                                      error::ARRAY_SLICE_FAILED_TO_CREATE_ARRAY_PROXY);
-
-  const auto proxy_id = libmexclass::proxy::ProxyManager::manageProxy(sliced_array_proxy);
-
-  mda::ArrayFactory factory;
-  mda::StructArray output = factory.createStructArray({1, 1}, {"ProxyID", "TypeID"});
-  output[0]["ProxyID"] = factory.createScalar(proxy_id);
-  output[0]["TypeID"] = factory.createScalar(type_id);
-  context.outputs[0] = output;
+  MATLAB_ASSIGN_OR_ERROR_WITH_CONTEXT(
+      context.outputs[0], arrow::matlab::proxy::wrap_and_manage(sliced_array), context,
+      error::ARRAY_SLICE_FAILED_TO_CREATE_ARRAY_PROXY);
 }
 
 void Array::exportToC(libmexclass::proxy::method::Context& context) {

matlab/src/cpp/arrow/matlab/array/proxy/chunked_array.cc

@@ -19,9 +19,8 @@
 
 #include "arrow/matlab/array/proxy/array.h"
 #include "arrow/matlab/array/proxy/chunked_array.h"
-#include "arrow/matlab/array/proxy/wrap.h"
 #include "arrow/matlab/error/error.h"
-#include "arrow/matlab/type/proxy/wrap.h"
+#include "arrow/matlab/proxy/wrap.h"
 
 #include "libmexclass/proxy/ProxyManager.h"
 
@@ -126,35 +125,15 @@ void ChunkedArray::getChunk(libmexclass::proxy::method::Context& context) {
   }
 
   const auto array = chunked_array->chunk(index);
-  MATLAB_ASSIGN_OR_ERROR_WITH_CONTEXT(auto array_proxy,
-                                      arrow::matlab::array::proxy::wrap(array), context,
-                                      error::UNKNOWN_PROXY_FOR_ARRAY_TYPE);
-
-  const auto array_proxy_id = libmexclass::proxy::ProxyManager::manageProxy(array_proxy);
-  const auto type_id = static_cast<int64_t>(array->type_id());
-
-  mda::StructArray output = factory.createStructArray({1, 1}, {"ProxyID", "TypeID"});
-  output[0]["ProxyID"] = factory.createScalar(array_proxy_id);
-  output[0]["TypeID"] = factory.createScalar(type_id);
-  context.outputs[0] = output;
+  MATLAB_ASSIGN_OR_ERROR_WITH_CONTEXT(context.outputs[0],
+                                      arrow::matlab::proxy::wrap_and_manage(array),
+                                      context, error::UNKNOWN_PROXY_FOR_ARRAY_TYPE);
 }
 
 void ChunkedArray::getType(libmexclass::proxy::method::Context& context) {
-  namespace mda = ::matlab::data;
-
-  mda::ArrayFactory factory;
-
-  MATLAB_ASSIGN_OR_ERROR_WITH_CONTEXT(auto type_proxy,
-                                      type::proxy::wrap(chunked_array->type()), context,
-                                      error::ARRAY_FAILED_TO_CREATE_TYPE_PROXY);
-
-  const auto proxy_id = libmexclass::proxy::ProxyManager::manageProxy(type_proxy);
-  const auto type_id = static_cast<int32_t>(type_proxy->unwrap()->id());
-
-  mda::StructArray output = factory.createStructArray({1, 1}, {"ProxyID", "TypeID"});
-  output[0]["ProxyID"] = factory.createScalar(proxy_id);
-  output[0]["TypeID"] = factory.createScalar(type_id);
-  context.outputs[0] = output;
+  MATLAB_ASSIGN_OR_ERROR_WITH_CONTEXT(
+      context.outputs[0], arrow::matlab::proxy::wrap_and_manage(chunked_array->type()),
+      context, error::ARRAY_FAILED_TO_CREATE_TYPE_PROXY);
 }
 
 void ChunkedArray::isEqual(libmexclass::proxy::method::Context& context) {

matlab/src/cpp/arrow/matlab/array/proxy/list_array.cc

@@ -17,9 +17,10 @@
 
 #include "arrow/matlab/array/proxy/list_array.h"
 #include "arrow/matlab/array/proxy/numeric_array.h"
-#include "arrow/matlab/array/proxy/wrap.h"
 #include "arrow/matlab/array/validation_mode.h"
 #include "arrow/matlab/error/error.h"
+#include "arrow/matlab/proxy/wrap.h"
+
 #include "libmexclass/proxy/ProxyManager.h"
 
 namespace arrow::matlab::array::proxy {
@@ -78,20 +79,9 @@ void ListArray::getValues(libmexclass::proxy::method::Context& context) {
   auto list_array = std::static_pointer_cast<arrow::ListArray>(array);
   auto value_array = list_array->values();
 
-  // Wrap the array within a proxy object if possible.
-  MATLAB_ASSIGN_OR_ERROR_WITH_CONTEXT(auto value_array_proxy, proxy::wrap(value_array),
+  MATLAB_ASSIGN_OR_ERROR_WITH_CONTEXT(context.outputs[0],
+                                      arrow::matlab::proxy::wrap_and_manage(value_array),
                                       context, error::UNKNOWN_PROXY_FOR_ARRAY_TYPE);
-  const auto value_array_proxy_id = ProxyManager::manageProxy(value_array_proxy);
-  const auto type_id = value_array->type_id();
-
-  // Return a struct with two fields: ProxyID and TypeID. The MATLAB
-  // layer will use these values to construct the appropriate MATLAB
-  // arrow.array.Array subclass.
-  mda::ArrayFactory factory;
-  mda::StructArray output = factory.createStructArray({1, 1}, {"ProxyID", "TypeID"});
-  output[0]["ProxyID"] = factory.createScalar(value_array_proxy_id);
-  output[0]["TypeID"] = factory.createScalar(static_cast<int32_t>(type_id));
-  context.outputs[0] = output;
 }
 
 void ListArray::getOffsets(libmexclass::proxy::method::Context& context) {

matlab/src/cpp/arrow/matlab/array/proxy/struct_array.cc

@@ -16,11 +16,10 @@
 // under the License.
 
 #include "arrow/matlab/array/proxy/struct_array.h"
-#include "arrow/matlab/array/proxy/wrap.h"
 #include "arrow/matlab/bit/pack.h"
 #include "arrow/matlab/error/error.h"
 #include "arrow/matlab/index/validate.h"
-
+#include "arrow/matlab/proxy/wrap.h"
 #include "arrow/util/utf8.h"
 
 #include "libmexclass/proxy/ProxyManager.h"
@@ -114,21 +113,9 @@ void StructArray::getFieldByIndex(libmexclass::proxy::method::Context& context)
   const int32_t index = matlab_index - 1;
 
   auto field_array = struct_array->field(index);
-
-  // Wrap the array within a proxy object if possible.
-  MATLAB_ASSIGN_OR_ERROR_WITH_CONTEXT(auto field_array_proxy, proxy::wrap(field_array),
+  MATLAB_ASSIGN_OR_ERROR_WITH_CONTEXT(context.outputs[0],
+                                      arrow::matlab::proxy::wrap_and_manage(field_array),
                                       context, error::UNKNOWN_PROXY_FOR_ARRAY_TYPE);
-  const auto field_array_proxy_id = ProxyManager::manageProxy(field_array_proxy);
-  const auto type_id = field_array->type_id();
-
-  // Return a struct with two fields: ProxyID and TypeID. The MATLAB
-  // layer will use these values to construct the appropriate MATLAB
-  // arrow.array.Array subclass.
-  mda::ArrayFactory factory;
-  mda::StructArray output = factory.createStructArray({1, 1}, {"ProxyID", "TypeID"});
-  output[0]["ProxyID"] = factory.createScalar(field_array_proxy_id);
-  output[0]["TypeID"] = factory.createScalar(static_cast<int32_t>(type_id));
-  context.outputs[0] = output;
 }
 
 void StructArray::getFieldByName(libmexclass::proxy::method::Context& context) {
@@ -154,19 +141,9 @@ void StructArray::getFieldByName(libmexclass::proxy::method::Context& context) {
   }
 
   // Wrap the array within a proxy object if possible.
-  MATLAB_ASSIGN_OR_ERROR_WITH_CONTEXT(auto field_array_proxy, proxy::wrap(field_array),
+  MATLAB_ASSIGN_OR_ERROR_WITH_CONTEXT(context.outputs[0],
+                                      arrow::matlab::proxy::wrap_and_manage(field_array),
                                       context, error::UNKNOWN_PROXY_FOR_ARRAY_TYPE);
-  const auto field_array_proxy_id = ProxyManager::manageProxy(field_array_proxy);
-  const auto type_id = field_array->type_id();
-
-  // Return a struct with two fields: ProxyID and TypeID. The MATLAB
-  // layer will use these values to construct the appropriate MATLAB
-  // arrow.array.Array subclass.
-  mda::ArrayFactory factory;
-  mda::StructArray output = factory.createStructArray({1, 1}, {"ProxyID", "TypeID"});
-  output[0]["ProxyID"] = factory.createScalar(field_array_proxy_id);
-  output[0]["TypeID"] = factory.createScalar(static_cast<int32_t>(type_id));
-  context.outputs[0] = output;
 }
 
 void StructArray::getFieldNames(libmexclass::proxy::method::Context& context) {

matlab/src/cpp/arrow/matlab/array/proxy/wrap.cc

@@ -18,11 +18,9 @@
 #include "arrow/array.h"
 #include "arrow/c/bridge.h"
 
-#include "arrow/matlab/array/proxy/wrap.h"
 #include "arrow/matlab/c/proxy/array_importer.h"
 #include "arrow/matlab/error/error.h"
-
-#include "libmexclass/proxy/ProxyManager.h"
+#include "arrow/matlab/proxy/wrap.h"
 
 namespace arrow::matlab::c::proxy {
 
@@ -35,7 +33,6 @@ libmexclass::proxy::MakeResult ArrayImporter::make(
 
 void ArrayImporter::import(libmexclass::proxy::method::Context& context) {
   namespace mda = ::matlab::data;
-  using namespace libmexclass::proxy;
 
   mda::StructArray args = context.inputs[0];
   const mda::TypedArray<uint64_t> arrow_array_address_mda = args[0]["ArrowArrayAddress"];
@@ -52,18 +49,9 @@ void ArrayImporter::import(libmexclass::proxy::method::Context& context) {
                                       arrow::ImportArray(arrow_array, arrow_schema),
                                       context, error::C_IMPORT_FAILED);
 
-  MATLAB_ASSIGN_OR_ERROR_WITH_CONTEXT(auto array_proxy,
-                                      arrow::matlab::array::proxy::wrap(array), context,
-                                      error::UNKNOWN_PROXY_FOR_ARRAY_TYPE);
-
-  mda::ArrayFactory factory;
-  const auto array_proxy_id = ProxyManager::manageProxy(array_proxy);
-  const auto array_proxy_id_mda = factory.createScalar(array_proxy_id);
-  const auto array_type_id_mda =
-      factory.createScalar(static_cast<int32_t>(array->type_id()));
-
-  context.outputs[0] = array_proxy_id_mda;
-  context.outputs[1] = array_type_id_mda;
+  MATLAB_ASSIGN_OR_ERROR_WITH_CONTEXT(context.outputs[0],
+                                      arrow::matlab::proxy::wrap_and_manage(array),
+                                      context, error::UNKNOWN_PROXY_FOR_ARRAY_TYPE);
 }
 
 }  // namespace arrow::matlab::c::proxy