Main Content

coder.read

Read data files at run time in generated code

Since R2023a

    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.

    example

    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.

    example

    [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

    collapse all

    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

    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

    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 data in a .coderdata file, use the coder.write function in MATLAB.

    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

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

    CoderReadProblemReading2

    Issue while reading the .coderdata file.

    CoderReadUnexpectedValue3

    Unexpected value in the .coderdata file.

    CoderReadWrongHeader4

    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.

    CoderReadWrongVersion5

    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.

    CoderReadStructArray6

    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.

    MATFile7

    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.

    WrongType8

    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