fread

Syntax

• [A,count] = fread(fid,size,precision)
  [A,count] = fread(fid,size,precision,skip)
  

Description

[A,count] = fread(fid,size,precision) reads binary data from the specified file and writes it into matrix A. Optional output argument count returns the number of elements successfully read. fid is an integer file identifier obtained from fopen.

size is an optional argument that determines how much data is read. If size is not specified, fread reads to the end of the file and the file pointer is at the end of the file

Valid options are:

n	Reads n elements into a column vector.
inf	Reads to the end of the file, resulting in a column vector containing the same number of elements as are in the file.
[m,n]	Reads enough elements to fill an m-by-n matrix, filling in elements in column order, padding with zeros if the file is too small to fill the matrix. n can be specified as inf, but m cannot.

precision is a string that specifies the format of the data to be read. It commonly contains a datatype specifier such as int or float, followed by an integer giving the size in bits. Any of the strings in the following table, either the MATLAB version or their C or Fortran equivalent, may be used. If precision is not specified, the default is 'uchar'.

MATLAB	C or Fortran	Interpretation
'schar'	'signed char'	Signed character; 8 bits
'uchar'	'unsigned char'	Unsigned character; 8 bits
'int8'	'integer*1'	Integer; 8 bits
'int16'	'integer*2'	Integer; 16 bits
'int32'	'integer*4'	Integer; 32 bits
'int64'	'integer*8'	Integer; 64 bits
'uint8'	'integer*1'	Unsigned integer; 8 bits
'uint16'	'integer*2'	Unsigned integer; 16 bits
'uint32'	'integer*4'	Unsigned integer; 32 bits
'uint64'	'integer*8'	Unsigned integer; 64 bits
'float32'	'real*4'	Floating-point; 32 bits
'float64'	'real*8'	Floating-point; 64 bits
'double'	'real*8'	Floating-point; 64 bits

.

The following platform dependent formats are also supported but they are not guaranteed to be the same size on all platforms.



MATLAB	C or Fortran	Interpretation
'char'	'char*1'	Character; 8 bits
'short'	'short'	Integer; 16 bits
'int'	'int'	Integer; 32 bits
'long'	'long'	Integer; 32 or 64 bits
'ushort'	'unsigned short'	Unsigned integer; 16 bits
'uint'	'unsigned int'	Unsigned integer; 32 bits
'ulong'	'unsigned long'	Unsigned integer; 32 or 64 bits
'float'	'float'	Floating-point; 32 bits

The following formats map to an input stream of bits rather than bytes.

MATLAB	C or Fortran	Interpretation
'bitN'	-	Signed integer; N bits (1 N 64)
'ubitN'	-	Unsigned integer; N bits (1 N 64)

By default, numeric values are returned in class double arrays. To return numeric values stored in classes other than double, create your precision argument by first specifying your source format, and then following it with the characters "=>", and finally specifying your destination format. You are not required to use the exact name of a MATLAB class type for destination. (See class for details). fread translates the name to the most appropriate MATLAB class type. If the source and destination formats are the same, the following shorthand notation can be used.

• *source
  

which means

• source=>source
  

This table shows some example precision format strings.

'uint8=>uint8'	Read in unsigned 8-bit integers and save them in an unsigned 8-bit integer array.
'*uint8'	Shorthand version of the above.
'bit4=>int8'	Read in signed 4-bit integers packed in bytes and save them in a signed 8-bit array. Each 4-bit integer becomes an 8-bit integer.
'double=>real*4'	Read in doubles, convert and save as a 32-bit floating point array.

[A,count] = fread(fid,size,precision,skip) includes an optional skip argument that specifies the number of bytes to skip after each precision value is read. If precision specifies a bit format, like 'bitN' or 'ubitN', the skip argument is interpreted as the number of bits to skip.

When skip is used, the precision string may contain a positive integer repetition factor of the form 'N*' which prepends the source format specification, such as '40*uchar'.

Note Do not confuse the asterisk (*) used in the repetition factor with the asterisk used as precision format shorthand. The format string '40*uchar' is equivalent to '40*uchar=>double', not '40*uchar=>uchar'.

When skip is specified, fread reads in, at most, a repetition factor number of values (default is 1), skips the amount of input specified by the skip argument, reads in another block of values, again skips input, and so on, until size number of values have been read. If a skip argument is not specified, the repetition factor is ignored. Use the repetition factor with the skip argument to extract data in noncontiguous fields from fixed length records.

If the input stream is bytes and fread reaches the end of file in the middle of reading the number of bytes required for an element, the partial result is ignored. However, if the input stream is bits, then the partial result is returned as the last value. If an error occurs before reaching the end of file, only full elements read up to that point are used.

Examples

For example,

• type fread.m
  

displays the complete M-file containing this fread help entry. To simulate this command using fread, enter the following:

• fid = fopen('fread.m','r');
  F = fread(fid);
  s = char(F')
  

In the example, the fread command assumes the default size, inf, and the default precision, 'uchar'. fread reads the entire file, converting the unsigned characters into a column vector of class 'double' (double precision floating point). To display the result as readable text, the 'double' column vector is transposed to a row vector and converted to class 'char' using the char function.

As another example,

• s = fread(fid,120,'40*uchar=>uchar',8);
  

reads in 120 characters in blocks of 40, each separated by 8 characters. Note that the class type of s is 'uint8' since it is the appropriate class corresponding to the destination format, 'uchar'. Also, since 40 evenly divides 120, the last block read is a full block which means that a final skip will be done before the command is finished. If the last block read is not a full block then fread will not finish with a skip.

See fopen for information about reading Big and Little Endian files.