Main Content

coder.read

Read data files at run time in generated code

Since R2023a

    Description

    example

    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.

    example

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

    collapse all

    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

    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

    collapse all

    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.

    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

    collapse all

    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

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

    Enumeration MemberEnumeration ValueError Reference
    Success0

    Read operation success.

    CoderReadCouldNotOpen1

    Unable to open specified .coderdata file.

    CoderReadProblemReading2

    Issue while reading .coderdata file.

    CoderReadUnexpectedValue3

    Unexpected value in .coderdata file.

    CoderReadWrongHeader4

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

    CoderReadWrongVersion5

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

    CoderReadStructArray6

    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.

    MATFile7

    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.

    WrongType8

    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