Mapping Toolbox

readfields

Read fields or records from a fixed format file.

Syntax

• struc = readfields(fname,fstruc)
  struc = readfields(fname,fstruc,recordIDs)
  struc = readfields(fname,fstruc,recordIDs,mformat)
  struc = readfields(fname,fstruc,recordIDs,mformat,fid)
  struc = readfields(fname,fstruc,recordIDs,mformat,fid,'sparse') 
  

Background

Map data is often provided as binary or ASCII files with a fixed format. Writing your own functions to read the data into MATLAB 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.

Description

struc = readfields(fname,fstruc) reads all the records from a fixed format file. fname is a string containing the name of the file. If it is empty, the file is selected interactively. fstruc is 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 of 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 of the records. fieldIDs may 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.

Examples

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: 1
  

Limitations

Formatted 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/line-feed line ending everywhere except the last record. File sizes are not checked when an open file is provided.

Remarks

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 data binary data of the type that would be read by fread, length is the number of elements to be read, name is a string containing the fieldname under which the read data will be stored in the output structure, and type is a format string 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'; % spaced will be suppressed
  filestruc(1).type = 'char';
  
  fstruc(2).length = 2;     
  fstruc(2).name = 'integer Field';   % spaced will be suppressed
  fstruc(2).type = 'int16';
  
  fstruc(3).length = 1;     
  fstruc(3).name = 'float Field';     % spaced will be suppressed
  fstruc(3).type = 'real*4';
  

The type can also be a fscanf and sscanf-style format string of the form '%nX', where n is the number of characters within which the formatted data is found, and Xis the conversion character such as 'g' or 'd'. For formatted fields, the length entry in fstruc is the number of elements, each of which have the width specified in the type string. Fortran-style double precision output such as '0.0D00' may be read using a type string such as '%nD', where n is the number of characters per element. This is an extension to the C-style format strings accepted by sscanf. Users unfamiliar with C should note that '%d' is preferred over '%i' for formatted integers. MATLAB 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 6 characters wide would be of the form:

• fstruc(4).length = 2;     
  fstruc(4).name = 'Elevation Units';  
  fstruc(4).type = '%6d'
  

To summarize, length is number of elements for binary numbers, the number of characters for strings, and the number of elements for formatted data.

Fields can be omitted from all output by providing an empty string for the fstruc name field.

See Also

grepfields	Search within fields of a fixed format file
readmtx	Read a matrix stored in a file
textread	Read formatted text files
spcread	Read columns of data from an ASCII text file
dlmread	Read ASCII delimited file

rcurve

readmtx