Commits


sgilmore10 authored and GitHub committed 0344a2cdf62
GH-36217: [MATLAB] Add arrow.array.TimestampArray (#36333) ### Rationale for this change We would like to extend the MATLAB interface to support timestamp data. ### What changes are included in this PR? 1. Added a new `arrow.array.MATLABArray` class that can be converted to/from a MATLAB `datetime` array. 2. Added a new type class called `arrow.type.TimestampType`. 3. Added a new enum class called `arrow.type.TimeUnit`. **Example** ```matlab >> dates = datetime(2023, 6, 27) + days(0:3)' dates = 3×1 datetime array 27-Jun-2023 28-Jun-2023 29-Jun-2023 >> timestampArray = arrow.array.TimestampArray(dates) timestampArray = [ 2023-06-27 00:00:00.000000, 2023-06-28 00:00:00.000000, 2023-06-29 00:00:00.000000 ] >> fromArrow = datetime(timestampArray) fromArrow = 3×1 datetime array 27-Jun-2023 28-Jun-2023 29-Jun-2023 >> isequal(dates, fromArrow) ans = logical 1 ``` `TimestampArray` uses `Microsecond` as the default `TimeUnit.` However, you can specify the `TimeUnit` via a name-value pair during construction. ```matlab >> timestampArray = arrow.array.TimestampArray(dates, TimeUnit="second") timestampArray = [ 2023-06-27 00:00:00, 2023-06-28 00:00:00, 2023-06-29 00:00:00 ] >> timestampArray.Type ans = TimestampType with properties: TimeZone: "" TimeUnit: Second ID: Timestamp BitWidth: 64 NumFields: 0 NumBuffers: 2 ``` The `TimestampArray` is timezone-aware if the MATLAB `datetime` array's TimeZone property is set: ```matlab >> dates = datetime(2023, 6, 27, TimeZone="America/Anchorage") + days(0:3)'; >> timestampArray = arrow.array.TimestampArray(dates); >> timestampArray.Type.TimeZone ans = "America/Anchorage" ``` Lastly, `arrow.array.TimestampArray` treats `NaT` as null values by default. However, users can control this behavior by supplying either `InferNulls` or `Valid` as name-value pairs. ```matlab >> dates = [datetime(2023, 6, 27) NaT datetime(2023, 6, 29)]; >> timestampArray = arrow.array.TimestampArray(dates) timestampArray = [ 2023-06-27 00:00:00.000000, null, 2023-06-29 00:00:00.000000 ] >> timestampArray = arrow.array.TimestampArray(dates, Valid=3) timestampArray = [ null, null, 2023-06-29 00:00:00.000000 ] ``` ### Are these changes tested? Added three new test files: 1. `tTimestampArray.m` 2.`tTimestampType.m` 3. `tTimeUnit.m` ### Are there any user-facing changes? Yes. 1. Added `arrow.array.TimestampArray` ### Notes Thank you @ kevingurney for the help! * Closes: #36217 Authored-by: Sarah Gilmore <sgilmore@mathworks.com> Signed-off-by: Sutou Kouhei <kou@clear-code.com>