Read fields or records from fixed-format files
struc = readfields(fname,fstruc)
struc = readfields(fname,fstruc,recordIDs)
struc = readfields(fname,fstruc,fieldIDs)
struc = readfields(fname,fstruc,recordIDs,mformat)
struc = readfields(fname,fstruc,recordIDs,mformat,fid)
struc = readfields(fname,fstruc,recordIDs,mformat,fid,'sparse')
struc = readfields(fname,fstruc) reads
all the records from a fixed format file. fname is
a character vector containing the name of the file. If it is empty,
the file is selected interactively. fstruc is a
structure defining the format of the file. The contents of fstruc are
described below. The result is returned in a structure.
struc = readfields(fname,fstruc,recordIDs) reads
only the records specified in the vector recordIDs.
For example, recordIDs = [1 2 3 4]. All the fields
in the selected records are read.
struc = readfields(fname,fstruc,fieldIDs)
reads only the fields specified in the cell array fieldIDs.
For example, fieldIDs = {1 2 4}. The selected fields
are read from all the records. fieldIDs can be
used in place of recordIDs in all calling forms.
struc = readfields(fname,fstruc,recordIDs,mformat)
opens the file with the specified machine format. mformat must
be recognized by fopen.
struc = readfields(fname,fstruc,recordIDs,mformat,fid) reads
from a file that is already open. fid is the file
identifier returned by fopen. The records are read
starting from the current location in the file.
struc = readfields(fname,fstruc,recordIDs,mformat,fid,'sparse') disables
error messages when the number of elements read does not agree with
the stated format of the file. This is useful for formatted files
with empty fields. Use fid = [] for files that
are not already open. This option is only compatible with reading
selected records.
Map data is often provided as binary or ASCII files with a fixed format. Writing your own functions to read the data into the MATLAB® workspace can be difficult and time-consuming, particularly for binary files. This function allows you to read the data by simply specifying the format of the file.
Write a binary file and read it.
fid = fopen('testbin','wb');
for i = 1:3
fwrite(fid,['character' num2str(i) ],'char');
fwrite(fid,i,'int8');
fwrite(fid,[i i],'int16');
fwrite(fid,i,'integer*4');
fwrite(fid,i,'real*8');
end
fclose(fid);
fs(1).length = 10;fs(1).type = 'char';fs(1).name = 'field 1';
fs(2).length = 1;fs(2).type = 'int8'; fs(2).name = 'field 2';
fs(3).length = 2;fs(3).type = 'int16';fs(3).name = 'field 3';
fs(4).length = 1;fs(4).type = 'integer*4';fs(4).name = 'field 4';
fs(5).length = 1;fs(5).type = 'float64'; fs(5).name = 'field 5';
s = readfields('testbin',fs);
s(1)
ans =
field1: 'character1'
field2: 1
field3: [1 1]
field4: 1
field5: 1Formatted numbers must stay within the width specified for them. Files must have a size that is an integer multiple of the computed record length. This is potentially a problem for formatted files on DOS platforms that use a carriage return/linefeed line ending everywhere except the last record. File sizes are not checked when an open file is provided.
The format of the file is described in the input argument fstruc. fstruc is
a structure with one entry for every field in the file. fstruc has
three required fields: length, name,
and type. For fields containing binary data of
the type that would be read by fread, length is
the number of elements to be read, name is a character
vector containing the field name under which the read data is stored
in the output structure, and type is a format recognized
by fread. Repetition modifiers such as '40*char' are not supported.
Fields with empty field names are omitted from the output.
The following fstruc definition is for a
file with a 40-character field, a field containing two integers, and
a field with a single-precision floating-point number.
fstruc(1).length = 40; fstruc(1).name = 'character Field'; % spaces will be suppressed filestruc(1).type = 'char'; fstruc(2).length = 2; fstruc(2).name = 'integer Field'; % spaces will be suppressed fstruc(2).type = 'int16'; fstruc(3).length = 1; fstruc(3).name = 'float Field'; % spaces will be suppressed fstruc(3).type = 'real*4';
The type can also be a fscanf and sscanf-style
format of the form '%nX', where n is
the number of characters within which the formatted data is found,
and X is the conversion character such as 'g' or 'd'.
For formatted fields, the length entry in fstruc is
the number of elements, each of which has the width specified in the
type. Fortran-style double-precision output such as '0.0D00' can
be read using a type such as '%nD', where n is
the number of characters per element. This is an extension to the
C-style formats accepted by sscanf. Users unfamiliar
with C should note that '%d' is preferred over '%i' for
formatted integers. MATLAB syntax follows C in interpreting '%i' integers
with leading zeros as octal. Line-ending characters in ASCII files
must also be counted in the fstruc specification.
Note that the number of line-ending characters differs across platforms.
A field specification for a formatted field with two integers each six characters wide would be of the form
fstruc(4).length = 2; fstruc(4).name = 'Elevation Units'; fstruc(4).type = '%6d'
To summarize, length is the number of elements
for binary numbers, the number of characters, and the number of elements
for formatted data.
You can omit fields from all output by providing an empty character
vector ('') for the fstruc name
field.
dlmread | grepfields | readmtx | spcread | textread