sgilmore10 opened a new pull request, #36978:
URL: https://github.com/apache/arrow/pull/36978
<!--
Thanks for opening a pull request!
If this is your first pull request you can find detailed information on how
to contribute here:
* [New Contributor's
Guide](https://arrow.apache.org/docs/dev/developers/guide/step_by_step/pr_lifecycle.html#reviews-and-merge-of-the-pull-request)
* [Contributing
Overview](https://arrow.apache.org/docs/dev/developers/overview.html)
If this is not a [minor
PR](https://github.com/apache/arrow/blob/main/CONTRIBUTING.md#Minor-Fixes).
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](http://theapacheway.com/open/#:~:text=Openness%20allows%20new%20users%20the,must%20happen%20in%20the%20open.)
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}
-->
### Rationale for this change
As discussed in #36855, we think it would be better to move the recommended
APIs for the MATLAB Interface directly under the top-level `arrow.*` package.
This should help simplify the interface, and will make it easier for users to
switch between multiple language bindings. We have already moved the `type`
convenience constructors to the `arrow` package. Now we want to add a gateway
function that creates arrays to mirror `PyArrow`. As part of this change, we
will modify the array constructors to accept `libmexclass.proxy.Proxy` objects
- similar to how the `arrow.type.<Type>` constructors accept
`libmexclass.proxy.Proxy` objects.
### What changes are included in this PR?
1. Added `arrow.array()` gateway function that can be used to construct
arrays:
```matlab
>> arrowArray = arrow.array([1 2 3 4]);
>> class(arrowArray)
ans =
'arrow.array.Float64Array'
>> arrowArray = arrow.array(["A" "B" "C"]);
>> class(arrowArray)
ans =
'arrow.array.StringArray'
```
2. Added a static `fromMATLAB()` method to all subclasses
of`arrow.array.Array`.
```matlab
>> array = arrow.array.StringArray.fromMATLAB(["A" "B" "C"])
array =
[
"A",
"B",
"C"
]
>> array = arrow.array.TimestampArray.fromMATLAB(datetime(2023, 8, 1))
array =
[
2023-08-01 00:00:00.000000
]
```
As part of this change, users can no longer use the `arrow.array.Array`
subclass constructors to create arrays. Instead, they can use either
`arrow.array()` or the static `fromMATLAB` method.
### Are these changes tested?
Updated the existing tests to account for the API changes and added the
following new test classes:
1. arrow/internal/validate/tType.m
2. arrow/internal/validate/tShape.m
3. arrow/internal/validate/tRealNumeric.m
4. arrow/internal/validate/tNonsparse.m
5. arrow/internal/validate/tNumeric.m
6. arrow/array/tArray.m
### Are there any user-facing changes?
Yes, we changed the signature of all `arrow.array.Array` subclasses to
accept scalar `libmexclass.proxy.Proxy` classes. NOTE: The MATLAB interface is
still under active development.
### Future Directions
1. In a followup PR, we plan on adding a new name-value pair to
`arrow.array()` called `Type`, which can be set to an `arrow.type.Type` object.
This will let users specify what kind of arrow array they would like to create
from MATLAB data.
<!--
If there are any breaking changes to public APIs, please uncomment the line
below and explain which changes are breaking.
-->
<!-- **This PR includes breaking changes to public APIs.** -->
<!--
Please uncomment the line below (and provide explanation) if the changes fix
either (a) a security vulnerability, (b) a bug that caused incorrect or invalid
data to be produced, or (c) a bug that causes a crash (even when the API
contract is upheld). We use this to highlight fixes to issues that may affect
users without their knowledge. For this reason, fixing bugs that cause errors
don't count, since those are usually obvious.
-->
<!-- **This PR contains a "Critical Fix".** -->
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
