% -*- texinfo -*-
% @deftypefn {Function File} {@var{code} =} encode (@var{msg},@var{n},@var{k})
% @deftypefnx {Function File} {@var{code} =} encode (@var{msg},@var{n},@var{k},@var{typ})
% @deftypefnx {Function File} {@var{code} =} encode (@var{msg},@var{n},@var{k},@var{typ},@var{opt})
% @deftypefnx {Function File} {[@var{code}, @var{added}] =} encode (@var{...})
%
% Top level block encoder. This function makes use of the lower level
% functions such as @dfn{cyclpoly}, @dfn{cyclgen}, @dfn{hammgen}, and
% @dfn{bchenco}. The message to code is pass in @var{msg}, the
% codeword length is @var{n} and the message length is @var{k}. This
% function is used to encode 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 coded message @var{code} being in
% a binary format. In this case the argument @var{opt} is the generator
% matrix, and is required.
% @item 'cyclic' or 'cyclic/binary'
% A cyclic code is assumed with the coded message @var{code} being in a
% binary format. The generator polynomial to use can be defined in @var{opt}.
% The default generator polynomial to use will be
% @dfn{cyclpoly(@var{n},@var{k})}
% @item 'hamming' or 'hamming/binary'
% A Hamming code is assumed with the coded message @var{code} 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{opt}. The default primitive polynomial to use is
% the same as defined by @dfn{hammgen}.
% @item 'bch' or 'bch/binary'
% A BCH code is assumed with the coded message @var{code} being in a binary
% format. The generator polynomial to use can be defined in @var{opt}.
% The default generator polynomial to use will be
% @dfn{bchpoly(@var{n},@var{k})}
% @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{k} matrix
% Each row of this matrix represents a symbol to be coded
% @item A vector
% The symbols are created from groups of @var{k} elements of this vector.
% If the vector length is not divisble by @var{k}, then zeros are added
% and the number of zeros added is returned in @var{added}.
% @end table
%
% 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{encode} 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{encode}
% recalculate this matrix at each iteration. In this case @var{typ} should
% be 'linear'. The exception to this case is BCH codes, whose encoder
% is implemented directly from the polynomial and is significantly faster.
%
% @end deftypefn
% @seealso{decode,cyclgen,cyclpoly,hammgen,bchenco,bchpoly}