Main Content

read

Class: matlab.io.datastore.DsFileReader
Package: matlab.io.datastore

Read bytes from file

Syntax

A = read(fr,size)
A = read(fr,size,Name,Value)
[A,count] = read(___)

Description

A = read(fr,size) returns data, from the file represented by the file-reader object fr. The number of bytes specified in size determines the amount of data that is read.

A = read(fr,size,Name,Value)specifies additional parameters using one or more name-value pair arguments. For example, you can specify the output type from the read operation to be char by specifying 'OutputType','char'.

[A,count] = read(___) returns a count of the number of bytes of data that were actually read by the read method.

Input Arguments

expand all

File-reader object, specified as a matlab.io.datastore.DsFileReader object. To create a DsFileReader object, see matlab.io.datastore.DsFileReader.

Size of data to read, specified as an integer that represents the number of bytes to read.

Example: read(fr,20)

Data Types: double

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'OutputType','uint8'

Output data type, specified as the comma-separated pair consisting of 'OutputType' and a character vector or string scalar containing one of these values: 'uint8', 'int8', 'int16', 'int32', 'int64', 'uint16', 'uint32', 'uint64', 'single', 'double', or 'char'.

Example: 'OutputType','uint8'

Data Types: char | string

Interpret size input, specified as the comma-separated pair consisting of 'SizeMethod' and one of these values:

  • 'NumBytes' - Interpret the size input argument as the number of bytes to read from the file.

  • 'OutputSize' - Interpret the size input argument as the size of the output A from the read method.

Example: 'SizeMethod','OutputSize'

Data Types: char | string

Output Arguments

expand all

Output data, returned as an array.

Number of bytes read, returned as a numeric scalar integer.

  • If the 'SizeMethod' property is unspecified or set to 'NumBytes', then count is the number of bytes read.

  • If the 'SizeMethod' property is set to 'OutputSize', then count is equal to size(A).

Data Types: double

Examples

Read Portion of File Specified by Starting Position and Size

Create a file-reader object for a file, seek to the desired starting position, and read a portion of the file.

Create a DsFileReader object for airlinesmall.csv.

fr = matlab.io.datastore.DsFileReader('airlinesmall.csv');

The airlinesmall.csv file has variable names at the beginning of the file. The variable names line ends at the position marked by 299 bytes. To get past the variable names line, use the seek method to move the read pointer to the starting position.

seek(fr,299,'RespectTextEncoding',true);

Check if the file has data to read using the hasdata method. The read method reads 1000 bytes from the file and interprets them as characters.

if hasdata(fr)
   [d,count] = read(fr,1000,'OutputType','char');
end

Read enough bytes from the file to fill 1000 characters by setting the SizeMethod parameter to OutputSize.

if hasdata(fr)
    [d,count] = read(fr,1000,'SizeMethod','OutputSize',...
                                       'OutputType','char');
end

Introduced in R2017b