GH-38164: [MATLAB] Rename Length property on arrow.array.Array an…

…d `arrow.array.ChunkedArray` to `NumElements` (#38190)

### Rationale for this change

We would like to rename the `Length` property on `arrow.array.Array` (and `arrow.array.ChunkedArray`) to `NumElements` because MATLAB has a function called `length(A)`, which returns the length of the largest array dimension in `A`.  
Because `arrow.array.Array` inherits from `matlab.mixin.Scalar`, it's size is always `1x1`, so the `length()` function always returns `1`. This may confuse users because the `Length` property of `arrow.array.Array` returns the number of elements within the array, which may not be `1`. 

```matlab
>> array = arrow.array([1 2 3 4 5]);

% The length property returns the number of elements in the array
>> array.Length

ans =

  int64

   5

% The length method returns the length of the largest dimension
>> length(array)

ans =

     1
```

I suspect this inconsistency will confuse users, so we should rename the `Length` property to `NumElements`. 

### What changes are included in this PR?

1. Renamed `Length` property on `arrow.array.Array` to `NumElements`
2. Renamed `Length` property on `arrow.array.ChunkedArray` to `NumElements`

### Are these changes tested?

Yes. I modified the existing `Length` test cases to now test the `NumElements` property.

### Are there any user-facing changes?

Yes. Please note this is a breaking change because `Length` is no longer a property on either `arrow.array.Array` or `arrow.array.ChunkedArray`. However, we have not yet cut an initial release of the MATLAB interface, so we don't expect this change should affect too many users at this point. 

* Closes: #38164

Authored-by: Sarah Gilmore <sgilmore@mathworks.com>
Signed-off-by: Kevin Gurney <kgurney@mathworks.com>

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

@@ -31,7 +31,7 @@ namespace arrow::matlab::array::proxy {
 
         // Register Proxy methods.
         REGISTER_METHOD(Array, toString);
-        REGISTER_METHOD(Array, getLength);
+        REGISTER_METHOD(Array, getNumElements);
         REGISTER_METHOD(Array, getValid);
         REGISTER_METHOD(Array, getType);
         REGISTER_METHOD(Array, isEqual);
@@ -50,7 +50,7 @@ namespace arrow::matlab::array::proxy {
         context.outputs[0] = str_mda;
     }
 
-    void Array::getLength(libmexclass::proxy::method::Context& context) {
+    void Array::getNumElements(libmexclass::proxy::method::Context& context) {
         ::matlab::data::ArrayFactory factory;
         auto length_mda = factory.createScalar(array->length());
         context.outputs[0] = length_mda;

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

@@ -36,7 +36,7 @@ class Array : public libmexclass::proxy::Proxy {
 
         void toString(libmexclass::proxy::method::Context& context);
 
-        void getLength(libmexclass::proxy::method::Context& context);
+        void getNumElements(libmexclass::proxy::method::Context& context);
 
         void getValid(libmexclass::proxy::method::Context& context);
 

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

@@ -47,7 +47,7 @@ namespace arrow::matlab::array::proxy {
     ChunkedArray::ChunkedArray(std::shared_ptr<arrow::ChunkedArray> chunked_array) : chunked_array{std::move(chunked_array)} {
 
         // Register Proxy methods.
-        REGISTER_METHOD(ChunkedArray, getLength);
+        REGISTER_METHOD(ChunkedArray, getNumElements);
         REGISTER_METHOD(ChunkedArray, getNumChunks);
         REGISTER_METHOD(ChunkedArray, getChunk);
         REGISTER_METHOD(ChunkedArray, getType);
@@ -86,11 +86,11 @@ namespace arrow::matlab::array::proxy {
         return chunked_array;
     }
 
-    void ChunkedArray::getLength(libmexclass::proxy::method::Context& context) {
+    void ChunkedArray::getNumElements(libmexclass::proxy::method::Context& context) {
         namespace mda = ::matlab::data;
         mda::ArrayFactory factory;
-        auto length_mda = factory.createScalar(chunked_array->length());
-        context.outputs[0] = length_mda;
+        auto num_elements_mda = factory.createScalar(chunked_array->length());
+        context.outputs[0] = num_elements_mda;
     }
 
     void ChunkedArray::getNumChunks(libmexclass::proxy::method::Context& context) {

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

@@ -35,7 +35,7 @@ class ChunkedArray : public libmexclass::proxy::Proxy {
 
     protected:
 
-        void getLength(libmexclass::proxy::method::Context& context);
+        void getNumElements(libmexclass::proxy::method::Context& context);
 
         void getNumChunks(libmexclass::proxy::method::Context& context);
 

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

@@ -22,7 +22,7 @@
     end
 
     properties(Dependent, SetAccess=private, GetAccess=public)
-        Length
+        NumElements
         Valid % Validity bitmap
         Type(1, 1) arrow.type.Type
     end
@@ -35,8 +35,8 @@
             obj.Proxy = proxy;
         end
 
-        function numElements = get.Length(obj)
-            numElements = obj.Proxy.getLength();
+        function numElements = get.NumElements(obj)
+            numElements = obj.Proxy.getNumElements();
         end
 
         function validElements = get.Valid(obj)

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

@@ -25,7 +25,7 @@
     properties(Dependent, SetAccess=private, GetAccess=public)
         Type
         NumChunks
-        Length
+        NumElements
     end
 
     methods
@@ -41,8 +41,8 @@
             numChunks = obj.Proxy.getNumChunks();
         end
 
-        function length = get.Length(obj)
-            length = obj.Proxy.getLength();
+        function numElements = get.NumElements(obj)
+            numElements = obj.Proxy.getNumElements();
         end
 
         function type = get.Type(obj)
@@ -61,11 +61,11 @@
         end
 
         function data = toMATLAB(obj)
-            data = preallocateMATLABArray(obj.Type,  obj.Length);
+            data = preallocateMATLABArray(obj.Type,  obj.NumElements);
             startIndex = 1;
             for ii = 1:obj.NumChunks
                 chunk = obj.chunk(ii);
-                endIndex = startIndex + chunk.Length - 1;
+                endIndex = startIndex + chunk.NumElements - 1;
                 % Use 2D indexing to support tabular MATLAB types.
                 data(startIndex:endIndex, :) = toMATLAB(chunk);
                 startIndex = endIndex + 1;

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

@@ -133,7 +133,7 @@
 
             validateArrayLengths(arrowArrays);
             validateColumnNames(opts.FieldNames, numel(arrowArrays));
-            validElements = parseValid(opts, arrowArrays{1}.Length);
+            validElements = parseValid(opts, arrowArrays{1}.NumElements);
 
             arrayProxyIDs = getArrayProxyIDs(arrowArrays);
             args = struct(ArrayProxyIDs=arrayProxyIDs, ...

matlab/src/matlab/+arrow/+tabular/+internal/validateArrayLengths.m

@@ -24,14 +24,14 @@ function validateArrayLengths(arrowArrays)
         return;
     end
 
-    expectedLength = arrowArrays{1}.Length;
+    expectedNumElements = arrowArrays{1}.NumElements;
 
     for ii = 2:numel(arrowArrays)
-        if arrowArrays{ii}.Length ~= expectedLength
+        if arrowArrays{ii}.NumElements ~= expectedNumElements
             errid = "arrow:tabular:UnequalArrayLengths";
-            msg = compose("Expected all arrays to have a length of %d," + ...
-                " but the array at position %d has a length of %d.", ...
-                expectedLength, ii, arrowArrays{ii}.Length);
+            msg = compose("Expected all arrays to have %d elements," + ...
+                " but the array at position %d has %d elements.", ...
+                    expectedNumElements, ii, arrowArrays{ii}.NumElements);
             error(errid, msg);
         end
     end

matlab/test/arrow/array/hNumericArray.m

@@ -105,7 +105,7 @@ function ErrorIfNonVector(tc)
         function AllowNDimensionalEmptyArray(tc)
             data = tc.MatlabArrayFcn(reshape([], [1 0 0]));
             A = tc.ArrowArrayConstructorFcn(data);
-            tc.verifyEqual(A.Length, int64(0));
+            tc.verifyEqual(A.NumElements, int64(0));
             tc.verifyEqual(toMATLAB(A), tc.MatlabArrayFcn(reshape([], [0 1])));
         end
 
@@ -154,7 +154,7 @@ function TestIsEqualTrue(tc)
             % Verifies arrays are considered equal if:
             %
             %  1. Their Type properties are equal
-            %  2. They have the same length (i.e. their Length properties are equal)
+            %  2. They have the same number of elements (i.e. their NumElements properties are equal)
             %  3. They have the same validity bitmap (i.e. their Valid properties are equal)
             %  4. All corresponding valid elements have the same values
 
@@ -191,7 +191,7 @@ function TestIsEqualFalse(tc)
             % Their Type properties are not equal
             tc.verifyFalse(isequal(array1, array4));
 
-            % Their Length properties are not equal
+            % Their NumElements properties are not equal
             tc.verifyFalse(isequal(array1, array5));
 
             % Comparing an arrow.array.Array to a MATLAB double

matlab/test/arrow/array/tBooleanArray.m

@@ -142,7 +142,7 @@ function ErrorIfNonVector(tc)
         function AllowNDimensionalEmptyArray(tc)
             data = tc.MatlabArrayFcn(reshape([], [1 0 0]));
             A = tc.ArrowArrayConstructorFcn(data);
-            tc.verifyEqual(A.Length, int64(0));
+            tc.verifyEqual(A.NumElements, int64(0));
             tc.verifyEqual(toMATLAB(A), tc.MatlabArrayFcn(reshape([], [0 1])));
         end
 
@@ -163,7 +163,7 @@ function TestIsEqualTrue(tc)
             % Verifies arrays are considered equal if:
             %
             %  1. Their Type properties are equal
-            %  2. They have the same length (i.e. their Length properties are equal)
+            %  2. They have the same number of elements (i.e. their NumElements properties are equal)
             %  3. They have the same validity bitmap (i.e. their Valid properties are equal)
             %  4. All corresponding valid elements have the same values
 
@@ -202,7 +202,7 @@ function TestIsEqualFalse(tc)
             % Their Type properties are not equal
             tc.verifyFalse(isequal(array1, array4));
 
-            % Their Length properties are not equal
+            % Their NumElements properties are not equal
             tc.verifyFalse(isequal(array1, array5));
 
             % Comparing an arrow.array.Array to a MATLAB double