% DELAY delays a time-series using various methods.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% DESCRIPTION: DELAY delays a time-series using various methods.
%
% CALL:        b = delay(a, pl)
%
%
% PARAMETERS:  N   - delay the time-series by N samples. [default: 0]
%                    Choose a 'method' for how the end of the time-series
%                    is handled:
%                    'zero'   - zero pad the time-series
%
% <a href="matlab:utils.helper.displayMethodInfo('ao', 'delay')">Parameters Description</a>
% 
% EXAMPLES:    1) Shift by 10 samples and zero pad the end of the time-series
%                 >> b = delay(a, plist('N', 10, 'method', 'zero'));
%
%
% VERSION:     $Id: delay.m,v 1.27 2011/04/08 08:56:11 hewitson Exp $
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% TODO
%                        'extrap' - extrapolate the last N samples

function varargout = delay(varargin)

  % Check if this is a call for parameters
  if utils.helper.isinfocall(varargin{:})
    varargout{1} = getInfo(varargin{3});
    return
  end
  
  import utils.const.*
  utils.helper.msg(msg.PROC3, 'running %s/%s', mfilename('class'), mfilename);

  % Collect input variable names
  in_names = cell(size(varargin));
  for ii = 1:nargin,in_names{ii} = inputname(ii);end

  % Collect all AOs
  [as, ao_invars] = utils.helper.collect_objects(varargin(:), 'ao', in_names);
  pl              = utils.helper.collect_objects(varargin(:), 'plist', in_names);

  % Decide on a deep copy or a modify
  bs = copy(as, nargout);

  % Combine plists
  pl = parse(pl, getDefaultPlist);

  %----------- Get parameters

  % 1: Sample shift
  N      = find(pl, 'N');
  method = find(pl, 'method');

  % Loop over AOs
  for j=1:numel(bs)
    if ~isa(bs(j).data, 'tsdata')
      warning('!!! Skipping object %s - it contains no tsdata.', ao_invars{j});
    else
      % Which method to use
      switch lower(method)
        case 'zero'
          bs(j).data.setY([zeros(N,1); bs(j).data.getY(1:end-N)]);
        otherwise
          error('### Unknown method for dealing with end of time-series.');
      end
      % make output analysis object
      bs(j).name = sprintf('delay(%s)', ao_invars{j});
      % Add history
      bs(j).addHistory(getInfo('None'), pl, ao_invars(j), bs(j).hist);
      % Clear the errors since they don't make sense anymore
      clearErrors(bs(j));
    end
  end

  
  % Set output
  if nargout == numel(bs)
    % List of outputs
    for ii = 1:numel(bs)
      varargout{ii} = bs(ii);
    end
  else
    % Single output
    varargout{1} = bs;
  end
end

%--------------------------------------------------------------------------
% Get Info Object
%--------------------------------------------------------------------------
function ii = getInfo(varargin)
  if nargin == 1 && strcmpi(varargin{1}, 'None')
    sets = {};
    pl   = [];
  else
    sets = {'Default'};
    pl   = getDefaultPlist;
  end
  % Build info object
  ii = minfo(mfilename, 'ao', 'ltpda', utils.const.categories.sigproc, '$Id: delay.m,v 1.27 2011/04/08 08:56:11 hewitson Exp $', sets, pl);
end

%--------------------------------------------------------------------------
% Get Default Plist
%--------------------------------------------------------------------------

function plout = getDefaultPlist()
  persistent pl;  
  if exist('pl', 'var')==0 || isempty(pl)
    pl = buildplist();
  end
  plout = pl;  
end

function pl = buildplist()
  pl = plist();
  
  % N
  p = param({'N', 'The number of samples to delay by.'}, {1, {0}, paramValue.OPTIONAL});
  pl.append(p);
  
  % Method
  p = param({'method', 'The method for handling the end of the time-series.'}, {1, {'zero'}, paramValue.SINGLE});
  pl.append(p);
end