% These bindings provide light-weight bindings to the GetData C library for
% use withing MATLAB.  In general, there is a one-to-one mapping between C API
% functions and matlab functions.  Differences in behaviour, where notable, are
% provided in the corresponing function help.
%
% The Dirifle object:
%   Dirfile objects returned from GD_OPEN and similar should be treated as
%   opaque objects.  They should not be used other than when passing to a
%   function in these bindings.
%
% GetData symbolic constants:
%   Like the underlying C API, the GetData bindings make use of a large number
%   of special numbers.  For convenience, a struct containing all these numbers
%   is provided by the GETDATA_CONSTANTS function, which is typically used by
%   doing something like:
%
%     >> GD = GETDATA_CONSTANTS;
%
%   This then allows the use of these constants as GD.UINT8, GD.RAW_ENTRY, &c.,
%   which is both shorter than using the function directly, i.e.,
%   GETDATA_CONSTANTS.UINT8, and also only requires evaluating the
%   GETDATA_CONSTANTS function once.
%
%   In this documentation, when a reference is made to a GetData symbolic
%   constant, it is done so as if the GD variable had been created as above.
%   The reader should understand, e.g., GD.UINT8 as referring to the same
%   special number as the similarly-named C API's symbolic constant, e.g.,
%   GD_UINT8.
%
% Input and Output:
%   Functions in these GetData bindings produce either one or zero scalar or
%   vector outputs, as explained in the corresponding function documentation.
%
%   In general, where the C API would allow a NULL string pointer, these
%   bindings accept a numeric zero (0) instead of a string input in place of a
%   NULL.
%
%   Unlike the C Library, real and complex data may be used interchangeably in
%   function calls.
%
% Error reporting:
%   GetData C Library errors are represented in MATLAB as standard exceptions
%   (see MEXCEPTION).  In general, GetData functions should be evaluated in a
%   TRY ... CATCH ... END block.  GetData-specific exceptions can be identified
%   through their MEXCEPTION.identifier.  The component part of a GetData
%   MEXCPETION.identifier will always start with 'GetData:'.
%
%   Exceptions representing a GetData C Library error will have the component
%   identifier 'GetData:Lib'.  Exceptions generated by the bindings themselves
%   (almost all of which are failures in data conversion between MATLAB and C
%   API data types) will have the component identifier 'GetData:GDMX'.  For C
%   Library errors, the mnemonic part of the MEXCEPTION.identifier corresponds
%   to the C library error code (e.g. 'GetData:Lib:BadCode').  For C Library
%   errors, numeric error codes can be obtained using the GD_ERROR function, as
%   in the C Library.  The return value of GD_ERROR is unspecified after an
%   exception in the MATLAB bindings (i.e. a 'GetData:GDMX' exception).
%
% The Entry structure:
%   Functions which deal with generic field metadata (GD_ADD, GD_ALTER_ENTRY,
%   GD_ENTRY, &c.) use structures mirroring the C API's gd_entry_t object with
%   the following exceptions:
%
%   * In entries with multiple input fields, .IN_FIELDS is a cell array of
%     strings of the appropriate length.  For entries with a single input field,
%     .IN_FIELDS may be either a simple string or else a cell array of length
%     one.
%
%   * A distinction is not made between real and complex data.  As a result,
%     the entry struct for, say, a POLYNOM, stores co-efficients in the .A
%     member, regardless of whether they are complex or purely real.
%
%   * LINCOM entries don't provide a .N_FIELDS member, nor do POLYNOM entries
%     provide a .POLY_ORD member; these values should be determined by
%     determining the length of .IN_FIELDS, .M, or .B for LINCOMs or of .A for
%     POLYNOMs.
%
%   * The .SCALAR and .SCALAR_IND members are provided for field types which
%     allow non-literal parameters.  Where the C API would have NULL pointers
%     in .SCALAR to indicate a literal, the bindings will have a numeric 0 in
%     the corresponding .SCALAR cell array element.  As with .IN_FIELDS, a
%     length-one .SCALAR cell array may be replaced by a scalar.
%
%   See gd_entry(3) in section 3 of the UNIX manual for details on the C API's
%   gd_entry_t object.
%
% Function list:
%   NOTE: accompanying documentation for the functions below in general only
%         point out differences in behaviour between these MATLAB bindings and
%         the underlying C API function which the MATLAB function wraps.  Users
%         should also consult the C API documentation, which can be found in
%         section 3 of the UNIX manual, e.g.
%
%           $ man 3 gd_open
%
