GH-47263: [MATLAB] Add NumNulls property to arrow.array.ChunkedArray class (#47264)

### Rationale for this change

This is a followup to #38422. Now that `NumNulls` is a property on `arrow.array.Array`, we should add `NumNulls` as a property on `arrow.array.ChunkedArray`.

### What changes are included in this PR?

Added `NumNulls` as a property to `arrow.array.ChunkedArray`.

**Example**:
```matlab
>> a1 = arrow.array(1:10);
>> a2 = arrow.array([11 12 NaN 14 NaN]);
>> a3 = arrow.array([16 17 NaN 18 19]);
>> a4 = arrow.array(20:30);

>> C1 = arrow.array.ChunkedArray.fromArrays(a1, a2, a3)

C1 = 

  ChunkedArray with properties:

           Type: [1×1 arrow.type.Float64Type]
      NumChunks: 4
    NumElements: 31
       NumNulls: 3

>> C1.NumNulls

ans =

  int64

   3
```

### Are these changes tested?

1. Added a `NumNullsNoSetter` test case to `tChunkedArray.m`.
2. Updated `tChunkedArray/verifyChunkedArray` helper method to verify the `NumNulls` property value is set to the expected value.

### Are there any user-facing changes?

Yes. `arrow.array.ChunkedArray` has a new public property called `NumNulls`.

* GitHub Issue: #47263

Authored-by: Sarah Gilmore <[email protected]>
Signed-off-by: Sutou Kouhei <[email protected]>

Author: sgilmore10

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

@@ -52,6 +52,7 @@ ChunkedArray::ChunkedArray(std::shared_ptr<arrow::ChunkedArray> chunked_array)
     : chunked_array{std::move(chunked_array)} {
   // Register Proxy methods.
   REGISTER_METHOD(ChunkedArray, getNumElements);
+  REGISTER_METHOD(ChunkedArray, getNumNulls);
   REGISTER_METHOD(ChunkedArray, getNumChunks);
   REGISTER_METHOD(ChunkedArray, getChunk);
   REGISTER_METHOD(ChunkedArray, getType);
@@ -94,6 +95,13 @@ void ChunkedArray::getNumElements(libmexclass::proxy::method::Context& context)
   context.outputs[0] = num_elements_mda;
 }
 
+void ChunkedArray::getNumNulls(libmexclass::proxy::method::Context& context) {
+  namespace mda = ::matlab::data;
+  mda::ArrayFactory factory;
+  auto num_nulls_mda = factory.createScalar(chunked_array->null_count());
+  context.outputs[0] = num_nulls_mda;
+}
+
 void ChunkedArray::getNumChunks(libmexclass::proxy::method::Context& context) {
   namespace mda = ::matlab::data;
   mda::ArrayFactory factory;

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

@@ -37,6 +37,8 @@ class ChunkedArray : public libmexclass::proxy::Proxy {
  protected:
   void getNumElements(libmexclass::proxy::method::Context& context);
 
+  void getNumNulls(libmexclass::proxy::method::Context& context);
+
   void getNumChunks(libmexclass::proxy::method::Context& context);
 
   void getChunk(libmexclass::proxy::method::Context& context);

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

@@ -26,6 +26,7 @@
         Type
         NumChunks
         NumElements
+        NumNulls
     end
 
     methods
@@ -45,6 +46,10 @@
             numElements = obj.Proxy.getNumElements();
         end
 
+        function numNulls = get.NumNulls(obj)
+            numNulls = obj.Proxy.getNumNulls();
+        end
+
         function type = get.Type(obj)
             typeStruct = obj.Proxy.getType();
             traits = arrow.type.traits.traits(arrow.type.ID(typeStruct.TypeID));
@@ -123,5 +128,5 @@
 
             chunkedArray = arrow.array.ChunkedArray(proxy);
         end
-    end 
-end
+    end
+end

matlab/test/arrow/array/tChunkedArray.m

@@ -113,8 +113,9 @@ function TestIsEqualTrue(testCase)
             %
             %  1. Their Type properties are equal
             %  2. Their NumElements properties are equal
-            %  3. The same elements are considered null
-            %  4. All corresponding valid elements have the same values
+            %  3. Their NumNulls properties are equal
+            %  4. The same elements are considered null
+            %  5. All corresponding valid elements have the same values
             %
             % NOTE: Having the same "chunking" is not a requirement for two
             % ChunkedArrays to be equal. ChunkedArrays are considered equal
@@ -204,6 +205,18 @@ function NumElementsNoSetter(testCase)
             testCase.verifyError(fcn, "MATLAB:class:SetProhibited");
         end
 
+        function NumNullsNoSetter(testCase)
+            % Verify an error is thrown when trying to set the value
+            % of the NumNulls property.
+            import arrow.array.ChunkedArray
+
+            arrays = {testCase.Float64Array1, testCase.Float64Array2, testCase.Float64Array3};
+            chunkedArray = ChunkedArray.fromArrays(arrays{:});
+            
+            fcn = @() setfield(chunkedArray, "NumNulls", int64(100));
+            testCase.verifyError(fcn, "MATLAB:class:SetProhibited");
+        end
+
         function ChunkNonNumericIndexError(testCase)
             % Verify that an error is thrown when a non-numeric index value
             % is provided to the chunk() method.
@@ -476,10 +489,14 @@ function verifyChunkedArray(testCase, chunkedArray, opts)
             end
             testCase.assertTrue(numel(opts.Arrays) == opts.NumChunks); 
             allNumElements = cellfun(@(a) a.NumElements, opts.Arrays, UniformOutput=true);
+            allNumNulls = cellfun(@(a) a.NumNulls, opts.Arrays, UniformOutput=true);
+
             expectedNumElements = int64(sum(allNumElements));
+            expectedNumNulls = int64(sum(allNumNulls));
 
             testCase.verifyEqual(chunkedArray.NumChunks, opts.NumChunks);
             testCase.verifyEqual(chunkedArray.NumElements, expectedNumElements);
+            testCase.verifyEqual(chunkedArray.NumNulls, expectedNumNulls);
             testCase.verifyEqual(chunkedArray.Type, opts.Type);
 
             for ii = 1:opts.NumChunks