coder.read

Read data files at run time in generated code

Since R2023a

Syntax

dataFromFile = coder.read(filename)

dataFromFile = coder.read(filename,TypeHeaderFrom=typeHeaderFilename)

[dataFromFile,errID] = coder.read(___)

Description

In your MATLAB^® code for which you intend to generate C/C++ code, use the coder.read function to read data from .coderdata files. The generated code performs the data read at run time.

To store your data in a .coderdata file, use the coder.write function in MATLAB execution.

Each .coderdata file contains a type header that specifies the type and size of the data stored in the file. The coder.read function uses this information when interpreting the contents of the file.

dataFromFile = coder.read(filename) reads from the filename.coderdata storage file and returns the data stored within the file. This syntax works for a constant filename input only. The file that this name represents must exist in your current folder during code generation

You can use the coder.write function to change the data contained in filename.coderdata before you run the generated code. However, the type and size of data contained in filename.coderdata must be the same at compile time and run time.

dataFromFile = coder.read(filename,TypeHeaderFrom=typeHeaderFilename) uses the type and size information contained in typeHeaderFilename to interpret the data in filename. The typeHeaderFilename argument must be a compile-time constant and the file that this name represents must exist in your current folder during code generation. The code generator obtains the type and size information from typeHeaderFilename at compile time.

The code generated for the coder.read function can read any .coderdata file at run time, as long as the type and size of the contained data is consistent with the compile-time type and size information that you supply using the typeHeaderFilename file.

[dataFromFile,errID] = coder.read(___) suppresses run-time errors during a read operation. If any errors occur, coder.read returns the first error as errID. The dataFromFile argument returns the unusable file content. Use this syntax to test the generated code for targets for which run-time errors are disabled.

Examples

Read Data of Fixed Type and Size

Use coder.write to create a .coderdata file that stores a single array from your MATLAB workspace. Then generate code for a coder.read function call that reads this file at run time.

Create a 100-by-100 array of type double in your workspace.

data = rand(100);

Store this variable in a file named exampleData.coderdata in the current folder.

coder.write('myfile.coderdata',data);

Wrote file 'myfile.coderdata'. You can read this file with 'coder.read'.

To read from a .coderdata file with the constant file name exampleData, use the coder.read function syntax that has a single input argument.

function y = my_entry_point(x) %#codegen
dataOut = coder.read('myfile.coderdata');
y = x + mean(dataOut,"all");
end

Generate a MEX function my_entry_point_mex and then call the generated MEX by running these commands:

codegen my_entry_point -args {0}
my_entry_point_mex(1)

Code generation successful.

ans =

    1.4996

You can now update the data stored in myfile.coderdata to a different 100-by-100 array of type double. If you then call my_entry_point_mex that you already generated, the MEX now reads and uses the new data.

d = rand(100) - 1;
coder.write('myfile.coderdata',d);
my_entry_point_mex(1)

Wrote file 'myfile.coderdata'. You can read this file with 'coder.read'.

ans =

    0.4963

Read Data Whose Size Can Change at Run Time

Generate code for a coder.read command that can read multiple .coderdata files at run time. These files contain array data that have the same type, but different sizes. To enable a single coder.read call to read all these files, pass a type header file that is consistent with all your individual data files to the coder.read function call.

To start, create the storage files that you want the generated code to read. At the command line, create variables var_a and var_b that are both of type double but have different sizes. Use the coder.write function to store array var_a and array var_b in the files file_a.coderdata and file_b.coderdata, respectively.

var_a = rand(10,20);
var_b = rand(5,30);
coder.write("file_a.coderdata",var_a)
coder.write("file_b.coderdata",var_b)

Wrote file 'file_a.coderdata'. You can read this file with 'coder.read'.
Wrote file 'file_b.coderdata'. You can read this file with 'coder.read'.

A coder.Type object that is consistent with both variables var_a and var_b must have variable-size dimensions. The upper bounds of the two array dimensions must be at least 10 and 30, respectively. Create a coder.Type object that represents a variable-size type double with these bounds.

t = coder.typeof(var_a,[10 30],[1 1])

t = 

coder.PrimitiveType
   :10×:30 double

Modify the header information of file_a.coderdata to be compatible with both arrays var_a and var_b. You can use the modified file as your desired common type header file.

coder.write("file_a.coderdata",a,TypeHeader=t);

Wrote file 'file_a.coderdata'. You can read this file with 'coder.read'.

Create a MATLAB entry-point function readMultipleFiles that can read file_a.coderdata and file_b.coderdata.

function data = readMultipleFiles(filename) %#codegen
data = coder.read(filename,TypeHeaderFrom="file_a.coderdata");
end

Generate a MEX function for readMultipleFiles. Specify the input argument type as an unbounded variable-size character vector so that it can represent file names of arbitrary length.

codegen readMultipleFiles -args {coder.typeof('a',[1 inf])} -report

Code generation successful: View report

Run the generated MEX function with inputs 'file_a.coderdata' and 'file_b.coderdata'.

readMultipleFiles_mex('file_a.coderdata');
readMultipleFiles_mex('file_b.coderdata');

Input Arguments

filename — Name of .coderdata storage file

string scalar (default) | character vector

Name of the .coderdata storage file from which you want to read data, specified as a string scalar or character vector.

To store your data in a .coderdata file, use the coder.write function in MATLAB.

typeHeaderFilename — Constant name of .coderdata file that stores type and size information

string scalar | character vector

Name of a .coderdata file that stores type and size information about the files to read at run time, specified as a string scalar or character vector. typeHeaderFilename must be a compile-time constant.

Each .coderdata file contains a type header that specifies the type and size of the data stored in the file. The code generated for the coder.read function can read any .coderdata file at run time, as long as the type and size of the contained data is consistent with the compile-time type and size information that you supply using the typeHeaderFilename file. This file is also referred to as the type header file.

To create a type header file, use the coder.write function in MATLAB.

Output Arguments

dataFromFile — Data read from .coderdata storage file

array | structure | cell array | enumeration | categorical | sparse array

Data read from the .coderdata storage file, returned as an array or multiple arrays stored within a structure or cell array.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | string | struct | cell | categorical | sparse

errID — Read error enumeration object

coder.ReadStatus object

Read error enumeration object, specified as one of these values.

Enumeration Member	Enumeration Value	Error Reference
Success	0	Read operation success.
CoderReadCouldNotOpen	1	Unable to open the specified .coderdata file.
CoderReadProblemReading	2	Issue while reading the .coderdata file.
CoderReadUnexpectedValue	3	Unexpected value in the .coderdata file.
CoderReadWrongHeader	4	The .coderdata file does not contain expected metadata. The input file might be corrupted or is not a .coderdata file. Use coder.write to create .coderdata files.
CoderReadWrongVersion	5	The .coderdata file is not compatible with the current release of MATLAB Coder™. Create a new .coderdata file with the current version of the product to generate a compatible file.
CoderReadStructArray	6	Expected to read a scalar structure, but the .coderdata file contains a structure array. Provide a compatible TypeHeaderFrom argument to read this file. Alternatively, use the first syntax that accepts a constant filename input only.
MATFile	7	Reading MAT-files using coder.read is not supported. Convert your MAT-file to a .coderdata file by running these commands in the command window: s = load("MATFileName"); coder.write("filename.coderdata",s); Read the new .coderdata file by using coder.read.
WrongType	8	The type information of the .coderdata file is not compatible with the type information specified by the TypeHeaderFrom argument.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

Introduced in R2023a