kevingurney commented on code in PR #45973:
URL: https://github.com/apache/arrow/pull/45973#discussion_r2023129894
##########
matlab/doc/matlab_interface_for_apache_arrow_design.md:
##########
@@ -109,19 +109,7 @@ ans =
To serialize MATLAB data to a file on disk (e.g. Feather, Parquet), a MATLAB
developer could start by constructing an `arrow.Table` using one of several
different approaches.
-They could individually compose the table from a set of `arrow.Array` objects
(one for each table variable).
-
-###### Example Code:
-``` matlab
->> Var1 = arrow.array(["foo"; "bar"; "baz"]);
-
->> Var2 = arrow.array([today; today + 1; today + 2]);
-
->> Var3 = arrow.array([10; 20; 30]);
-
->> AT = arrow.Table(Var1, Var2, Var3);
-```
-Alternatively, they could directly convert from an existing MATLAB `table` to
an `arrow.Table` using a function like `arrow.matlab2arrow` to convert between
an existing MATLAB `table` and an `arrow.Table`.
+They could directly convert from an existing MATLAB `table` to an
`arrow.Table` using a function like `arrow.table`.
Review Comment:
The title of Use Case 2 is "Developer Workflow for Writing a MATLAB Table to
a Feather File". However, the changes you've made are using the Arrow IPC file
I/O APIs, rather than Feather V1 APIs. If we want to change this to talk about
the Arrow IPC format, then we should probably replace all mentions of Feather
with "Arrow IPC file format", or something similar.
##########
matlab/doc/matlab_interface_for_apache_arrow_design.md:
##########
@@ -133,23 +121,36 @@ Alternatively, they could directly convert from an
existing MATLAB `table` to an
>> T = table(Weight, Radius, Density); % Create a MATLAB table
->> AT = arrow.matlab2arrow(T); % Create an arrow.Table
+>> AT = arrow.table(T); % Create an arrow.Table
```
-To serialize the `arrow.Table`, `AT`, to a file (e.g. Feather) on disk, the
user could then instantiate an `arrow.FeatherTableWriter`.
+
+To serialize the `arrow.Table`, `AT`, to a file (e.g. Feather) on disk, the
user could then instantiate an `arrow.io.ipc.RecordBatchFileWriter`.
###### Example Code:
``` matlab
->> featherTableWriter = arrow.FeatherTableWriter();
+% create a RecordBatch out of the table from the previous example
+>> recordBatch = arrow.recordBatch(AT);
+>> filename = fullfile(pwd, "data.arrow");
->> featherTableWriter.write(AT, "data.feather");
+% write the RecordBatch schema and the RecordBatch itself
+>> writer = arrow.io.ipc.RecordBatchFileWriter(filename, recordBatch.Schema);
Review Comment:
```suggestion
>> writer = arrow.io.ipc.RecordBatchFileWriter(filename, recordBatch.Schema);
```
##########
matlab/doc/matlab_interface_for_apache_arrow_design.md:
##########
@@ -179,22 +180,28 @@ Roughly speaking, local memory sharing workflows can be
divided into two categor
To share a MATLAB `arrow.Array` with PyArrow efficiently, a user could use the
`exportToCDataInterface` method to export the Arrow memory wrapped by an
`arrow.Array` to the C Data Interface format, consisting of two C-style
structs, [`ArrowArray`] and [`ArrowSchema`], which represent the Arrow data and
associated metadata.
-Memory addresses to the `ArrowArray` and `ArrowSchema` structs are returned by
the call to `exportToCDataInterface`. These addresses can be passed to Python
directly, without having to make any copies of the underlying Arrow data
structures that they refer to. A user can then wrap the underlying data pointed
to by the `ArrowArray` struct (which is already in the [Arrow Columnar
Format]), as well as extract the necessary metadata from the `ArrowSchema`
struct, to create a `pyarrow.Array` by using the static method
`py.pyarrow.Array._import_from_c`.
+Memory addresses to the `ArrowArray` and `ArrowSchema` structs are returned by
the call to `export`. These addresses can be passed to Python directly, without
having to make any copies of the underlying Arrow data structures that they
refer to. A user can then wrap the underlying data pointed to by the
`ArrowArray` struct (which is already in the [Arrow Columnar Format]), as well
as extract the necessary metadata from the `ArrowSchema` struct, to create a
`pyarrow.Array` by using the static method `pyarrow.Array._import_from_c`.
###### Example Code:
``` matlab
% Create a MATLAB arrow.Array.
>> AA = arrow.array([1, 2, 3, 4, 5]);
+% create C Data Interface for array values and schema
+>> cArray = arrow.c.Array();
+>> cSchema = arrow.c.Schema();
+
% Export the MATLAB arrow.Array to the C Data Interface format, returning the
% memory addresses of the required ArrowArray and ArrowSchema C-style structs.
->> [arrayMemoryAddress, schemaMemoryAddress] = AA.exportToCDataInterface();
+>> AA.export(cArray.Address, cSchema.Address);
% Import the memory addresses of the C Data Interface format structs to create
a pyarrow.Array.
->> PA = py.pyarrow.Array._import_from_c(arrayMemoryAddress,
schemaMemoryAddress);
+>> PA = pyrun("import pyarrow as pa; array =
pa.Array._import_from_c(arrayMemoryAddress, schemaMemoryAddress)", "array",
arrayMemoryAddress=cArray.Address, schemaMemoryAddress=cSchema.Address);
```
Conversely, a user can create an Arrow array using PyArrow and share it with
MATLAB. To do this, they can call the method `_export_to_c` to export a
`pyarrow.Array` to the C Data Interface format.
+Since the python calls to `_export_to_c` and `_import_from_c` have underscores
at the beginning, they cannot be called in MATLAB. MATLAB member functions or
variables are not allowed to start with an underscore shown [in the "variable
names" syntax page on the Mathworks
website](https://www.mathworks.com/help/matlab/matlab_prog/variable-names.html).
Instead, to initialize your Python pyarrow array, you must use MATLAB's
built-in `pyrun` to execute code in Python, which allows for variables and
functions to start with underscore.
Review Comment:
```suggestion
**NOTE:** Since the python calls to `_export_to_c` and `_import_from_c` have
underscores at the beginning of their names, they cannot be called directly in
MATLAB. MATLAB member functions or variables are [not allowed to start with an
underscore](https://www.mathworks.com/help/matlab/matlab_prog/variable-names.html).
To initialize a Python `pyarrow` array, the MATLAB `pyrunfile` command can
be used, which supports the execution of Python code containing variables and
functions with names that start with an underscore.
```
##########
matlab/doc/matlab_interface_for_apache_arrow_design.md:
##########
@@ -133,23 +121,36 @@ Alternatively, they could directly convert from an
existing MATLAB `table` to an
>> T = table(Weight, Radius, Density); % Create a MATLAB table
->> AT = arrow.matlab2arrow(T); % Create an arrow.Table
+>> AT = arrow.table(T); % Create an arrow.Table
```
-To serialize the `arrow.Table`, `AT`, to a file (e.g. Feather) on disk, the
user could then instantiate an `arrow.FeatherTableWriter`.
+
+To serialize the `arrow.Table`, `AT`, to a file (e.g. Feather) on disk, the
user could then instantiate an `arrow.io.ipc.RecordBatchFileWriter`.
###### Example Code:
``` matlab
->> featherTableWriter = arrow.FeatherTableWriter();
+% create a RecordBatch out of the table from the previous example
+>> recordBatch = arrow.recordBatch(AT);
+>> filename = fullfile(pwd, "data.arrow");
->> featherTableWriter.write(AT, "data.feather");
+% write the RecordBatch schema and the RecordBatch itself
+>> writer = arrow.io.ipc.RecordBatchFileWriter(filename, recordBatch.Schema);
+>> writer.writeRecordBatch(recordBatch);
+
+% close the writer to enable reading
+>> writer.close();
```
-The Feather file could then be read and operated on by an external process
like Rust or Go. To read it back into MATLAB after modification by another
process, the user could instantiate an `arrow.FeatherTableReader`.
+The Feather file could then be read and operated on by an external process
like Rust or Go. To read it back into MATLAB after modification by another
process, the user could instantiate an `arrow.io.ipc.RecordBatchFileReader`.
Review Comment:
```suggestion
The Arrow IPC file could then be read and operated on by an external process
like Rust or Go. To read it back into MATLAB, the user could instantiate an
`arrow.io.ipc.RecordBatchFileReader`.
```
##########
matlab/doc/matlab_interface_for_apache_arrow_design.md:
##########
@@ -109,19 +109,7 @@ ans =
To serialize MATLAB data to a file on disk (e.g. Feather, Parquet), a MATLAB
developer could start by constructing an `arrow.Table` using one of several
different approaches.
-They could individually compose the table from a set of `arrow.Array` objects
(one for each table variable).
-
-###### Example Code:
-``` matlab
->> Var1 = arrow.array(["foo"; "bar"; "baz"]);
-
->> Var2 = arrow.array([today; today + 1; today + 2]);
-
->> Var3 = arrow.array([10; 20; 30]);
-
->> AT = arrow.Table(Var1, Var2, Var3);
-```
-Alternatively, they could directly convert from an existing MATLAB `table` to
an `arrow.Table` using a function like `arrow.matlab2arrow` to convert between
an existing MATLAB `table` and an `arrow.Table`.
+They could directly convert from an existing MATLAB `table` to an
`arrow.Table` using a function like `arrow.table`.
Review Comment:
```suggestion
They could directly convert from an existing MATLAB `table` to an
`arrow.tabular.Table` using a function like `arrow.table`.
```
##########
matlab/doc/matlab_interface_for_apache_arrow_design.md:
##########
@@ -133,23 +121,36 @@ Alternatively, they could directly convert from an
existing MATLAB `table` to an
>> T = table(Weight, Radius, Density); % Create a MATLAB table
->> AT = arrow.matlab2arrow(T); % Create an arrow.Table
+>> AT = arrow.table(T); % Create an arrow.Table
```
-To serialize the `arrow.Table`, `AT`, to a file (e.g. Feather) on disk, the
user could then instantiate an `arrow.FeatherTableWriter`.
+
+To serialize the `arrow.Table`, `AT`, to a file (e.g. Feather) on disk, the
user could then instantiate an `arrow.io.ipc.RecordBatchFileWriter`.
###### Example Code:
``` matlab
->> featherTableWriter = arrow.FeatherTableWriter();
+% create a RecordBatch out of the table from the previous example
+>> recordBatch = arrow.recordBatch(AT);
+>> filename = fullfile(pwd, "data.arrow");
->> featherTableWriter.write(AT, "data.feather");
+% write the RecordBatch schema and the RecordBatch itself
+>> writer = arrow.io.ipc.RecordBatchFileWriter(filename, recordBatch.Schema);
+>> writer.writeRecordBatch(recordBatch);
+
+% close the writer to enable reading
+>> writer.close();
```
-The Feather file could then be read and operated on by an external process
like Rust or Go. To read it back into MATLAB after modification by another
process, the user could instantiate an `arrow.FeatherTableReader`.
+The Feather file could then be read and operated on by an external process
like Rust or Go. To read it back into MATLAB after modification by another
process, the user could instantiate an `arrow.io.ipc.RecordBatchFileReader`.
###### Example Code:
``` matlab
->> featherTableReader = arrow.FeatherTableReader("data.feather");
+% open record batch file reader
+>> reader = arrow.io.ipc.RecordBatchFileReader(filename);
+
+% read in the first RecordBatch
+>> newBatch = reader.read(1);
->> AT = featherTableReader.read();
+% create a table that matches AT before it was written to data.arrow from the
RecordBatch
+>> AT = table(newBatch);
```
#### Advanced MATLAB User Workflow for Implementing Support for Writing to
Feather Files
Review Comment:
Since there is potentially a lot of content to update here for this to be
cohesive, maybe we can do this in a separate, follow up pull request, but we
should probably rewrite this section a bit to be more accurate.
##########
matlab/doc/matlab_interface_for_apache_arrow_design.md:
##########
@@ -179,22 +180,28 @@ Roughly speaking, local memory sharing workflows can be
divided into two categor
To share a MATLAB `arrow.Array` with PyArrow efficiently, a user could use the
`exportToCDataInterface` method to export the Arrow memory wrapped by an
`arrow.Array` to the C Data Interface format, consisting of two C-style
structs, [`ArrowArray`] and [`ArrowSchema`], which represent the Arrow data and
associated metadata.
-Memory addresses to the `ArrowArray` and `ArrowSchema` structs are returned by
the call to `exportToCDataInterface`. These addresses can be passed to Python
directly, without having to make any copies of the underlying Arrow data
structures that they refer to. A user can then wrap the underlying data pointed
to by the `ArrowArray` struct (which is already in the [Arrow Columnar
Format]), as well as extract the necessary metadata from the `ArrowSchema`
struct, to create a `pyarrow.Array` by using the static method
`py.pyarrow.Array._import_from_c`.
+Memory addresses to the `ArrowArray` and `ArrowSchema` structs are returned by
the call to `export`. These addresses can be passed to Python directly, without
having to make any copies of the underlying Arrow data structures that they
refer to. A user can then wrap the underlying data pointed to by the
`ArrowArray` struct (which is already in the [Arrow Columnar Format]), as well
as extract the necessary metadata from the `ArrowSchema` struct, to create a
`pyarrow.Array` by using the static method `pyarrow.Array._import_from_c`.
###### Example Code:
``` matlab
% Create a MATLAB arrow.Array.
>> AA = arrow.array([1, 2, 3, 4, 5]);
+% create C Data Interface for array values and schema
Review Comment:
```suggestion
% Export C Data Interface C-style structs for `arrow.array.Array` values and
schema
```
##########
matlab/doc/matlab_interface_for_apache_arrow_design.md:
##########
@@ -133,23 +121,36 @@ Alternatively, they could directly convert from an
existing MATLAB `table` to an
>> T = table(Weight, Radius, Density); % Create a MATLAB table
->> AT = arrow.matlab2arrow(T); % Create an arrow.Table
+>> AT = arrow.table(T); % Create an arrow.Table
Review Comment:
```suggestion
% Create an `arrow.tabular.Table` from the MATLAB `table`
>> AT = arrow.table(T);
```
##########
matlab/doc/matlab_interface_for_apache_arrow_design.md:
##########
@@ -133,23 +121,36 @@ Alternatively, they could directly convert from an
existing MATLAB `table` to an
>> T = table(Weight, Radius, Density); % Create a MATLAB table
Review Comment:
```suggestion
% Create a MATLAB `table`
>> T = table(Weight, Radius, Density);
```
##########
matlab/doc/matlab_interface_for_apache_arrow_design.md:
##########
@@ -133,23 +121,36 @@ Alternatively, they could directly convert from an
existing MATLAB `table` to an
>> T = table(Weight, Radius, Density); % Create a MATLAB table
->> AT = arrow.matlab2arrow(T); % Create an arrow.Table
+>> AT = arrow.table(T); % Create an arrow.Table
```
-To serialize the `arrow.Table`, `AT`, to a file (e.g. Feather) on disk, the
user could then instantiate an `arrow.FeatherTableWriter`.
+
+To serialize the `arrow.Table`, `AT`, to a file (e.g. Feather) on disk, the
user could then instantiate an `arrow.io.ipc.RecordBatchFileWriter`.
###### Example Code:
``` matlab
->> featherTableWriter = arrow.FeatherTableWriter();
+% create a RecordBatch out of the table from the previous example
+>> recordBatch = arrow.recordBatch(AT);
+>> filename = fullfile(pwd, "data.arrow");
->> featherTableWriter.write(AT, "data.feather");
+% write the RecordBatch schema and the RecordBatch itself
+>> writer = arrow.io.ipc.RecordBatchFileWriter(filename, recordBatch.Schema);
+>> writer.writeRecordBatch(recordBatch);
+
+% close the writer to enable reading
+>> writer.close();
```
-The Feather file could then be read and operated on by an external process
like Rust or Go. To read it back into MATLAB after modification by another
process, the user could instantiate an `arrow.FeatherTableReader`.
+The Feather file could then be read and operated on by an external process
like Rust or Go. To read it back into MATLAB after modification by another
process, the user could instantiate an `arrow.io.ipc.RecordBatchFileReader`.
###### Example Code:
``` matlab
->> featherTableReader = arrow.FeatherTableReader("data.feather");
+% open record batch file reader
Review Comment:
```suggestion
```
##########
matlab/doc/matlab_interface_for_apache_arrow_design.md:
##########
@@ -179,22 +180,28 @@ Roughly speaking, local memory sharing workflows can be
divided into two categor
To share a MATLAB `arrow.Array` with PyArrow efficiently, a user could use the
`exportToCDataInterface` method to export the Arrow memory wrapped by an
`arrow.Array` to the C Data Interface format, consisting of two C-style
structs, [`ArrowArray`] and [`ArrowSchema`], which represent the Arrow data and
associated metadata.
-Memory addresses to the `ArrowArray` and `ArrowSchema` structs are returned by
the call to `exportToCDataInterface`. These addresses can be passed to Python
directly, without having to make any copies of the underlying Arrow data
structures that they refer to. A user can then wrap the underlying data pointed
to by the `ArrowArray` struct (which is already in the [Arrow Columnar
Format]), as well as extract the necessary metadata from the `ArrowSchema`
struct, to create a `pyarrow.Array` by using the static method
`py.pyarrow.Array._import_from_c`.
+Memory addresses to the `ArrowArray` and `ArrowSchema` structs are returned by
the call to `export`. These addresses can be passed to Python directly, without
having to make any copies of the underlying Arrow data structures that they
refer to. A user can then wrap the underlying data pointed to by the
`ArrowArray` struct (which is already in the [Arrow Columnar Format]), as well
as extract the necessary metadata from the `ArrowSchema` struct, to create a
`pyarrow.Array` by using the static method `pyarrow.Array._import_from_c`.
###### Example Code:
``` matlab
% Create a MATLAB arrow.Array.
>> AA = arrow.array([1, 2, 3, 4, 5]);
+% create C Data Interface for array values and schema
+>> cArray = arrow.c.Array();
+>> cSchema = arrow.c.Schema();
+
% Export the MATLAB arrow.Array to the C Data Interface format, returning the
% memory addresses of the required ArrowArray and ArrowSchema C-style structs.
->> [arrayMemoryAddress, schemaMemoryAddress] = AA.exportToCDataInterface();
+>> AA.export(cArray.Address, cSchema.Address);
% Import the memory addresses of the C Data Interface format structs to create
a pyarrow.Array.
->> PA = py.pyarrow.Array._import_from_c(arrayMemoryAddress,
schemaMemoryAddress);
+>> PA = pyrun("import pyarrow as pa; array =
pa.Array._import_from_c(arrayMemoryAddress, schemaMemoryAddress)", "array",
arrayMemoryAddress=cArray.Address, schemaMemoryAddress=cSchema.Address);
Review Comment:
This is a bit hard to parse since it's all on one line. Maybe we could break
this out into a separate code block and use `pyrunfile` instead of `pyrun` here?
##########
matlab/doc/matlab_interface_for_apache_arrow_design.md:
##########
@@ -133,23 +121,36 @@ Alternatively, they could directly convert from an
existing MATLAB `table` to an
>> T = table(Weight, Radius, Density); % Create a MATLAB table
->> AT = arrow.matlab2arrow(T); % Create an arrow.Table
+>> AT = arrow.table(T); % Create an arrow.Table
```
-To serialize the `arrow.Table`, `AT`, to a file (e.g. Feather) on disk, the
user could then instantiate an `arrow.FeatherTableWriter`.
+
+To serialize the `arrow.Table`, `AT`, to a file (e.g. Feather) on disk, the
user could then instantiate an `arrow.io.ipc.RecordBatchFileWriter`.
###### Example Code:
``` matlab
->> featherTableWriter = arrow.FeatherTableWriter();
+% create a RecordBatch out of the table from the previous example
+>> recordBatch = arrow.recordBatch(AT);
+>> filename = fullfile(pwd, "data.arrow");
Review Comment:
For simplicitly, I think we can just a relative path `"data.arrow"` here,
unless there is some issue with the code supporting that (in which case, we
should create an issue for that).
```suggestion
>> filename = "data.arrow";
```
##########
matlab/doc/matlab_interface_for_apache_arrow_design.md:
##########
@@ -133,23 +121,36 @@ Alternatively, they could directly convert from an
existing MATLAB `table` to an
>> T = table(Weight, Radius, Density); % Create a MATLAB table
->> AT = arrow.matlab2arrow(T); % Create an arrow.Table
+>> AT = arrow.table(T); % Create an arrow.Table
```
-To serialize the `arrow.Table`, `AT`, to a file (e.g. Feather) on disk, the
user could then instantiate an `arrow.FeatherTableWriter`.
+
+To serialize the `arrow.Table`, `AT`, to a file (e.g. Feather) on disk, the
user could then instantiate an `arrow.io.ipc.RecordBatchFileWriter`.
###### Example Code:
``` matlab
->> featherTableWriter = arrow.FeatherTableWriter();
+% create a RecordBatch out of the table from the previous example
+>> recordBatch = arrow.recordBatch(AT);
+>> filename = fullfile(pwd, "data.arrow");
->> featherTableWriter.write(AT, "data.feather");
+% write the RecordBatch schema and the RecordBatch itself
+>> writer = arrow.io.ipc.RecordBatchFileWriter(filename, recordBatch.Schema);
+>> writer.writeRecordBatch(recordBatch);
+
+% close the writer to enable reading
+>> writer.close();
```
-The Feather file could then be read and operated on by an external process
like Rust or Go. To read it back into MATLAB after modification by another
process, the user could instantiate an `arrow.FeatherTableReader`.
+The Feather file could then be read and operated on by an external process
like Rust or Go. To read it back into MATLAB after modification by another
process, the user could instantiate an `arrow.io.ipc.RecordBatchFileReader`.
###### Example Code:
``` matlab
->> featherTableReader = arrow.FeatherTableReader("data.feather");
+% open record batch file reader
+>> reader = arrow.io.ipc.RecordBatchFileReader(filename);
+
+% read in the first RecordBatch
+>> newBatch = reader.read(1);
->> AT = featherTableReader.read();
+% create a table that matches AT before it was written to data.arrow from the
RecordBatch
Review Comment:
```suggestion
% Create a MATLAB `table` from the `arrow.tabular.RecordBatch`
```
##########
matlab/doc/matlab_interface_for_apache_arrow_design.md:
##########
@@ -133,23 +121,36 @@ Alternatively, they could directly convert from an
existing MATLAB `table` to an
>> T = table(Weight, Radius, Density); % Create a MATLAB table
->> AT = arrow.matlab2arrow(T); % Create an arrow.Table
+>> AT = arrow.table(T); % Create an arrow.Table
```
-To serialize the `arrow.Table`, `AT`, to a file (e.g. Feather) on disk, the
user could then instantiate an `arrow.FeatherTableWriter`.
+
+To serialize the `arrow.Table`, `AT`, to a file (e.g. Feather) on disk, the
user could then instantiate an `arrow.io.ipc.RecordBatchFileWriter`.
###### Example Code:
``` matlab
->> featherTableWriter = arrow.FeatherTableWriter();
+% create a RecordBatch out of the table from the previous example
+>> recordBatch = arrow.recordBatch(AT);
+>> filename = fullfile(pwd, "data.arrow");
->> featherTableWriter.write(AT, "data.feather");
+% write the RecordBatch schema and the RecordBatch itself
+>> writer = arrow.io.ipc.RecordBatchFileWriter(filename, recordBatch.Schema);
+>> writer.writeRecordBatch(recordBatch);
+
+% close the writer to enable reading
+>> writer.close();
```
-The Feather file could then be read and operated on by an external process
like Rust or Go. To read it back into MATLAB after modification by another
process, the user could instantiate an `arrow.FeatherTableReader`.
+The Feather file could then be read and operated on by an external process
like Rust or Go. To read it back into MATLAB after modification by another
process, the user could instantiate an `arrow.io.ipc.RecordBatchFileReader`.
###### Example Code:
``` matlab
->> featherTableReader = arrow.FeatherTableReader("data.feather");
+% open record batch file reader
+>> reader = arrow.io.ipc.RecordBatchFileReader(filename);
+
+% read in the first RecordBatch
Review Comment:
```suggestion
% Read in the first RecordBatch
```
##########
matlab/doc/matlab_interface_for_apache_arrow_design.md:
##########
@@ -133,23 +121,36 @@ Alternatively, they could directly convert from an
existing MATLAB `table` to an
>> T = table(Weight, Radius, Density); % Create a MATLAB table
->> AT = arrow.matlab2arrow(T); % Create an arrow.Table
+>> AT = arrow.table(T); % Create an arrow.Table
```
-To serialize the `arrow.Table`, `AT`, to a file (e.g. Feather) on disk, the
user could then instantiate an `arrow.FeatherTableWriter`.
+
+To serialize the `arrow.Table`, `AT`, to a file (e.g. Feather) on disk, the
user could then instantiate an `arrow.io.ipc.RecordBatchFileWriter`.
###### Example Code:
``` matlab
->> featherTableWriter = arrow.FeatherTableWriter();
+% create a RecordBatch out of the table from the previous example
Review Comment:
```suggestion
% Make an `arrow.tabular.RecordBatch` from the `arrow.tabular.Table` created
in the previous step
```
##########
matlab/doc/matlab_interface_for_apache_arrow_design.md:
##########
@@ -133,23 +121,36 @@ Alternatively, they could directly convert from an
existing MATLAB `table` to an
>> T = table(Weight, Radius, Density); % Create a MATLAB table
->> AT = arrow.matlab2arrow(T); % Create an arrow.Table
+>> AT = arrow.table(T); % Create an arrow.Table
```
-To serialize the `arrow.Table`, `AT`, to a file (e.g. Feather) on disk, the
user could then instantiate an `arrow.FeatherTableWriter`.
+
+To serialize the `arrow.Table`, `AT`, to a file (e.g. Feather) on disk, the
user could then instantiate an `arrow.io.ipc.RecordBatchFileWriter`.
###### Example Code:
``` matlab
->> featherTableWriter = arrow.FeatherTableWriter();
+% create a RecordBatch out of the table from the previous example
+>> recordBatch = arrow.recordBatch(AT);
+>> filename = fullfile(pwd, "data.arrow");
->> featherTableWriter.write(AT, "data.feather");
+% write the RecordBatch schema and the RecordBatch itself
+>> writer = arrow.io.ipc.RecordBatchFileWriter(filename, recordBatch.Schema);
+>> writer.writeRecordBatch(recordBatch);
+
+% close the writer to enable reading
Review Comment:
```suggestion
% Close the writer to finalize writing
```
##########
matlab/doc/matlab_interface_for_apache_arrow_design.md:
##########
@@ -205,21 +212,18 @@ The example code below is adapted from the
[`test_cffi.py` test cases for PyArro
>> PA = py.pyarrow.array([1, 2, 3, 4, 5]);
% Create ArrowArray and ArrowSchema C-style structs adhering to the Arrow C
Data Interface format.
->> array = py.pyarrow.cffi.ffi.new("struct ArrowArray*")
-
->> arrayMemoryAddress = py.int(py.pyarrow.cffi.ffi.cast("uintptr_t", array));
-
->> schema = py.pyarrow.cffi.ffi.new("struct ArrowSchema*")
-
->> schemaMemoryAddress = py.int(py.pyarrow.cffi.ffi.cast("uintptr_t",
schema));
+>> cArray = arrow.c.Array();
+>> cSchema = arrow.c.Schema();
% Export the pyarrow.Array to the C Data Interface format, populating the
required ArrowArray and ArrowShema structs.
->> PA.export_to_c(arrayMemoryAddress, schemaMemoryAddress)
+>> pyrun("import pyarrow as pa; PA._export_to_c(arrayMemoryAddress,
schemaMemoryAddress)", PA=PA, arrayMemoryAddress=cArray.Address,
schemaMemoryAddress=cSchema.Address);
Review Comment:
Same comment as above, perhaps, we could use `pyrunfile` here instead?
##########
matlab/doc/matlab_interface_for_apache_arrow_design.md:
##########
@@ -205,21 +212,18 @@ The example code below is adapted from the
[`test_cffi.py` test cases for PyArro
>> PA = py.pyarrow.array([1, 2, 3, 4, 5]);
% Create ArrowArray and ArrowSchema C-style structs adhering to the Arrow C
Data Interface format.
->> array = py.pyarrow.cffi.ffi.new("struct ArrowArray*")
-
->> arrayMemoryAddress = py.int(py.pyarrow.cffi.ffi.cast("uintptr_t", array));
-
->> schema = py.pyarrow.cffi.ffi.new("struct ArrowSchema*")
-
->> schemaMemoryAddress = py.int(py.pyarrow.cffi.ffi.cast("uintptr_t",
schema));
+>> cArray = arrow.c.Array();
+>> cSchema = arrow.c.Schema();
% Export the pyarrow.Array to the C Data Interface format, populating the
required ArrowArray and ArrowShema structs.
->> PA.export_to_c(arrayMemoryAddress, schemaMemoryAddress)
+>> pyrun("import pyarrow as pa; PA._export_to_c(arrayMemoryAddress,
schemaMemoryAddress)", PA=PA, arrayMemoryAddress=cArray.Address,
schemaMemoryAddress=cSchema.Address);
% Import the C Data Interface structs to create a MATLAB arrow.Array.
->> AA = arrow.Array.importFromCDataInterface(arrayMemoryAddress,
schemaMemoryAddress);
+>> AA = arrow.array.Array.import(cArray, cSchema);
```
+For the same reasons as mentioned above in the export from MATLAB to Python
example, we must also run the export command inside of the `pyrun` function.
Review Comment:
I think we can omit this comment since it has already been explained above.
```suggestion
```
--
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]
