GH-38419: [MATLAB] Implement a ClassTypeValidator class that validates a MATLAB cell array contains only values of the same class type.

[sgilmore10]

Rationale for this change

Adding this ClassTypeValidator class is a step towards implementing the arrow.array.ListArray.fromMATLAB() method for creating ListArrays whose ValueTypes is either a numeric, boolean, string, time32, or time64 array from a MATLAB cell array.

What changes are included in this PR?

Added an abstract class arrow.array.internal.list.ListTypeValidator that defines three abstract methods:

1. validateElement(obj, element)
2. length = getElementLength(obj, element)
3. C = reshapeCellElements(obj, C)

These abstract methods will be used in ListArray.fromMATLAB to create ListArrays from MATLAB cell arrays. Below is a "pared-down" version of how the fromMATLAB algorithm will work:

function listArray = fromMATLAB(C)

    % Create the appropriate ListTypeValidator from the
    % first element in the cell array C
    validator = createListTypeValidator(C{1});

    % Pre-allocate a uint32 vector for the offsets
    numRows = numel(C);
    offsets = zeros([numRows 1], "int32");

    for ii = 1:numRows
         cellElement = C{ii};
    
        % Validate cellElement can be used to create
        % one row in the ListArray, i.e. For example,
        % if the first element in C was a double, verify
        % cellElement is also a double.
        validator.validateElement(cellElement);

        % Determine how much to increment the 
        % last offset value by to set the offset at index ii + 1.
        length = validator.getElementLEngth(cellElement);
        offsets[ii + 1] = length + offsets[i];
    end

    % Reshape the elements in cell array C so that they
    % can be vertically concatenated.
    C = validator.reshapeCellElements(C);
    
    % Extract the cell array elements and vertically concatenate
    % them into one array. Then pass this array to arrow.array().
    values = vertcat(C{:});
    valueArray = arrow.array(values);
     
    % Create an Int32Array from offsets
    offsetArray = arrow.array(offsets);

    listArray = arrow.array.ListArray(Values=valueArray, Offsets=offsetArray)
end

The concrete type of the validator object is created based on the first element in the cell array C. We use the first element to determine what kind of ListArray to construct from the input cell array.

--

Added a concrete class called arrow.array.internal.list.ClassTypeValidator, which inherits from arrow.array.internal.list.ListTypeValidator:

1. validateElement(obj, element) - Throws an error if the element's class type does not match the expected value.
2. length = getElementLength(obj, element) - Returns the number of elements in the input array.
3. C = reshapeCellElements(obj, C) - Reshapes all elements in the cell array C to be column vectors.

ClassTypeValidator will be used when creating ListArrays from MATLAB cell arrays containing "primitive types", such as numerics, strings, and durations.

Are these changes tested?

Yes. I added a new class called tClassTypeValidator.m.

Are there any user-facing changes?

No.

Future Directions

1. [MATLAB] Implement a DatetimeValidator class that validates a MATLAB cell array contains only values of zoned or unzoned datetimes #38420
2. [MATLAB] Implement a TableTypeValidator class that validates a MATLAB cell array contains only tables that share the same schema #38417
3. [MATLAB] Implement fromMATLAB method for arrow.array.ListArray. #38354

• Closes: [MATLAB] Implement a ClassTypeValidator class that validates a MATLAB cell array contains only values of the same class type.  #38419

[github-actions]

Thanks for opening a pull request!

If this is not a minor PR. Could you open an issue for this pull request on GitHub? https://github.com/apache/arrow/issues/new/choose

Opening GitHub issues ahead of time contributes to the Openness of the Apache Arrow project.

Then could you also rename the pull request title in the following format?

GH-${GITHUB_ISSUE_ID}: [${COMPONENT}] ${SUMMARY}

or

MINOR: [${COMPONENT}] ${SUMMARY}

In the case of PARQUET issues on JIRA the title also supports:

PARQUET-${JIRA_ISSUE_ID}: [${COMPONENT}] ${SUMMARY}

See also:

• Other pull requests
• Contribution Guidelines - How to contribute patches

[kevingurney]

Looks good! Thanks for the pull request!

[kevingurney]

+1

[conbench-apache-arrow]

After merging your PR, Conbench analyzed the 4 benchmarking runs that have been run so far on merge-commit aaf01e8.

There were no benchmark performance regressions. 🎉

The full Conbench report has more details.