GH-36212: [MATLAB] Update README.md to mention support for `arrow.a…

…rray.Array` classes (#36213)

### Rationale for this change

This pull request updates the `README.md` for the MATLAB interface to include a few more usage examples of working with the new `arrow.arrayArray` classes and to mention that the `-D MATLAB_ARROW_INTERFACE=ON` flag for building the MATLAB interface code. 

### What changes are included in this PR?

1. `README.md` updated to include usage examples for `arrow.array.Array` classes
2. `README.md` updated to mention `-D MATLAB_ARROW_INTERFACE=ON` flag 

### Are these changes tested?

"Yes". Manually verified that the changes look as expected visually.

### Are there any user-facing changes?

Yes. The `README.md` is now updated to include mention of the new `arrow.array.Array` classes.

### Future Directions

1. In the future, we plan to incrementally keep the `README.md` up to date (and potentially add more extensive documentation in other files) as we continue to build out the APIs for the MATLAB interface. We might consider restructuring the documentation more extensively as we move closer to a "v1" version of the MATLAB interface.

### Notes

1. Thanks @ sgilmore10 for your help with this pull request!
* Closes: #36212

Lead-authored-by: Kevin Gurney <[email protected]>
Co-authored-by: Kevin Gurney <[email protected]>
Co-authored-by: Sutou Kouhei <[email protected]>
Co-authored-by: Sarah Gilmore <[email protected]>
Signed-off-by: Sutou Kouhei <[email protected]>

matlab/README.md

@@ -21,9 +21,32 @@
 
 ## Status
 
+> **Warning** The MATLAB interface is under active development and should be considered experimental.
+
 This is a very early stage MATLAB interface to the Apache Arrow C++ libraries.
 
-The current code only supports reading/writing numeric types from/to Feather v1 files.
+Currently, the MATLAB interface supports:
+
+1. Creating a subset of Arrow `Array` types (e.g. numeric and boolean) from MATLAB data
+2. Reading and writing numeric types from/to Feather v1 files.
+
+Supported `arrow.array.Array` types are included in the table below.
+
+**NOTE**: All Arrow `Array` classes are part of the `arrow.array` package (e.g. `arrow.array.Float64Array`).
+
+| MATLAB Array Type | Arrow Array Type |
+| ----------------- | ---------------- |
+| `single`          | `Float32Array`   |
+| `double`          | `Float64Array`   |
+| `uint8`           | `UInt8Array`     |
+| `uint16`          | `UInt16Array`    |
+| `uint32`          | `UInt32Array`    |
+| `uint64`          | `UInt64Array`    |
+| `int8`            | `Int8Array`      |
+| `int16`           | `Int16Array`     |
+| `int32`           | `Int32Array`     |
+| `int64`           | `Int64Array`     |
+| `logical`         | `BooleanArray`   |
 
 ## Prerequisites
 
@@ -53,10 +76,12 @@ $ cd arrow/matlab
 To build the MATLAB interface, use [CMake](https://cmake.org/cmake/help/latest/):
 
 ```console
-$ cmake -S . -B build 
+$ cmake -S . -B build -D MATLAB_ARROW_INTERFACE=ON
 $ cmake --build build --config Release
 ```
 
+**NOTE:** To build the experimental MATLAB interface code, `-D MATLAB_ARROW_INTERFACE=ON` must be specified as shown above.
+
 ## Install
 
 To install the MATLAB interface to the default software installation location for the target machine (e.g. `/usr/local` on Linux or `C:\Program Files` on Windows), pass the `--target install` flag to CMake.
@@ -75,18 +100,18 @@ There are two kinds of tests for the MATLAB Interface: MATLAB and C++.
 
 ### MATLAB
 
-To run the MATLAB tests, start MATLAB in the `arrow/matlab` directory and call the [`runtests`](https://mathworks.com/help/matlab/ref/runtests.html) command on the `test` directory:
+To run the MATLAB tests, start MATLAB in the `arrow/matlab` directory and call the [`runtests`](https://mathworks.com/help/matlab/ref/runtests.html) command on the `test` directory with `IncludeSubFolders=true`:
 
 ``` matlab
->> runtests test;
+>> runtests("test", IncludeSubFolders=true);
 ```
 
 ### C++
 
 To enable the C++ tests, set the `MATLAB_BUILD_TESTS` flag to `ON` at build time: 
 
 ```console
-$ cmake -S . -B build -D MATLAB_BUILD_TESTS=ON
+$ cmake -S . -B build -D MATLAB_ARROW_INTERFACE=ON -D MATLAB_BUILD_TESTS=ON
 $ cmake --build build --config Release
 ```
 
@@ -100,15 +125,97 @@ $ ctest --test-dir build
 
 Included below are some example code snippets that illustrate how to use the MATLAB interface.
 
-### Write a MATLAB table to a Feather v1 file
+### Arrow `Array` classes (i.e. `arrow.array.<Array>`)
+
+#### Create an Arrow `Float64Array` from a MATLAB `double` array
+
+```matlab
+>> matlabArray = double([1, 2, 3])
+
+matlabArray =
+
+     1     2     3
+
+>> arrowArray = arrow.array.Float64Array(matlabArray)
+
+arrowArray = 
+
+[
+  1,
+  2,
+  3
+]
+```
+
+#### Create a MATLAB `logical` array from an Arrow `BooleanArray`
+
+```matlab
+>> arrowArray = arrow.array.BooleanArray([true, false, true])
+
+arrowArray = 
+
+[
+  true,
+  false,
+  true
+]
+
+>> matlabArray = toMATLAB(arrowArray)
+
+matlabArray =
+
+  3×1 logical array
+
+   1
+   0
+   1
+```
+
+#### Specify `Null` Values when constructing an `arrow.array.Int8Array`
+
+```matlab
+>> matlabArray = int8([122, -1, 456, -10, 789])
+
+matlabArray =
+
+  1×5 int8 row vector
+
+    122     -1    127    -10    127
+
+% Treat all negative array elements as Null
+>> validElements = matlabArray > 0
+
+validElements =
+
+  1×5 logical array
+
+   1   0   1   0   1
+
+% Specify which values are Null/Valid by supplying a logical validity "mask"
+>> arrowArray = arrow.array.Int8Array(matlabArray, Valid=validElements)
+
+arrowArray = 
+
+[
+  122,
+  null,
+  127,
+  null,
+  127
+]
+```
+
+### Feather V1
+
+#### Write a MATLAB table to a Feather v1 file
 
 ``` matlab
 >> t = array2table(rand(10, 10));
 >> filename = 'table.feather';
 >> featherwrite(filename,t);
 ```
 
-### Read a Feather v1 file into a MATLAB table
+#### Read a Feather v1 file into a MATLAB table
 
 ``` matlab
 >> filename = 'table.feather';