apacheGH-38532: [MATLAB] Add a validate method to all arrow.array.Array classes (apache#47059)

### Rationale for this change

As a follow up to apache#38531 (see apache#38531 (comment)), we should consider adding a `validate` method to all `arrow.array.Array` classes, which would allow users to explicitly validate the contents of an `arrow.array.Array` after it is created.

### What changes are included in this PR?

Added `validate()` as a method to `arrow.array.Array`. This method has one name-value pair which is called `ValidationMode`. `ValidationMode` can either be specified as `"minimal"` or `"full"`. By default, `ValidationMode="minimal"`.

**Example Usage:**

```matlab
>> offsets = arrow.array(int32([0 1 0]));
>> values = arrow.array(1:3);
>> array = arrow.array.ListArray.fromArrays(offsets, values);
>> array.validate(ValidationMode="full")
>> array.validate(ValidationMode="full")
Error using .  (line 63)
Offset invariant failure: non-monotonic offset at slot 2: 0 < 1

Error in arrow.array.Array/validate (line 68)
             obj.Proxy.validate(struct(ValidationMode=uint8(opts.ValidationMode)));
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

```

### Are these changes tested?

Yes. Added a MATLAB test class called `tValidateArray.m`.

### Are there any user-facing changes?

Yes. There is a new public method that is accessible via any subclass of `arrow.array.Array`. 

* GitHub Issue: apache#38532

Lead-authored-by: Sarah Gilmore <[email protected]>
Co-authored-by: Sarah Gilmore <[email protected]>
Co-authored-by: Kevin Gurney <[email protected]>
Signed-off-by: Sarah Gilmore <[email protected]>

Author: sgilmore10

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

@@ -19,6 +19,7 @@
 #include "arrow/util/utf8.h"
 
 #include "arrow/matlab/array/proxy/array.h"
+#include "arrow/matlab/array/validation_mode.h"
 #include "arrow/matlab/bit/unpack.h"
 #include "arrow/matlab/error/error.h"
 #include "arrow/matlab/index/validate.h"
@@ -41,6 +42,7 @@ Array::Array(std::shared_ptr<arrow::Array> array) : array{std::move(array)} {
   REGISTER_METHOD(Array, isEqual);
   REGISTER_METHOD(Array, slice);
   REGISTER_METHOD(Array, exportToC);
+  REGISTER_METHOD(Array, validate);
 }
 
 std::shared_ptr<arrow::Array> Array::unwrap() { return array; }
@@ -175,4 +177,37 @@ void Array::exportToC(libmexclass::proxy::method::Context& context) {
       error::C_EXPORT_FAILED);
 }
 
+void Array::validate(libmexclass::proxy::method::Context& context) {
+  namespace mda = ::matlab::data;
+  mda::StructArray args = context.inputs[0];
+  const mda::TypedArray<std::uint8_t> validation_mode_mda = args[0]["ValidationMode"];
+  const auto validation_mode_integer = uint8_t(validation_mode_mda[0]);
+  // Convert integer representation to ValidationMode enum.
+  const auto validation_mode = static_cast<ValidationMode>(validation_mode_integer);
+  switch (validation_mode) {
+    case ValidationMode::None: {
+      // Do nothing.
+      break;
+    }
+    case ValidationMode::Minimal: {
+      MATLAB_ERROR_IF_NOT_OK_WITH_CONTEXT(array->Validate(), context,
+                                          error::ARRAY_VALIDATE_MINIMAL_FAILED);
+      break;
+    }
+    case ValidationMode::Full: {
+      MATLAB_ERROR_IF_NOT_OK_WITH_CONTEXT(array->ValidateFull(), context,
+                                          error::ARRAY_VALIDATE_FULL_FAILED);
+      break;
+    }
+    default: {
+      // Throw an error if an unsupported enumeration value is provided.
+      const auto msg = "Unsupported ValidationMode enumeration value: " +
+                       std::to_string(validation_mode_integer);
+      context.error =
+          libmexclass::error::Error{error::ARRAY_VALIDATE_UNSUPPORTED_ENUM, msg};
+      return;
+    }
+  }
+}
+
 }  // namespace arrow::matlab::array::proxy

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

@@ -47,6 +47,8 @@ class Array : public libmexclass::proxy::Proxy {
 
   void exportToC(libmexclass::proxy::method::Context& context);
 
+  void validate(libmexclass::proxy::method::Context& context);
+
   std::shared_ptr<arrow::Array> array;
 };
 

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

@@ -17,7 +17,6 @@
 
 #include "arrow/matlab/array/proxy/list_array.h"
 #include "arrow/matlab/array/proxy/numeric_array.h"
-#include "arrow/matlab/array/validation_mode.h"
 #include "arrow/matlab/error/error.h"
 #include "arrow/matlab/proxy/wrap.h"
 
@@ -29,7 +28,6 @@ ListArray::ListArray(std::shared_ptr<arrow::ListArray> list_array)
     : proxy::Array{std::move(list_array)} {
   REGISTER_METHOD(ListArray, getValues);
   REGISTER_METHOD(ListArray, getOffsets);
-  REGISTER_METHOD(ListArray, validate);
 }
 
 libmexclass::proxy::MakeResult ListArray::make(
@@ -98,37 +96,4 @@ void ListArray::getOffsets(libmexclass::proxy::method::Context& context) {
   context.outputs[0] = factory.createScalar(offsets_int32_array_proxy_id);
 }
 
-void ListArray::validate(libmexclass::proxy::method::Context& context) {
-  namespace mda = ::matlab::data;
-  mda::StructArray args = context.inputs[0];
-  const mda::TypedArray<std::uint8_t> validation_mode_mda = args[0]["ValidationMode"];
-  const auto validation_mode_integer = uint8_t(validation_mode_mda[0]);
-  // Convert integer representation to ValidationMode enum.
-  const auto validation_mode = static_cast<ValidationMode>(validation_mode_integer);
-  switch (validation_mode) {
-    case ValidationMode::None: {
-      // Do nothing.
-      break;
-    }
-    case ValidationMode::Minimal: {
-      MATLAB_ERROR_IF_NOT_OK_WITH_CONTEXT(array->Validate(), context,
-                                          error::ARRAY_VALIDATE_MINIMAL_FAILED);
-      break;
-    }
-    case ValidationMode::Full: {
-      MATLAB_ERROR_IF_NOT_OK_WITH_CONTEXT(array->ValidateFull(), context,
-                                          error::ARRAY_VALIDATE_FULL_FAILED);
-      break;
-    }
-    default: {
-      // Throw an error if an unsupported enumeration value is provided.
-      const auto msg = "Unsupported ValidationMode enumeration value: " +
-                       std::to_string(validation_mode_integer);
-      context.error =
-          libmexclass::error::Error{error::ARRAY_VALIDATE_UNSUPPORTED_ENUM, msg};
-      return;
-    }
-  }
-}
-
 }  // namespace arrow::matlab::array::proxy

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

@@ -32,7 +32,6 @@ class ListArray : public arrow::matlab::array::proxy::Array {
  protected:
   void getValues(libmexclass::proxy::method::Context& context);
   void getOffsets(libmexclass::proxy::method::Context& context);
-  void validate(libmexclass::proxy::method::Context& context);
 };
 
 }  // namespace arrow::matlab::array::proxy

matlab/src/matlab/+arrow/+array/Array.m

@@ -53,6 +53,20 @@
             proxy = libmexclass.proxy.Proxy(Name=traits.TypeProxyClassName, ID=typeStruct.ProxyID);
             type = traits.TypeConstructor(proxy);
         end
+
+        function validate(obj, opts)
+             arguments
+                obj
+                opts.Mode(1, 1) arrow.array.ValidationMode = arrow.array.ValidationMode.Minimal
+             end
+
+             if opts.Mode == arrow.array.ValidationMode.None
+                 id = "arrow:array:InvalidValidationMode";
+                 msg = "Invalid Mode. Mode must be ""Minimal"" or ""Full"".";
+                 error(id, msg);
+             end
+             obj.Proxy.validate(struct(ValidationMode=uint8(opts.Mode)));
+        end
     end
 
     methods (Access = private)

matlab/test/arrow/array/tValidateArray.m

@@ -0,0 +1,101 @@
+%TVALIDATEARRAY Test class for the arrow.array.Array/validate() method.
+
+% 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.
+
+classdef tValidateArray < matlab.unittest.TestCase
+
+    methods (Test)
+
+        function InvalidModeInput(test)
+            % Verify arrow.array.Array/validate() throws an exception if
+            % provided an invalid value for the Mode name-value 
+            % pair.
+            array = arrow.array.Float64Array.fromMATLAB(1:5);
+
+            % Cannot convert "abc" to a ValidationMode value
+            fcn = @() array.validate(Mode="abc");
+            test.verifyError(fcn, "MATLAB:validation:UnableToConvert");
+
+            % Mode must be scalar
+            modes = [arrow.array.ValidationMode.Full arrow.array.ValidationMode.Minimal];
+            fcn = @() array.validate(Mode=modes);
+            test.verifyError(fcn, "MATLAB:validation:IncompatibleSize");
+
+            % ValidationMode.None is not supported
+            mode = arrow.array.ValidationMode.None;
+            fcn = @() array.validate(Mode=mode);
+            test.verifyError(fcn, "arrow:array:InvalidValidationMode");
+        end
+
+        function ValidationModeMinimalFails(test)
+            % Verify arrow.array.Array/validate() throws an exception 
+            % with the ID arrow:array:ValidateMinimalFailed if
+            % Mode="Minimal" and the array fails the "Minimal"
+            % validation checks.
+            offsets = arrow.array(int32([0 1 3 4 5]));
+            values = arrow.array([1 2 3]);
+            array = arrow.array.ListArray.fromArrays(offsets, values, ValidationMode="None");
+            fcn = @() array.validate(Mode="Minimal");
+            test.verifyError(fcn, "arrow:array:ValidateMinimalFailed")
+        end
+
+        function ValidationModeMinimalPasses(test)
+            % Verify arrow.array.Array/validate() does not throw an
+            % exception if Mode="Minimal" and the array passes the
+            % "Minimal" validation checks.
+            offsets = arrow.array(int32([0 1 0]));
+            values = arrow.array([1 2 3]);
+            % NOTE: the array is actually invalid, but it passes the
+            % "Minimal" validation checks.
+            array = arrow.array.ListArray.fromArrays(offsets, values);
+            fcn = @() array.validate(Mode="Minimal");
+            test.verifyWarningFree(fcn, "arrow:array:ValidateMinimalFailed")
+        end
+
+        function ValidationModeFullFails(test)
+            % Verify arrow.array.Array/validate() throws an exception 
+            % with the ID arrow:array:ValidateFullFailed if
+            % Mode="Full" and the array fails the "Full"
+            % validation checks.
+            offsets = arrow.array(int32([0 1 0]));
+            values = arrow.array([1 2 3]);
+            array = arrow.array.ListArray.fromArrays(offsets, values);
+            fcn = @() array.validate(Mode="Full");
+            test.verifyError(fcn, "arrow:array:ValidateFullFailed")
+        end
+
+        function ValidationModeFullPasses(test)
+            % Verify arrow.array.Array/validate() does not throw an
+            % exception if Mode="Full" and the array passes
+            % the "full" validation checks.
+            offsets = arrow.array(int32([0 1 3]));
+            values = arrow.array([1 2 3]);
+            array = arrow.array.ListArray.fromArrays(offsets, values);
+            fcn = @() array.validate(Mode="Full");
+            test.verifyWarningFree(fcn);
+        end
+
+        function DefaultValidationModeIsMimimal(test)
+            % Verify the default Mode value is "Minimal".
+            offsets = arrow.array(int32([0 1 2 3]));
+            values = arrow.array([1 2 3]);
+            array = arrow.array.ListArray.fromArrays(offsets, values);
+            fcn = @() array.validate();
+            test.verifyWarningFree(fcn, "arrow:array:ValidateMinimalFailed")
+        end
+    end
+
+end