########################################################################
##
## 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{m} =} meanabs (@var{x})
## @deftypefnx {} {[@var{m}, @var{n}] =} meanabs (@var{x})
##
## Compute the magnitude each element of the array or cell input @var{x} and
## return the mean of the result as a scalar output @var{m}.  @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{m}.
##
## @example
## @group
## a = [1 2 Inf -3];
## [m, n] = meanabs (@var{a})
## @result{}
##    m =
##        2
##    n =
##         3
## @end group
## @end example
## @seealso{mean, abs, meansq, meansqr, sumsqr, sumabs}
## @end deftypefn

function [m, n] = meanabs (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 ("meanabs: MEANABS 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 ("meanabs: MEANABS 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
    m = 0;
  else
    m = mean(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 (meanabs (2), 2)
%!assert (class (meanabs (single (2))), "single")
%!assert (class (meanabs ({single(2)})), "single")
%!assert (meanabs (3+4i), 5)
%!assert (meanabs ([1, 2, -3]), 2)
%!assert (meanabs ([1, 2, -3]'), 2)
%!assert (meanabs (magic (2)-2), 1)
%!assert (meanabs ({magic(2)-2}), 1)
%!assert (meanabs ('test'), 112)
%!assert (meanabs (cat (3, magic(2)-2, magic(2)-2)), 1)
%!assert (meanabs ([3+4i, 5-12i; 9+12i, 8+15i]), 12.5, 10*eps)
%!assert (meanabs ({[3+4i, 5-12i; 9+12i, 8+15i]}), 12.5, 10*eps)

##test mixed inputs
%!assert (meanabs ([{[{1}, {-2}]},{[3; -4]'}]), 2.5, 10*eps)
%!assert (meanabs ({1, -2, [3, -4]', 'test'}), 57.25, 10*eps)
%!assert (meanabs ([{1}, {[{-2, {[3, -4], [5, -6]}, -7}]}]), 4, 10*eps)

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

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

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