% -*- texinfo -*-
% @deftypefn {Function File} {@var{msg} =} decode (@var{code},@var{n},@var{k})
% @deftypefnx {Function File} {@var{msg} =} decode (@var{code},@var{n},@var{k},@var{typ})
% @deftypefnx {Function File} {@var{msg} =} decode (@var{code},@var{n},@var{k},@var{typ},@var{opt1})
% @deftypefnx {Function File} {@var{msg} =} decode (@var{code},@var{n},@var{k},@var{typ},@var{opt1},@var{opt2})
% @deftypefnx {Function File} {[@var{msg}, @var{err}] =} decode (@var{...})
% @deftypefnx {Function File} {[@var{msg}, @var{err}, @var{ccode}] =} decode (@var{...})
% @deftypefnx {Function File} {[@var{msg}, @var{err}, @var{ccode}, @var{cerr}] =} decode (@var{...})
%
% Top level block decoder. This function makes use of the lower level
% functions such as @dfn{cyclpoly}, @dfn{cyclgen}, @dfn{hammgen}, and
% @dfn{bchenco}. The coded message to decode is pass in @var{code}, the
% codeword length is @var{n} and the message length is @var{k}. This
% function is used to decode messages using either:
%
% @table @asis
% @item A [n,k] linear block code defined by a generator matrix
% @item A [n,k] cyclic code defined by a generator polynomial
% @item A [n,k] Hamming code defined by a primitive polynomial
% @item A [n,k] BCH code code defined by a generator polynomial
% @end table
%
% The type of coding to use is defined by the variable @var{typ}. This
% variable is a string taking one of the values
%
% @table @code
% @item 'linear' or 'linear/binary'
% A linear block code is assumed with the message @var{msg} being in a
% binary format. In this case the argument @var{opt1} is the generator
% matrix, and is required. Additionally, @var{opt2} containing the
% syndrome lookup table (see @dfn{syndtable}) can also be passed.
% @item 'cyclic' or 'cyclic/binary'
% A cyclic code is assumed with the message @var{msg} being in a binary
% format. The generator polynomial to use can be defined in @var{opt1}.
% The default generator polynomial to use will be
% @dfn{cyclpoly(@var{n},@var{k})}. Additionally, @var{opt2} containing the
% syndrome lookup table (see @dfn{syndtable}) can also be passed.
% @item 'hamming' or 'hamming/binary'
% A Hamming code is assumed with the message @var{msg} being in a binary
% format. In this case @var{n} must be of an integer of the form
% @code{2^@var{m}-1}, where @var{m} is an integer. In addition @var{k}
% must be @code{@var{n}-@var{m}}. The primitive polynomial to use can
% be defined in @var{opt1}. The default primitive polynomial to use is
% the same as defined by @dfn{hammgen}. The variable @var{opt2} should
% not be defined.
% @item 'bch' or 'bch/binary'
% A BCH code is assumed with the message @var{msg} being in a binary
% format. The primitive polynomial to use can be defined in @var{opt2}.
% The error correction capability of the code can also be defined in
% @var{opt1}. Use the empty matrix [] to let the error correction
% capability take the default value.
% @end table
%
% In addition the argument 'binary' above can be replaced with 'decimal',
% in which case the message is assumed to be a decimal vector, with each
% value representing a symbol to be coded. The binary format can be in two
% forms
%
% @table @code
% @item An @var{x}-by-@var{n} matrix
% Each row of this matrix represents a symbol to be decoded
% @item A vector with length divisible by @var{n}
% The coded symbols are created from groups of @var{n} elements of this vector
% @end table
%
% The decoded message is return in @var{msg}. The number of errors encountered
% is returned in @var{err}. If the coded message format is 'decimal' or a
% 'binary' matrix, then @var{err} is a column vector having a length equal
% to the number of decoded symbols. If @var{code} is a 'binary' vector, then
% @var{err} is the same length as @var{msg} and indicated the number of
% errors in each symbol. If the value @var{err} is positive it indicates the
% number of errors corrected in the corresponding symbol. A negative value
% indicates an uncorrectable error. The corrected code is returned in
% @var{ccode} in a similar format to the coded message @var{msg}. The
% variable @var{cerr} contains similar data to @var{err} for @var{ccode}.
%
% It should be noted that all internal calculations are performed in the
% binary format. Therefore for large values of @var{n}, it is preferable
% to use the binary format to pass the messages to avoid possible rounding
% errors. Additionally, if repeated calls to @dfn{decode} will be performed,
% it is often faster to create a generator matrix externally with the
% functions @dfn{hammgen} or @dfn{cyclgen}, rather than let @dfn{decode}
% recalculate this matrix at each iteration. In this case @var{typ} should
% be 'linear'. The exception to this case is BCH codes, where the required
% syndrome table is too large. The BCH decoder, decodes directly from the
% polynomial never explicitly forming the syndrome table.
%
% @end deftypefn
% @seealso{encode,cyclgen,cyclpoly,hammgen,bchdeco,bchpoly,syndtable}