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

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. Use this function in your MATLAB^® code for which you want to generate C/C++ code. The generated code performs the data read at run time.

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

dataFromFile = coder.read(fileName,TypeHeaderFrom=typeHeaderFilename) uses the information contained in typeHeaderFilename to determine the type and size of the data to be read from fileName. Both fileName and typeHeaderFilename must be .coderdata files. The typeHeaderFilename argument must be a compile-time constant and the file that this name represents must exist in your current directory during code generation.

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, while the file type and size is consistent with the type and size information that you supply using the typeHeaderFilename file during code generation.

To create a .coderdatafile to use with the TypeHeaderFrom argument, use the coder.write function in MATLAB.

[dataFromFile,errID] = coder.read(___) suppresses run-time errors during a read operation. errID is a coder.ReadStatus enumeration object. If any errors occur, coder.read returns the first error through errID and dataFromFile returns unusable content. Use this option to test the generated code for targets for which run-time errors are disabled.

Examples

Read Data from a Fixed .coderdata File at Run Time

In this example, you use coder.write to create a .coderdata file that stores a single array from your MATLAB workspace. You then generate code for a coder.read function call that reads this file at run time.

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

c = rand(20);

Store this variable in a file named exampleData.coderdata in your current directory.

coder.write("exampleData.coderdata",c);

To read from a .coderdata file with the constant file name exampleData, use the coder.read function as shown in your MATLAB entry-point function.

function data = readSingleFile %#codegen
data = coder.read("exampleData.coderdata");
end

Generate a MEX function for readSingleFile.

codegen readSingleFile -report

Read the data stored in exampleData.coderdata at run time by running the generated MEX.

readSingleFile_mex

Read Data from Multiple .coderdata Files at Run Time

This example shows how to 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 a storage file that you want the generated code to read. The following coder.write command creates the storage file file_a.coderdata, which contains two variables with array data of type double. Variables a and b are of different sizes.

a = rand(10,20);
b = rand(5,30);
coder.write("file_a.coderdata",a);

A coder.Type object that is consistent with both variables a and 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 double type with these bounds.

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

t = 

coder.PrimitiveType
   :10×:30 double

You can modify the header information of file_a.coderdata and use the modified file as the source of the type header information.

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

You can also create the file_b.coderdata file with the required type header information by running this command.

coder.write("file_b.coderdata",b,TypeHeader=t);

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_b.coderdata");
end

Generate a MEX for readMultipleFiles. Specify the input argument type as an unbounded variable-size character vector.

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

Run the generated MEX 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 workspace variables 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

Constant file 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.

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 while the file type and size is consistent with the type and size information that you supply using the typeHeaderFilename file during code generation. 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 specified .coderdata file.
CoderReadProblemReading	2	Issue while reading .coderdata file.
CoderReadUnexpectedValue	3	Unexpected value in .coderdata file.
CoderReadWrongHeader	4	.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	.coderdata file is not compatible with this release of MATLAB Coder™. Create a new .coderdata file with this version of the product to generate a compatible file.
CoderReadStructArray	6	Expected to read a scalar structure, but .coderdata file contains a structure array. Use a compatible TypeHeader to read this file or a constant file name.
MATFile	7	coder.read cannot read MAT file. Convert your MAT file to a .coderdata files 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 does not match the type information in the specified by the TypeHeaderFrom argument.

Extended Capabilities

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

Version History

Introduced in R2023a