%FREAD  Read binary data from file.
%   [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.
%   
%   The SIZE argument is optional; if not specified, the entire
%   file is read and the file pointer is at the end of the file (see
%   FEOF for details); if specified, valid entries are:
%       N      read N elements into a column vector.
%       inf    read to the end of the file.
%       [M,N]  read elements to fill an M-by-N matrix, in column order.
%              N can be inf, but M can't.
%   
%   The PRECISION argument is a string that specifies the format
%   of the data to be read. It commonly contains a datatype specifier
%   like 'int' or 'float' followed by an integer giving the size in
%   bits.  Any of the following strings, either the MATLAB version,
%   or their C or Fortran equivalent, may be used.  If not specified,
%   the default is 'uchar'.
%   
%       MATLAB    C or Fortran     Description
%       'uchar'   'unsigned char'  unsigned character,  8 bits.
%       'schar'   'signed char'    signed 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.
%       'single'  'real*4'         floating point, 32 bits.
%       'float32' 'real*4'         floating point, 32 bits.
%       'double'  'real*8'         floating point, 64 bits.
%       'float64' 'real*8'         floating point, 64 bits.
%
%   For example,
%
%       type fread.m
%
%   displays the complete M-file containing this FREAD help entry.  To
%   simulate this command one could enter instead:
%
%       fid = fopen('fread.m','r');
%       F = fread(fid);
%       s = char(F')
%
%   The FOPEN command opens the M-file on the MATLAB path with name,
%   'fread.m' for reading. The FREAD command assumes the default SIZE of
%   inf and the default PRECISION of 'uchar'. It 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' (character) using the CHAR
%   function.
%
%   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     Description
%       'char'    'char*1'         character,  8 bits (signed or unsigned).
%       '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 bits or 64 bits.
%       'float'   'float'          floating point, 32 bits.
%
%   The following formats map to an input stream of bits rather than
%   bytes.
%
%       '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, then following it by '=>', and finally specifying your
%   destination format. You are not required to use the exact name
%   of a MATLAB class type (see CLASS for details) for the destination.
%   The name is translated for you to the name of the most appropriate
%   MATLAB class type.  If the source and destination formats are the
%   same then the following shorthand notation may be used:
%
%       *source
%
%   which means:
%
%       source=>source
%
%   For example,
%
%       uint8=>uint8               read in unsigned 8-bit integers and
%                                  save them in an unsigned 8-bit integer
%                                  array
%
%       *uint8                     shorthand version of previous example
%
%       bit4=>int8                 read in signed 4-bit integers packed
%                                  in bytes and save them in a signed
%                                  8-bit integer array (each 4-bit
%                                  integer becomes one 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 a SKIP argument
%   that specifies the number of bytes to skip after each PRECISION value
%   is read. When SKIP is used, the PRECISION string may contain a
%   positive integer repetition factor of the form 'N*' which prepends
%   the source format of the PRECISION argument, like '40*uchar'.  Note
%   that 40*uchar for the PRECISION alone is equivalent to
%   '40*uchar=>double', not '40*uchar=>uchar'. With the SKIP specified,
%   FREAD reads in at most a repetition factor number of values
%   (default of 1), does a skip of input specified by the SKIP argument,
%   reads in another block of values and does a skip of input, etc. until
%   SIZE number of values have been read. If PRECISION includes a source
%   format like 'bitN' or 'ubitN' SKIP is specified in bits. Repetition
%   with skip is useful for extracting data in noncontiguous fields from
%   fixed length records.
%
%   For 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 on how to read Big and Little Endian files.
%
%   See also FWRITE, FSEEK, FSCANF, FGETL, FGETS, LOAD, FOPEN.

%   [A,COUNT] = FREAD(...,MACHINEFORMAT) also accepts a MACHINEFORMAT
%   parameter (see FOPEN for details). 

%   Copyright 1984-2000 The MathWorks, Inc. 
%   $Revision: 5.16 $  $Date: 2000/08/30 21:51:31 $
%   Built-in function.
