Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[MATLAB] Add arrow.array.ListArray MATLAB class #37815

Closed
kevingurney opened this issue Sep 20, 2023 · 1 comment · Fixed by #38357
Closed

[MATLAB] Add arrow.array.ListArray MATLAB class #37815

kevingurney opened this issue Sep 20, 2023 · 1 comment · Fixed by #38357

Comments

@kevingurney
Copy link
Member

kevingurney commented Sep 20, 2023

Describe the enhancement requested

Now that many of the commonly-used "primitive" array types have been added to the MATLAB interface, we can implement an arrow.array.ListArray class.

Component(s)

MATLAB

@github-project-automation github-project-automation bot moved this to Backlog in Arrow MATLAB Sep 20, 2023
@kevingurney kevingurney moved this from Backlog to Todo in Arrow MATLAB Sep 20, 2023
kevingurney added a commit that referenced this issue Oct 11, 2023
### Rationale for this change

In support of adding an [`arrow.array.ListArray`](#37815) MATLAB class, this pull request adds a new `arrow.type.ListType` MATLAB class.

### What changes are included in this PR?

1. New `arrow.list(<type>)` MATLAB construction function.
2. New `arrow.list.ListType` MATLAB class. `ListType` has a property named `Type` which indicates the inner type of the `List`. `Type` can be set to any subclass `arrow.type.Type` (including `arrow.type.ListType`, to support nested lists).
3. New `arrow.type.ID.List` type ID enumeration value.
4. New `arrow.type.traits.ListTraits` type traits class. Some of the properties, such as `ArrayConstructor` and `ArrayProxyClassName`, are set to `missing` because they are dependent on adding [`arrow.array.ListArray`](#37815) first.

**Example**
```matlab
% Create a simple List<String> type.
>> stringListType = arrow.list(arrow.string())

stringListType = 

  ListType with properties:

      ID: List
    Type: [1x1 arrow.type.StringType]

% Create a nested List<List<Boolean>> type.
>> nestedListType = arrow.list(arrow.list(arrow.boolean()))

nestedListType = 

  ListType with properties:

      ID: List
    Type: [1x1 arrow.type.ListType]

% Extract the first-level, inner type, which is List<Boolean>.
>> innerType = nestedListType.Type

innerType = 

  ListType with properties:

      ID: List
    Type: [1x1 arrow.type.BooleanType]

% Extract the second-level, nested inner type, which is Boolean.
>> innerType.Type  

ans = 

  BooleanType with properties:

    ID: Boolean
```

### Are these changes tested?

Yes.

1. Added `tListType.m`.
2. Added `tListTraits.m`.
3. Updated `tField.m` to include `arrow.list`.
4. Updated `tID.m` to include `arrow.type.ID.List`.
6. Updated `tTypeDisplay.m` to include `arrow.type.ListType`.
7. Updated `ttraits.m` to include `arrow.type.traits.ListTraits`.

### Are there any user-facing changes?

Yes.

Client MATLAB code can now creates instances of `arrow.type.ListType` by using the `arrow.list(<type>)` construction function.

### Future Directions

1. #37815
* Closes: #37812

Authored-by: Kevin Gurney <[email protected]>
Signed-off-by: Kevin Gurney <[email protected]>
llama90 pushed a commit to llama90/arrow that referenced this issue Oct 12, 2023
…he#38189)

### Rationale for this change

In support of adding an [`arrow.array.ListArray`](apache#37815) MATLAB class, this pull request adds a new `arrow.type.ListType` MATLAB class.

### What changes are included in this PR?

1. New `arrow.list(<type>)` MATLAB construction function.
2. New `arrow.list.ListType` MATLAB class. `ListType` has a property named `Type` which indicates the inner type of the `List`. `Type` can be set to any subclass `arrow.type.Type` (including `arrow.type.ListType`, to support nested lists).
3. New `arrow.type.ID.List` type ID enumeration value.
4. New `arrow.type.traits.ListTraits` type traits class. Some of the properties, such as `ArrayConstructor` and `ArrayProxyClassName`, are set to `missing` because they are dependent on adding [`arrow.array.ListArray`](apache#37815) first.

**Example**
```matlab
% Create a simple List<String> type.
>> stringListType = arrow.list(arrow.string())

stringListType = 

  ListType with properties:

      ID: List
    Type: [1x1 arrow.type.StringType]

% Create a nested List<List<Boolean>> type.
>> nestedListType = arrow.list(arrow.list(arrow.boolean()))

nestedListType = 

  ListType with properties:

      ID: List
    Type: [1x1 arrow.type.ListType]

% Extract the first-level, inner type, which is List<Boolean>.
>> innerType = nestedListType.Type

innerType = 

  ListType with properties:

      ID: List
    Type: [1x1 arrow.type.BooleanType]

% Extract the second-level, nested inner type, which is Boolean.
>> innerType.Type  

ans = 

  BooleanType with properties:

    ID: Boolean
```

### Are these changes tested?

Yes.

1. Added `tListType.m`.
2. Added `tListTraits.m`.
3. Updated `tField.m` to include `arrow.list`.
4. Updated `tID.m` to include `arrow.type.ID.List`.
6. Updated `tTypeDisplay.m` to include `arrow.type.ListType`.
7. Updated `ttraits.m` to include `arrow.type.traits.ListTraits`.

### Are there any user-facing changes?

Yes.

Client MATLAB code can now creates instances of `arrow.type.ListType` by using the `arrow.list(<type>)` construction function.

### Future Directions

1. apache#37815
* Closes: apache#37812

Authored-by: Kevin Gurney <[email protected]>
Signed-off-by: Kevin Gurney <[email protected]>
@kevingurney kevingurney moved this from Todo to In Progress in Arrow MATLAB Oct 17, 2023
@kevingurney
Copy link
Member Author

take

JerAguilon pushed a commit to JerAguilon/arrow that referenced this issue Oct 23, 2023
…he#38189)

### Rationale for this change

In support of adding an [`arrow.array.ListArray`](apache#37815) MATLAB class, this pull request adds a new `arrow.type.ListType` MATLAB class.

### What changes are included in this PR?

1. New `arrow.list(<type>)` MATLAB construction function.
2. New `arrow.list.ListType` MATLAB class. `ListType` has a property named `Type` which indicates the inner type of the `List`. `Type` can be set to any subclass `arrow.type.Type` (including `arrow.type.ListType`, to support nested lists).
3. New `arrow.type.ID.List` type ID enumeration value.
4. New `arrow.type.traits.ListTraits` type traits class. Some of the properties, such as `ArrayConstructor` and `ArrayProxyClassName`, are set to `missing` because they are dependent on adding [`arrow.array.ListArray`](apache#37815) first.

**Example**
```matlab
% Create a simple List<String> type.
>> stringListType = arrow.list(arrow.string())

stringListType = 

  ListType with properties:

      ID: List
    Type: [1x1 arrow.type.StringType]

% Create a nested List<List<Boolean>> type.
>> nestedListType = arrow.list(arrow.list(arrow.boolean()))

nestedListType = 

  ListType with properties:

      ID: List
    Type: [1x1 arrow.type.ListType]

% Extract the first-level, inner type, which is List<Boolean>.
>> innerType = nestedListType.Type

innerType = 

  ListType with properties:

      ID: List
    Type: [1x1 arrow.type.BooleanType]

% Extract the second-level, nested inner type, which is Boolean.
>> innerType.Type  

ans = 

  BooleanType with properties:

    ID: Boolean
```

### Are these changes tested?

Yes.

1. Added `tListType.m`.
2. Added `tListTraits.m`.
3. Updated `tField.m` to include `arrow.list`.
4. Updated `tID.m` to include `arrow.type.ID.List`.
6. Updated `tTypeDisplay.m` to include `arrow.type.ListType`.
7. Updated `ttraits.m` to include `arrow.type.traits.ListTraits`.

### Are there any user-facing changes?

Yes.

Client MATLAB code can now creates instances of `arrow.type.ListType` by using the `arrow.list(<type>)` construction function.

### Future Directions

1. apache#37815
* Closes: apache#37812

Authored-by: Kevin Gurney <[email protected]>
Signed-off-by: Kevin Gurney <[email protected]>
kevingurney added a commit that referenced this issue Oct 23, 2023
### Rationale for this change

Now that many of the commonly-used "primitive" array types have been added to the MATLAB interface, we can implement an `arrow.array.ListArray` class.

This pull request adds a new `arrow.array.ListArray` class which can be converted to a MATLAB `cell` array by calling the static `toMATLAB` method.

### What changes are included in this PR?

1. Added a new `arrow.array.ListArray` MATLAB class.

*Methods*

`cellArray = arrow.array.ListArray.toMATLAB()`
`listArray = arrow.array.ListArray.fromArrays(offsets, values)`

*Properties*

`Offsets` - `Int32Array` list offsets (uses zero-based indexing)
`Values` - Array of values in the list (supports nesting)

2. Added a new `arrow.type.traits.ListTraits` MATLAB class.

**Example**
```matlab
>> offsets = arrow.array(int32([0, 2, 3, 7]))

offsets = 

[
  0,
  2,
  3,
  7
]

>> values = arrow.array(["A", "B", "C", "D", "E", "F", "G"])

values = 

[
  "A",
  "B",
  "C",
  "D",
  "E",
  "F",
  "G"
]

>> arrowArray = arrow.array.ListArray.fromArrays(offsets, values)

arrowArray = 

[
  [
    "A",
    "B"
  ],
  [
    "C"
  ],
  [
    "D",
    "E",
    "F",
    "G"
  ]
]

>> matlabArray = arrowArray.toMATLAB()

matlabArray =

  3x1 cell array

    {2x1 string}
    {["C"     ]}
    {4x1 string}

>> matlabArray{:}

ans = 

  2x1 string array

    "A"
    "B"

ans = 

    "C"

ans = 

  4x1 string array

    "D"
    "E"
    "F"
    "G"

```

### Are these changes tested?

Yes.

1. Added a new `tListArray.m` test class.
2. Added a new `tListTraits.m` test class.
3. Updated `arrow.internal.test.tabular.createAllSupportedArrayTypes` to include `ListArray`.

### Are there any user-facing changes?

Yes.

1. Users can now create an `arrow.array.ListArray` from an `offsets` and `values` array by calling the static `arrow.array.ListArray.fromArrays(offsets, values)` method. `ListArray`s can be converted into MATLAB `cell` arrays by calling the static `arrow.array.ListArray.toMATLAB` method.

### Notes

1. We chose to use the "missing-class" `missing` value as the `NullSubstitutionValue` for the time being for `ListArray`. However, we eventually want to add `arrow.array.NullArray`, and will most likely want to use the "missing-class" `missing` value to represent `NullArray` values in MATLAB. So, this could cause some ambiguity in the future. We have been thinking about whether we should consider introducing some sort of special "sentinel value" to represent null values when converting to MATLAB `cell` arrays. Perhaps, something like `arrow.Null`, or something to that effect, in order to avoid this ambiguity. If we think it makes sense to do that, we may want to retroactively change the `NullSubstitutionValue` to be `arrow.Null` and break compatibility. Since we are still in pre-`0.1`, we don't think the impact of such a behavior change would be very large.
2. Implementing `ListArray` is fairly involved. So, in the spirit of incremental delivery, we chose not to include an implementation of `arrow.array.ListArray.fromMATLAB` in this initial pull request. We plan on following up with some more changes to `arrow.array.ListArray`. See #38353, #38354, and #38361.
3. Thank you @ sgilmore10 for your help with this pull request!

### Future Directions

1. #38353
2. #38354
3. #38361
4. Consider adding a null sentinel value like `arrow.Null` for conversion to MATLAB `cell` arrays.
* Closes: #37815 

Lead-authored-by: Kevin Gurney <[email protected]>
Co-authored-by: Sarah Gilmore <[email protected]>
Signed-off-by: Kevin Gurney <[email protected]>
@github-project-automation github-project-automation bot moved this from In Progress to Done in Arrow MATLAB Oct 23, 2023
@kevingurney kevingurney added this to the 15.0.0 milestone Oct 23, 2023
JerAguilon pushed a commit to JerAguilon/arrow that referenced this issue Oct 25, 2023
…ache#38357)

### Rationale for this change

Now that many of the commonly-used "primitive" array types have been added to the MATLAB interface, we can implement an `arrow.array.ListArray` class.

This pull request adds a new `arrow.array.ListArray` class which can be converted to a MATLAB `cell` array by calling the static `toMATLAB` method.

### What changes are included in this PR?

1. Added a new `arrow.array.ListArray` MATLAB class.

*Methods*

`cellArray = arrow.array.ListArray.toMATLAB()`
`listArray = arrow.array.ListArray.fromArrays(offsets, values)`

*Properties*

`Offsets` - `Int32Array` list offsets (uses zero-based indexing)
`Values` - Array of values in the list (supports nesting)

2. Added a new `arrow.type.traits.ListTraits` MATLAB class.

**Example**
```matlab
>> offsets = arrow.array(int32([0, 2, 3, 7]))

offsets = 

[
  0,
  2,
  3,
  7
]

>> values = arrow.array(["A", "B", "C", "D", "E", "F", "G"])

values = 

[
  "A",
  "B",
  "C",
  "D",
  "E",
  "F",
  "G"
]

>> arrowArray = arrow.array.ListArray.fromArrays(offsets, values)

arrowArray = 

[
  [
    "A",
    "B"
  ],
  [
    "C"
  ],
  [
    "D",
    "E",
    "F",
    "G"
  ]
]

>> matlabArray = arrowArray.toMATLAB()

matlabArray =

  3x1 cell array

    {2x1 string}
    {["C"     ]}
    {4x1 string}

>> matlabArray{:}

ans = 

  2x1 string array

    "A"
    "B"

ans = 

    "C"

ans = 

  4x1 string array

    "D"
    "E"
    "F"
    "G"

```

### Are these changes tested?

Yes.

1. Added a new `tListArray.m` test class.
2. Added a new `tListTraits.m` test class.
3. Updated `arrow.internal.test.tabular.createAllSupportedArrayTypes` to include `ListArray`.

### Are there any user-facing changes?

Yes.

1. Users can now create an `arrow.array.ListArray` from an `offsets` and `values` array by calling the static `arrow.array.ListArray.fromArrays(offsets, values)` method. `ListArray`s can be converted into MATLAB `cell` arrays by calling the static `arrow.array.ListArray.toMATLAB` method.

### Notes

1. We chose to use the "missing-class" `missing` value as the `NullSubstitutionValue` for the time being for `ListArray`. However, we eventually want to add `arrow.array.NullArray`, and will most likely want to use the "missing-class" `missing` value to represent `NullArray` values in MATLAB. So, this could cause some ambiguity in the future. We have been thinking about whether we should consider introducing some sort of special "sentinel value" to represent null values when converting to MATLAB `cell` arrays. Perhaps, something like `arrow.Null`, or something to that effect, in order to avoid this ambiguity. If we think it makes sense to do that, we may want to retroactively change the `NullSubstitutionValue` to be `arrow.Null` and break compatibility. Since we are still in pre-`0.1`, we don't think the impact of such a behavior change would be very large.
2. Implementing `ListArray` is fairly involved. So, in the spirit of incremental delivery, we chose not to include an implementation of `arrow.array.ListArray.fromMATLAB` in this initial pull request. We plan on following up with some more changes to `arrow.array.ListArray`. See apache#38353, apache#38354, and apache#38361.
3. Thank you @ sgilmore10 for your help with this pull request!

### Future Directions

1. apache#38353
2. apache#38354
3. apache#38361
4. Consider adding a null sentinel value like `arrow.Null` for conversion to MATLAB `cell` arrays.
* Closes: apache#37815 

Lead-authored-by: Kevin Gurney <[email protected]>
Co-authored-by: Sarah Gilmore <[email protected]>
Signed-off-by: Kevin Gurney <[email protected]>
loicalleyne pushed a commit to loicalleyne/arrow that referenced this issue Nov 13, 2023
…he#38189)

### Rationale for this change

In support of adding an [`arrow.array.ListArray`](apache#37815) MATLAB class, this pull request adds a new `arrow.type.ListType` MATLAB class.

### What changes are included in this PR?

1. New `arrow.list(<type>)` MATLAB construction function.
2. New `arrow.list.ListType` MATLAB class. `ListType` has a property named `Type` which indicates the inner type of the `List`. `Type` can be set to any subclass `arrow.type.Type` (including `arrow.type.ListType`, to support nested lists).
3. New `arrow.type.ID.List` type ID enumeration value.
4. New `arrow.type.traits.ListTraits` type traits class. Some of the properties, such as `ArrayConstructor` and `ArrayProxyClassName`, are set to `missing` because they are dependent on adding [`arrow.array.ListArray`](apache#37815) first.

**Example**
```matlab
% Create a simple List<String> type.
>> stringListType = arrow.list(arrow.string())

stringListType = 

  ListType with properties:

      ID: List
    Type: [1x1 arrow.type.StringType]

% Create a nested List<List<Boolean>> type.
>> nestedListType = arrow.list(arrow.list(arrow.boolean()))

nestedListType = 

  ListType with properties:

      ID: List
    Type: [1x1 arrow.type.ListType]

% Extract the first-level, inner type, which is List<Boolean>.
>> innerType = nestedListType.Type

innerType = 

  ListType with properties:

      ID: List
    Type: [1x1 arrow.type.BooleanType]

% Extract the second-level, nested inner type, which is Boolean.
>> innerType.Type  

ans = 

  BooleanType with properties:

    ID: Boolean
```

### Are these changes tested?

Yes.

1. Added `tListType.m`.
2. Added `tListTraits.m`.
3. Updated `tField.m` to include `arrow.list`.
4. Updated `tID.m` to include `arrow.type.ID.List`.
6. Updated `tTypeDisplay.m` to include `arrow.type.ListType`.
7. Updated `ttraits.m` to include `arrow.type.traits.ListTraits`.

### Are there any user-facing changes?

Yes.

Client MATLAB code can now creates instances of `arrow.type.ListType` by using the `arrow.list(<type>)` construction function.

### Future Directions

1. apache#37815
* Closes: apache#37812

Authored-by: Kevin Gurney <[email protected]>
Signed-off-by: Kevin Gurney <[email protected]>
loicalleyne pushed a commit to loicalleyne/arrow that referenced this issue Nov 13, 2023
…ache#38357)

### Rationale for this change

Now that many of the commonly-used "primitive" array types have been added to the MATLAB interface, we can implement an `arrow.array.ListArray` class.

This pull request adds a new `arrow.array.ListArray` class which can be converted to a MATLAB `cell` array by calling the static `toMATLAB` method.

### What changes are included in this PR?

1. Added a new `arrow.array.ListArray` MATLAB class.

*Methods*

`cellArray = arrow.array.ListArray.toMATLAB()`
`listArray = arrow.array.ListArray.fromArrays(offsets, values)`

*Properties*

`Offsets` - `Int32Array` list offsets (uses zero-based indexing)
`Values` - Array of values in the list (supports nesting)

2. Added a new `arrow.type.traits.ListTraits` MATLAB class.

**Example**
```matlab
>> offsets = arrow.array(int32([0, 2, 3, 7]))

offsets = 

[
  0,
  2,
  3,
  7
]

>> values = arrow.array(["A", "B", "C", "D", "E", "F", "G"])

values = 

[
  "A",
  "B",
  "C",
  "D",
  "E",
  "F",
  "G"
]

>> arrowArray = arrow.array.ListArray.fromArrays(offsets, values)

arrowArray = 

[
  [
    "A",
    "B"
  ],
  [
    "C"
  ],
  [
    "D",
    "E",
    "F",
    "G"
  ]
]

>> matlabArray = arrowArray.toMATLAB()

matlabArray =

  3x1 cell array

    {2x1 string}
    {["C"     ]}
    {4x1 string}

>> matlabArray{:}

ans = 

  2x1 string array

    "A"
    "B"

ans = 

    "C"

ans = 

  4x1 string array

    "D"
    "E"
    "F"
    "G"

```

### Are these changes tested?

Yes.

1. Added a new `tListArray.m` test class.
2. Added a new `tListTraits.m` test class.
3. Updated `arrow.internal.test.tabular.createAllSupportedArrayTypes` to include `ListArray`.

### Are there any user-facing changes?

Yes.

1. Users can now create an `arrow.array.ListArray` from an `offsets` and `values` array by calling the static `arrow.array.ListArray.fromArrays(offsets, values)` method. `ListArray`s can be converted into MATLAB `cell` arrays by calling the static `arrow.array.ListArray.toMATLAB` method.

### Notes

1. We chose to use the "missing-class" `missing` value as the `NullSubstitutionValue` for the time being for `ListArray`. However, we eventually want to add `arrow.array.NullArray`, and will most likely want to use the "missing-class" `missing` value to represent `NullArray` values in MATLAB. So, this could cause some ambiguity in the future. We have been thinking about whether we should consider introducing some sort of special "sentinel value" to represent null values when converting to MATLAB `cell` arrays. Perhaps, something like `arrow.Null`, or something to that effect, in order to avoid this ambiguity. If we think it makes sense to do that, we may want to retroactively change the `NullSubstitutionValue` to be `arrow.Null` and break compatibility. Since we are still in pre-`0.1`, we don't think the impact of such a behavior change would be very large.
2. Implementing `ListArray` is fairly involved. So, in the spirit of incremental delivery, we chose not to include an implementation of `arrow.array.ListArray.fromMATLAB` in this initial pull request. We plan on following up with some more changes to `arrow.array.ListArray`. See apache#38353, apache#38354, and apache#38361.
3. Thank you @ sgilmore10 for your help with this pull request!

### Future Directions

1. apache#38353
2. apache#38354
3. apache#38361
4. Consider adding a null sentinel value like `arrow.Null` for conversion to MATLAB `cell` arrays.
* Closes: apache#37815 

Lead-authored-by: Kevin Gurney <[email protected]>
Co-authored-by: Sarah Gilmore <[email protected]>
Signed-off-by: Kevin Gurney <[email protected]>
dgreiss pushed a commit to dgreiss/arrow that referenced this issue Feb 19, 2024
…he#38189)

### Rationale for this change

In support of adding an [`arrow.array.ListArray`](apache#37815) MATLAB class, this pull request adds a new `arrow.type.ListType` MATLAB class.

### What changes are included in this PR?

1. New `arrow.list(<type>)` MATLAB construction function.
2. New `arrow.list.ListType` MATLAB class. `ListType` has a property named `Type` which indicates the inner type of the `List`. `Type` can be set to any subclass `arrow.type.Type` (including `arrow.type.ListType`, to support nested lists).
3. New `arrow.type.ID.List` type ID enumeration value.
4. New `arrow.type.traits.ListTraits` type traits class. Some of the properties, such as `ArrayConstructor` and `ArrayProxyClassName`, are set to `missing` because they are dependent on adding [`arrow.array.ListArray`](apache#37815) first.

**Example**
```matlab
% Create a simple List<String> type.
>> stringListType = arrow.list(arrow.string())

stringListType = 

  ListType with properties:

      ID: List
    Type: [1x1 arrow.type.StringType]

% Create a nested List<List<Boolean>> type.
>> nestedListType = arrow.list(arrow.list(arrow.boolean()))

nestedListType = 

  ListType with properties:

      ID: List
    Type: [1x1 arrow.type.ListType]

% Extract the first-level, inner type, which is List<Boolean>.
>> innerType = nestedListType.Type

innerType = 

  ListType with properties:

      ID: List
    Type: [1x1 arrow.type.BooleanType]

% Extract the second-level, nested inner type, which is Boolean.
>> innerType.Type  

ans = 

  BooleanType with properties:

    ID: Boolean
```

### Are these changes tested?

Yes.

1. Added `tListType.m`.
2. Added `tListTraits.m`.
3. Updated `tField.m` to include `arrow.list`.
4. Updated `tID.m` to include `arrow.type.ID.List`.
6. Updated `tTypeDisplay.m` to include `arrow.type.ListType`.
7. Updated `ttraits.m` to include `arrow.type.traits.ListTraits`.

### Are there any user-facing changes?

Yes.

Client MATLAB code can now creates instances of `arrow.type.ListType` by using the `arrow.list(<type>)` construction function.

### Future Directions

1. apache#37815
* Closes: apache#37812

Authored-by: Kevin Gurney <[email protected]>
Signed-off-by: Kevin Gurney <[email protected]>
dgreiss pushed a commit to dgreiss/arrow that referenced this issue Feb 19, 2024
…ache#38357)

### Rationale for this change

Now that many of the commonly-used "primitive" array types have been added to the MATLAB interface, we can implement an `arrow.array.ListArray` class.

This pull request adds a new `arrow.array.ListArray` class which can be converted to a MATLAB `cell` array by calling the static `toMATLAB` method.

### What changes are included in this PR?

1. Added a new `arrow.array.ListArray` MATLAB class.

*Methods*

`cellArray = arrow.array.ListArray.toMATLAB()`
`listArray = arrow.array.ListArray.fromArrays(offsets, values)`

*Properties*

`Offsets` - `Int32Array` list offsets (uses zero-based indexing)
`Values` - Array of values in the list (supports nesting)

2. Added a new `arrow.type.traits.ListTraits` MATLAB class.

**Example**
```matlab
>> offsets = arrow.array(int32([0, 2, 3, 7]))

offsets = 

[
  0,
  2,
  3,
  7
]

>> values = arrow.array(["A", "B", "C", "D", "E", "F", "G"])

values = 

[
  "A",
  "B",
  "C",
  "D",
  "E",
  "F",
  "G"
]

>> arrowArray = arrow.array.ListArray.fromArrays(offsets, values)

arrowArray = 

[
  [
    "A",
    "B"
  ],
  [
    "C"
  ],
  [
    "D",
    "E",
    "F",
    "G"
  ]
]

>> matlabArray = arrowArray.toMATLAB()

matlabArray =

  3x1 cell array

    {2x1 string}
    {["C"     ]}
    {4x1 string}

>> matlabArray{:}

ans = 

  2x1 string array

    "A"
    "B"

ans = 

    "C"

ans = 

  4x1 string array

    "D"
    "E"
    "F"
    "G"

```

### Are these changes tested?

Yes.

1. Added a new `tListArray.m` test class.
2. Added a new `tListTraits.m` test class.
3. Updated `arrow.internal.test.tabular.createAllSupportedArrayTypes` to include `ListArray`.

### Are there any user-facing changes?

Yes.

1. Users can now create an `arrow.array.ListArray` from an `offsets` and `values` array by calling the static `arrow.array.ListArray.fromArrays(offsets, values)` method. `ListArray`s can be converted into MATLAB `cell` arrays by calling the static `arrow.array.ListArray.toMATLAB` method.

### Notes

1. We chose to use the "missing-class" `missing` value as the `NullSubstitutionValue` for the time being for `ListArray`. However, we eventually want to add `arrow.array.NullArray`, and will most likely want to use the "missing-class" `missing` value to represent `NullArray` values in MATLAB. So, this could cause some ambiguity in the future. We have been thinking about whether we should consider introducing some sort of special "sentinel value" to represent null values when converting to MATLAB `cell` arrays. Perhaps, something like `arrow.Null`, or something to that effect, in order to avoid this ambiguity. If we think it makes sense to do that, we may want to retroactively change the `NullSubstitutionValue` to be `arrow.Null` and break compatibility. Since we are still in pre-`0.1`, we don't think the impact of such a behavior change would be very large.
2. Implementing `ListArray` is fairly involved. So, in the spirit of incremental delivery, we chose not to include an implementation of `arrow.array.ListArray.fromMATLAB` in this initial pull request. We plan on following up with some more changes to `arrow.array.ListArray`. See apache#38353, apache#38354, and apache#38361.
3. Thank you @ sgilmore10 for your help with this pull request!

### Future Directions

1. apache#38353
2. apache#38354
3. apache#38361
4. Consider adding a null sentinel value like `arrow.Null` for conversion to MATLAB `cell` arrays.
* Closes: apache#37815 

Lead-authored-by: Kevin Gurney <[email protected]>
Co-authored-by: Sarah Gilmore <[email protected]>
Signed-off-by: Kevin Gurney <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Archived in project
Development

Successfully merging a pull request may close this issue.

1 participant