sgilmore10 opened a new pull request, #38020:
URL: https://github.com/apache/arrow/pull/38020
<!--
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
To unblock use cases that are not satisfied by the default Arrow -> MATLAB
conversions (i.e. the `toMATLAB()` on `arrow.array.Array`), we would like
expose the underlying Arrow data representation as a property on
`arrow.array.Array`. One possible name for this property would be `DataLayout`,
which would be an `arrow.array.DataLayout` object. Note, this class does not
yet exist, so we would have to add it.
For example, the `DataLayout` property for temporal array types would return
an object of the following class type:
```matlab
classdef TemporalDataLayout < arrow.array.DataLayout
properties
Values % an arrow.array.Int32Array or an arrow.array.Int64Array
Valid % an arrow.buffer.Buffer
end
end
```
However, the `Valid` property on this class would need to be an
`arrow.buffer.Buffer` object, which does not yet exist in the MATLAB interface.
Therefore, it would be helpful to first add the `arrow.buffer.Buffer` class
before adding the `DataLayout` property/class hierarchy. It's worth mentioning
that adding `arrow.buffer.Buffer` will open up additional advanced use cases in
the future.
### What changes are included in this PR?
Added `arrow.buffer.Buffer` MATLAB class.
*Properties of `arrow.buffer.Buffer`*
1. `NumBytes` - a scalar `int64` value representing the size of the buffer
in bytes.
*Methods of `arrow.buffer.Buffer`*
1. `toMATLAB` - returns the data in the buffer as `Nx1` `uint8` vector,
where `N` is the number of bytes.
2. `fromMATLAB(data)` - Static method that creates an `arrow.buffer.Buffer`
from a numeric array.
**Example: **
```matlab
>> dataIn = [1 2];
>> buffer = arrow.buffer.Buffer.fromMATLAB(dataIn)
buffer =
Buffer with properties:
NumBytes: 16
>> dataOut = toMATLAB(buffer)
dataOut =
16×1 uint8 column vector
0
0
0
0
0
0
240
63
0
0
0
0
0
0
0
64
% Reinterpret bit pattern as a double array
>> toDouble = typecast(dataOut, "double")
toDouble =
1
2
```
### Are these changes tested?
Yes. Added a new test class called `tBuffer.m`
### Are there any user-facing changes?
Yes. Users can now create `arrow.buffer.Buffer` objects via the `fromMATLAB`
static method. However, there's not much users can do with this object as of
now. We implemented this class to facilitate adding `DataLayout` property to
`arrow.array.Array`, as described in the **Rational for this change** section.
<!--
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]
