########################################################################
##
## Copyright (C) 1998-2021 The Octave Project Developers
##
## See the file COPYRIGHT.md in the top-level directory of this
## distribution or <https://octave.org/copyright/>.
##
## This file is part of Octave.
##
## Octave is free software: you can redistribute it and/or modify it
## under the terms of the GNU General Public License as published by
## the Free Software Foundation, either version 3 of the License, or
## (at your option) any later version.
##
## Octave is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
## GNU General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with Octave; see the file COPYING.  If not, see
## <https://www.gnu.org/licenses/>.
##
########################################################################

## -*- texinfo -*-
## @deftypefn  {} {@var{s} =} sumabs (@var{x})
## @deftypefnx {} {[@var{s}, @var{n}] =} sumabs (@var{x})
##
## Compute the magnitude each element of the array or cell input @var{x} and
## return the sum of the result as a scalar output @var{s}.  @var{x} may consist
## of numeric, char, logical, or complex values, and cells may contain mixed
## types.  Non-finite (Inf, NaN, NA) values are ignored for the calculation.  If
## requested, the optional output argument @var{n} will contain the number of
## finite elements in @var{x} used to calculate @var{s}.
##
## @example
## @group
## a = [1 2 Inf -3];
## [s, n] = sumabs (@var{a})
## @result{}
##    s =
##        6
##    n =
##         3
## @end group
## @end example
## @seealso{sum, abs, sumsqr, meanabs, meansq, meansqr}
## @end deftypefn

function [s, n] = sumabs (x)

  if ((nargin != 1) || (!any (nargout == [0 1 2])))
    print_usage ();
  endif

  if (isnumeric (x) || islogical (x) || ischar (x))

    ## abs first to convert any char to numeric, output column vector
    x = abs (x(:));

  elseif strcmp (class (x), "cell")
    ## input validation: check contents after cell flattened

    ## output 1 column cell array with 1 column array cell contents to avoid
    ## problems with mismatched cell content sizes
    x = flatten_to_column_cell (x);

    ##check flattened content types
    if ! all(cellfun (@(C) isnumeric (C) || islogical (C) || ischar (C), x))
      bad_cells = ! cellfun (@(C) isnumeric (C) || islogical (C) || ischar (C), x);
      bad_class = find (bad_cells, 1, "first");
      error ("sumabs: SUMABS not defined for cell arrays containing type %s", class (x{bad_class}));
    endif

    ## convert any chars to numeric with @abs, then revert to array.
    x = cell2mat (cellfun (@abs, x, "UniformOutput", false));

  else
    error ("sumabs: SUMABS not defined for type %s", class (x));
  endif

  ## convert to single column input and exclude non-finite (NaN,Inf, NA)
  x = x(isfinite (x));

  n = numel (x);

  if n == 0
    s = 0;
  else
    s = sum (x);
  endif

endfunction

function C = flatten_to_column_cell (C)
  ## recursively flatten cell of any depth into a n x 1 cell array.
  if iscell (C)
    C = cellfun (@flatten_to_column_cell, C, 'UniformOutput', false);
    C = vertcat (C{:});
  else
    C = {C(:)};
  endif
endfunction


%!assert (sumabs (2), 2)
%!assert (class (sumabs (single (2))), "single")
%!assert (class (sumabs ({single(2)})), "single")
%!assert (sumabs (3+4i), 5)
%!assert (sumabs ([1, 2, -3]), 6)
%!assert (sumabs ([1, 2, -3]'), 6)
%!assert (sumabs (magic (2)-2), 4)
%!assert (sumabs ({magic(2)-2}), 4)
%!assert (sumabs ('test'), 448)
%!assert (sumabs (cat (3, magic(2)-2, magic(2)-2)), 8)
%!assert (sumabs ([3+4i, 5-12i; 9+12i, 8+15i]), 50)
%!assert (sumabs ({[3+4i, 5-12i; 9+12i, 8+15i]}), 50)

##test mixed inputs
%!assert (sumabs ([{[{1}, {-2}]},{[3; -4]'}]), 10)
%!assert (sumabs ({1, -2, [3, -4]', 'test'}), 458)
%!assert (sumabs ([{1}, {[{-2, {[3, -4], [5, -6]}, -7}]}]), 28)

## test nonfinite inputs
%!assert (sumabs ([]), 0)
%!assert (sumabs (Inf), 0)
%!assert (sumabs ([Inf, NA, NaN]), 0)
%!assert (sumabs ([Inf, NA, NaN, -1]), 1)

%!test
%! a = [{'test'}, {[{2, -7}]}, Inf];
%! [s, n] = sumabs (a);
%! assert (s, 457)
%! assert (n, 6)

## Test input validation
%!error sumabs ()
%!error sumabs (1, 2)
%!error [a, b, c] = sumabs (1, 2)
%!error <SUMABS not defined for type> sumabs (struct("a",1))
%!error <SUMABS not defined for cell arrays containing type> sumabs ({1, struct("a",1)})