data.cc

Go to the documentation of this file.

////////////////////////////////////////////////////////////////////////
//
// Copyright (C) 1994-2026 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/>.
//
////////////////////////////////////////////////////////////////////////
 
#if defined (HAVE_CONFIG_H)
#  include "config.h"
#endif
 
#include <cmath>
#include <cstddef>
#include <cstdint>
#include <ctime>
 
#include <algorithm>
#include <limits>
#include <string>
 
#include "lo-ieee.h"
#include "mx-base.h"
#include "oct-base64.h"
#include "oct-binmap.h"
#include "oct-time.h"
#include "quit.h"
 
#include "cdef-utils.h"
#include "Cell.h"
#include "data.h"
#include "defun.h"
#include "error.h"
#include "errwarn.h"
#include "interpreter-private.h"
#include "interpreter.h"
#include "oct-map.h"
#include "ov-class.h"
#include "ov-classdef.h"
#include "ov-complex.h"
#include "ov-cx-mat.h"
#include "ov-cx-sparse.h"
#include "ov-float.h"
#include "ov-flt-complex.h"
#include "ov-flt-cx-mat.h"
#include "ov.h"
#include "ovl.h"
#include "pager.h"
#include "pt-mat.h"
#include "utils.h"
#include "variables.h"
#include "xnorm.h"
 
OCTAVE_BEGIN_NAMESPACE(octave)
 
static void
get_dim_vecdim_all (const octave_value& dimarg, octave_value& arg,
                    int& dim, Array<int>& perm_vec, bool& do_perm,
                    bool& allflag, const char *fcn)
{
  if (dimarg.is_scalar_type ())
    {
      dim = dimarg.int_value () - 1;
      if (dim < 0)
        error ("%s: invalid dimension DIM = %d", fcn, dim + 1);
    }
  else
    {
      Array<int> vec = dimarg.int_vector_value ();
      std::vector<int> vecdim;
      dim_vector sz = arg.dims ();
      int ndims = arg.ndims ();
      // Check for invalid dims and ignore any dims larger than actual ndims
      for (int i = 0; i < vec.numel (); i++)
        {
          vec(i)--;
          if (vec(i) < 0)
            error ("%s: invalid dimension in VECDIM = %d", fcn, vec(i)+1);
          if (vec(i) < ndims)
            vecdim.push_back (vec(i));
        }
      int n = vecdim.size ();
      // If no dimensions left, set DIM = ndims to return input as is
      if (n == 0)
        {
          dim = ndims;
          return;
        }
      octave_idx_type szvecdim = 1;
      // Check for duplicate dims and add VECDIM to permutation vector
      perm_vec.resize (dim_vector (1, ndims));
      std::sort (vecdim.begin (), vecdim.end ());
      // Check for duplicates FIRST before any array writes
      auto dup = std::adjacent_find (vecdim.begin (), vecdim.end ());
      if (dup != vecdim.end ())
        error ("%s: duplicate dimension in VECDIM = %d", fcn, *dup + 1);
 
       // Verified vecdim has unique entries in [0, ndims-1], hence n <= ndims
       int out_pos = ndims - n;
       for (int d : vecdim)
         {
           szvecdim *= sz (d);
           perm_vec(out_pos++) = d;
         }
 
      // Parse vecdim
      if (n == 1)
        // Only one dimension given, treat as if dim were specified instead
        dim = vecdim[0];
      else if (ndims == n)
        // vecdim contains all dimensions, treat as if "all" flag given.
        allflag = true;
      else
        {
          dim_vector new_sz;
          new_sz.resize (ndims - n + 1);
          int idx = 0;
          // Add remaining dims to permutation vector
          for (int i = 0; i < ndims; i++)
            {
              if (std::find (vecdim.begin (), vecdim.end (), i)
                  == vecdim.end ())
                {
                  perm_vec(idx) = i;
                  new_sz(idx) = sz(i);
                  idx++;
                }
            }
          new_sz(idx) = szvecdim;
          arg = arg.permute (perm_vec, false);
          arg = arg.reshape (new_sz);
          do_perm = true;
          dim = idx;
        }
    }
}
 
DEFUN (all, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{tf} =} all (@var{x})
@deftypefnx {} {@var{tf} =} all (@var{x}, @var{dim})
@deftypefnx {} {@var{tf} =} all (@var{x}, @var{vecdim})
@deftypefnx {} {@var{tf} =} all (@var{x}, "all")
Return true (logical 1) if all elements are nonzero or true.
 
If @var{x} is a vector, then @code{all (@var{x})} returns true (logical 1) if
all elements of the vector are nonzero.
 
If @var{x} is a matrix, then @code{all (@var{x})} returns a row vector of
logical ones and zeros where each element indicates whether all of the elements
of the corresponding column of the matrix are nonzero.
 
If @var{x} is an array, then @code{all(@var{x})} operates along the first
non-singleton dimension of @var{x} and returns a logical array, whose size is
equal to @var{x} except for the operating dimension which becomes 1.
 
The optional input @var{dim} specifies the dimension to operate on and must be
a positive integer.  Specifying any singleton dimension in @var{x}, including
any dimension exceeding @code{ndims (@var{x})}, will return @var{x}.
 
Specifying multiple dimensions with input @var{vecdim}, a vector of
non-repeating dimensions, will operate along the array slice defined by
@var{vecdim}.  If @var{vecdim} indexes all dimensions of @var{x}, then it is
equivalent to the option @qcode{"all"}.  Any dimension in @var{vecdim} greater
than @code{ndims (@var{x})} is ignored.  The size of the dimensions specified
by @var{vecdim} become 1 in the returned logical array.
 
Specifying the dimension as @qcode{"all"} will cause @code{all} to operate on
all elements of @var{x}, and is equivalent to @code{all (@var{x}(:))}.
@seealso{any}
@end deftypefn */)
{
  int nargin = args.length ();
 
  bool do_perm = false;
  bool allflag = false;
 
  while (nargin > 1 && args(nargin - 1).is_string ())
    {
      std::string str = args(nargin - 1).string_value ();
 
      if (str == "all")
        allflag = true;
      else
        error ("all: unrecognized optional argument '%s'", str.c_str ());
 
      nargin--;
    }
 
  if (nargin < 1 || nargin > 2)
    print_usage ();
  if (allflag && nargin > 1)
    error ("all: cannot set DIM or VECDIM with 'all' flag");
 
  octave_value arg = args(0);
 
  // Handle DIM, VECDIM
  int dim = -1;
  Array<int> perm_vec;
  if (nargin == 2)
    {
      octave_value dimarg = args(1);
      get_dim_vecdim_all (dimarg, arg, dim, perm_vec, do_perm, allflag, "all");
    }
 
  // Handle allflag
  if (allflag)
    arg = arg.reshape (dim_vector (arg.numel (), 1));
 
  octave_value retval = arg.all (dim);
 
  if (do_perm)
    retval = retval.permute (perm_vec, true);
 
  return retval;
}
 
/*
%!test
%! x = ones (3);
%! x(1,1) = 0;
%! assert (all (all (rand (3) + 1) == [1, 1, 1]) == 1);
%! assert (all (all (x) == [0, 1, 1]) == 1);
%! assert (all (x, 1) == [0, 1, 1]);
%! assert (all (x, 2) == [0; 1; 1]);
 
%!test
%! x = ones (3, "single");
%! x(1,1) = 0;
%! assert (all (all (single (rand (3) + 1)) == [1, 1, 1]) == 1);
%! assert (all (all (x) == [0, 1, 1]) == 1);
%! assert (all (x, 1) == [0, 1, 1]);
%! assert (all (x, 2) == [0; 1; 1]);
 
%!test
%! x = ones (3, 3, 3);
%! x(3) = 0;
%! y = all (x);
%! assert (y(:,:,1), logical ([0, 1, 1]));
%! assert (y(:,:,2), logical ([1, 1, 1]));
%! assert (y(:,:,3), logical ([1, 1, 1]));
%! y = all (x, [1, 2]);
%! assert (y(:,:,1), false);
%! assert (y(:,:,2), true);
%! assert (y(:,:,3), true);
%! assert (all (x, [1, 3]), logical ([0, 1, 1]));
%! assert (all (x, [2, 3]), logical ([1; 1; 0]));
%! assert (all (x, "all"), false);
 
%!assert (all (ones (2), 3), logical (ones (2)))
%!assert (all (ones (2), [3, 5]), logical (ones (2)))
 
## Test empty matrices
%!assert (all ([]), true)
%!assert (all ([], 1), true (1, 0))
%!assert (all ([], 2), true (0, 1))
%!assert (all ([], 3), true (0, 0))
%!assert (all (ones (1,0)), true)
%!assert (all (ones (1,0), 1), true (1, 0))
%!assert (all (ones (1,0), 2), true)
%!assert (all (ones (1,0), 3), true (1, 0))
%!assert (all (ones (0,1)), true)
%!assert (all (ones (0,1), 1), true)
%!assert (all (ones (0,1), 2), true (0, 1))
%!assert (all (ones (0,1), 3), true (0, 1))
 
## Test sparse matrices
%!assert (all (sparse ([NaN, NaN, 1, 4, 2; 1, 2, 1, 0, NaN]), 2),
%!        sparse ([true; false]))
%!assert (all (sparse ([NaN, 0, 1, 4, 2; 1, 2, 1, 2, NaN]), 2),
%!        sparse ([false; true]))
 
## Test empty sparse matrices
%!assert (all (sparse ([])), sparse (true))
%!assert (all (sparse ([]), 1), sparse (true (1, 0)))
%!assert (all (sparse ([]), 2), sparse (true (0, 1)))
%!assert (all (sparse ([]), 3), sparse (true (0, 0)))
%!assert (all (sparse (ones (1,0))), sparse (true))
%!assert (all (sparse (ones (1,0)), 1), sparse (true (1, 0)))
%!assert (all (sparse (ones (1,0)), 2), sparse (true))
%!assert (all (sparse (ones (1,0)), 3), sparse (true (1, 0)))
%!assert (all (sparse (ones (0,1))), sparse (true))
%!assert (all (sparse (ones (0,1)), 1), sparse (true))
%!assert (all (sparse (ones (0,1)), 2), sparse (true (0, 1)))
%!assert (all (sparse (ones (0,1)), 3), sparse (true (0, 1)))
 
## Test input validation
%!error <Invalid call> all ()
%!error <Invalid call> all (1,2,3)
%!error <unrecognized optional argument 'foobar'> all (1, "foobar")
%!error <cannot set DIM or VECDIM with 'all' flag>
%! all (ones (3,3), 1, "all");
%!error <cannot set DIM or VECDIM with 'all' flag>
%! all (ones (3,3), [1, 2], "all");
%!error <invalid dimension DIM = 0> all (ones (3,3), 0)
%!error <invalid dimension DIM = -1> all (ones (3,3), -1)
%!error <invalid dimension in VECDIM = -2> all (ones (3,3), [1 -2])
%!error <duplicate dimension in VECDIM = 2> all (ones (3,3), [1 2 2])
%!error <duplicate dimension in VECDIM = 1> all (ones (3,3), [1 1 2])
*/
 
DEFUN (any, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{tf} =} any (@var{x})
@deftypefnx {} {@var{tf} =} any (@var{x}, @var{dim})
@deftypefnx {} {@var{tf} =} any (@var{x}, @var{vecdim})
@deftypefnx {} {@var{tf} =} any (@var{x}, "all")
Return true (logical 1) if any elements are nonzero or true.
 
If @var{x} is a vector, then @code{any (@var{x})} returns true (logical 1) if
any elements of the vector are nonzero.
 
If @var{x} is a matrix, then @code{any (@var{x})} returns a row vector of
logical ones and zeros where each element indicates whether any of the elements
of the corresponding column of the matrix are nonzero.
 
If @var{x} is an array, then @code{any(@var{x})} operates along the first
non-singleton dimension of @var{x} and returns a logical array, whose size is
equal to @var{x} except for the operating dimension which becomes 1.
 
The optional input @var{dim} specifies the dimension to operate on and must be
a positive integer.  Specifying any singleton dimension in @var{x}, including
any dimension exceeding @code{ndims (@var{x})}, will return @var{x}.
 
Specifying multiple dimensions with input @var{vecdim}, a vector of
non-repeating dimensions, will operate along the array slice defined by
@var{vecdim}.  If @var{vecdim} indexes all dimensions of @var{x}, then it is
equivalent to the option @qcode{"all"}.  Any dimension in @var{vecdim} greater
than @code{ndims (@var{x})} is ignored.  The size of the dimensions specified
by @var{vecdim} become 1 in the returned logical array.
 
Specifying the dimension as @qcode{"all"} will cause @code{any} to operate on
all elements of @var{x}, and is equivalent to @code{any (@var{x}(:))}.
@seealso{all}
@end deftypefn */)
{
  int nargin = args.length ();
 
  bool do_perm = false;
  bool allflag = false;
 
  while (nargin > 1 && args(nargin - 1).is_string ())
    {
      std::string str = args(nargin - 1).string_value ();
 
      if (str == "all")
        allflag = true;
      else
        error ("any: unrecognized optional argument '%s'", str.c_str ());
 
      nargin--;
    }
 
  if (nargin < 1 || nargin > 2)
    print_usage ();
  if (allflag && nargin > 1)
    error ("any: cannot set DIM or VECDIM with 'all' flag");
 
  octave_value arg = args(0);
 
  // Handle DIM, VECDIM
  int dim = -1;
  Array<int> perm_vec;
  if (nargin == 2)
    {
      octave_value dimarg = args(1);
      get_dim_vecdim_all (dimarg, arg, dim, perm_vec, do_perm, allflag, "any");
    }
 
  // Handle allflag
  if (allflag)
    arg = arg.reshape (dim_vector (arg.numel (), 1));
 
  octave_value retval = arg.any (dim);
 
  if (do_perm)
    retval = retval.permute (perm_vec, true);
 
  return retval;
}
 
/*
%!test
%! x = zeros (3);
%! x(3,3) = 1;
%! assert (all (any (x) == [0, 0, 1]) == 1);
%! assert (all (any (ones (3)) == [1, 1, 1]) == 1);
%! assert (any (x, 1) == [0, 0, 1]);
%! assert (any (x, 2) == [0; 0; 1]);
 
%!test
%! x = zeros (3, "single");
%! x(3,3) = 1;
%! assert (all (any (x) == [0, 0, 1]) == 1);
%! assert (all (any (ones (3, "single")) == [1, 1, 1]) == 1);
%! assert (any (x, 1) == [0, 0, 1]);
%! assert (any (x, 2) == [0; 0; 1]);
 
%!test
%! x = zeros (3, 3, 3);
%! x(3) = 1;
%! y = any (x);
%! assert (y(:,:,1), logical ([1, 0, 0]));
%! assert (y(:,:,2), logical ([0, 0, 0]));
%! assert (y(:,:,3), logical ([0, 0, 0]));
%! y = any (x, [1, 2]);
%! assert (y(:,:,1), true);
%! assert (y(:,:,2), false);
%! assert (y(:,:,3), false);
%! assert (any (x, [1, 3]), logical ([1, 0, 0]));
%! assert (any (x, [2, 3]), logical ([0; 0; 1]));
%! assert (any (x, "all"), true);
 
## Test empty matrices
%!assert (any ([]), false)
%!assert (any ([], 1), false (1, 0))
%!assert (any ([], 2), false (0, 1))
%!assert (any ([], 3), false (0, 0))
%!assert (any (ones (1,0)), false)
%!assert (any (ones (1,0), 1), false (1, 0))
%!assert (any (ones (1,0), 2), false)
%!assert (any (ones (1,0), 3), false (1, 0))
%!assert (any (ones (0,1)), false)
%!assert (any (ones (0,1), 1), false)
%!assert (any (ones (0,1), 2), false (0, 1))
%!assert (any (ones (0,1), 3), false (0, 1))
 
## Test sparse matrices
%!assert (any (sparse ([NaN, NaN, 1, 4, 2; 1, 2, 1, 0, NaN]), 2),
%!        sparse ([true; true]))
%!assert (any (sparse ([0, 0, 0, 0, 0; 1, 2, 1, 2, NaN]), 2),
%!        sparse ([false; true]))
%!assert (any (sparse ([0, 0, 0, 0i, 0; 1, 2, 1, 2, NaN]), 2),
%!        sparse ([false; true]))
%!assert (any (sparse ([0, 0, 0, 0+i, 0; 1, 2, 1, 2, NaN]), 2),
%!        sparse ([true; true]))
 
## Test empty sparse matrices
%!assert (any (sparse ([])), sparse (false))
%!assert (any (sparse ([]), 1), sparse (false (1, 0)))
%!assert (any (sparse ([]), 2), sparse (false (0, 1)))
%!assert (any (sparse ([]), 3), sparse (false (0, 0)))
%!assert (any (sparse (ones (1,0))), sparse (false))
%!assert (any (sparse (ones (1,0)), 1), sparse (false (1, 0)))
%!assert (any (sparse (ones (1,0)), 2), sparse (false))
%!assert (any (sparse (ones (1,0)), 3), sparse (false (1, 0)))
%!assert (any (sparse (ones (0,1))), sparse (false))
%!assert (any (sparse (ones (0,1)), 1), sparse (false))
%!assert (any (sparse (ones (0,1)), 2), sparse (false (0, 1)))
%!assert (any (sparse (ones (0,1)), 3), sparse (false (0, 1)))
 
## Test input validation
%!error <Invalid call> any ()
%!error <Invalid call> any (1,2,3)
%!error <unrecognized optional argument 'foobar'> any (1, "foobar")
%!error <cannot set DIM or VECDIM with 'all' flag>
%! any (ones (3,3), 1, "all");
%!error <cannot set DIM or VECDIM with 'all' flag>
%! any (ones (3,3), [1, 2], "all");
%!error <invalid dimension DIM = 0> any (ones (3,3), 0)
%!error <invalid dimension DIM = -1> any (ones (3,3), -1)
%!error <invalid dimension in VECDIM = -2> any (ones (3,3), [1 -2])
%!error <duplicate dimension in VECDIM = 2> any (ones (3,3), [1 2 2])
%!error <duplicate dimension in VECDIM = 1> any (ones (3,3), [1 1 2])
*/
 
// These mapping functions may also be useful in other places, eh?
 
DEFUN (atan2, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{angle} =} atan2 (@var{y}, @var{x})
Compute atan (@var{y} / @var{x}) for corresponding elements of @var{y} and
@var{x}.
 
@var{y} and @var{x} must match in size and orientation.  The signs of elements
of @var{y} and @var{x} are used to determine the quadrants of each resulting
value.
 
This function is equivalent to @code{arg (complex (@var{x}, @var{y}))}.
@seealso{tan, tand, tanh, atanh}
@end deftypefn */)
{
  if (args.length () != 2)
    print_usage ();
 
  octave_value retval;
 
  if (! args(0).isnumeric ())
    err_wrong_type_arg ("atan2", args(0));
 
  if (! args(1).isnumeric ())
    err_wrong_type_arg ("atan2", args(1));
 
  if (args(0).iscomplex () || args(1).iscomplex ())
    error ("atan2: not defined for complex numbers");
 
  if (args(0).is_single_type () || args(1).is_single_type ())
    {
      if (args(0).is_scalar_type () && args(1).is_scalar_type ())
        retval = atan2f (args(0).float_value (), args(1).float_value ());
      else
        {
          FloatNDArray a0 = args(0).float_array_value ();
          FloatNDArray a1 = args(1).float_array_value ();
          retval = binmap<float> (a0, a1, std::atan2, "atan2");
        }
    }
  else
    {
      if (args(0).is_scalar_type () && args(1).is_scalar_type ())
        retval = atan2 (args(0).scalar_value (), args(1).scalar_value ());
      else if (args(0).issparse ())
        {
          SparseMatrix m0 = args(0).sparse_matrix_value ();
          SparseMatrix m1 = args(1).sparse_matrix_value ();
          retval = binmap<double> (m0, m1, std::atan2, "atan2");
        }
      else
        {
          NDArray a0 = args(0).array_value ();
          NDArray a1 = args(1).array_value ();
          retval = binmap<double> (a0, a1, std::atan2, "atan2");
        }
    }
 
  return retval;
}
 
/*
%!assert (size (atan2 (zeros (0, 2), zeros (0, 2))), [0, 2])
%!assert (size (atan2 (rand (2, 3, 4), zeros (2, 3, 4))), [2, 3, 4])
%!assert (size (atan2 (rand (2, 3, 4), 1)), [2, 3, 4])
%!assert (size (atan2 (1, rand (2, 3, 4))), [2, 3, 4])
%!assert (size (atan2 (1, 2)), [1, 1])
 
%!test
%! rt2 = sqrt (2);
%! rt3 = sqrt (3);
%! v = [0, pi/6, pi/4, pi/3, -pi/3, -pi/4, -pi/6, 0];
%! y = [0, rt3, 1, rt3, -rt3, -1, -rt3, 0];
%! x = [1, 3, 1, 1, 1, 1, 3, 1];
%! assert (atan2 (y, x), v, sqrt (eps));
 
%!test
%! rt2 = sqrt (2);
%! rt3 = sqrt (3);
%! v = single ([0, pi/6, pi/4, pi/3, -pi/3, -pi/4, -pi/6, 0]);
%! y = single ([0, rt3, 1, rt3, -rt3, -1, -rt3, 0]);
%! x = single ([1, 3, 1, 1, 1, 1, 3, 1]);
%! assert (atan2 (y, x), v, sqrt (eps ("single")));
 
%!assert (any (ones (2), 3), logical (ones (2)))
%!assert (any (ones (2), [3, 5]), logical (ones (2)))
 
## Test sparse implementations
%!shared xs
%! xs = sparse (0:3);
%!test
%! y = atan2 (1, xs);
%! assert (issparse (y), false);
%! assert (nnz (y), 4);
%! assert (y, atan2 (1, 0:3));
%!test
%! y = atan2 (0, xs);
%! assert (issparse (y), false);
%! assert (nnz (y), 0);
%! assert (y, zeros (1,4));
%!test
%! y = atan2 (xs, 1);
%! assert (issparse (y));
%! assert (nnz (y), 3);
%! assert (y, sparse (atan2 (0:3, 1)));
%!test
%! y = atan2 (xs, 0);
%! assert (issparse (y));
%! assert (nnz (y), 3);
%! assert (y, sparse (atan2 (0:3, 0)));
%!test
%! y = atan2 (xs, sparse (ones (1, 4)));
%! assert (issparse (y));
%! assert (nnz (y), 3);
%! assert (y, sparse (atan2 (0:3, ones (1,4))));
%!test
%! y = atan2 (xs, sparse (zeros (1,4)));
%! assert (issparse (y));
%! assert (nnz (y), 3);
%! assert (y, sparse (atan2 (0:3, zeros (1,4))));
 
%!error atan2 ()
%!error atan2 (1, 2, 3)
*/
 
static octave_value
do_hypot (const octave_value& x, const octave_value& y)
{
  octave_value retval;
 
  octave_value arg0 = x;
  octave_value arg1 = y;
  if (! arg0.isnumeric ())
    err_wrong_type_arg ("hypot", arg0);
  if (! arg1.isnumeric ())
    err_wrong_type_arg ("hypot", arg1);
 
  if (arg0.iscomplex ())
    arg0 = arg0.abs ();
  if (arg1.iscomplex ())
    arg1 = arg1.abs ();
 
  if (arg0.is_single_type () || arg1.is_single_type ())
    {
      if (arg0.is_scalar_type () && arg1.is_scalar_type ())
        retval = hypotf (arg0.float_value (), arg1.float_value ());
      else
        {
          FloatNDArray a0 = arg0.float_array_value ();
          FloatNDArray a1 = arg1.float_array_value ();
          retval = binmap<float> (a0, a1, std::hypot, "hypot");
        }
    }
  else
    {
      if (arg0.is_scalar_type () && arg1.is_scalar_type ())
        retval = hypot (arg0.scalar_value (), arg1.scalar_value ());
      else if (arg0.issparse () || arg1.issparse ())
        {
          SparseMatrix m0 = arg0.sparse_matrix_value ();
          SparseMatrix m1 = arg1.sparse_matrix_value ();
          retval = binmap<double> (m0, m1, std::hypot, "hypot");
        }
      else
        {
          NDArray a0 = arg0.array_value ();
          NDArray a1 = arg1.array_value ();
          retval = binmap<double> (a0, a1, std::hypot, "hypot");
        }
    }
 
  return retval;
}
 
DEFUN (hypot, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{h} =} hypot (@var{x}, @var{y})
@deftypefnx {} {@var{h} =} hypot (@var{x}, @var{y}, @var{z}, @dots{})
Compute the element-by-element square root of the sum of the squares of
@var{x} and @var{y}.
 
This is equivalent to
@code{sqrt (@var{x}.^2 + @var{y}.^2)}, but is calculated in a manner that
avoids overflows for large values of @var{x} or @var{y}.
 
@code{hypot} can also be called with more than 2 arguments; in this case,
the arguments are accumulated from left to right:
 
@example
@group
hypot (hypot (@var{x}, @var{y}), @var{z})
hypot (hypot (hypot (@var{x}, @var{y}), @var{z}), @var{w}), etc.
@end group
@end example
@end deftypefn */)
{
  int nargin = args.length ();
 
  if (nargin < 2)
    print_usage ();
 
  octave_value retval;
 
  if (nargin == 2)
    retval = do_hypot (args(0), args(1));
  else
    {
      retval = args(0);
 
      for (int i = 1; i < nargin; i++)
        retval = do_hypot (retval, args(i));
    }
 
  return retval;
}
 
/*
%!assert (size (hypot (zeros (0, 2), zeros (0, 2))), [0, 2])
%!assert (size (hypot (rand (2, 3, 4), zeros (2, 3, 4))), [2, 3, 4])
%!assert (size (hypot (rand (2, 3, 4), 1)), [2, 3, 4])
%!assert (size (hypot (1, rand (2, 3, 4))), [2, 3, 4])
%!assert (size (hypot (1, 2)), [1, 1])
%!assert (hypot (1:10, 1:10), sqrt (2) * [1:10], 16*eps)
%!assert (hypot (single (1:10), single (1:10)), single (sqrt (2) * [1:10]))
 
## Test sparse implementations
%!shared xs
%! xs = sparse (0:3);
%!test
%! y = hypot (1, xs);
%! assert (nnz (y), 4);
%! assert (y, sparse (hypot (1, 0:3)));
%!test
%! y = hypot (0, xs);
%! assert (nnz (y), 3);
%! assert (y, xs);
%!test
%! y = hypot (xs, 1);
%! assert (nnz (y), 4);
%! assert (y, sparse (hypot (0:3, 1)));
%!test
%! y = hypot (xs, 0);
%! assert (nnz (y), 3);
%! assert (y, xs);
%!test
%! y = hypot (sparse ([0 0]), sparse ([0 1]));
%! assert (nnz (y), 1);
%! assert (y, sparse ([0 1]));
%!test
%! y = hypot (sparse ([0 1]), sparse ([0 0]));
%! assert (nnz (y), 1);
%! assert (y, sparse ([0 1]));
 
*/
 
template <typename T, typename ET>
void
map_2_xlog2 (const Array<T>& x, Array<T>& f, Array<ET>& e)
{
  f = Array<T> (x.dims ());
  e = Array<ET> (x.dims ());
  for (octave_idx_type i = 0; i < x.numel (); i++)
    {
      int exp;
      f.xelem (i) = math::log2 (x(i), exp);
      e.xelem (i) = exp;
    }
}
 
DEFUN (log2, args, nargout,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{y} =} log2 (@var{x})
@deftypefnx {} {[@var{f}, @var{e}] =} log2 (@var{x})
Compute the base-2 logarithm of each element of @var{x}.
 
If called with one output, compute the base-2 logarithm such that
@tex
$2^y = x$.
@end tex
@ifnottex
@code{2^@var{y} = @var{x}}.
@end ifnottex
 
If called with two output arguments, split @var{x} into binary mantissa
(@var{f}) and exponent (@var{e}) such that
@tex
$x = f \cdot 2^e$
@end tex
@ifnottex
@code{@var{x} = @var{f} * 2^@var{e}}
@end ifnottex
where
@tex
${1 \over 2} \le \left| f \right| < 1$
@end tex
@ifnottex
@w{@code{1/2 <= abs (@var{f}) < 1}}
@end ifnottex
and @var{e} is an integer.  If
@tex
$x = 0$, $f = e = 0$.
@end tex
@ifnottex
@w{@code{x = 0}}, @w{@code{f = e = 0}}.
@end ifnottex
@seealso{pow2, log, log10, exp}
@end deftypefn */)
{
  if (args.length () != 1)
    print_usage ();
 
  octave_value_list retval;
 
  if (nargout < 2)
    retval = ovl (args(0).log2 ());
  else if (args(0).is_single_type ())
    {
      if (args(0).isreal ())
        {
          FloatNDArray f;
          FloatNDArray x = args(0).float_array_value ();
          // FIXME: should E be an int value?
          FloatMatrix e;
          map_2_xlog2 (x, f, e);
          retval = ovl (f, e);
        }
      else if (args(0).iscomplex ())
        {
          FloatComplexNDArray f;
          FloatComplexNDArray x = args(0).float_complex_array_value ();
          // FIXME: should E be an int value?
          FloatNDArray e;
          map_2_xlog2 (x, f, e);
          retval = ovl (f, e);
        }
    }
  else if (args(0).isreal ())
    {
      NDArray f;
      NDArray x = args(0).array_value ();
      // FIXME: should E be an int value?
      Matrix e;
      map_2_xlog2 (x, f, e);
      retval = ovl (f, e);
    }
  else if (args(0).iscomplex ())
    {
      ComplexNDArray f;
      ComplexNDArray x = args(0).complex_array_value ();
      // FIXME: should E be an int value?
      NDArray e;
      map_2_xlog2 (x, f, e);
      retval = ovl (f, e);
    }
  else
    err_wrong_type_arg ("log2", args(0));
 
  return retval;
}
 
/*
%!assert (log2 ([1/4, 1/2, 1, 2, 4]), [-2, -1, 0, 1, 2])
%!assert (log2 (Inf), Inf)
%!assert (isnan (log2 (NaN)))
%!assert (log2 (4*i), 2 + log2 (1*i))
%!assert (log2 (complex (0,Inf)), Inf + log2 (i))
 
%!test
%! [f, e] = log2 ([0,-1; 2,-4; Inf,-Inf]);
%! assert (f, [0,-0.5; 0.5,-0.5; Inf,-Inf]);
%! assert (e(1:2,:), [0,1;2,3]);
 
%!test
%! [f, e] = log2 (complex (zeros (3, 2), [0,-1; 2,-4; Inf,-Inf]));
%! assert (f, complex (zeros (3, 2), [0,-0.5; 0.5,-0.5; Inf,-Inf]));
%! assert (e(1:2,:), [0,1; 2,3]);
 
%!assert <*42583> (all (log2 (pow2 (-1074:1023)) == -1074:1023))
*/
 
DEFUN (rem, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{r} =} rem (@var{x}, @var{y})
Return the remainder of the division @code{@var{x} / @var{y}}.
 
The remainder is computed using the expression
 
@example
x - y .* fix (x ./ y)
@end example
 
An error message is printed if the dimensions of the arguments do not agree,
or if either argument is complex.
 
Programming Notes: When calculating with floating point numbers (double,
single), values within a few eps of an integer will be rounded to that
integer before computation for compatibility with @sc{matlab}.  Any floating
point integers greater than @code{flintmax} (2^53 for double) will not compute
correctly.  For larger integer values convert the input to @code{uint64} before
calling this function.
 
By convention,
 
@example
@group
rem (@var{x}, 0) = NaN  if @var{x} is a floating point variable
rem (@var{x}, 0) = 0    if @var{x} is an integer variable
rem (@var{x}, @var{y})  returns a value with the signbit from @var{x}
@end group
@end example
 
For the opposite conventions see the @code{mod} function.  In general,
@code{rem} is best when computing the remainder after division of two
@emph{positive} numbers.  For negative numbers, or when the values are
periodic, @code{mod} is a better choice.
@seealso{mod}
@end deftypefn */)
{
  if (args.length () != 2)
    print_usage ();
 
  octave_value retval;
 
  if (! args(0).isnumeric ())
    err_wrong_type_arg ("rem", args(0));
 
  if (! args(1).isnumeric ())
    err_wrong_type_arg ("rem", args(1));
 
  if (args(0).iscomplex () || args(1).iscomplex ())
    error ("rem: not defined for complex numbers");
 
  if (args(0).isinteger () || args(1).isinteger ())
    {
      builtin_type_t btyp0 = args(0).builtin_type ();
      builtin_type_t btyp1 = args(1).builtin_type ();
      if (btyp0 == btyp_double || btyp0 == btyp_float)
        btyp0 = btyp1;
      if (btyp1 == btyp_double || btyp1 == btyp_float)
        btyp1 = btyp0;
 
      if (btyp0 != btyp1)
        error ("rem: cannot combine %s and %s",
               args(0).class_name ().c_str (),
               args(1).class_name ().c_str ());
 
      switch (btyp0)
        {
#define MAKE_INT_BRANCH(X)                                              \
          case btyp_ ## X:                                              \
            {                                                           \
              X##NDArray a0 = args(0).X##_array_value ();               \
              X##NDArray a1 = args(1).X##_array_value ();               \
              retval = binmap<octave_##X,octave_##X,octave_##X> (a0, a1, rem, "rem"); \
            }                                                           \
            break
 
          MAKE_INT_BRANCH (int8);
          MAKE_INT_BRANCH (int16);
          MAKE_INT_BRANCH (int32);
          MAKE_INT_BRANCH (int64);
          MAKE_INT_BRANCH (uint8);
          MAKE_INT_BRANCH (uint16);
          MAKE_INT_BRANCH (uint32);
          MAKE_INT_BRANCH (uint64);
 
#undef MAKE_INT_BRANCH
 
          case btyp_double:
          case btyp_float:
          case btyp_complex:
          case btyp_float_complex:
          case btyp_bool:
          case btyp_char:
          case btyp_struct:
          case btyp_cell:
          case btyp_func_handle:
          case btyp_unknown:
            error ("rem: unexpected: found %s instead of integer - please report this bug", btyp_class_name[btyp0].c_str ());
            break;
 
          // We should have handled all possible enum values above.
          // Rely on compiler diagnostics to warn if we haven't.  For
          // example, GCC's -Wswitch option, enabled by -Wall, will
          // provide a warning.
        }
    }
  else if (args(0).is_single_type () || args(1).is_single_type ())
    {
      if (args(0).is_scalar_type () && args(1).is_scalar_type ())
        retval = math::rem (args(0).float_value (), args(1).float_value ());
      else
        {
          FloatNDArray a0 = args(0).float_array_value ();
          FloatNDArray a1 = args(1).float_array_value ();
          retval = binmap<float> (a0, a1, math::rem<float>, "rem");
        }
    }
  else
    {
      if (args(0).is_scalar_type () && args(1).is_scalar_type ())
        retval = math::rem (args(0).scalar_value (), args(1).scalar_value ());
      else if (args(0).issparse () || args(1).issparse ())
        {
          SparseMatrix m0 = args(0).sparse_matrix_value ();
          SparseMatrix m1 = args(1).sparse_matrix_value ();
          retval = binmap<double> (m0, m1, math::rem<double>, "rem");
        }
      else
        {
          NDArray a0 = args(0).array_value ();
          NDArray a1 = args(1).array_value ();
          retval = binmap<double> (a0, a1, math::rem<double>, "rem");
        }
    }
 
  return retval;
}
 
/*
%!assert (size (rem (zeros (0, 2), zeros (0, 2))), [0, 2])
%!assert (size (rem (rand (2, 3, 4), zeros (2, 3, 4))), [2, 3, 4])
%!assert (size (rem (rand (2, 3, 4), 1)), [2, 3, 4])
%!assert (size (rem (1, rand (2, 3, 4))), [2, 3, 4])
%!assert (size (rem (1, 2)), [1, 1])
 
%!assert (rem ([1, 2, 3; -1, -2, -3], 2), [1, 0, 1; -1, 0, -1])
%!assert (rem ([1, 2, 3; -1, -2, -3], 2 * ones (2, 3)),[1, 0, 1; -1, 0, -1])
%!assert (rem ([0, 1, 2], [0, 0, 1]), [NaN, NaN, 0])
%!assert (rem (uint8 ([1, 2, 3; -1, -2, -3]), uint8 (2)),
%!        uint8 ([1, 0, 1; -1, 0, -1]))
%!assert (uint8 (rem ([1, 2, 3; -1, -2, -3], 2 * ones (2, 3))),
%!        uint8 ([1, 0, 1; -1, 0, -1]))
%!assert (rem (uint8 ([0, 1, 2]), [0, 0, 1]), uint8 ([0, 0, 0]))
 
## Test sparse implementations
%!shared xs
%! xs = sparse (0:3);
%!test
%! y = rem (11, xs);
%! assert (isnan (y(1)));
%! assert (y, sparse (rem (11, 0:3)));
%!test
%! y = rem (0, xs);
%! assert (nnz (y), 1);
%! assert (y, sparse ([NaN 0 0 0]));
%!test
%! y = rem (xs, 2);
%! assert (nnz (y), 2);
%! assert (y, sparse (rem (0:3, 2)));
%!test
%! y = rem (xs, 1);
%! assert (nnz (y), 0);
%! assert (y, sparse (rem (0:3, 1)));
%!test
%! y = rem (sparse ([11 11 11 11]), xs);
%! assert (nnz (y), 3);
%! assert (y, sparse (rem (11, 0:3)));
%!test
%! y = rem (sparse ([0 0 0 0]), xs);
%! assert (nnz (y), 1);
%! assert (y, sparse ([NaN 0 0 0]));
 
%!assert <*45587> (signbit (rem (-0, 1)))
%!assert <*45587> (! signbit (rem (0, 1)))
 
%!assert <*42627> (rem (0.94, 0.01), 0.0)
 
## Test rem (x-1, x) for x close to flintmax. Should return x-1 and not zero.
%!test <*67339>
%! x = flintmax - (10:-1:1);
%! assert (rem (x-1, x), x-1);
%! x = flintmax ("single") - (10:-1:1);
%! assert (rem (x-1, x), x-1);
 
%!error rem (uint (8), int8 (5))
%!error rem (uint8 ([1, 2]), uint8 ([3, 4, 5]))
%!error rem ()
%!error rem (1, 2, 3)
%!error rem ([1, 2], [3, 4, 5])
%!error rem (i, 1)
*/
 
DEFUN (mod, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{m} =} mod (@var{x}, @var{y})
Compute the modulo of @var{x} and @var{y}.
 
Conceptually this is given by
 
@example
x - y .* floor (x ./ y)
@end example
 
@noindent
and is written such that the correct modulus is returned for integer types.
This function handles negative values correctly.  That is,
@w{@code{mod (-1, 3)}}@ is 2, not -1, as @w{@code{rem (-1, 3)}}@ returns.
 
An error results if the dimensions of the arguments do not agree, or if
either of the arguments is complex.
 
Programming Notes: When calculating with floating point numbers (double,
single), values within a few eps of an integer will be rounded to that
integer before computation for compatibility with @sc{matlab}.  Any floating
point integers greater than @code{flintmax} (2^53 for double) will not compute
correctly.  For larger integer values convert the input to @code{uint64} before
calling this function.
 
By convention,
 
@example
@group
mod (@var{x}, 0) = @var{x}
mod (@var{x}, @var{y})      returns a value with the signbit from @var{y}
@end group
@end example
 
For the opposite conventions see the @code{rem} function.  In general,
@code{mod} is a better choice than @code{rem} when any of the inputs are
negative numbers or when the values are periodic.
@seealso{rem}
@end deftypefn */)
{
  if (args.length () != 2)
    print_usage ();
 
  octave_value retval;
 
  if (! args(0).isnumeric ())
    err_wrong_type_arg ("mod", args(0));
 
  if (! args(1).isnumeric ())
    err_wrong_type_arg ("mod", args(1));
 
  if (args(0).iscomplex () || args(1).iscomplex ())
    error ("mod: not defined for complex numbers");
 
  if (args(0).isinteger () || args(1).isinteger ())
    {
      builtin_type_t btyp0 = args(0).builtin_type ();
      builtin_type_t btyp1 = args(1).builtin_type ();
      if (btyp0 == btyp_double || btyp0 == btyp_float)
        btyp0 = btyp1;
      if (btyp1 == btyp_double || btyp1 == btyp_float)
        btyp1 = btyp0;
 
      if (btyp0 != btyp1)
        error ("mod: cannot combine %s and %s",
               args(0).class_name ().c_str (),
               args(1).class_name ().c_str ());
 
      switch (btyp0)
        {
#define MAKE_INT_BRANCH(X)                                              \
          case btyp_ ## X:                                              \
            {                                                           \
              X##NDArray a0 = args(0).X##_array_value ();               \
              X##NDArray a1 = args(1).X##_array_value ();               \
              retval = binmap<octave_##X,octave_##X,octave_##X> (a0, a1, mod, "mod"); \
            }                                                           \
            break
 
          MAKE_INT_BRANCH (int8);
          MAKE_INT_BRANCH (int16);
          MAKE_INT_BRANCH (int32);
          MAKE_INT_BRANCH (int64);
          MAKE_INT_BRANCH (uint8);
          MAKE_INT_BRANCH (uint16);
          MAKE_INT_BRANCH (uint32);
          MAKE_INT_BRANCH (uint64);
 
#undef MAKE_INT_BRANCH
 
          case btyp_double:
          case btyp_float:
          case btyp_complex:
          case btyp_float_complex:
          case btyp_bool:
          case btyp_char:
          case btyp_struct:
          case btyp_cell:
          case btyp_func_handle:
          case btyp_unknown:
            error ("mod: unexpected: found %s instead of integer - please report this bug", btyp_class_name[btyp0].c_str ());
            break;
 
          // We should have handled all possible enum values above.
          // Rely on compiler diagnostics to warn if we haven't.  For
          // example, GCC's -Wswitch option, enabled by -Wall, will
          // provide a warning.
        }
    }
  else if (args(0).is_single_type () || args(1).is_single_type ())
    {
      if (args(0).is_scalar_type () && args(1).is_scalar_type ())
        retval = math::mod (args(0).float_value (), args(1).float_value ());
      else
        {
          FloatNDArray a0 = args(0).float_array_value ();
          FloatNDArray a1 = args(1).float_array_value ();
          retval = binmap<float> (a0, a1, math::mod<float>, "mod");
        }
    }
  else
    {
      if (args(0).is_scalar_type () && args(1).is_scalar_type ())
        retval = math::mod (args(0).scalar_value (), args(1).scalar_value ());
      else if (args(0).issparse () || args(1).issparse ())
        {
          SparseMatrix m0 = args(0).sparse_matrix_value ();
          SparseMatrix m1 = args(1).sparse_matrix_value ();
          retval = binmap<double> (m0, m1, math::mod<double>, "mod");
        }
      else
        {
          NDArray a0 = args(0).array_value ();
          NDArray a1 = args(1).array_value ();
          retval = binmap<double> (a0, a1, math::mod<double>, "mod");
        }
    }
 
  return retval;
}
 
/*
## empty input test
%!assert (isempty (mod ([], [])))
 
## x mod y, y != 0 tests
%!assert (mod (5, 3), 2)
%!assert (mod (-5, 3), 1)
%!assert (mod (0, 3), 0)
%!assert (mod ([-5, 5, 0], [3, 3, 3]), [1, 2, 0])
%!assert (mod ([-5; 5; 0], [3; 3; 3]), [1; 2; 0])
%!assert (mod ([-5, 5; 0, 3], [3, 3 ; 3, 1]), [1, 2 ; 0, 0])
 
## x mod 0 tests
%!assert (mod (5, 0), 5)
%!assert (mod (-5, 0), -5)
%!assert (mod ([-5, 5, 0], [3, 0, 3]), [1, 5, 0])
%!assert (mod ([-5; 5; 0], [3; 0; 3]), [1; 5; 0])
%!assert (mod ([-5, 5; 0, 3], [3, 0 ; 3, 1]), [1, 5 ; 0, 0])
%!assert (mod ([-5, 5; 0, 3], [0, 0 ; 0, 0]), [-5, 5; 0, 3])
 
## mixed scalar/matrix tests
%!assert (mod ([-5, 5; 0, 3], 0), [-5, 5; 0, 3])
%!assert (mod ([-5, 5; 0, 3], 3), [1, 2; 0, 0])
%!assert (mod (-5, [0,0; 0,0]), [-5, -5; -5, -5])
%!assert (mod (-5, [3,0; 3,1]), [1, -5; 1, 0])
%!assert (mod (-5, [3,2; 3,1]), [1, 1; 1, 0])
 
## integer types
%!assert (mod (uint8 (5), uint8 (4)), uint8 (1))
%!assert (mod (uint8 ([1:5]), uint8 (4)), uint8 ([1,2,3,0,1]))
%!assert (mod (uint8 ([1:5]), uint8 (0)), uint8 ([1:5]))
%!error mod (uint8 (5), int8 (4))
 
## mixed integer/real types
%!assert (mod (uint8 (5), 4), uint8 (1))
%!assert (mod (5, uint8 (4)), uint8 (1))
%!assert (mod (uint8 ([1:5]), 4), uint8 ([1,2,3,0,1]))
 
## non-integer real numbers
%!assert (mod (2.1, 0.1), 0)
%!assert (mod (2.1, 0.2), 0.1, eps)
 
%!assert <*45587> (signbit (mod (-0, 0)))
%!assert <*45587> (! signbit (mod (0, -0)))
 
%!assert <*42627> (mod (0.94, 0.01), 0.0)
 
%!assert <*54602> (mod (int8 (125), int8 (-25)), int8 (0))
%!assert <*54602> (mod (int8 (-125), int8 (-25)), int8 (0))
%!assert <*54602> (mod (int8 (-125), int8 (0)), int8 (-125))
%!assert <*54602> (mod (int8 (0), int8 (-25)), int8 (0))
 
## Test mod (x-1, x) for x close to flintmax. Should return x-1 and not zero.
%!test <*67339>
%! x = flintmax - (10:-1:1);
%! assert (mod (x-1, x), x-1);
%! x = flintmax ("single") - (10:-1:1);
%! assert (mod (x-1, x), x-1);
*/
 
DEFUN (cumprod, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{y} =} cumprod (@var{x})
@deftypefnx {} {@var{y} =} cumprod (@var{x}, @var{dim})
@deftypefnx {} {@var{y} =} cumprod (@var{x}, @var{vecdim})
@deftypefnx {} {@var{y} =} cumprod (@dots{}, "all")
@deftypefnx {} {@var{y} =} cumprod (@dots{}, @var{direction})
@deftypefnx {} {@var{y} =} cumprod (@dots{}, @var{nanflag})
Compute the cumulative product of elements in @var{x}.
 
If @var{x} is a vector, then @code{cumprod (@var{x})} returns a vector of the
same size with the cumulative product of @var{x}.
 
If @var{x} is a matrix, then @code{cumprod (@var{x})} returns a matrix of the
same size with the cumulative product along each column of @var{x}.
 
If @var{x} is an array, then @code{cumprod(@var{x})} returns an array of the
same size with the cumulative product along the first non-singleton dimension
of @var{x}.
 
The class of output @var{y} is the same as the class of input @var{x}, unless
@var{x} is logical, in which case @var{y} is double.
 
The optional input @var{dim} specifies the dimension to operate on and must be
a positive integer.  Specifying any singleton dimension in @var{x}, including
any dimension exceeding @code{ndims (@var{x})}, will return @var{x}.
 
Specifying multiple dimensions with input @var{vecdim}, a vector of
non-repeating dimensions, will operate along the array slice defined by
@var{vecdim}.  If @var{vecdim} indexes all dimensions of @var{x}, then it is
equivalent to the option @qcode{"all"}.  Any dimension in @var{vecdim} greater
than @code{ndims (@var{x})} is ignored.
 
Specifying the dimension as @qcode{"all"} will cause @code{cumprod} to operate
on all elements of @var{x}, and is equivalent to @code{cumprod (@var{x}(:))}.
 
The optional input @var{direction} specifies how the operating dimension is
traversed and can take the following values:
 
@table @asis
@item @qcode{"forward"} (default)
 
The cumulative product is computed from beginning (index 1) to end along the
operating dimension.
 
@item @qcode{"reverse"}
 
The cumulative product is computed from end to beginning along the operating
dimension.
@end table
 
The optional variable @var{nanflag} specifies whether to include or exclude
NaN values from the calculation using any of the previously specified input
argument combinations.  The default value for @var{nanflag} is
@qcode{"includenan"} which keeps NaN values in the calculation.  To exclude
NaN values set the value of @var{nanflag} to @qcode{"omitnan"}.  The output
will still contain NaN values if @var{x} consists of all NaN values in the
operating dimension.
@seealso{prod, cumsum}
@end deftypefn */)
{
  int nargin = args.length ();
 
  bool direction = false;
  bool do_perm = false;
  bool allflag = false;
  bool nanflag = false;
 
  while (nargin > 1 && args(nargin - 1).is_string ())
    {
      std::string str = args(nargin - 1).string_value ();
 
      if (str == "forward")
        direction = false;
      else if (str == "reverse")
        direction = true;
      else if (str == "all")
        allflag = true;
      else if (str == "omitnan" || str == "omitmissing")
        {
          if (args(0).is_double_type () || args(0).is_single_type ())
            nanflag = true;
        }
      else if (str == "includenan" || str == "includemissing")
        nanflag = false;
      else
        error ("cumprod: unrecognized optional argument '%s'", str.c_str ());
 
      nargin--;
    }
 
  if (nargin < 1 || nargin > 2)
    print_usage ();
  if (allflag && nargin > 1)
    error ("cumprod: cannot set DIM or VECDIM with 'all' flag");
 
  octave_value arg = args(0);
 
  // Handle DIM, VECDIM
  int dim = -1;
  Array<int> perm_vec;
  if (nargin == 2)
    {
      octave_value dimarg = args(1);
      get_dim_vecdim_all (dimarg, arg, dim, perm_vec, do_perm, allflag, "cumprod");
    }
 
  // Handle allflag
  if (allflag)
    arg = arg.reshape (dim_vector (arg.numel (), 1));
 
  octave_value retval;
 
  switch (arg.builtin_type ())
    {
    case btyp_double:
      if (arg.issparse ())
        {
          if (direction)
            error ("cumprod: DIRECTION is not supported for sparse matrices");
          else
            retval = arg.sparse_matrix_value ().cumprod (dim, nanflag);
        }
      else
        {
          if (direction)
            retval = arg.array_value ().flip (dim).cumprod (dim, nanflag).flip (dim);
          else
            retval = arg.array_value ().cumprod (dim, nanflag);
        }
      break;
 
    case btyp_complex:
      if (arg.issparse ())
        {
          if (direction)
            error ("cumprod: DIRECTION is not supported for sparse matrices");
          else
            retval = arg.sparse_complex_matrix_value ().cumprod (dim, nanflag);
        }
      else
        {
          if (direction)
            retval = arg.complex_array_value ().flip (dim).cumprod (dim, nanflag).flip (dim);
          else
            retval = arg.complex_array_value ().cumprod (dim, nanflag);
        }
      break;
 
    case btyp_float:
      if (direction)
        retval = arg.float_array_value ().flip (dim).cumprod (dim, nanflag).flip (dim);
      else
        retval = arg.float_array_value ().cumprod (dim, nanflag);
      break;
 
    case btyp_float_complex:
      if (direction)
        retval = arg.float_complex_array_value ().flip (dim).cumprod (dim, nanflag).flip (dim);
      else
        retval = arg.float_complex_array_value ().cumprod (dim, nanflag);
      break;
 
#define MAKE_INT_BRANCH(X)                                            \
      case btyp_ ## X:                                                \
        if (direction)                                                \
          retval = arg.X ## _array_value ().flip (dim).cumprod (dim).flip (dim);  \
        else                                                          \
          retval = arg.X ## _array_value ().cumprod (dim);            \
        break;
 
      MAKE_INT_BRANCH (int8);
      MAKE_INT_BRANCH (int16);
      MAKE_INT_BRANCH (int32);
      MAKE_INT_BRANCH (int64);
      MAKE_INT_BRANCH (uint8);
      MAKE_INT_BRANCH (uint16);
      MAKE_INT_BRANCH (uint32);
      MAKE_INT_BRANCH (uint64);
 
#undef MAKE_INT_BRANCH
 
    case btyp_bool:
      if (arg.issparse ())
        {
          if (direction)
            error ("cumprod: DIRECTION is not supported for sparse matrices");
          retval = arg.sparse_matrix_value ().cumprod (dim);
        }
      else
        {
          if (direction)
            retval = arg.array_value ().flip (dim).cumprod (dim).flip (dim);
          else
            retval = arg.array_value ().cumprod (dim);
        }
      break;
 
    default:
      err_wrong_type_arg ("cumprod", arg);
    }
 
  if (do_perm)
    retval = retval.permute (perm_vec, true);
 
  return retval;
}
 
/*
%!assert (cumprod ([1, 2, 3]), [1, 2, 6])
%!assert (cumprod ([-1; -2; -3]), [-1; 2; -6])
%!assert (cumprod ([i, 2+i, -3+2i, 4]), [i, -1+2i, -1-8i, -4-32i])
%!assert (cumprod ([1, 2, 3; i, 2i, 3i; 1+i, 2+2i, 3+3i]),
%!        [1, 2, 3; i, 4i, 9i; -1+i, -8+8i, -27+27i])
 
%!assert (cumprod (single ([1, 2, 3])), single ([1, 2, 6]))
%!assert (cumprod (single ([-1; -2; -3])), single ([-1; 2; -6]))
%!assert (cumprod (single ([i, 2+i, -3+2i, 4])),
%!        single ([i, -1+2i, -1-8i, -4-32i]))
%!assert (cumprod (single ([1, 2, 3; i, 2i, 3i; 1+i, 2+2i, 3+3i])),
%!        single ([1, 2, 3; i, 4i, 9i; -1+i, -8+8i, -27+27i]))
 
%!assert (cumprod ([2, 3; 4, 5], 1), [2, 3; 8, 15])
%!assert (cumprod ([2, 3; 4, 5], 2), [2, 6; 4, 20])
 
%!assert (cumprod (single ([2, 3; 4, 5]), 1), single ([2, 3; 8, 15]))
%!assert (cumprod (single ([2, 3; 4, 5]), 2), single ([2, 6; 4, 20]))
 
%!test
%! x = reshape ([1:8], 2, 2, 2);
%! y = cumprod (x);
%! assert (y(:,:,1), [1, 3; 2, 12]);
%! assert (y(:,:,2), [5, 7; 30, 56]);
%! assert (flip (cumprod (flip (x))), cumprod (x, "reverse"));
%! y = cumprod (x, 2);
%! assert (y(:,:,1), [1, 3; 2, 8]);
%! assert (y(:,:,2), [5, 35; 6, 48]);
%! y = cumprod (x, 2, "reverse");
%! assert (y(:,:,1), [3, 3; 8, 4]);
%! assert (y(:,:,2), [35, 7; 48, 8]);
%! assert (flip (cumprod (flip (x, 2), 2), 2), cumprod (x, 2, "reverse"));
%! y = cumprod (x, [1, 2]);
%! assert (y(:,:,1), [1; 2; 6; 24]);
%! assert (y(:,:,2), [5; 30; 210; 1680]);
%! y = cumprod (x, [1, 3]);
%! assert (y(:,1), [1; 2; 10; 60]);
%! assert (y(:,2), [3; 12; 84; 672]);
%! y = cumprod (x, [2, 3]);
%! assert (y(1,:), [1, 3, 15, 105]);
%! assert (y(2,:), [2, 8, 48, 384]);
%! assert (cumprod (x, [1, 2, 3]), cumprod (x, "all"));
 
## Test exceeding dimensions
%!test
%! x = reshape ([1:8], 2, 2, 2);
%! x(3) = NaN;
%! y = cumprod (x);
%! assert (y(:,:,1), [1, NaN; 2, NaN]);
%! y = cumprod (x, "omitnan");
%! assert (y(:,:,1), [1, 1; 2, 4]);
%! assert (flip (cumprod (flip (x))), cumprod (x, "reverse"));
%! assert (flip (cumprod (flip (x), "omitnan")),
%!         cumprod (x, "reverse", "omitnan"));
%! y = cumprod (x, 2);
%! assert (y(:,:,1), [1, NaN; 2, 8]);
%! y = cumprod (x, 2, "omitnan");
%! assert (y(:,:,1), [1, 1; 2, 8]);
%! y = cumprod (x, 2, "reverse");
%! assert (y(:,:,1), [NaN, NaN; 8, 4]);
%! y = cumprod (x, 2, "reverse", "omitnan");
%! assert (y(:,:,1), [1, 1; 8, 4]);
%! assert (flip (cumprod (flip (x, 3), 3), 3), cumprod (x, 3, "reverse"));
%! assert (flip (cumprod (flip (x, 3), 3, "omitnan"), 3),
%!         cumprod (x, 3, "reverse", "omitnan"));
%! y = cumprod (x, [1, 2]);
%! assert (y(:,:,1), [1; 2; NaN; NaN]);
%! y = cumprod (x, [1, 2], "omitnan");
%! assert (y(:,:,1), [1; 2; 2; 8]);
%! y = cumprod (x, [1, 2], "reverse");
%! assert (y(:,:,1), [NaN; NaN; NaN; 4]);
%! assert (y(:,:,2), [1680; 336; 56; 8]);
%! y = cumprod (x, [1, 2], "reverse", "omitnan");
%! assert (y(:,:,1), [8; 8; 4; 4]);
%! y = cumprod (x, [1, 3]);
%! assert (y(:,1), [1; 2; 10; 60]);
%! assert (y(:,2), nan (4, 1));
%! y = cumprod (x, [1, 3], "omitnan");
%! assert (y(:,2), [1; 4; 28; 224]);
%! y = cumprod (x, [1, 3], "omitnan", "reverse");
%! assert (y(:,1), [60; 60; 30; 6]);
%! assert (y(:,2), [224; 224; 56; 8]);
%! y = cumprod (x, [2, 3], "omitnan");
%! assert (y(1,:), [1, 1, 5, 35]);
%! y = cumprod (x, [2, 3], "omitnan", "reverse");
%! assert (y(1,:), [35, 35, 35, 7]);
%! assert (y(2,:), [384, 192, 48, 8]);
%! assert (cumprod (x, [1, 2, 3]), cumprod (x, "all"));
 
## Test exceeding dimensions
%!test
%! x = reshape ([1:8], 2, 2, 2);
%! assert (cumprod (x, 4), x);
%! assert (cumprod (x, 2), cumprod (x, [2, 4]));
%! assert (cumprod (x, 2, "reverse"), cumprod (x, [2, 4], "reverse"));
%! x(3) = NaN;
%! assert (cumprod (x, 4), x);
%! y = x;
%! y(3) = 1;
%! assert (cumprod (x, 4, "omitnan"), y);
%! assert (cumprod (x, 2, "omitnan"), cumprod (x, [2, 4], "omitnan"));
%! assert (cumprod (x, 2, "reverse", "omitnan"),
%!         cumprod (x, [2, 4], "reverse", "omitnan"));
%!assert (cumprod (sparse ([1, 2; 3, 4]), 3), sparse ([1, 2; 3, 4]))
%!assert (cumprod (sparse ([1, 2i; 3, 4]), 3), sparse ([1, 2i; 3, 4]))
 
%!test
%! x = ones (3);
%! assert (class (cumprod (uint8 (x))), "uint8");
%! assert (cumprod (x), cumprod (x, "omitnan"));
%! assert (class (cumprod (uint16 (x))), "uint16");
%! assert (class (cumprod (uint32 (x))), "uint32");
%! assert (class (cumprod (uint64 (x))), "uint64");
%! assert (class (cumprod (int8 (x))), "int8");
%! assert (class (cumprod (int16 (x))), "int16");
%! assert (class (cumprod (int32 (x))), "int32");
%! assert (class (cumprod (int64 (x))), "int64");
%!assert (class (cumprod ([true, false])), "double")
%!assert (cumprod ([true, false]), [1, 0])
%!assert (cumprod ([true, false], "reverse"), [0, 0])
 
%!assert (cumprod (ones (2), 4), ones (2))
%!assert (cumprod (ones (2), [4, 5]), ones (2))
%!assert (cumprod (single (ones (2)), 4),single (ones (2)))
%!assert (cumprod (single (ones (2)), [4, 5]),single (ones (2)))
 
%!assert (cumprod ([NaN, NaN], "omitnan"), [1, 1])
 
## Test sparse matrices
%!assert (cumprod (sparse ([NaN, NaN, 1, 4, 2; 1, 2, 1, 2, NaN])),
%!        sparse ([NaN, NaN, 1, 4, 2; NaN, NaN, 1, 8, NaN]))
%!assert (cumprod (sparse ([NaN, NaN, 1, 4, 2; 1, 2, 1, 2, NaN]), "omitnan"),
%!        sparse ([1, 1, 1, 4, 2; 1, 2, 1, 8, 2]))
%!assert (cumprod (sparse ([NaN, NaN, 1, 4, 2; 1, 2, 1, 2, NaN]), 2),
%!        sparse ([NaN, NaN, NaN, NaN, NaN; 1, 2, 2, 4, NaN]))
%!assert (cumprod (sparse ([NaN, NaN, 1, 4, 2; 1, 2, 1, 2, NaN]), 2, "omitnan"),
%!        sparse ([1, 1, 1, 4, 8; 1, 2, 2, 4, 4]))
%!assert (cumprod (sparse ([NaN, NaN, 1i, 4, 2; 1, 2, 1, 2, NaN]), 2, "omitnan"),
%!        sparse ([1, 1, 1i, 4i, 8i; 1, 2, 2, 4, 4]))
%!assert (cumprod (sparse ([NaN, 0i, 1, 4, 2; 1, 2, 1, 2, NaN]), 2, "omitnan"),
%!        sparse ([1, 0, 0, 0, 0; 1, 2, 2, 4, 4]))
 
## Test input validation
%!error <Invalid call> cumprod ()
%!error <Invalid call> cumprod (1,2,3)
%!error <unrecognized optional argument 'foobar'> cumprod (1, "foobar")
%!error <cannot set DIM or VECDIM with 'all' flag>
%! cumprod (ones (3,3), 1, "all");
%!error <cannot set DIM or VECDIM with 'all' flag>
%! cumprod (ones (3,3), [1, 2], "all");
%!error <invalid dimension DIM = 0> cumprod (ones (3,3), 0)
%!error <invalid dimension DIM = -1> cumprod (ones (3,3), -1)
%!error <invalid dimension in VECDIM = -2> cumprod (ones (3), [1 -2])
%!error <duplicate dimension in VECDIM = 2> cumprod (ones (3), [1 2 2])
%!error <duplicate dimension in VECDIM = 1> cumprod (ones (3), [1 1 2])
%!error <DIRECTION is not supported for sparse matrices>
%! cumprod (sparse (ones (3,3)), "reverse");
*/
 
DEFUN (cumsum, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{y} =} cumsum (@var{x})
@deftypefnx {} {@var{y} =} cumsum (@var{x}, @var{dim})
@deftypefnx {} {@var{y} =} cumsum (@var{x}, @var{vecdim})
@deftypefnx {} {@var{y} =} cumsum (@dots{}, "all")
@deftypefnx {} {@var{y} =} cumsum (@dots{}, @var{direction})
@deftypefnx {} {@var{y} =} cumsum (@dots{}, @var{nanflag})
Compute the cumulative sum of elements in @var{x}.
 
If @var{x} is a vector, then @code{cumsum (@var{x})} returns a vector of the
same size with the cumulative sum of @var{x}.
 
If @var{x} is a matrix, then @code{cumsum (@var{x})} returns a matrix of the
same size with the cumulative sum along each column of @var{x}.
 
If @var{x} is an array, then @code{cumsum(@var{x})} returns an array of the
same size with the cumulative sum along the first non-singleton dimension of
@var{x}.
 
The class of output @var{y} is the same as the class of input @var{x}, unless
@var{x} is logical, in which case @var{y} is double.
 
The optional input @var{dim} specifies the dimension to operate on and must be
a positive integer.  Specifying any singleton dimension in @var{x}, including
any dimension exceeding @code{ndims (@var{x})}, will return @var{x}.
 
Specifying multiple dimensions with input @var{vecdim}, a vector of
non-repeating dimensions, will operate along the array slice defined by
@var{vecdim}.  If @var{vecdim} indexes all dimensions of @var{x}, then it is
equivalent to the option @qcode{"all"}.  Any dimension in @var{vecdim} greater
than @code{ndims (@var{x})} is ignored.
 
Specifying the dimension as @qcode{"all"} will cause @code{cumsum} to operate
on all elements of @var{x}, and is equivalent to @code{cumsum (@var{x}(:))}.
 
The optional input @var{direction} specifies how the operating dimension is
traversed and can take the following values:
 
@table @asis
@item @qcode{"forward"} (default)
 
The cumulative sum is computed from beginning (index 1) to end along the
operating dimension.
 
@item @qcode{"reverse"}
 
The cumulative sum is computed from end to beginning along the operating
dimension.
@end table
 
The optional variable @var{nanflag} specifies whether to include or exclude
NaN values from the calculation using any of the previously specified input
argument combinations.  The default value for @var{nanflag} is
@qcode{"includenan"} which keeps NaN values in the calculation.  To exclude
NaN values set the value of @var{nanflag} to @qcode{"omitnan"}.  The output
will still contain NaN values if @var{x} consists of all NaN values in the
operating dimension.
@seealso{sum, cumprod}
@end deftypefn */)
{
  int nargin = args.length ();
 
  bool direction = false;
  bool do_perm = false;
  bool allflag = false;
  bool nanflag = false;
 
  while (nargin > 1 && args(nargin - 1).is_string ())
    {
      std::string str = args(nargin - 1).string_value ();
 
      if (str == "forward")
        direction = false;
      else if (str == "reverse")
        direction = true;
      else if (str == "all")
        allflag = true;
      else if (str == "omitnan" || str == "omitmissing")
        {
          if (args(0).is_double_type () || args(0).is_single_type ())
            nanflag = true;
        }
      else if (str == "includenan" || str == "includemissing")
        nanflag = false;
      else
        error ("cumsum: unrecognized optional argument '%s'", str.c_str ());
 
      nargin--;
    }
 
  if (nargin < 1 || nargin > 2)
    print_usage ();
  if (allflag && nargin > 1)
    error ("cumsum: cannot set DIM or VECDIM with 'all' flag");
 
  octave_value arg = args(0);
 
  // Handle DIM, VECDIM
  int dim = -1;
  Array<int> perm_vec;
  if (nargin == 2)
    {
      octave_value dimarg = args(1);
      get_dim_vecdim_all (dimarg, arg, dim, perm_vec, do_perm, allflag, "cumsum");
    }
 
  // Handle allflag
  if (allflag)
    arg = arg.reshape (dim_vector (arg.numel (), 1));
 
  octave_value retval;
 
  switch (arg.builtin_type ())
    {
    case btyp_double:
      if (arg.issparse ())
        {
          if (direction)
            error ("cumsum: DIRECTION is not supported for sparse matrices");
          else
            retval = arg.sparse_matrix_value ().cumsum (dim, nanflag);
        }
      else
        {
          if (direction)
            retval = arg.array_value ().flip (dim).cumsum (dim, nanflag).flip (dim);
          else
            retval = arg.array_value ().cumsum (dim, nanflag);
        }
      break;
 
    case btyp_complex:
      if (arg.issparse ())
        {
          if (direction)
            error ("cumsum: DIRECTION is not supported for sparse matrices");
          else
            retval = arg.sparse_complex_matrix_value ().cumsum (dim, nanflag);
        }
      else
        {
          if (direction)
            retval = arg.complex_array_value ().flip (dim).cumsum (dim, nanflag).flip (dim);
          else
            retval = arg.complex_array_value ().cumsum (dim, nanflag);
        }
      break;
 
    case btyp_float:
      if (direction)
        retval = arg.float_array_value ().flip (dim).cumsum (dim, nanflag).flip (dim);
      else
        retval = arg.float_array_value ().cumsum (dim, nanflag);
      break;
 
    case btyp_float_complex:
      if (direction)
        retval = arg.float_complex_array_value ().flip (dim).cumsum (dim, nanflag).flip (dim);
      else
        retval = arg.float_complex_array_value ().cumsum (dim, nanflag);
      break;
 
#define MAKE_INT_BRANCH(X)                                            \
      case btyp_ ## X:                                                \
        if (direction)                                                \
          retval = arg.X ## _array_value ().flip (dim).cumsum (dim).flip (dim);  \
        else                                                          \
          retval = arg.X ## _array_value ().cumsum (dim);             \
        break;
 
      MAKE_INT_BRANCH (int8);
      MAKE_INT_BRANCH (int16);
      MAKE_INT_BRANCH (int32);
      MAKE_INT_BRANCH (int64);
      MAKE_INT_BRANCH (uint8);
      MAKE_INT_BRANCH (uint16);
      MAKE_INT_BRANCH (uint32);
      MAKE_INT_BRANCH (uint64);
 
#undef MAKE_INT_BRANCH
 
    case btyp_bool:
      if (arg.issparse ())
        {
          if (direction)
            error ("cumsum: DIRECTION is not supported for sparse matrices");
          retval = arg.sparse_matrix_value ().cumsum (dim);
        }
      else
        {
          // OPTIMIZED: Direct boolean cumulative count
          boolNDArray m = arg.bool_array_value ();
 
          if (dim < 0)
            dim = m.dims ().first_non_singleton ();
 
          if (dim >= m.ndims ())
            {
              retval = NDArray (m);
              break;
            }
 
          // Calculate extent triplet (l, n, u) for column-major indexing
          dim_vector dv = m.dims ();
          octave_idx_type l = 1;
          for (int i = 0; i < dim; i++)
            l *= dv(i);
 
          octave_idx_type n = dv(dim);
 
          octave_idx_type u = 1;
          for (int i = dim + 1; i < dv.ndims (); i++)
            u *= dv(i);
 
          NDArray result (dv);
          const bool *data = m.data ();
          double *r = result.rwdata ();
 
          if (direction)
            {
              // Reverse direction
              for (octave_idx_type outer = 0; outer < u; outer++)
                {
                  const octave_idx_type outer_base = outer * n * l;
                  for (octave_idx_type inner = 0; inner < l; inner++)
                    {
                      double cumval = 0.0;
                      octave_idx_type base = outer_base + inner;
 
                      // walk from last to first
                      for (octave_idx_type j = n - 1; j >= 0; j--)
                        {
                          octave_idx_type idx = base + j * l;
                          cumval += data[idx];
                          r[idx] = cumval;
                        }
                    }
                }
            }
          else
            {
              // Forward direction
              for (octave_idx_type outer = 0; outer < u; outer++)
                {
                  const octave_idx_type outer_base = outer * n * l;
                  for (octave_idx_type inner = 0; inner < l; inner++)
                    {
                      double cumval = 0.0;
                      octave_idx_type base = outer_base + inner;
                      for (octave_idx_type j = 0; j < n; j++)
                        {
                          octave_idx_type idx = base + j * l;
                          cumval += data[idx];
                          r[idx] = cumval;
                        }
                    }
                }
            }
 
          retval = result;
        }
      break;
 
    default:
      err_wrong_type_arg ("cumsum", arg);
    }
 
  if (do_perm)
    retval = retval.permute (perm_vec, true);
 
  return retval;
}
 
/*
%!assert (cumsum ([1, 2, 3]), [1, 3, 6])
%!assert (cumsum ([-1; -2; -3]), [-1; -3; -6])
%!assert (cumsum ([i, 2+i, -3+2i, 4]), [i, 2+2i, -1+4i, 3+4i])
%!assert (cumsum ([1, 2, 3; i, 2i, 3i; 1+i, 2+2i, 3+3i]),
%!        [1, 2, 3; 1+i, 2+2i, 3+3i; 2+2i, 4+4i, 6+6i])
 
%!assert (cumsum (single ([1, 2, 3])), single ([1, 3, 6]))
%!assert (cumsum (single ([-1; -2; -3])), single ([-1; -3; -6]))
%!assert (cumsum (single ([i, 2+i, -3+2i, 4])),
%!        single ([i, 2+2i, -1+4i, 3+4i]))
%!assert (cumsum (single ([1, 2, 3; i, 2i, 3i; 1+i, 2+2i, 3+3i])),
%!        single ([1, 2, 3; 1+i, 2+2i, 3+3i; 2+2i, 4+4i, 6+6i]))
 
%!assert (cumsum ([1, 2; 3, 4], 1), [1, 2; 4, 6])
%!assert (cumsum ([1, 2; 3, 4], 2), [1, 3; 3, 7])
 
%!assert (cumsum (single ([1, 2; 3, 4]), 1), single ([1, 2; 4, 6]))
%!assert (cumsum (single ([1, 2; 3, 4]), 2), single ([1, 3; 3, 7]))
 
%!test
%! x = reshape ([1:8], 2, 2, 2);
%! y = cumsum (x);
%! assert (y(:,:,1), [1, 3; 3, 7]);
%! assert (y(:,:,2), [5, 7; 11, 15]);
%! assert (flip (cumsum (flip (x))), cumsum (x, "reverse"));
%! y = cumsum (x, 2);
%! assert (y(:,:,1), [1, 4; 2, 6]);
%! assert (y(:,:,2), [5, 12; 6, 14]);
%! y = cumsum (x, 2, "reverse");
%! assert (y(:,:,1), [4, 3; 6, 4]);
%! assert (y(:,:,2), [12, 7; 14, 8]);
%! assert (flip (cumsum (flip (x, 2), 2), 2), cumsum (x, 2, "reverse"));
%! y = cumsum (x, [1, 2]);
%! assert (y(:,:,1), [1; 3; 6; 10]);
%! assert (y(:,:,2), [5; 11; 18; 26]);
%! y = cumsum (x, [1, 3]);
%! assert (y(:,1), [1; 3; 8; 14]);
%! assert (y(:,2), [3; 7; 14; 22]);
%! y = cumsum (x, [2, 3]);
%! assert (y(1,:), [1, 4, 9, 16]);
%! assert (y(2,:), [2, 6, 12, 20]);
%! assert (cumsum (x, [1, 2, 3]), cumsum (x, "all"));
 
## Test exceeding dimensions
%!test
%! x = reshape ([1:8], 2, 2, 2);
%! x(3) = NaN;
%! y = cumsum (x);
%! assert (y(:,:,1), [1, NaN; 3, NaN]);
%! y = cumsum (x, "omitnan");
%! assert (y(:,:,1), [1, 0; 3, 4]);
%! assert (flip (cumsum (flip (x))), cumsum (x, "reverse"));
%! assert (flip (cumsum (flip (x), "omitnan")),
%!         cumsum (x, "reverse", "omitnan"));
%! y = cumsum (x, 2);
%! assert (y(:,:,1), [1, NaN; 2, 6]);
%! y = cumsum (x, 2, "omitnan");
%! assert (y(:,:,1), [1, 1; 2, 6]);
%! y = cumsum (x, 2, "reverse");
%! assert (y(:,:,1), [NaN, NaN; 6, 4]);
%! y = cumsum (x, 2, "reverse", "omitnan");
%! assert (y(:,:,1), [1, 0; 6, 4]);
%! assert (flip (cumsum (flip (x, 3), 3), 3), cumsum (x, 3, "reverse"));
%! assert (flip (cumsum (flip (x, 3), 3, "omitnan"), 3),
%!         cumsum (x, 3, "reverse", "omitnan"));
%! y = cumsum (x, [1, 2]);
%! assert (y(:,:,1), [1; 3; NaN; NaN]);
%! y = cumsum (x, [1, 2], "omitnan");
%! assert (y(:,:,1), [1; 3; 3; 7]);
%! y = cumsum (x, [1, 2], "reverse");
%! assert (y(:,:,1), [NaN; NaN; NaN; 4]);
%! assert (y(:,:,2), [26; 21; 15; 8]);
%! y = cumsum (x, [1, 2], "reverse", "omitnan");
%! assert (y(:,:,1), [7; 6; 4; 4]);
%! assert (y(:,:,2), [26; 21; 15; 8]);
%! y = cumsum (x, [1, 3]);
%! assert (y(:,1), [1; 3; 8; 14]);
%! assert (y(:,2), nan (4, 1));
%! y = cumsum (x, [1, 3], "omitnan");
%! assert (y(:,2), [0; 4; 11; 19]);
%! y = cumsum (x, [1, 3], "omitnan", "reverse");
%! assert (y(:,1), [14; 13; 11; 6]);
%! assert (y(:,2), [19; 19; 15; 8]);
%! y = cumsum (x, [2, 3], "omitnan");
%! assert (y(1,:), [1, 1, 6, 13]);
%! y = cumsum (x, [2, 3], "omitnan", "reverse");
%! assert (y(1,:), [13, 12, 12, 7]);
%! assert (y(2,:), [20, 18, 14, 8]);
%! assert (cumsum (x, [1, 2, 3]), cumsum (x, "all"));
 
## Test exceeding dimensions
%!test
%! x = reshape ([1:8], 2, 2, 2);
%! assert (cumsum (x, 4), x);
%! assert (cumsum (x, 2), cumsum (x, [2, 4]));
%! assert (cumsum (x, 2, "reverse"), cumsum (x, [2, 4], "reverse"));
%! x(3) = NaN;
%! assert (cumsum (x, 4), x);
%! y = x;
%! y(3) = 0;
%! assert (cumsum (x, 4, "omitnan"), y);
%! assert (cumsum (x, 2, "omitnan"), cumsum (x, [2, 4], "omitnan"));
%! assert (cumsum (x, 2, "reverse", "omitnan"),
%!         cumsum (x, [2, 4], "reverse", "omitnan"));
%!assert (cumsum (sparse ([1, 2; 3, 4]), 3), sparse ([1, 2; 3, 4]))
%!assert (cumsum (sparse ([1, 2i; 3, 4]), 3), sparse ([1, 2i; 3, 4]))
 
%!test
%! x = ones (3);
%! assert (class (cumsum (uint8 (x))), "uint8");
%! assert (cumsum (x), cumsum (x, "omitnan"));
%! assert (class (cumsum (uint16 (x))), "uint16");
%! assert (class (cumsum (uint32 (x))), "uint32");
%! assert (class (cumsum (uint64 (x))), "uint64");
%! assert (class (cumsum (int8 (x))), "int8");
%! assert (class (cumsum (int16 (x))), "int16");
%! assert (class (cumsum (int32 (x))), "int32");
%! assert (class (cumsum (int64 (x))), "int64");
%!assert (class (cumsum ([true, false])), "double")
%!assert (cumsum ([true, false]), [1, 1])
%!assert (cumsum ([true, false], "reverse"), [1, 0])
 
%!assert (cumsum (ones (2), 4), ones (2))
%!assert (cumsum (ones (2), [4, 5]), ones (2))
%!assert (cumsum (single (ones (2)), 4),single (ones (2)))
%!assert (cumsum (single (ones (2)), [4, 5]),single (ones (2)))
 
%!assert (cumsum ([NaN, NaN], "omitnan"), [0, 0])
 
## Test sparse matrices
%!assert (cumsum (sparse ([NaN, NaN, 1, 4, 2; 1, 2, 1, 2, NaN])),
%!        sparse ([NaN, NaN, 1, 4, 2; NaN, NaN, 2, 6, NaN]))
%!assert (cumsum (sparse ([NaN, NaN, 1, 4, 2; 1, 2, 1, 2, NaN]), "omitnan"),
%!        sparse ([0, 0, 1, 4, 2; 1, 2, 2, 6, 2]))
%!assert (cumsum (sparse ([NaN, NaN, 1, 4, 2; 1, 2, 1, 2, NaN]), 2),
%!        sparse ([NaN, NaN, NaN, NaN, NaN; 1, 3, 4, 6, NaN]))
%!assert (cumsum (sparse ([NaN, NaN, 1, 4, 2; 1, 2, 1, 2, NaN]), 2, "omitnan"),
%!        sparse ([0, 0, 1, 5, 7; 1, 3, 4, 6, 6]))
%!assert (cumsum (sparse ([NaN, NaN, 1i, 4, 2; 1, 2, 1, 2, NaN]), 2, "omitnan"),
%!        sparse ([0, 0, 1i, 4+i, 6+i; 1, 3, 4, 6, 6]))
%!assert (cumsum (sparse ([NaN, 0i, 1, 4, 2; 1, 2, 1, 2, NaN]), 2, "omitnan"),
%!        sparse ([0, 0, 1, 5, 7; 1, 3, 4, 6, 6]))
 
## Test input validation
%!error <Invalid call> cumsum ()
%!error <Invalid call> cumsum (1,2,3)
%!error <unrecognized optional argument 'foobar'> cumsum (1, "foobar")
%!error <cannot set DIM or VECDIM with 'all' flag> ...
%!      cumsum (ones (3,3), 1, "all")
%!error <cannot set DIM or VECDIM with 'all' flag> ...
%!      cumsum (ones (3,3), [1, 2], "all")
%!error <invalid dimension DIM = 0> cumsum (ones (3,3), 0)
%!error <invalid dimension DIM = -1> cumsum (ones (3,3), -1)
%!error <invalid dimension in VECDIM = -2> cumsum (ones (3), [1 -2])
%!error <duplicate dimension in VECDIM = 2> cumsum (ones (3), [1 2 2])
%!error <duplicate dimension in VECDIM = 1> cumsum (ones (3), [1 1 2])
%!error <DIRECTION is not supported for sparse matrices> ...
%!      cumsum (sparse (ones (3,3)), "reverse")
*/
 
/* Additional cumsum boolean tests
%!test
%! x = [true, false, true; false, true, false];
%! assert (cumsum (x, 1), [1, 0, 1; 1, 1, 1]);
%! assert (cumsum (x, 2), [1, 1, 2; 0, 1, 1]);
 
%!test
%! x = rand (100, 100) > 0.5;
%! assert (cumsum (x, 2), cumsum (double (x), 2));
*/
 
DEFUN (diag, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{M} =} diag (@var{v})
@deftypefnx {} {@var{M} =} diag (@var{v}, @var{k})
@deftypefnx {} {@var{M} =} diag (@var{v}, @var{m}, @var{n})
@deftypefnx {} {@var{v} =} diag (@var{M})
@deftypefnx {} {@var{v} =} diag (@var{M}, @var{k})
Return a diagonal matrix with vector @var{v} on diagonal @var{k}.
 
The second argument is optional.  If it is positive, the vector is placed on
the @var{k}-th superdiagonal.  If it is negative, it is placed on the
@var{-k}-th subdiagonal.  The default value of @var{k} is 0, and the vector
is placed on the main diagonal.  For example:
 
@example
@group
diag ([1, 2, 3], 1)
   @xresult{}  0  1  0  0
       0  0  2  0
       0  0  0  3
       0  0  0  0
@end group
@end example
 
@noindent
The 3-input form returns a diagonal matrix with vector @var{v} on the main
diagonal and the resulting matrix being of size @var{m} rows x @var{n}
columns.
 
Given a matrix argument, instead of a vector, @code{diag} extracts the
@var{k}-th diagonal of the matrix.
@end deftypefn */)
{
  int nargin = args.length ();
 
  if (nargin < 1 || nargin > 3)
    print_usage ();
 
  octave_value retval;
 
  if (nargin == 1)
    retval = args(0).diag ();
  else if (nargin == 2)
    {
      octave_idx_type k = args(1).strict_idx_type_value ("diag: invalid argument K");
 
      retval = args(0).diag (k);
    }
  else
    {
      octave_value arg0 = args(0);
 
      if (arg0.ndims () != 2 || (arg0.rows () != 1 && arg0.columns () != 1))
        error ("diag: V must be a vector");
 
      octave_idx_type m = args(1).strict_idx_type_value ("diag: invalid dimension M");
      octave_idx_type n = args(2).strict_idx_type_value ("diag: invalid dimension N");
 
      retval = arg0.diag (m, n);
    }
 
  return retval;
}
 
/*
 
%!assert (full (diag ([1; 2; 3])), [1, 0, 0; 0, 2, 0; 0, 0, 3])
%!assert (diag ([1; 2; 3], 1),
%!        [0, 1, 0, 0; 0, 0, 2, 0; 0, 0, 0, 3; 0, 0, 0, 0])
%!assert (diag ([1; 2; 3], 2),
%!        [0 0 1 0 0; 0 0 0 2 0; 0 0 0 0 3; 0 0 0 0 0; 0 0 0 0 0])
%!assert (diag ([1; 2; 3],-1),
%!       [0 0 0 0; 1 0 0 0; 0 2 0 0; 0 0 3 0])
%!assert (diag ([1; 2; 3],-2),
%!        [0 0 0 0 0; 0 0 0 0 0; 1 0 0 0 0; 0 2 0 0 0; 0 0 3 0 0])
 
%!assert (diag ([1, 0, 0; 0, 2, 0; 0, 0, 3]), [1; 2; 3])
%!assert (diag ([0, 1, 0, 0; 0, 0, 2, 0; 0, 0, 0, 3; 0, 0, 0, 0], 1),
%!        [1; 2; 3])
%!assert (diag ([0, 0, 0, 0; 1, 0, 0, 0; 0, 2, 0, 0; 0, 0, 3, 0], -1),
%!        [1; 2; 3])
%!assert (diag (ones (1, 0), 2), zeros (2))
%!assert (diag (1:3, 4, 2), [1, 0; 0, 2; 0, 0; 0, 0])
 
%!assert (full (diag (single ([1; 2; 3]))),
%!        single ([1, 0, 0; 0, 2, 0; 0, 0, 3]))
%!assert (diag (single ([1; 2; 3]), 1),
%!        single ([0, 1, 0, 0; 0, 0, 2, 0; 0, 0, 0, 3; 0, 0, 0, 0]))
%!assert (diag (single ([1; 2; 3]), 2),
%!        single ([0 0 1 0 0; 0 0 0 2 0; 0 0 0 0 3; 0 0 0 0 0; 0 0 0 0 0]))
%!assert (diag (single ([1; 2; 3]),-1),
%!        single ([0, 0, 0, 0; 1, 0, 0, 0; 0, 2, 0, 0; 0, 0, 3, 0]))
%!assert (diag (single ([1; 2; 3]),-2),
%!        single ([0 0 0 0 0; 0 0 0 0 0; 1 0 0 0 0; 0 2 0 0 0; 0 0 3 0 0]))
 
%!assert (diag (single ([1, 0, 0; 0, 2, 0; 0, 0, 3])), single ([1; 2; 3]))
%!assert (diag (single ([0, 1, 0, 0; 0, 0, 2, 0; 0, 0, 0, 3; 0, 0, 0, 0]), 1),
%!        single ([1; 2; 3]))
%!assert (diag (single ([0, 0, 0, 0; 1, 0, 0, 0; 0, 2, 0, 0; 0, 0, 3, 0]), -1),
%!        single ([1; 2; 3]))
 
%!assert (diag (int8 ([1; 2; 3])), int8 ([1, 0, 0; 0, 2, 0; 0, 0, 3]))
%!assert (diag (int8 ([1; 2; 3]), 1),
%!        int8 ([0, 1, 0, 0; 0, 0, 2, 0; 0, 0, 0, 3; 0, 0, 0, 0]))
%!assert (diag (int8 ([1; 2; 3]), 2),
%!        int8 ([0 0 1 0 0; 0 0 0 2 0; 0 0 0 0 3; 0 0 0 0 0; 0 0 0 0 0]))
%!assert (diag (int8 ([1; 2; 3]),-1),
%!        int8 ([0 0 0 0; 1 0 0 0; 0 2 0 0; 0 0 3 0]))
%!assert (diag (int8 ([1; 2; 3]),-2),
%!        int8 ([0 0 0 0 0; 0 0 0 0 0; 1 0 0 0 0; 0 2 0 0 0; 0 0 3 0 0]))
 
%!assert (diag (int8 ([1, 0, 0; 0, 2, 0; 0, 0, 3])), int8 ([1; 2; 3]))
%!assert (diag (int8 ([0, 1, 0, 0; 0, 0, 2, 0; 0, 0, 0, 3; 0, 0, 0, 0]), 1),
%!        int8 ([1; 2; 3]))
%!assert (diag (int8 ([0, 0, 0, 0; 1, 0, 0, 0; 0, 2, 0, 0; 0, 0, 3, 0]), -1),
%!        int8 ([1; 2; 3]))
 
%!assert (diag (1, 3, 3), diag ([1, 0, 0]))
%!assert (diag (i, 3, 3), diag ([i, 0, 0]))
%!assert (diag (single (1), 3, 3), diag ([single(1), 0, 0]))
%!assert (diag (single (i), 3, 3), diag ([single(i), 0, 0]))
%!assert (diag ([1, 2], 3, 3), diag ([1, 2, 0]))
%!assert (diag ([1, 2]*i, 3, 3), diag ([1, 2, 0]*i))
%!assert (diag (single ([1, 2]), 3, 3), diag (single ([1, 2, 0])))
%!assert (diag (single ([1, 2]*i), 3, 3), diag (single ([1, 2, 0]*i)))
 
%!assert <*37411> (diag (diag ([5, 2, 3])(:,1)), diag([5 0 0 ]))
%!assert <*37411> (diag (diag ([5, 2, 3])(:,1), 2),  [0 0 5 0 0; zeros(4, 5)])
%!assert <*37411> (diag (diag ([5, 2, 3])(:,1), -2),
%!                 [[0 0 5 0 0]', zeros(5, 4)])
 
## Test non-square size
%!assert (diag ([1,2,3], 6, 3), [1 0 0; 0 2 0; 0 0 3; 0 0 0; 0 0 0; 0 0 0])
%!assert (diag (1, 2, 3), [1,0,0; 0,0,0])
%!assert (diag ({1}, 2, 3), {1,[],[]; [],[],[]})
%!assert (diag ({1,2}, 3, 4), {1,[],[],[]; [],2,[],[]; [],[],[],[]})
%!assert <*56711> (diag ({1,2,3}, 2, 1), {1; []})
 
## Test out-of-range diagonals
%!assert (diag (ones (3,3), 4), zeros (0, 1))
%!assert (diag (cell (3,3), 4), cell (0, 1))
%!assert (diag (sparse (ones (3,3)), 4), sparse (zeros (0, 1)))
 
## Test input validation
%!error <Invalid call to diag> diag ()
%!error <Invalid call to diag> diag (1,2,3,4)
%!error <V must be a vector> diag (ones (2), 3, 3)
%!error diag (1:3, -4, 3)
%!error diag (1:3, 4, -3)
 
*/
 
DEFUN (prod, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{y} =} prod (@var{x})
@deftypefnx {} {@var{y} =} prod (@var{x}, @var{dim})
@deftypefnx {} {@var{y} =} prod (@var{x}, @var{vecdim})
@deftypefnx {} {@var{y} =} prod (@var{x}, "all")
@deftypefnx {} {@var{y} =} prod (@dots{}, @var{outtype})
@deftypefnx {} {@var{y} =} prod (@dots{}, @var{nanflag})
Compute the product of the elements of @var{x}.
 
If @var{x} is a vector, then @code{prod (@var{x})} returns the product of the
elements in @var{x}.
 
If @var{x} is a matrix, then @code{prod (@var{x})} returns a row vector with
each element containing the product of the corresponding column in @var{x}.
 
If @var{x} is an array, then @code{prod(@var{x})} computes the product along
the first non-singleton dimension of @var{x}.
 
The optional input @var{dim} specifies the dimension to operate on and must be
a positive integer.  Specifying any singleton dimension in @var{x}, including
any dimension exceeding @code{ndims (@var{x})}, will return @var{x}.
 
Specifying multiple dimensions with input @var{vecdim}, a vector of
non-repeating dimensions, will operate along the array slice defined by
@var{vecdim}.  If @var{vecdim} indexes all dimensions of @var{x}, then it is
equivalent to the option @qcode{"all"}.  Any dimension in @var{vecdim} greater
than @code{ndims (@var{x})} is ignored.
 
Specifying the dimension as @qcode{"all"} will cause @code{prod} to operate on
all elements of @var{x}, and is equivalent to @code{prod (@var{x}(:))}.
 
The optional input @var{outtype} specifies the data type that is returned as
well as the class of the variable used for calculations.
@var{outtype} can take the following values:
 
@table @asis
@item @qcode{"default"}
Operations on floating point inputs (double or single) are performed in their
native data type; while operations on integer, logical, and character data
types are performed using doubles.  Output is of type double, unless the input
is single in which case the output is of type single.
 
@item @qcode{"double"}
Operations are performed in double precision even for single precision inputs.
Output is of type double.
 
@item @qcode{"native"}
Operations are performed in their native data types and output is of the same
type as the input as reported by (@code{class (@var{x})}).  When the input is
logical, @code{prod (@var{x}, "native")} is equivalent to @code{all (@var{x})}.
@end table
 
The optional variable @var{nanflag} specifies whether to include or exclude
NaN values from the calculation using any of the previously specified input
argument combinations.  The default value for @var{nanflag} is
@qcode{"includenan"} which keeps NaN values in the calculation.  To exclude
NaN values set the value of @var{nanflag} to @qcode{"omitnan"}.  The output
will be @var{1}, if @var{x} consists of all NaN values in the
operating dimension.
@seealso{cumprod, sum}
@end deftypefn */)
{
  int nargin = args.length ();
 
  bool isnative = false;
  bool isdouble = false;
  bool do_perm = false;
  bool allflag = false;
  bool nanflag = false;
 
  while (nargin > 1 && args(nargin - 1).is_string ())
    {
      std::string str = args(nargin - 1).string_value ();
 
      if (str == "native")
        isnative = true;
      else if (str == "double")
        isdouble = true;
      else if (str == "all")
        allflag = true;
      else if (str == "omitnan" || str == "omitmissing")
        {
          if (args(0).is_double_type () || args(0).is_single_type ())
            nanflag = true;
        }
      else if (str == "includenan" || str == "includemissing")
        nanflag = false;
      else if (str != "default")
        error ("prod: unrecognized optional argument '%s'", str.c_str ());
 
      nargin--;
    }
 
  if (nargin < 1 || nargin > 2)
    print_usage ();
  if (allflag && nargin > 1)
    error ("prod: cannot set DIM or VECDIM with 'all' flag");
 
  octave_value arg = args(0);
 
  // Handle DIM, VECDIM
  int dim = -1;
  Array<int> perm_vec;
  if (nargin == 2)
    {
      octave_value dimarg = args(1);
      get_dim_vecdim_all (dimarg, arg, dim, perm_vec, do_perm, allflag, "prod");
    }
 
  // Handle allflag
  if (allflag)
    arg = arg.reshape (dim_vector (arg.numel (), 1));
 
  octave_value retval;
 
  switch (arg.builtin_type ())
    {
    case btyp_double:
      if (arg.issparse ())
        retval = arg.sparse_matrix_value ().prod (dim, nanflag);
      else
        retval = arg.array_value ().prod (dim, nanflag);
      break;
 
    case btyp_complex:
      if (arg.issparse ())
        retval = arg.sparse_complex_matrix_value ().prod (dim, nanflag);
      else
        retval = arg.complex_array_value ().prod (dim, nanflag);
      break;
 
    case btyp_float:
      if (isdouble)
        retval = arg.float_array_value ().dprod (dim, nanflag);
      else
        retval = arg.float_array_value ().prod (dim, nanflag);
      break;
 
    case btyp_float_complex:
      if (isdouble)
        retval = arg.float_complex_array_value ().dprod (dim, nanflag);
      else
        retval = arg.float_complex_array_value ().prod (dim, nanflag);
      break;
 
#define MAKE_INT_BRANCH(X)                              \
      case btyp_ ## X:                                  \
        if (isnative)                                   \
          retval = arg.X ## _array_value ().prod (dim); \
        else                                            \
          retval = arg.array_value ().prod (dim);       \
        break;
 
      MAKE_INT_BRANCH (int8);
      MAKE_INT_BRANCH (int16);
      MAKE_INT_BRANCH (int32);
      MAKE_INT_BRANCH (int64);
      MAKE_INT_BRANCH (uint8);
      MAKE_INT_BRANCH (uint16);
      MAKE_INT_BRANCH (uint32);
      MAKE_INT_BRANCH (uint64);
 
#undef MAKE_INT_BRANCH
 
    // GAGME: Accursed Matlab compatibility...
    case btyp_char:
      retval = arg.array_value (true).prod (dim);
      break;
 
    case btyp_bool:
      if (arg.issparse ())
        {
          if (isnative)
            retval = arg.sparse_bool_matrix_value ().all (dim);
          else
            retval = arg.sparse_matrix_value ().prod (dim);
        }
      else if (isnative)
        retval = arg.bool_array_value ().all (dim);
      else
        retval = NDArray (arg.bool_array_value ().all (dim));
      break;
 
    default:
      err_wrong_type_arg ("prod", arg);
    }
 
  if (do_perm)
    retval = retval.permute (perm_vec, true);
 
  return retval;
}
 
/*
%!assert (prod ([1, 2, 3]), 6)
%!assert (prod ([-1; -2; -3]), -6)
%!assert (prod ([i, 2+i, -3+2i, 4]), -4 - 32i)
%!assert (prod ([1, 2, 3; i, 2i, 3i; 1+i, 2+2i, 3+3i]), [-1+i, -8+8i, -27+27i])
 
%!assert (prod (single ([1, 2, 3])), single (6))
%!assert (prod (single ([-1; -2; -3])), single (-6))
%!assert (prod (single ([i, 2+i, -3+2i, 4])), single (-4 - 32i))
%!assert (prod (single ([1, 2, 3; i, 2i, 3i; 1+i, 2+2i, 3+3i])),
%!        single ([-1+i, -8+8i, -27+27i]))
 
## Test sparse
%!assert (prod (sparse ([1, 2, 3])), sparse (6))
%!assert (prod (sparse ([-1; -2; -3])), sparse (-6))
## Commented out until bug #42290 is fixed
#%!assert (prod (sparse ([i, 2+i, -3+2i, 4])), sparse (-4 - 32i))
#%!assert (prod (sparse ([1, 2, 3; i, 2i, 3i; 1+i, 2+2i, 3+3i])),
#%!         sparse ([-1+i, -8+8i, -27+27i]))
 
%!assert (prod ([1, 2; 3, 4], 1), [3, 8])
%!assert (prod ([1, 2; 3, 4], 2), [2; 12])
%!assert (prod (single ([1, 2; 3, 4]), 1), single ([3, 8]))
%!assert (prod (single ([1, 2; 3, 4]), 2), single ([2; 12]))
 
## Test empty matrices
%!assert (prod ([]), 1)
%!assert (prod ([], 1), zeros (1, 0))
%!assert (prod ([], 2), zeros (0, 1))
%!assert (prod ([], 3), zeros (0, 0))
%!assert (prod (zeros (1, 0)), 1)
%!assert (prod (zeros (1, 0), 1), zeros (1, 0))
%!assert (prod (zeros (1, 0), 2), 1)
%!assert (prod (zeros (0, 1)), 1)
%!assert (prod (zeros (0, 1), 1), 1)
%!assert (prod (zeros (0, 1), 2), zeros (0, 1))
%!assert (prod (zeros (2, 0)), zeros (1, 0))
%!assert (prod (zeros (2, 0), 1), zeros (1, 0))
%!assert (prod (zeros (2, 0), 2), [1; 1])
%!assert (prod (zeros (0, 2)), [1, 1])
%!assert (prod (zeros (0, 2), 1), [1, 1])
%!assert (prod (zeros (0, 2), 2), zeros (0, 1))
 
%!assert (prod (single ([])), single (1))
%!assert (prod (single ([]), 1), single (zeros (1, 0)))
%!assert (prod (single ([]), 2), single (zeros (0, 1)))
%!assert (prod (single ([]), 3), single (zeros (0, 0)))
%!assert (prod (zeros (1, 0, "single")), single (1))
%!assert (prod (zeros (1, 0, "single"), 1), zeros (1, 0, "single"))
%!assert (prod (zeros (1, 0, "single"), 2), single (1))
%!assert (prod (zeros (0, 1, "single")), single (1))
%!assert (prod (zeros (0, 1, "single"), 1), single (1))
%!assert (prod (zeros (0, 1, "single"), 2), zeros (0, 1, "single"))
%!assert (prod (zeros (2, 0, "single")), zeros (1, 0, "single"))
%!assert (prod (zeros (2, 0, "single"), 1), zeros (1, 0, "single"))
%!assert (prod (zeros (2, 0, "single"), 2), single ([1; 1]))
%!assert (prod (zeros (0, 2, "single")), single ([1, 1]))
%!assert (prod (zeros (0, 2, "single"), 1), single ([1, 1]))
%!assert (prod (zeros (0, 2, "single"), 2), zeros (0, 1, "single"))
 
## Test "double" type argument
%!assert (prod (single ([1, 2, 3]), "double"), 6)
%!assert (prod (single ([-1; -2; -3]), "double"), -6)
%!assert (prod (single ([i, 2+i, -3+2i, 4]), "double"), -4 - 32i)
%!assert (prod (single ([1, 2, 3; i, 2i, 3i; 1+i, 2+2i, 3+3i]), "double"),
%!        [-1+i, -8+8i, -27+27i])
 
## Test "native" type argument
%!assert (prod (uint8 ([1, 2, 3]), "native"), uint8 (6))
%!assert (prod (uint8 ([-1; -2; -3]), "native"), uint8 (0))
%!assert (prod (int8 ([1, 2, 3]), "native"), int8 (6))
%!assert (prod (int8 ([-1; -2; -3]), "native"), int8 (-6))
%!assert (prod ([true false; true true], "native"), [true false])
%!assert (prod ([true false; true true], 2, "native"), [false; true])
 
## Test "default"
%!assert (prod (single (1)), prod (single (1), "default"))
%!assert (prod ([true true], "default"), double (1))
%!assert (prod (uint8 (1), "default"), double (1))
 
## Test character arrays
%!assert (prod (["aa";"aa"])', prod (["aa";"aa"], 2))
%!assert (prod ("aa"), sum ("a") * sum ("a"))
%!assert (prod ("a", 3), 97)
%!assert (prod (["a";"a"], 3), [97; 97])
%!assert (prod (["a";"a"], [1, 3]), sum ("a") * sum ("a"))
%!assert (prod (["a";"a"], [2, 3]), [97; 97])
 
## Test dimension indexing with vecdim in N-dimensional arrays
%!test
%! x = repmat ([1:20;6:25], [5 2 6 3]);
%! assert (size (prod (x, [3 2])), [10 1 1 3]);
%! assert (size (prod (x, [1 2])), [1 1 6 3]);
%! assert (size (prod (x, [1 2 4])), [1 1 6]);
%! assert (size (prod (x, [1 4 3])), [1 40]);
%! assert (size (prod (x, [1 2 3 4])), [1 1]);
 
## Test exceeding dimensions
%!assert (prod (ones (2,2), 3), ones (2,2))
%!assert (prod (ones (2,2,2), 99), ones (2,2,2))
%!assert (prod (magic (3), 3), magic (3))
%!assert (prod (magic (3), [1 3]), prod (magic (3)))
%!assert (prod (magic (3), [2 99]), prod (magic (3), 2))
%!assert (prod (ones (2), 4), ones (2))
%!assert (prod (ones (2), [4, 5]), ones (2))
%!assert (prod (single (ones (2)), 4),single (ones (2)))
%!assert (prod (single (ones (2)), [4, 5]),single (ones (2)))
%!assert (prod (sparse ([1, 2; 3, 4]), 3), sparse ([1, 2; 3, 4]))
%!assert (prod (sparse ([1, 2i; 3, 4]), 3), sparse ([1, 2i; 3, 4]))
 
## Test nanflag
%!test
%! x = ones (3,4,5);
%! x(1) = NaN;
%! assert (prod (x)(:,:,1), [NaN, 1, 1, 1]);
%! assert (prod (x, "includenan")(:,:,1), [NaN, 1, 1, 1]);
%! assert (prod (x, "omitnan")(:,:,1), [1, 1, 1, 1]);
%! assert (prod (x, "omitmissing")(:,:,1), [1, 1, 1, 1]);
%! assert (prod (x, [2 3]), [NaN; 1; 1]);
%! assert (prod (x, [2 3], "omitnan"), [1; 1; 1]);
 
## Test cases for "omitnan"
%!test
%! A = [2, NaN; 3, NaN; 4, NaN];
%! assert (prod (A, 2, "omitnan"), [2; 3; 4]);
%!test
%! A = [NaN, NaN, NaN];
%! assert (prod (A, "omitnan"), 1);
%!test
%! A = [2, 3, NaN; 4, 5, NaN; 1, 2, NaN];
%! assert (prod (A, 2, "omitnan"), [6; 20; 2]);
%!test
%! A = [2, NaN, 3; 3, NaN, 2; 2, NaN, 4];
%! assert (prod (A, 1, "omitnan"), [12, 1, 24]);
%!test
%! A = [1+i, NaN; 2+2i, NaN];
%! assert (prod (A, 2, "omitnan"), [1+i; 2+2i]);
%!test
%! A = single ([NaN, NaN, NaN]);
%! assert (prod (A, "omitnan"), single (1));
 
## Test sparse matrices
%!assert (prod (sparse ([NaN, NaN, 1, 4, 2; 1, 2, 1, 2, NaN])),
%!        sparse ([NaN, NaN, 1, 8, NaN]))
%!assert (prod (sparse ([NaN, NaN, 1, 4, 2; 1, 2, 1, 2, NaN]), "omitnan"),
%!        sparse ([1, 2, 1, 8, 2]))
%!assert (prod (sparse ([NaN, NaN, 1, 4, 2; 1, 2, 1, 2, NaN]), 2),
%!        sparse ([NaN; NaN]))
%!assert (prod (sparse ([NaN, NaN, 1, 4, 2; 1, 2, 1, 2, NaN]), 2, "omitnan"),
%!        sparse ([8; 4]))
%!assert (prod (sparse ([NaN, NaN, 1i, 4, 2; 1, 2, 1, 2, NaN]), 2, "omitnan"),
%!        sparse ([8i; 4]))
%!assert (prod (sparse ([NaN, 0i, 1i, 4, 2; 1, 2, 1, 2, NaN]), 2, "omitnan"),
%!        sparse ([0; 4]))
%!assert (prod (sparse ([NaN, 1+i, 1i, 4, 2; 1, 2, 1, 2, NaN]), 2, "omitnan"),
%!        sparse ([-8+8i; 4]))
%!assert (prod (sparse ([NaN, NaN, NaN])), sparse (NaN))
%!assert (prod (sparse ([0, 0, 0, NaN, NaN, NaN])), sparse (NaN))
%!assert (prod (sparse ([NaN, NaN, NaN]), "omitnan"), sparse (1))
%!assert (prod (sparse ([0, 0, 0, NaN, NaN, NaN]), "omitnan"), sparse (0))
 
## Test empty sparse matrices
%!assert (prod (sparse (ones(1, 0))), sparse (1))
%!assert (size (prod (sparse (ones(1, 0)), 1)), [1, 0])
%!assert (size (prod (sparse (ones(1, 0)), 2)), [1, 1])
%!assert (prod (sparse (ones(0, 1))), sparse (1))
%!assert (size (prod (sparse (ones(0, 1)), 1)), [1, 1])
%!assert (size (prod (sparse (ones(0, 1)), 1)), [1, 1])
%!assert (size (prod (sparse (ones(0, 1)), 2)), [0, 1])
%!assert (prod (sparse (ones(0, 0))), sparse (1))
%!assert (size (prod (sparse (ones(0, 0)), 1)), [1, 0])
%!assert (size (prod (sparse (ones(0, 0)), 2)), [0, 1])
%!assert (size (prod (sparse (ones(0, 0)), 3)), [0, 0])
 
## Test input validation
%!error <Invalid call> prod ()
%!error <Invalid call> prod (1,2,3)
%!error <unrecognized optional argument 'foobar'> prod (1, "foobar")
%!error <cannot set DIM or VECDIM with 'all' flag>
%! prod (ones (3,3), 1, "all");
%!error <cannot set DIM or VECDIM with 'all' flag>
%! prod (ones (3,3), [1, 2], "all");
%!error <invalid dimension DIM = 0> prod (ones (3,3), 0)
%!error <invalid dimension DIM = -1> prod (ones (3,3), -1)
%!error <invalid dimension in VECDIM = -2> prod (ones (3,3), [1 -2])
%!error <duplicate dimension in VECDIM = 2> prod (ones (3,3), [1 2 2])
%!error <duplicate dimension in VECDIM = 1> prod (ones (3,3), [1 1 2])
*/
 
static bool
all_scalar_1x1 (const octave_value_list& args)
{
  int n_args = args.length ();
  for (int i = 0; i < n_args; i++)
    if (args(i).numel () != 1)
      return false;
 
  return true;
}
 
template <typename TYPE, typename T>
static void
single_type_concat (Array<T>& result,
                    const octave_value_list& args,
                    int dim)
{
  int n_args = args.length ();
  if (! (equal_types<T, char>::value
         || equal_types<T, octave_value>::value)
      && all_scalar_1x1 (args))
    {
      // Optimize all scalars case.
      dim_vector dv (1, 1);
      if (dim == -1 || dim == -2)
        dim = -dim - 1;
      else if (dim >= 2)
        dv.resize (dim+1, 1);
      dv(dim) = n_args;
 
      result.clear (dv);
 
      for (int j = 0; j < n_args; j++)
        {
          octave_quit ();
 
          result(j) = octave_value_extract<T> (args(j));
        }
    }
  else
    {
      OCTAVE_LOCAL_BUFFER (Array<T>, array_list, n_args);
 
      for (int j = 0; j < n_args; j++)
        {
          octave_quit ();
 
          array_list[j] = octave_value_extract<TYPE> (args(j));
        }
 
      result = Array<T>::cat (dim, n_args, array_list);
    }
}
 
template <typename TYPE, typename T>
static void
single_type_concat (Sparse<T>& result,
                    const octave_value_list& args,
                    int dim)
{
  octave_idx_type n_args = args.length ();
  OCTAVE_LOCAL_BUFFER (Sparse<T>, sparse_list, n_args);
 
  for (octave_idx_type j = 0; j < n_args; j++)
    {
      octave_quit ();
 
      sparse_list[j] = octave_value_extract<TYPE> (args(j));
    }
 
  result = Sparse<T>::cat (dim, n_args, sparse_list);
}
 
// Dispatcher.
template <typename TYPE>
static TYPE
do_single_type_concat (const octave_value_list& args, int dim)
{
  TYPE result;
 
  single_type_concat<TYPE, typename TYPE::element_type> (result, args, dim);
 
  return result;
}
 
template <typename MAP>
static void
single_type_concat_map (octave_map& result,
                        const octave_value_list& args,
                        int dim)
{
  int n_args = args.length ();
  OCTAVE_LOCAL_BUFFER (MAP, map_list, n_args);
 
  for (int j = 0; j < n_args; j++)
    {
      octave_quit ();
 
      map_list[j] = octave_value_extract<MAP> (args(j));
    }
 
  result = octave_map::cat (dim, n_args, map_list);
}
 
static octave_map
do_single_type_concat_map (const octave_value_list& args,
                           int dim)
{
  octave_map result;
  if (all_scalar_1x1 (args)) // optimize all scalars case.
    single_type_concat_map<octave_scalar_map> (result, args, dim);
  else
    single_type_concat_map<octave_map> (result, args, dim);
 
  return result;
}
 
static octave_value
do_single_type_concat_cdef (const octave_value_list& args, int dim)
{
  // Concatenate a list of octave_classdef values of the same
  // class along dimension dim
 
  Array<cdef_object> arr;
  int n_args = args.length ();
 
  if (all_scalar_1x1 (args))
    {
      // Optimize all scalars case.
      dim_vector dv (1, 1);
      if (dim == -1 || dim == -2)
        dim = -dim - 1;
      else if (dim >= 2)
        dv.resize (dim+1, 1);
      dv(dim) = n_args;
 
      arr.clear (dv);
 
      for (int j = 0; j < n_args; j++)
        {
          octave_quit ();
 
          arr(j) = args(j).classdef_object_value ()->get_object ();
        }
    }
  else
    {
      OCTAVE_LOCAL_BUFFER (Array<cdef_object>, array_list, n_args);
 
      for (int j = 0; j < n_args; j++)
        {
          octave_quit ();
 
          cdef_object obj = args(j).classdef_object_value ()->get_object ();
          if (obj.is_array ())
            array_list[j] = obj.array_value ();
          else
            array_list[j] = Array<cdef_object> (dim_vector (1,1), obj);
        }
 
      arr = Array<cdef_object>::cat (dim, n_args, array_list);
    }
 
  cdef_object obj_result = cdef_object (new cdef_object_array (arr));
  obj_result.set_class (arr(0).get_class ());
 
  return to_ov (obj_result);
}
 
static octave_value
attempt_type_conversion (const octave_value& ov, std::string dtype)
{
  octave_value retval;
 
  // First try to find function in the class of OV that can convert to
  // the dispatch type dtype.  It will have the name of the dispatch
  // type.
 
  std::string cname = ov.class_name ();
 
  interpreter& interp = __get_interpreter__ ();
 
  symbol_table& symtab = interp.get_symbol_table ();
 
  cdef_manager& cdef_mgr = interp.get_cdef_manager ();
 
  auto fcn = cdef_mgr.find_method_symbol (dtype, cname);
  if (! fcn.is_defined ())
    fcn = symtab.find_method (dtype, cname);
 
  if (fcn.is_defined ())
    {
      octave_value_list result;
 
      try
        {
          result = interp.feval (fcn, ovl (ov), 1);
        }
      catch (execution_exception& ee)
        {
          error (ee, "conversion from %s to %s failed", dtype.c_str (),
                 cname.c_str ());
        }
 
      if (result.empty ())
        error ("conversion from %s to %s failed", dtype.c_str (),
               cname.c_str ());
 
      retval = result(0);
    }
  else
    {
      // No conversion function available.  Try the constructor for the
      // dispatch type.
      // We can't go purely through the symbol table here, we have to
      // check the classdef manager as well for classdef methods
      auto ctor = cdef_mgr.find_method_symbol (dtype, dtype);
 
      if (! ctor.is_defined ())
        ctor = symtab.find_method (dtype, dtype);
 
      octave_value_list result;
 
      // The following code looks fairly ugly because we have to handle
      // old-style classes and classdef constructors separately
      if (ctor.is_defined () && ctor.is_function ())
        {
          octave_function *ctor_fcn = ctor.function_value ();
 
            if (ctor_fcn->is_legacy_constructor ())
              {
                // Old-style class constructor
                octave::unwind_protect frame;
 
                octave::interpreter_try (frame);
 
                try
                  {
                   result = interp.feval (ctor, ovl (ov), 1);
                  }
                catch (const octave::execution_exception&)
                  {
                    interp.recover_from_exception ();
                  }
              }
            else
              // Classdef constructor
              {
                auto cls = lookup_class (dtype, false, false);
 
                try
                  {
                    result = to_ov (cls.construct_object (ovl (ov)));
                  }
                catch (execution_exception& ee)
                  {
                    error (ee, "%s constructor failed for %s argument",
                           dtype.c_str (), cname.c_str ());
                  }
 
              }
        }
 
       retval = result(0);
    }
 
  return retval;
}
 
octave_value
do_class_concat (const octave_value_list& ovl,
                 const std::string& cattype, int dim)
{
  octave_value retval;
 
  // Get dominant type for list
 
  std::string dtype = get_dispatch_type (ovl);
 
  interpreter& interp = __get_interpreter__ ();
 
  cdef_manager& cdef_mgr = __get_cdef_manager__ ();
 
  symbol_table& symtab = interp.get_symbol_table ();
 
  octave_value ov_fcn = symtab.find_method (cattype, dtype);
 
  if (ov_fcn.is_defined ())
    {
      // Have method for dominant type.  Call it and let it handle conversions.
 
      octave_value_list tmp2;
 
      try
        {
          tmp2 = interp.feval (ov_fcn, ovl, 1);
        }
      catch (execution_exception& ee)
        {
          error (ee, "cat: %s/%s method failed", dtype.c_str (), cattype.c_str ());
        }
 
      if (tmp2.empty ())
        error ("cat: %s/%s method did not return a value", dtype.c_str (),
               cattype.c_str ());
 
      retval = tmp2(0);
    }
  else
    {
      // No method for dominant type, so attempt type conversions for
      // all elements that are not of the dominant type, then do the
      // default operation for octave_class values.
 
      octave_idx_type j = 0;
      octave_idx_type len = ovl.length ();
      octave_value_list tmp (len, octave_value ());
      for (octave_idx_type k = 0; k < len; k++)
        {
          octave_value elt = ovl(k);
 
          std::string t1_type = elt.class_name ();
 
          if (t1_type == dtype)
            tmp(j++) = elt;
          else if (elt.isobject () || ! elt.isempty ())
            {
              auto ov = attempt_type_conversion (elt, dtype);
              // Abort concatenation if type cannot be converted
              if ( ! ov.is_defined ())
                error ("cat: cannot convert from type \"%s\" to type \"%s\"",
                       t1_type.c_str (), dtype.c_str ());
              tmp(j++) = ov;
            }
        }
 
      tmp.resize (j);
 
      // See if dominant type is a classdef
      cdef_class cdef = cdef_mgr.find_class (dtype, false);
 
      if (cdef.ok ())
        // Default classdef concat
        retval = do_single_type_concat_cdef (tmp, dim);
      else
        {
          // Default struct-based class concat
          octave_map m = do_single_type_concat_map (tmp, dim);
 
          std::string cname = tmp(0).class_name ();
          std::list<std::string> parents = tmp(0).parent_class_name_list ();
 
          retval = octave_value (new octave_class (m, cname, parents));
        }
    }
 
  return retval;
}
 
static octave_value
do_cat (const octave_value_list& xargs, int dim, std::string fname)
{
  octave_value retval;
 
  // We may need to convert elements of the list to cells, so make a copy.
  // This should be efficient, it is done mostly by incrementing reference
  // counts.
  octave_value_list args = xargs;
 
  int n_args = args.length ();
 
  if (n_args == 0)
    retval = Matrix ();
  else if (n_args == 1)
    retval = args(0);
  else if (n_args > 1)
    {
      std::string result_type;
 
      bool all_strings_p = true;
      bool all_sq_strings_p = true;
      bool all_dq_strings_p = true;
      bool all_real_p = true;
      bool all_cmplx_p = true;
      bool any_sparse_p = false;
      bool any_cell_p = false;
      bool any_class_p = false;
 
      bool first_elem_is_struct = false;
 
      for (int i = 0; i < n_args; i++)
        {
          if (i == 0)
            {
              result_type = args(i).class_name ();
 
              first_elem_is_struct = args(i).isstruct ();
            }
          else
            result_type = get_concat_class (result_type, args(i).class_name ());
 
          if (all_strings_p && ! args(i).is_string ())
            all_strings_p = false;
          if (all_sq_strings_p && ! args(i).is_sq_string ())
            all_sq_strings_p = false;
          if (all_dq_strings_p && ! args(i).is_dq_string ())
            all_dq_strings_p = false;
          if (all_real_p && ! args(i).isreal ())
            all_real_p = false;
          if (all_cmplx_p && ! (args(i).iscomplex ()
                                || args(i).isreal ()))
            all_cmplx_p = false;
          if (! any_sparse_p && args(i).issparse ())
            any_sparse_p = true;
          if (! any_cell_p && args(i).iscell ())
            any_cell_p = true;
          if (! any_class_p && args(i).isobject ())
            any_class_p = true;
        }
 
      if (any_cell_p && ! any_class_p && ! first_elem_is_struct)
        {
          int j = 0;
          for (int i = 0; i < n_args; i++)
            {
              if (args(i).iscell ())
                args(j++) = args(i);
              else
                {
                  if (args(i).isempty ())
                    continue;  // Delete empty non-cell arg
                  else
                    args(j++) = Cell (args(i));
                }
            }
          n_args = j;
          args.resize (n_args);
        }
 
      if (any_class_p)
        retval = do_class_concat (args, fname, dim);
      else if (result_type == "double")
        {
          if (any_sparse_p)
            {
              if (all_real_p)
                retval = do_single_type_concat<SparseMatrix> (args, dim);
              else
                retval = do_single_type_concat<SparseComplexMatrix> (args, dim);
            }
          else
            {
              if (all_real_p)
                retval = do_single_type_concat<NDArray> (args, dim);
              else
                retval = do_single_type_concat<ComplexNDArray> (args, dim);
            }
        }
      else if (result_type == "single")
        {
          if (all_real_p)
            retval = do_single_type_concat<FloatNDArray> (args, dim);
          else
            retval = do_single_type_concat<FloatComplexNDArray> (args, dim);
        }
      else if (result_type == "char")
        {
          char type = (all_dq_strings_p ? '"' : '\'');
 
          if (! all_strings_p)
            warn_implicit_conversion ("Octave:num-to-str",
                                      "numeric", result_type);
          else
            maybe_warn_string_concat (all_dq_strings_p, all_sq_strings_p);
 
          charNDArray result = do_single_type_concat<charNDArray> (args, dim);
 
          retval = octave_value (result, type);
        }
      else if (result_type == "logical")
        {
          if (any_sparse_p)
            retval = do_single_type_concat<SparseBoolMatrix> (args, dim);
          else
            retval = do_single_type_concat<boolNDArray> (args, dim);
        }
      else if (result_type == "int8")
        retval = do_single_type_concat<int8NDArray> (args, dim);
      else if (result_type == "int16")
        retval = do_single_type_concat<int16NDArray> (args, dim);
      else if (result_type == "int32")
        retval = do_single_type_concat<int32NDArray> (args, dim);
      else if (result_type == "int64")
        retval = do_single_type_concat<int64NDArray> (args, dim);
      else if (result_type == "uint8")
        retval = do_single_type_concat<uint8NDArray> (args, dim);
      else if (result_type == "uint16")
        retval = do_single_type_concat<uint16NDArray> (args, dim);
      else if (result_type == "uint32")
        retval = do_single_type_concat<uint32NDArray> (args, dim);
      else if (result_type == "uint64")
        retval = do_single_type_concat<uint64NDArray> (args, dim);
      else if (result_type == "cell")
        retval = do_single_type_concat<Cell> (args, dim);
      else if (result_type == "struct")
        retval = do_single_type_concat_map (args, dim);
      else
        {
          dim_vector dv = args(0).dims ();
 
          // Default concatenation.
          bool (dim_vector::*concat_rule) (const dim_vector&, int)
            = &dim_vector::concat;
 
          if (dim == -1 || dim == -2)
            {
              concat_rule = &dim_vector::hvcat;
              dim = -dim - 1;
            }
 
          for (int i = 1; i < args.length (); i++)
            {
              if (! (dv.*concat_rule) (args(i).dims (), dim))
                error ("cat: dimension mismatch");
            }
 
          // The lines below might seem crazy, since we take a copy
          // of the first argument, resize it to be empty and then resize
          // it to be full.  This is done since it means that there is no
          // recopying of data, as would happen if we used a single resize.
          // It should be noted that resize operation is also significantly
          // slower than the do_cat_op function, so it makes sense to have
          // an empty matrix and copy all data.
          //
          // We might also start with a empty octave_value using
          //
          //   tmp = type_info::lookup_type (args(1).type_name());
          //
          // and then directly resize.  However, for some types there might
          // be some additional setup needed, and so this should be avoided.
 
          octave_value tmp = args(0);
          tmp = tmp.resize (dim_vector (0, 0)).resize (dv);
 
          int dv_len = dv.ndims ();
          Array<octave_idx_type> ra_idx (dim_vector (dv_len, 1), 0);
 
          for (int j = 0; j < n_args; j++)
            {
              // Can't fast return here to skip empty matrices as something
              // like cat (1,[],single ([])) must return an empty matrix of
              // the right type.
              tmp = cat_op (tmp, args(j), ra_idx);
 
              const dim_vector& dv_tmp = args(j).dims ();
 
              if (dim >= dv_len)
                {
                  if (j > 1)
                    error ("%s: indexing error", fname.c_str ());
 
                  break;
                }
              else
                ra_idx(dim) += (dim < dv_tmp.ndims () ? dv_tmp(dim) : 1);
            }
          retval = tmp;
        }
    }
  else
    print_usage ();
 
  return retval;
}
 
DEFUN (horzcat, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{A} =} horzcat (@var{array1}, @var{array2}, @dots{}, @var{arrayN})
Return the horizontal concatenation of N-D array objects, @var{array1},
@var{array2}, @dots{}, @var{arrayN} along dimension 2.
 
Arrays may also be concatenated horizontally using the syntax for creating
new matrices.  For example:
 
@example
@var{A} = [ @var{array1}, @var{array2}, @dots{} ]
@end example
 
This syntax is slightly more efficient because the Octave parser can
concatenate the arrays without the overhead of a function call.
@seealso{cat, vertcat}
@end deftypefn */)
{
  return do_cat (args, -2, "horzcat");
}
 
/*
## Test concatenation with all zero matrices
%!test
%! warning ("off", "Octave:num-to-str", "local");
%! assert (horzcat ("", 65* ones (1,10)), "AAAAAAAAAA");
%! assert (horzcat (65* ones (1,10), ""), "AAAAAAAAAA");
 
%!assert (class (horzcat (int64 (1), int64 (1))), "int64")
%!assert (class (horzcat (int64 (1), int32 (1))), "int64")
%!assert (class (horzcat (int64 (1), int16 (1))), "int64")
%!assert (class (horzcat (int64 (1), int8 (1))), "int64")
%!assert (class (horzcat (int64 (1), uint64 (1))), "int64")
%!assert (class (horzcat (int64 (1), uint32 (1))), "int64")
%!assert (class (horzcat (int64 (1), uint16 (1))), "int64")
%!assert (class (horzcat (int64 (1), uint8 (1))), "int64")
%!assert (class (horzcat (int64 (1), single (1))), "int64")
%!assert (class (horzcat (int64 (1), double (1))), "int64")
%!assert (class (horzcat (int64 (1), cell (1))), "cell")
%!assert (class (horzcat (int64 (1), true)), "int64")
%!test
%! warning ("off", "Octave:num-to-str", "local");
%! assert (class (horzcat (int64 (1), "a")), "char");
 
%!assert (class (horzcat (int32 (1), int64 (1))), "int32")
%!assert (class (horzcat (int32 (1), int32 (1))), "int32")
%!assert (class (horzcat (int32 (1), int16 (1))), "int32")
%!assert (class (horzcat (int32 (1), int8 (1))), "int32")
%!assert (class (horzcat (int32 (1), uint64 (1))), "int32")
%!assert (class (horzcat (int32 (1), uint32 (1))), "int32")
%!assert (class (horzcat (int32 (1), uint16 (1))), "int32")
%!assert (class (horzcat (int32 (1), uint8 (1))), "int32")
%!assert (class (horzcat (int32 (1), single (1))), "int32")
%!assert (class (horzcat (int32 (1), double (1))), "int32")
%!assert (class (horzcat (int32 (1), cell (1))), "cell")
%!assert (class (horzcat (int32 (1), true)), "int32")
%!test
%! warning ("off", "Octave:num-to-str", "local");
%! assert (class (horzcat (int32 (1), "a")), "char");
 
%!assert (class (horzcat (int16 (1), int64 (1))), "int16")
%!assert (class (horzcat (int16 (1), int32 (1))), "int16")
%!assert (class (horzcat (int16 (1), int16 (1))), "int16")
%!assert (class (horzcat (int16 (1), int8 (1))), "int16")
%!assert (class (horzcat (int16 (1), uint64 (1))), "int16")
%!assert (class (horzcat (int16 (1), uint32 (1))), "int16")
%!assert (class (horzcat (int16 (1), uint16 (1))), "int16")
%!assert (class (horzcat (int16 (1), uint8 (1))), "int16")
%!assert (class (horzcat (int16 (1), single (1))), "int16")
%!assert (class (horzcat (int16 (1), double (1))), "int16")
%!assert (class (horzcat (int16 (1), cell (1))), "cell")
%!assert (class (horzcat (int16 (1), true)), "int16")
%!test
%! warning ("off", "Octave:num-to-str", "local");
%! assert (class (horzcat (int16 (1), "a")), "char");
 
%!assert (class (horzcat (int8 (1), int64 (1))), "int8")
%!assert (class (horzcat (int8 (1), int32 (1))), "int8")
%!assert (class (horzcat (int8 (1), int16 (1))), "int8")
%!assert (class (horzcat (int8 (1), int8 (1))), "int8")
%!assert (class (horzcat (int8 (1), uint64 (1))), "int8")
%!assert (class (horzcat (int8 (1), uint32 (1))), "int8")
%!assert (class (horzcat (int8 (1), uint16 (1))), "int8")
%!assert (class (horzcat (int8 (1), uint8 (1))), "int8")
%!assert (class (horzcat (int8 (1), single (1))), "int8")
%!assert (class (horzcat (int8 (1), double (1))), "int8")
%!assert (class (horzcat (int8 (1), cell (1))), "cell")
%!assert (class (horzcat (int8 (1), true)), "int8")
%!test
%! warning ("off", "Octave:num-to-str", "local");
%! assert (class (horzcat (int8 (1), "a")), "char");
 
%!assert (class (horzcat (uint64 (1), int64 (1))), "uint64")
%!assert (class (horzcat (uint64 (1), int32 (1))), "uint64")
%!assert (class (horzcat (uint64 (1), int16 (1))), "uint64")
%!assert (class (horzcat (uint64 (1), int8 (1))), "uint64")
%!assert (class (horzcat (uint64 (1), uint64 (1))), "uint64")
%!assert (class (horzcat (uint64 (1), uint32 (1))), "uint64")
%!assert (class (horzcat (uint64 (1), uint16 (1))), "uint64")
%!assert (class (horzcat (uint64 (1), uint8 (1))), "uint64")
%!assert (class (horzcat (uint64 (1), single (1))), "uint64")
%!assert (class (horzcat (uint64 (1), double (1))), "uint64")
%!assert (class (horzcat (uint64 (1), cell (1))), "cell")
%!assert (class (horzcat (uint64 (1), true)), "uint64")
%!test
%! warning ("off", "Octave:num-to-str", "local");
%! assert (class (horzcat (uint64 (1), "a")), "char");
 
%!assert (class (horzcat (uint32 (1), int64 (1))), "uint32")
%!assert (class (horzcat (uint32 (1), int32 (1))), "uint32")
%!assert (class (horzcat (uint32 (1), int16 (1))), "uint32")
%!assert (class (horzcat (uint32 (1), int8 (1))), "uint32")
%!assert (class (horzcat (uint32 (1), uint64 (1))), "uint32")
%!assert (class (horzcat (uint32 (1), uint32 (1))), "uint32")
%!assert (class (horzcat (uint32 (1), uint16 (1))), "uint32")
%!assert (class (horzcat (uint32 (1), uint8 (1))), "uint32")
%!assert (class (horzcat (uint32 (1), single (1))), "uint32")
%!assert (class (horzcat (uint32 (1), double (1))), "uint32")
%!assert (class (horzcat (uint32 (1), cell (1))), "cell")
%!assert (class (horzcat (uint32 (1), true)), "uint32")
%!test
%! warning ("off", "Octave:num-to-str", "local");
%! assert (class (horzcat (uint32 (1), "a")), "char");
 
%!assert (class (horzcat (uint16 (1), int64 (1))), "uint16")
%!assert (class (horzcat (uint16 (1), int32 (1))), "uint16")
%!assert (class (horzcat (uint16 (1), int16 (1))), "uint16")
%!assert (class (horzcat (uint16 (1), int8 (1))), "uint16")
%!assert (class (horzcat (uint16 (1), uint64 (1))), "uint16")
%!assert (class (horzcat (uint16 (1), uint32 (1))), "uint16")
%!assert (class (horzcat (uint16 (1), uint16 (1))), "uint16")
%!assert (class (horzcat (uint16 (1), uint8 (1))), "uint16")
%!assert (class (horzcat (uint16 (1), single (1))), "uint16")
%!assert (class (horzcat (uint16 (1), double (1))), "uint16")
%!assert (class (horzcat (uint16 (1), cell (1))), "cell")
%!assert (class (horzcat (uint16 (1), true)), "uint16")
%!test
%! warning ("off", "Octave:num-to-str", "local");
%! assert (class (horzcat (uint16 (1), "a")), "char");
 
%!assert (class (horzcat (uint8 (1), int64 (1))), "uint8")
%!assert (class (horzcat (uint8 (1), int32 (1))), "uint8")
%!assert (class (horzcat (uint8 (1), int16 (1))), "uint8")
%!assert (class (horzcat (uint8 (1), int8 (1))), "uint8")
%!assert (class (horzcat (uint8 (1), uint64 (1))), "uint8")
%!assert (class (horzcat (uint8 (1), uint32 (1))), "uint8")
%!assert (class (horzcat (uint8 (1), uint16 (1))), "uint8")
%!assert (class (horzcat (uint8 (1), uint8 (1))), "uint8")
%!assert (class (horzcat (uint8 (1), single (1))), "uint8")
%!assert (class (horzcat (uint8 (1), double (1))), "uint8")
%!assert (class (horzcat (uint8 (1), cell (1))), "cell")
%!assert (class (horzcat (uint8 (1), true)), "uint8")
%!test
%! warning ("off", "Octave:num-to-str", "local");
%! assert (class (horzcat (uint8 (1), "a")), "char");
 
%!assert (class (horzcat (single (1), int64 (1))), "int64")
%!assert (class (horzcat (single (1), int32 (1))), "int32")
%!assert (class (horzcat (single (1), int16 (1))), "int16")
%!assert (class (horzcat (single (1), int8 (1))), "int8")
%!assert (class (horzcat (single (1), uint64 (1))), "uint64")
%!assert (class (horzcat (single (1), uint32 (1))), "uint32")
%!assert (class (horzcat (single (1), uint16 (1))), "uint16")
%!assert (class (horzcat (single (1), uint8 (1))), "uint8")
%!assert (class (horzcat (single (1), single (1))), "single")
%!assert (class (horzcat (single (1), double (1))), "single")
%!assert (class (horzcat (single (1), cell (1))), "cell")
%!assert (class (horzcat (single (1), true)), "single")
%!test
%! warning ("off", "Octave:num-to-str", "local");
%! assert (class (horzcat (single (1), "a")), "char");
 
%!assert (class (horzcat (double (1), int64 (1))), "int64")
%!assert (class (horzcat (double (1), int32 (1))), "int32")
%!assert (class (horzcat (double (1), int16 (1))), "int16")
%!assert (class (horzcat (double (1), int8 (1))), "int8")
%!assert (class (horzcat (double (1), uint64 (1))), "uint64")
%!assert (class (horzcat (double (1), uint32 (1))), "uint32")
%!assert (class (horzcat (double (1), uint16 (1))), "uint16")
%!assert (class (horzcat (double (1), uint8 (1))), "uint8")
%!assert (class (horzcat (double (1), single (1))), "single")
%!assert (class (horzcat (double (1), double (1))), "double")
%!assert (class (horzcat (double (1), cell (1))), "cell")
%!assert (class (horzcat (double (1), true)), "double")
%!test
%! warning ("off", "Octave:num-to-str", "local");
%! assert (class (horzcat (double (1), "a")), "char");
 
%!assert (class (horzcat (cell (1), int64 (1))), "cell")
%!assert (class (horzcat (cell (1), int32 (1))), "cell")
%!assert (class (horzcat (cell (1), int16 (1))), "cell")
%!assert (class (horzcat (cell (1), int8 (1))), "cell")
%!assert (class (horzcat (cell (1), uint64 (1))), "cell")
%!assert (class (horzcat (cell (1), uint32 (1))), "cell")
%!assert (class (horzcat (cell (1), uint16 (1))), "cell")
%!assert (class (horzcat (cell (1), uint8 (1))), "cell")
%!assert (class (horzcat (cell (1), single (1))), "cell")
%!assert (class (horzcat (cell (1), double (1))), "cell")
%!assert (class (horzcat (cell (1), cell (1))), "cell")
%!assert (class (horzcat (cell (1), true)), "cell")
%!assert (class (horzcat (cell (1), "a")), "cell")
 
%!assert (class (horzcat (true, int64 (1))), "int64")
%!assert (class (horzcat (true, int32 (1))), "int32")
%!assert (class (horzcat (true, int16 (1))), "int16")
%!assert (class (horzcat (true, int8 (1))), "int8")
%!assert (class (horzcat (true, uint64 (1))), "uint64")
%!assert (class (horzcat (true, uint32 (1))), "uint32")
%!assert (class (horzcat (true, uint16 (1))), "uint16")
%!assert (class (horzcat (true, uint8 (1))), "uint8")
%!assert (class (horzcat (true, single (1))), "single")
%!assert (class (horzcat (true, double (1))), "double")
%!assert (class (horzcat (true, cell (1))), "cell")
%!assert (class (horzcat (true, true)), "logical")
%!test
%! warning ("off", "Octave:num-to-str", "local");
%! assert (class (horzcat (true, "a")), "char");
 
%!test
%! warning ("off", "Octave:num-to-str", "local");
%! assert (class (horzcat ("a", int64 (1))), "char");
%! assert (class (horzcat ("a", int32 (1))), "char");
%! assert (class (horzcat ("a", int16 (1))), "char");
%! assert (class (horzcat ("a", int8 (1))), "char");
%! assert (class (horzcat ("a", int64 (1))), "char");
%! assert (class (horzcat ("a", int32 (1))), "char");
%! assert (class (horzcat ("a", int16 (1))), "char");
%! assert (class (horzcat ("a", int8 (1))), "char");
%! assert (class (horzcat ("a", single (1))), "char");
%! assert (class (horzcat ("a", double (1))), "char");
%! assert (class (horzcat ("a", cell (1))), "cell");
%! assert (class (horzcat ("a", true)), "char");
%! assert (class (horzcat ("a", "a")), "char");
 
%!assert (class (horzcat (cell (1), struct ("foo", "bar"))), "cell")
 
%!error horzcat (struct ("foo", "bar"), cell (1))
 
%!test <*39041> assert (class (horzcat (cell (0), struct ())), "cell")
%!test <51086> assert (class (horzcat (struct (), cell (0))), "struct")
*/
 
DEFUN (vertcat, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{A} =} vertcat (@var{array1}, @var{array2}, @dots{}, @var{arrayN})
Return the vertical concatenation of N-D array objects, @var{array1},
@var{array2}, @dots{}, @var{arrayN} along dimension 1.
 
Arrays may also be concatenated vertically using the syntax for creating
new matrices.  For example:
 
@example
@var{A} = [ @var{array1}; @var{array2}; @dots{} ]
@end example
 
This syntax is slightly more efficient because the Octave parser can
concatenate the arrays without the overhead of a function call.
@seealso{cat, horzcat}
@end deftypefn */)
{
  return do_cat (args, -1, "vertcat");
}
 
/*
%!test
%! c = {"foo"; "bar"; "bazoloa"};
%! assert (vertcat (c, "a", "bc", "def"),
%!         {"foo"; "bar"; "bazoloa"; "a"; "bc"; "def"});
*/
 
DEFUN (cat, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{A} =} cat (@var{dim}, @var{array1}, @var{array2}, @dots{}, @var{arrayN})
Return the concatenation of N-D array objects, @var{array1}, @var{array2},
@dots{}, @var{arrayN} along dimension @var{dim}.
 
@example
@group
A = ones (2, 2);
B = zeros (2, 2);
cat (2, A, B)
  @xresult{} 1 1 0 0
     1 1 0 0
@end group
@end example
 
Alternatively, we can concatenate @var{A} and @var{B} along the second
dimension in the following way:
 
@example
@group
[A, B]
@end group
@end example
 
@var{dim} can be larger than the dimensions of the N-D array objects and the
result will thus have @var{dim} dimensions as the following example shows:
 
@example
@group
cat (4, ones (2, 2), zeros (2, 2))
  @xresult{} ans(:,:,1,1) =
 
       1 1
       1 1
 
     ans(:,:,1,2) =
 
       0 0
       0 0
@end group
@end example
@seealso{horzcat, vertcat}
@end deftypefn */)
{
  if (args.length () == 0)
    print_usage ();
 
  int dim = args(0).strict_int_value ("cat: DIM must be an integer") - 1;
 
  if (dim < 0)
    error ("cat: DIM must be a valid dimension");
 
  return ovl (do_cat (args.slice (1, args.length () - 1), dim, "cat"));
}
 
/*
%!function ret = __testcat (t1, t2, tr, cmplx)
%!  assert (cat (1, cast ([], t1), cast ([], t2)), cast ([], tr));
%!
%!  assert (cat (1, cast (1, t1), cast (2, t2)), cast ([1; 2], tr));
%!  assert (cat (1, cast (1, t1), cast ([2; 3], t2)), cast ([1; 2; 3], tr));
%!  assert (cat (1, cast ([1; 2], t1), cast (3, t2)), cast ([1; 2; 3], tr));
%!  assert (cat (1, cast ([1; 2], t1), cast ([3; 4], t2)),
%!          cast ([1; 2; 3; 4], tr));
%!  assert (cat (2, cast (1, t1), cast (2, t2)), cast ([1, 2], tr));
%!  assert (cat (2, cast (1, t1), cast ([2, 3], t2)), cast ([1, 2, 3], tr));
%!  assert (cat (2, cast ([1, 2], t1), cast (3, t2)), cast ([1, 2, 3], tr));
%!  assert (cat (2, cast ([1, 2], t1), cast ([3, 4], t2)),
%!          cast ([1, 2, 3, 4], tr));
%!
%!  assert ([cast(1, t1); cast(2, t2)], cast ([1; 2], tr));
%!  assert ([cast(1, t1); cast([2; 3], t2)], cast ([1; 2; 3], tr));
%!  assert ([cast([1; 2], t1); cast(3, t2)], cast ([1; 2; 3], tr));
%!  assert ([cast([1; 2], t1); cast([3; 4], t2)], cast ([1; 2; 3; 4], tr));
%!  assert ([cast(1, t1), cast(2, t2)], cast ([1, 2], tr));
%!  assert ([cast(1, t1), cast([2, 3], t2)], cast ([1, 2, 3], tr));
%!  assert ([cast([1, 2], t1), cast(3, t2)], cast ([1, 2, 3], tr));
%!  assert ([cast([1, 2], t1), cast([3, 4], t2)], cast ([1, 2, 3, 4], tr));
%!
%!  if (nargin == 3 || cmplx)
%!    assert (cat (1, cast (1i, t1), cast (2, t2)), cast ([1i; 2], tr));
%!    assert (cat (1, cast (1i, t1), cast ([2; 3], t2)), cast ([1i; 2; 3], tr));
%!    assert (cat (1, cast ([1i; 2], t1), cast (3, t2)), cast ([1i; 2; 3], tr));
%!    assert (cat (1, cast ([1i; 2], t1), cast ([3; 4], t2)),
%!            cast ([1i; 2; 3; 4], tr));
%!    assert (cat (2, cast (1i, t1), cast (2, t2)), cast ([1i, 2], tr));
%!    assert (cat (2, cast (1i, t1), cast ([2, 3], t2)), cast ([1i, 2, 3], tr));
%!    assert (cat (2, cast ([1i, 2], t1), cast (3, t2)), cast ([1i, 2, 3], tr));
%!    assert (cat (2, cast ([1i, 2], t1), cast ([3, 4], t2)),
%!            cast ([1i, 2, 3, 4], tr));
%!    assert ([cast(1i, t1); cast(2, t2)], cast ([1i; 2], tr));
%!    assert ([cast(1i, t1); cast([2; 3], t2)], cast ([1i; 2; 3], tr));
%!    assert ([cast([1i; 2], t1); cast(3, t2)], cast ([1i; 2; 3], tr));
%!    assert ([cast([1i; 2], t1); cast([3; 4], t2)], cast ([1i; 2; 3; 4], tr));
%!    assert ([cast(1i, t1), cast(2, t2)], cast ([1i, 2], tr));
%!    assert ([cast(1i, t1), cast([2, 3], t2)], cast ([1i, 2, 3], tr));
%!    assert ([cast([1i, 2], t1), cast(3, t2)], cast ([1i, 2, 3], tr));
%!    assert ([cast([1i, 2], t1), cast([3, 4], t2)], cast ([1i, 2, 3, 4], tr));
%!
%!    assert (cat (1, cast (1, t1), cast (2i, t2)), cast ([1; 2i], tr));
%!    assert (cat (1, cast (1, t1), cast ([2i; 3], t2)), cast ([1; 2i; 3], tr));
%!    assert (cat (1, cast ([1; 2], t1), cast (3i, t2)), cast ([1; 2; 3i], tr));
%!    assert (cat (1, cast ([1; 2], t1), cast ([3i; 4], t2)),
%!            cast ([1; 2; 3i; 4], tr));
%!    assert (cat (2, cast (1, t1), cast (2i, t2)), cast ([1, 2i], tr));
%!    assert (cat (2, cast (1, t1), cast ([2i, 3], t2)), cast ([1, 2i, 3], tr));
%!    assert (cat (2, cast ([1, 2], t1), cast (3i, t2)), cast ([1, 2, 3i], tr));
%!    assert (cat (2, cast ([1, 2], t1), cast ([3i, 4], t2)),
%!            cast ([1, 2, 3i, 4], tr));
%!    assert ([cast(1, t1); cast(2i, t2)], cast ([1; 2i], tr));
%!    assert ([cast(1, t1); cast([2i; 3], t2)], cast ([1; 2i; 3], tr));
%!    assert ([cast([1; 2], t1); cast(3i, t2)], cast ([1; 2; 3i], tr));
%!    assert ([cast([1; 2], t1); cast([3i; 4], t2)], cast ([1; 2; 3i; 4], tr));
%!    assert ([cast(1, t1), cast(2i, t2)], cast ([1, 2i], tr));
%!    assert ([cast(1, t1), cast([2i, 3], t2)], cast ([1, 2i, 3], tr));
%!    assert ([cast([1, 2], t1), cast(3i, t2)], cast ([1, 2, 3i], tr));
%!    assert ([cast([1, 2], t1), cast([3i, 4], t2)], cast ([1, 2, 3i, 4], tr));
%!
%!    assert (cat (1, cast (1i, t1), cast (2i, t2)), cast ([1i; 2i], tr));
%!    assert (cat (1, cast (1i, t1), cast ([2i; 3], t2)),
%!            cast ([1i; 2i; 3], tr));
%!    assert (cat (1, cast ([1i; 2], t1), cast (3i, t2)),
%!            cast ([1i; 2; 3i], tr));
%!    assert (cat (1, cast ([1i; 2], t1), cast ([3i; 4], t2)),
%!            cast ([1i; 2; 3i; 4], tr));
%!    assert (cat (2, cast (1i, t1), cast (2i, t2)), cast ([1i, 2i], tr));
%!    assert (cat (2, cast (1i, t1), cast ([2i, 3], t2)),
%!            cast ([1i, 2i, 3], tr));
%!    assert (cat (2, cast ([1i, 2], t1), cast (3i, t2)),
%!            cast ([1i, 2, 3i], tr));
%!    assert (cat (2, cast ([1i, 2], t1), cast ([3i, 4], t2)),
%!            cast ([1i, 2, 3i, 4], tr));
%!
%!    assert ([cast(1i, t1); cast(2i, t2)], cast ([1i; 2i], tr));
%!    assert ([cast(1i, t1); cast([2i; 3], t2)], cast ([1i; 2i; 3], tr));
%!    assert ([cast([1i; 2], t1); cast(3i, t2)], cast ([1i; 2; 3i], tr));
%!    assert ([cast([1i; 2], t1); cast([3i; 4], t2)],
%!            cast ([1i; 2; 3i; 4], tr));
%!    assert ([cast(1i, t1), cast(2i, t2)], cast ([1i, 2i], tr));
%!    assert ([cast(1i, t1), cast([2i, 3], t2)], cast ([1i, 2i, 3], tr));
%!    assert ([cast([1i, 2], t1), cast(3i, t2)], cast ([1i, 2, 3i], tr));
%!    assert ([cast([1i, 2], t1), cast([3i, 4], t2)],
%!            cast ([1i, 2, 3i, 4], tr));
%!  endif
%!  ret = true;
%!endfunction
 
%!assert (__testcat ("double", "double", "double"))
%!assert (__testcat ("single", "double", "single"))
%!assert (__testcat ("double", "single", "single"))
%!assert (__testcat ("single", "single", "single"))
 
%!assert (__testcat ("double", "int8", "int8", false))
%!assert (__testcat ("int8", "double", "int8", false))
%!assert (__testcat ("single", "int8", "int8", false))
%!assert (__testcat ("int8", "single", "int8", false))
%!assert (__testcat ("int8", "int8", "int8", false))
%!assert (__testcat ("double", "int16", "int16", false))
%!assert (__testcat ("int16", "double", "int16", false))
%!assert (__testcat ("single", "int16", "int16", false))
%!assert (__testcat ("int16", "single", "int16", false))
%!assert (__testcat ("int16", "int16", "int16", false))
%!assert (__testcat ("double", "int32", "int32", false))
%!assert (__testcat ("int32", "double", "int32", false))
%!assert (__testcat ("single", "int32", "int32", false))
%!assert (__testcat ("int32", "single", "int32", false))
%!assert (__testcat ("int32", "int32", "int32", false))
%!assert (__testcat ("double", "int64", "int64", false))
%!assert (__testcat ("int64", "double", "int64", false))
%!assert (__testcat ("single", "int64", "int64", false))
%!assert (__testcat ("int64", "single", "int64", false))
%!assert (__testcat ("int64", "int64", "int64", false))
 
%!assert (__testcat ("double", "uint8", "uint8", false))
%!assert (__testcat ("uint8", "double", "uint8", false))
%!assert (__testcat ("single", "uint8", "uint8", false))
%!assert (__testcat ("uint8", "single", "uint8", false))
%!assert (__testcat ("uint8", "uint8", "uint8", false))
%!assert (__testcat ("double", "uint16", "uint16", false))
%!assert (__testcat ("uint16", "double", "uint16", false))
%!assert (__testcat ("single", "uint16", "uint16", false))
%!assert (__testcat ("uint16", "single", "uint16", false))
%!assert (__testcat ("uint16", "uint16", "uint16", false))
%!assert (__testcat ("double", "uint32", "uint32", false))
%!assert (__testcat ("uint32", "double", "uint32", false))
%!assert (__testcat ("single", "uint32", "uint32", false))
%!assert (__testcat ("uint32", "single", "uint32", false))
%!assert (__testcat ("uint32", "uint32", "uint32", false))
%!assert (__testcat ("double", "uint64", "uint64", false))
%!assert (__testcat ("uint64", "double", "uint64", false))
%!assert (__testcat ("single", "uint64", "uint64", false))
%!assert (__testcat ("uint64", "single", "uint64", false))
%!assert (__testcat ("uint64", "uint64", "uint64", false))
 
%!assert (cat (3, [], [1,2;3,4]), [1,2;3,4])
%!assert (cat (3, [1,2;3,4], []), [1,2;3,4])
%!assert (cat (3, [], [1,2;3,4], []), [1,2;3,4])
%!assert (cat (3, [], [], []), zeros (0, 0, 3))
 
%!assert (cat (3, [], [], 1, 2), cat (3, 1, 2))
%!assert (cat (3, [], [], [1,2;3,4]), [1,2;3,4])
%!assert (cat (4, [], [], [1,2;3,4]), [1,2;3,4])
 
%!assert ([zeros(3,2,2); ones(1,2,2)], repmat ([0;0;0;1],[1,2,2]))
%!assert ([zeros(3,2,2); ones(1,2,2)], vertcat (zeros (3,2,2), ones (1,2,2)))
 
%!test <*49759>
%! A = [];
%! B = {1; 2};
%! assert (cat (1, A, B), {1; 2});
%! assert (cat (2, A, B), {1; 2});
 
%!error <dimension mismatch> cat (3, cat (3, [], []), [1,2;3,4])
%!error <dimension mismatch> cat (3, zeros (0, 0, 2), [1,2;3,4])
*/
 
static octave_value
do_permute (const octave_value_list& args, bool inv)
{
  if (args.length () != 2 || args(1).length () < args(1).ndims ())
    print_usage ();
 
  Array<int> vec = args(1).int_vector_value ();
 
  // FIXME: maybe we should create an idx_vector object here
  //        and pass that to permute?
  int n = vec.numel ();
  for (int i = 0; i < n; i++)
    vec(i)--;
 
  return octave_value (args(0).permute (vec, inv));
}
 
DEFUN (permute, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{B} =} permute (@var{A}, @var{perm})
Return the generalized transpose for an N-D array object @var{A}.
 
The permutation vector @var{perm} must contain the elements
@w{@code{1:ndims (A)}}@ (in any order, but each element must appear only
once).  The @var{N}th dimension of @var{A} gets remapped to dimension
@code{@var{PERM}(@var{N})}.  For example:
 
@example
@group
@var{x} = zeros ([2, 3, 5, 7]);
size (@var{x})
   @xresult{}  2   3   5   7
 
size (permute (@var{x}, [2, 1, 3, 4]))
   @xresult{}  3   2   5   7
 
size (permute (@var{x}, [1, 3, 4, 2]))
   @xresult{}  2   5   7   3
 
## The identity permutation
size (permute (@var{x}, [1, 2, 3, 4]))
   @xresult{}  2   3   5   7
@end group
@end example
@seealso{ipermute}
@end deftypefn */)
{
  return do_permute (args, false);
}
 
DEFUN (ipermute, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{A} =} ipermute (@var{B}, @var{iperm})
The inverse of the @code{permute} function.
 
The expression
 
@example
ipermute (permute (A, perm), perm)
@end example
 
@noindent
returns the original array @var{A}.
@seealso{permute}
@end deftypefn */)
{
  return do_permute (args, true);
}
 
DEFUN (length, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{n} =} length (@var{A})
Return the length of the object @var{A}.
 
The length is 0 for empty objects, 1 for scalars, and the number of elements
for vectors.  For matrix or N-dimensional objects, the length is the number
of elements along the largest dimension
(equivalent to @w{@code{max (size (@var{A}))}}).
@seealso{numel, size}
@end deftypefn */)
{
  if (args.length () != 1)
    print_usage ();
 
  return ovl (args(0).length ());
}
 
DEFUN (ndims, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{n} =} ndims (@var{A})
Return the number of dimensions of @var{A}.
 
For any array, the result will always be greater than or equal to 2.
Trailing singleton dimensions are not counted, i.e., trailing dimensions
@var{d} greater than 2 for which @code{size (@var{A}, @var{d}) = 1}.
 
@example
@group
ndims (ones (4, 1, 2, 1))
    @xresult{} 3
@end group
@end example
@seealso{size}
@end deftypefn */)
{
  if (args.length () != 1)
    print_usage ();
 
  // This function *must* use size() to determine the desired values to be
  // compatible with Matlab and to allow user-defined class overloading.
  Matrix sz = octave_value (args(0)).size ();
 
  octave_idx_type ndims = sz.numel ();
 
  // Don't count trailing ones.  Trailing zeros are *not* singleton dimension.
  while ((ndims > 2) && (sz(ndims - 1) == 1))
    ndims--;
 
  return ovl (ndims);
}
 
/*
%!assert (ndims (1:5), 2)
%!assert (ndims (ones (4, 1, 2, 1)), 3)
%!assert (ndims (ones (4, 1, 2, 0)), 4)
*/
 
DEFUN (numel, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{n} =} numel (@var{A})
@deftypefnx {} {@var{n} =} numel (@var{A}, @var{idx1}, @var{idx2}, @dots{})
Return the number of elements in the object @var{A}.
 
Optionally, if indices @var{idx1}, @var{idx2}, @dots{} are supplied,
return the number of elements that would result from the indexing
 
@example
@var{A}(@var{idx1}, @var{idx2}, @dots{})
@end example
 
Note that the indices do not have to be scalar numbers.  For example,
 
@example
@group
@var{a} = 1;
@var{b} = ones (2, 3);
numel (@var{a}, @var{b})
@end group
@end example
 
@noindent
will return 6, as this is the number of ways to index with @var{b}.
Or the index could be the string @qcode{":"} which represents the colon
operator.  For example,
 
@example
@group
@var{A} = ones (5, 3);
numel (@var{A}, 2, ":")
@end group
@end example
 
@noindent
will return 3 as the second row has three column entries.
 
This method is also called when an object appears as lvalue with cs-list
indexing, i.e., @code{object@{@dots{}@}} or @code{object(@dots{}).field}.
@seealso{size, length, ndims}
@end deftypefn */)
{
  int nargin = args.length ();
 
  if (nargin == 0)
    print_usage ();
 
  octave_value retval;
 
  if (nargin == 1)
    retval = args(0).numel ();
  else if (nargin > 1)
    {
      // Don't use numel (const octave_value_list&) here as that corresponds to
      // an overloaded call, not to builtin!
      retval = dims_to_numel (args(0).dims (), args.slice (1, nargin-1));
    }
 
  return retval;
}
 
DEFUN (size, args, nargout,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{sz} =} size (@var{A})
@deftypefnx {} {@var{dim_sz} =} size (@var{A}, @var{dim})
@deftypefnx {} {@var{dim_sz} =} size (@var{A}, @var{d1}, @var{d2}, @dots{})
@deftypefnx {} {[@var{rows}, @var{cols}, @dots{}, @var{dim_N_sz}] =} size (@dots{})
Return a row vector with the size (number of elements) of each dimension for
the object @var{A}.
 
When given a second argument, @var{dim}, return the size of the corresponding
dimension.  If @var{dim} is a vector, return each of the corresponding
dimensions.  Multiple dimensions may also be specified as separate arguments.
 
With a single output argument, @code{size} returns a row vector.  When called
with multiple output arguments, @code{size} returns the size of dimension N
in the Nth argument.  The number of rows, dimension 1, is returned in the
first argument, the number of columns, dimension 2, is returned in the
second argument, etc.  If there are more dimensions in @var{A} than there are
output arguments, @code{size} returns the total number of elements in the
remaining dimensions in the final output argument.  If the requested dimension
@var{dim} is greater than the number of dimensions in @var{A}, @code{size}
returns 1 (not 0).
 
Example 1: single row vector output
 
@example
@group
size ([1, 2; 3, 4; 5, 6])
   @xresult{} [ 3, 2 ]
@end group
@end example
 
Example 2: number of elements in 2nd dimension (columns)
 
@example
@group
size ([1, 2; 3, 4; 5, 6], 2)
    @xresult{} 2
@end group
@end example
 
Example 3: number of output arguments == number of dimensions
 
@example
@group
[nr, nc] = size ([1, 2; 3, 4; 5, 6])
    @xresult{} nr = 3
    @xresult{} nc = 2
@end group
@end example
 
Example 4: number of output arguments < number of dimensions
 
@example
@group
[nr, remainder] = size (ones (2, 3, 4, 5))
    @xresult{} nr = 2
    @xresult{} remainder = 60
@end group
@end example
 
Example 5: number of elements in dimension > number of actual dimensions
 
@example
@group
sz4 = size (ones (2, 3), 4)
    @xresult{} sz4 = 1
@end group
@end example
 
@seealso{numel, ndims, length, rows, columns, size_equal, common_size}
@end deftypefn */)
{
  int nargin = args.length ();
 
  if (nargin == 0)
    print_usage ();
 
  // For compatibility with Matlab, size returns dimensions as doubles.
 
  Matrix m;
 
  dim_vector dimensions = args(0).dims ();
  int ndims = dimensions.ndims ();
 
  if (nargin == 1)
    {
      if (nargout > 1)
        {
          dimensions = dimensions.redim (nargout);
          ndims = dimensions.ndims ();
        }
 
      m.resize (1, ndims);
 
      for (octave_idx_type i = 0; i < ndims; i++)
        m(i) = dimensions(i);
    }
  else
    {
      Array<octave_idx_type> query_dims;
 
      if (nargin > 2)
        {
          query_dims.resize (dim_vector (1, nargin-1));
 
          for (octave_idx_type i = 0; i < nargin-1; i++)
            query_dims(i) = args(i+1).idx_type_value (true);
        }
      else
        query_dims = args(1).octave_idx_type_vector_value (true);
 
      if (nargout > 1 && nargout != query_dims.numel ())
        error ("size: nargout > 1 but does not match number of requested dimensions");
 
      octave_idx_type nidx = query_dims.numel ();
 
      m.resize (1, nidx);
 
      for (octave_idx_type i = 0; i < nidx; i++)
        {
          octave_idx_type nd = query_dims.xelem (i);
 
          if (nd < 1)
            error ("size: requested dimension DIM (= %"
                   OCTAVE_IDX_TYPE_FORMAT ") out of range", nd);
 
          m(i) = nd <= ndims ? dimensions (nd-1) : 1;
        }
    }
 
  if (nargout > 1)
    {
      octave_value_list retval (nargout);
 
      for (octave_idx_type i = 0; i < nargout; i++)
        retval(i) = m(i);
 
      return retval;
    }
 
  return ovl (m);
}
 
/*
## Plain call
 
%!assert (size ([1, 2; 3, 4; 5, 6]), [3, 2])
 
%!test
%! [nr, nc] = size ([1, 2; 3, 4; 5, 6]);
%! assert (nr, 3);
%! assert (nc, 2);
 
%!test
%! [nr, remainder] = size (ones (2, 3, 4, 5));
%! assert (nr, 2);
%! assert (remainder, 60);
 
## Call for single existing dimension
 
%!assert (size ([1, 2; 3, 4; 5, 6], 1), 3)
%!assert (size ([1, 2; 3, 4; 5, 6], 2), 2)
 
## Call for single non-existing dimension
 
%!assert (size ([1, 2; 3, 4; 5, 6], 3), 1)
%!assert (size ([1, 2; 3, 4; 5, 6], 4), 1)
 
## Call for more than existing dimensions
 
%!test
%! [nr, nc, e1, e2] = size ([1, 2; 3, 4; 5, 6]);
%! assert (nr, 3);
%! assert (nc, 2);
%! assert (e1, 1);
%! assert (e2, 1);
 
## Call for two arbitrary dimensions
 
%!test
%! dim = [3, 2, 1, 1, 1];
%! for i = 1:5
%!   for j = 1:5
%!     assert (size ([1, 2; 3, 4; 5, 6], i, j), [dim(i), dim(j)]);
%!     assert (size ([1, 2; 3, 4; 5, 6], [i, j]), [dim(i), dim(j)]);
%!     [a, b] = size ([1, 2; 3, 4; 5, 6], i, j);
%!     assert (a, dim(i));
%!     assert (b, dim(j));
%!     [a, b] = size ([1, 2; 3, 4; 5, 6], [i, j]);
%!     assert (a, dim(i));
%!     assert (b, dim(j));
%!   endfor
%! endfor
 
## Call for three arbitrary dimensions
 
%!test
%! dim = [3, 2, 1, 1, 1];
%! for i = 1:5
%!   for j = 1:5
%!     for k = 1:5
%!       assert (size ([1, 2; 3, 4; 5, 6], i, j, k), [dim(i), dim(j), dim(k)]);
%!       assert (size ([1, 2; 3, 4; 5, 6], [i, j, k]),
%!               [dim(i), dim(j), dim(k)]);
%!       [a, b, c] = size ([1, 2; 3, 4; 5, 6], i, j, k);
%!       assert (a, dim(i));
%!       assert (b, dim(j));
%!       assert (c, dim(k));
%!       [a, b, c] = size ([1, 2; 3, 4; 5, 6], [i, j, k]);
%!       assert (a, dim(i));
%!       assert (b, dim(j));
%!       assert (c, dim(k));
%!     endfor
%!   endfor
%! endfor
 
%!error <does not match number of requested dimensions>
%! [a, b, c] = size ([1, 2; 3, 4; 5, 6], 1:4)
*/
 
DEFUN (size_equal, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{TF} =} size_equal (@var{A}, @var{B})
@deftypefnx {} {@var{TF} =} size_equal (@var{A}, @var{B}, @dots{})
Return true if the dimensions of all arguments agree.
 
Trailing singleton dimensions are ignored.  When called with a single argument,
or no argument, @code{size_equal} returns true.
@seealso{size, numel, ndims, common_size}
@end deftypefn */)
{
  int nargin = args.length ();
 
  if (nargin >= 1)
    {
      const dim_vector& a_dims = args(0).dims ();
 
      for (int i = 1; i < nargin; ++i)
        {
          const dim_vector& b_dims = args(i).dims ();
 
          if (a_dims != b_dims)
            return ovl (false);
        }
    }
 
  return ovl (true);
}
 
DEFUN (nnz, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{n} =} nnz (@var{A})
Return the number of nonzero elements in @var{A}.
@seealso{nzmax, nonzeros, find}
@end deftypefn */)
{
  if (args.length () != 1)
    print_usage ();
 
  return ovl (args(0).nnz ());
}
 
/*
%!assert (nnz (1:5), 5)
%!assert (nnz (-5:-1), 5)
%!assert (nnz (0:5), 5)
%!assert (nnz (-5:0), 5)
%!assert (nnz (-5:5), 10)
%!assert (nnz (-2:1:2), 4)
%!assert (nnz (-2+eps (2):1:2), 5)
%!assert (nnz (-2-eps (2):1:2), 5)
%!assert (nnz (-2:1+eps (1):2), 5)
%!assert (nnz (-2:1-eps (1):2), 5)
%!assert (nnz ([1:5] * 0), 0)
%!assert (nnz ([-5:-1] * 0), 0)
%!assert (nnz ([-1:1] * 0), 0)
*/
 
DEFUN (nzmax, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{n} =} nzmax (@var{SM})
Return the amount of storage allocated to the sparse matrix @var{SM}.
 
Programming Note: Octave tends to crop unused memory at the first opportunity
for sparse objects.  Thus, in general the value of @code{nzmax} will be the
same as @code{nnz}, except for some cases of user-created sparse objects.
 
Also, note that Octave always reserves storage for at least one value.  Thus,
for empty matrices @code{nnz} will report 0, but @code{nzmax} will report 1.
@seealso{nnz, spalloc, sparse}
@end deftypefn */)
{
  if (args.length () != 1)
    print_usage ();
 
  return ovl (args(0).nzmax ());
}
 
DEFUN (rows, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{nr} =} rows (@var{A})
@deftypefnx {} {@var{nr} =} height (@var{A})
Return the number of rows of @var{A}.
 
This is equivalent to @code{size (@var{A}, 1)}.
 
Programming Note: @code{height} is an alias for @code{rows} and can be
used interchangeably.
 
@seealso{columns, size, length, numel, isscalar, isvector, ismatrix}
@end deftypefn */)
{
  if (args.length () != 1)
    print_usage ();
 
  // This function *must* use size() to determine the desired values to
  // allow user-defined class overloading.
 
  return ovl ((octave_value (args(0)).size ())(0));
}
 
DEFALIAS (height, rows);
 
/*
%!assert (rows (ones (2,5)), 2)
%!assert (rows (ones (5,2)), 5)
%!assert (rows (ones (5,4,3,2)), 5)
%!assert (rows (ones (3,4,5,2)), 3)
 
%!assert (rows (cell (2,5)), 2)
%!assert (rows (cell (5,2)), 5)
%!assert (rows (cell (5,4,3,2)), 5)
%!assert (rows (cell (3,4,5,2)), 3)
 
%!test
%! x(2,5,3).a = 1;
%! assert (rows (x), 2);
%! y(5,4,3).b = 2;
%! assert (rows (y), 5);
 
%!assert (rows ("Hello World"), 1)
 
%!assert (rows ([]), 0)
%!assert (rows (zeros (2,0)), 2)
 
## Test input validation
%!error rows ()
%!error rows (1,2)
*/
 
DEFUN (columns, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{nc} =} columns (@var{A})
@deftypefnx {} {@var{nc} =} width (@var{A})
Return the number of columns of @var{A}.
 
This is equivalent to @code{size (@var{A}, 2)}.
 
Programming Note: @code{width} is an alias for @code{columns} and can be
used interchangeably.
 
@seealso{rows, size, length, numel, isscalar, isvector, ismatrix}
@end deftypefn */)
{
  if (args.length () != 1)
    print_usage ();
 
  // This function *must* use size() to determine the desired values to
  // allow user-defined class overloading.
 
  return ovl ((octave_value (args(0)).size ())(1));
}
 
DEFALIAS (width, columns);
 
DEFUN (sum, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{y} =} sum (@var{x})
@deftypefnx {} {@var{y} =} sum (@var{x}, @var{dim})
@deftypefnx {} {@var{y} =} sum (@var{x}, @var{vecdim})
@deftypefnx {} {@var{y} =} sum (@var{x}, "all")
@deftypefnx {} {@var{y} =} sum (@dots{}, @var{outtype})
@deftypefnx {} {@var{y} =} sum (@dots{}, @var{nanflag})
Compute the sum of the elements of @var{x}.
 
If @var{x} is a vector, then @code{sum (@var{x})} returns the sum of the
elements in @var{x}.
 
If @var{x} is a matrix, then @code{sum (@var{x})} returns a row vector with
each element containing the sum of the corresponding column in @var{x}.
 
If @var{x} is an array, then @code{sum(@var{x})} computes the sum along the
first non-singleton dimension of @var{x}.
 
The optional input @var{dim} specifies the dimension to operate on and must be
a positive integer.  Specifying any singleton dimension in @var{x}, including
any dimension exceeding @code{ndims (@var{x})}, will return @var{x}.
 
Specifying multiple dimensions with input @var{vecdim}, a vector of
non-repeating dimensions, will operate along the array slice defined by
@var{vecdim}.  If @var{vecdim} indexes all dimensions of @var{x}, then it is
equivalent to the option @qcode{"all"}.  Any dimension in @var{vecdim} greater
than @code{ndims (@var{x})} is ignored.
 
Specifying the dimension as @qcode{"all"} will cause @code{sum} to operate
on all elements of @var{x}, and is equivalent to @code{cumsum (@var{x}(:))}.
 
The optional input @var{outtype} specifies the data type that is returned as
well as the class of the variable used for calculations.
@var{outtype} can take the following values:
 
@table @asis
@item @qcode{"default"}
Operations on floating point inputs (double or single) are performed in their
native data type, while operations on integer, logical, and character data
types are performed using doubles.  Output is of type double, unless the input
is single in which case the output is of type single.
 
@item @qcode{"double"}
Operations are performed in double precision even for single precision inputs.
Output is of type double.
 
@item @qcode{"extra"}
For double precision inputs, @code{sum} will use a more accurate algorithm than
straightforward summation.  For single precision inputs, @qcode{"extra"} is the
same as @qcode{"double"}.  For all other data types, @qcode{"extra"} has no
effect.
 
@item @qcode{"native"}
Operations are performed in their native data types and output is of the same
type as the input as reported by (@code{class (@var{x})}).  When the input is
logical, @code{sum (@var{x}, "native")} is equivalent to @code{any (@var{x})}.
@end table
 
The optional variable @var{nanflag} specifies whether to include or exclude
NaN values from the calculation using any of the previously specified input
argument combinations.  The default value for @var{nanflag} is
@qcode{"includenan"} which keeps NaN values in the calculation.  To exclude
NaN values set the value of @var{nanflag} to @qcode{"omitnan"}.  The output
will be @var{0}, if @var{x} consists of all NaN values in the
operating dimension.
@seealso{cumsum, sumsq, prod}
@end deftypefn */)
{
  int nargin = args.length ();
 
  bool isnative = false;
  bool isdouble = false;
  bool isextra = false;
  bool do_perm = false;
  bool allflag = false;
  bool nanflag = false;
 
  while (nargin > 1 && args(nargin - 1).is_string ())
    {
      std::string str = args(nargin - 1).string_value ();
 
      if (str == "native")
        isnative = true;
      else if (str == "double")
        isdouble = true;
      else if (str == "extra")
        isextra = true;
      else if (str == "all")
        allflag = true;
      else if (str == "omitnan" || str == "omitmissing")
        {
          if (args(0).is_double_type () || args(0).is_single_type ())
            nanflag = true;
        }
      else if (str == "includenan" || str == "includemissing")
        nanflag = false;
      else if (str != "default")
        error ("sum: unrecognized optional argument '%s'", str.c_str ());
 
      nargin--;
    }
 
  if (nargin < 1 || nargin > 2)
    print_usage ();
  if (allflag && nargin > 1)
    error ("sum: cannot set DIM or VECDIM with 'all' flag");
 
  octave_value arg = args(0);
 
  // Handle DIM, VECDIM
  int dim = -1;
  Array<int> perm_vec;
  if (nargin == 2)
    {
      octave_value dimarg = args(1);
      get_dim_vecdim_all (dimarg, arg, dim, perm_vec, do_perm, allflag, "sum");
    }
 
  // Handle allflag
  if (allflag)
    arg = arg.reshape (dim_vector (arg.numel (), 1));
 
  octave_value retval;
 
  switch (arg.builtin_type ())
    {
    case btyp_double:
      if (arg.issparse ())
        {
          if (isextra)
            retval = arg.sparse_matrix_value ().xsum (dim, nanflag);
          else
            retval = arg.sparse_matrix_value ().sum (dim, nanflag);
        }
      else
        {
          if (isextra)
            retval = arg.array_value ().xsum (dim, nanflag);
          else
            retval = arg.array_value ().sum (dim, nanflag);
        }
      break;
 
    case btyp_complex:
      if (arg.issparse ())
        {
          if (isextra)
            retval = arg.sparse_complex_matrix_value ().xsum (dim, nanflag);
          else
            retval = arg.sparse_complex_matrix_value ().sum (dim, nanflag);
        }
      else
        {
          if (isextra)
            retval = arg.complex_array_value ().xsum (dim, nanflag);
          else
            retval = arg.complex_array_value ().sum (dim, nanflag);
        }
      break;
 
    case btyp_float:
      if (isdouble || isextra)
        retval = arg.float_array_value ().dsum (dim, nanflag);
      else
        retval = arg.float_array_value ().sum (dim, nanflag);
      break;
 
    case btyp_float_complex:
      if (isdouble || isextra)
        retval = arg.float_complex_array_value ().dsum (dim, nanflag);
      else
        retval = arg.float_complex_array_value ().sum (dim, nanflag);
      break;
 
#define MAKE_INT_BRANCH(X)                              \
      case btyp_ ## X:                                  \
        if (isnative)                                   \
          retval = arg.X ## _array_value ().sum (dim);  \
        else                                            \
          retval = arg.X ## _array_value ().dsum (dim); \
        break;
 
      MAKE_INT_BRANCH (int8);
      MAKE_INT_BRANCH (int16);
      MAKE_INT_BRANCH (int32);
      MAKE_INT_BRANCH (int64);
      MAKE_INT_BRANCH (uint8);
      MAKE_INT_BRANCH (uint16);
      MAKE_INT_BRANCH (uint32);
      MAKE_INT_BRANCH (uint64);
 
#undef MAKE_INT_BRANCH
 
    // GAGME: Accursed Matlab compatibility...
    case btyp_char:
      if (isextra)
        retval = arg.array_value (true).xsum (dim);
      else
        retval = arg.array_value (true).sum (dim);
      break;
 
    case btyp_bool:
      if (arg.issparse ())
        {
          if (isnative)
            retval = arg.sparse_bool_matrix_value ().any (dim);
          else
            retval = arg.sparse_bool_matrix_value ().sum (dim);
        }
      else if (isnative)
        retval = arg.bool_array_value ().any (dim);
      else
        {
          boolNDArray m = arg.bool_array_value ();
          retval = do_mx_red_op<double, bool> (m, dim, mx_inline_count);
         }
      break;
 
    default:
      err_wrong_type_arg ("sum", arg);
    }
 
  if (do_perm)
    retval = retval.permute (perm_vec, true);
 
  return retval;
}
 
/*
%!assert (sum ([1, 2, 3]), 6)
%!assert (sum ([-1; -2; -3]), -6)
%!assert (sum ([i, 2+i, -3+2i, 4]), 3+4i)
%!assert (sum ([1, 2, 3; i, 2i, 3i; 1+i, 2+2i, 3+3i]), [2+2i, 4+4i, 6+6i])
 
%!assert (sum (single ([1, 2, 3])), single (6))
%!assert (sum (single ([-1; -2; -3])), single (-6))
%!assert (sum (single ([i, 2+i, -3+2i, 4])), single (3+4i))
%!assert (sum (single ([1, 2, 3; i, 2i, 3i; 1+i, 2+2i, 3+3i])),
%!        single ([2+2i, 4+4i, 6+6i]))
 
%!assert (sum ([1, 2; 3, 4], 1), [4, 6])
%!assert (sum ([1, 2; 3, 4], 2), [3; 7])
%!assert (sum (single ([1, 2; 3, 4]), 1), single ([4, 6]))
%!assert (sum (single ([1, 2; 3, 4]), 2), single ([3; 7]))
 
## Test empty matrices
%!assert (sum ([]), 0)
%!assert (sum ([], 1), zeros (1, 0))
%!assert (sum ([], 2), zeros (0, 1))
%!assert (sum ([], 3), zeros (0, 0))
%!assert (sum (zeros (1, 0)), 0)
%!assert (sum (zeros (1, 0), 1), zeros (1, 0))
%!assert (sum (zeros (1, 0), 2), 0)
%!assert (sum (zeros (0, 1)), 0)
%!assert (sum (zeros (0, 1), 1), 0)
%!assert (sum (zeros (0, 1), 2), zeros (0, 1))
%!assert (sum (zeros (2, 0)),  zeros (1, 0))
%!assert (sum (zeros (2, 0), 1), zeros (1, 0))
%!assert (sum (zeros (2, 0), 2),  [0; 0])
%!assert (sum (zeros (0, 2)), [0, 0])
%!assert (sum (zeros (0, 2), 1), [0, 0])
%!assert (sum (zeros (0, 2), 2), zeros (0, 1))
%!assert (sum (zeros (2, 2, 0, 3)), zeros (1, 2, 0, 3))
%!assert (sum (zeros (2, 2, 0, 3), 2), zeros (2, 1, 0, 3))
%!assert (sum (zeros (2, 2, 0, 3), 3), zeros (2, 2, 1, 3))
%!assert (sum (zeros (2, 2, 0, 3), 4), zeros (2, 2, 0))
%!assert (sum (zeros (2, 2, 0, 3), 7), zeros (2, 2, 0, 3))
 
%!assert (sum (single ([])), single (0))
%!assert (sum (single ([]), 1), single (zeros (1, 0)))
%!assert (sum (single ([]), 2), single (zeros (0, 1)))
%!assert (sum (single ([]), 3), single (zeros (0, 0)))
%!assert (sum (zeros (1, 0, "single")), single (0))
%!assert (sum (zeros (1, 0, "single"), 1), zeros (1, 0, "single"))
%!assert (sum (zeros (1, 0, "single"), 2), single (0))
%!assert (sum (zeros (0, 1, "single")), single (0))
%!assert (sum (zeros (0, 1, "single"), 1), single (0))
%!assert (sum (zeros (0, 1, "single"), 2), zeros (0, 1, "single"))
%!assert (sum (zeros (2, 0, "single")),  zeros (1, 0, "single"))
%!assert (sum (zeros (2, 0, "single"), 1), zeros (1, 0, "single"))
%!assert (sum (zeros (2, 0, "single"), 2),  single ([0; 0]))
%!assert (sum (zeros (0, 2, "single")), single ([0, 0]))
%!assert (sum (zeros (0, 2, "single"), 1), single ([0, 0]))
%!assert (sum (zeros (0, 2, "single"), 2), zeros (0, 1, "single"))
%!assert (sum (zeros (2, 2, 0, 3, "single")), zeros (1, 2, 0, 3, "single"))
%!assert (sum (zeros (2, 2, 0, 3, "single"), 2), zeros (2, 1, 0, 3, "single"))
%!assert (sum (zeros (2, 2, 0, 3, "single"), 3), zeros (2, 2, 1, 3, "single"))
%!assert (sum (zeros (2, 2, 0, 3, "single"), 4), zeros (2, 2, 0, "single"))
%!assert (sum (zeros (2, 2, 0, 3, "single"), 7), zeros (2, 2, 0, 3, "single"))
 
## Test "default"
%!assert (sum (single (1)), sum (single (1), "default"))
%!assert (sum ([true true], "default"), double (2))
%!assert (sum (uint8 (1), "default"), double (1))
 
## Test "double" and "extra"
%!assert (sum (single ([1 2 3]), "double"), double (6))
%!assert (sum (single ([1 2 3]), "extra"), double (6))
%!assert (sum ([true,true], "double"), double (2))
 
## Test "native"
%!assert (sum ([true,true]), 2)
%!assert (sum ([true,true], "native"), true)
%!assert (sum (int8 ([127,10,-20])), 117)
%!assert (sum (int8 ([127,10,-20]), "native"), int8 (107))
 
## Test character arrays
%!assert (sum ("Octave") + "8", sumsq (primes (17)))
%!assert (sum (repmat ("Octave", [2,1,3]), [1, 3]), [474 594 696 582 708 606])
%!assert (sum (repmat ("Octave", [2,1,3]), [1, 2, 3]), 3660)
%!assert (sum (repmat ("Octave", [2,1,3]), 'all'), 3660)
 
## Test dimension indexing with vecdim in N-dimensional arrays
%!test
%! x = repmat ([1:20;6:25], [5 2 6 3]);
%! assert (size (sum (x, [3 2])), [10 1 1 3]);
%! assert (size (sum (x, [1 2])), [1 1 6 3]);
%! assert (size (sum (x, [1 2 4])), [1 1 6]);
%! assert (size (sum (x, [1 4 3])), [1 40]);
%! assert (size (sum (x, [1 2 3 4])), [1 1]);
 
## Test exceeding dimensions
%!assert (sum (ones (2,2), 3), ones (2,2))
%!assert (sum (ones (2,2,2), 99), ones (2,2,2))
%!assert (sum (magic (3), 3), magic (3))
%!assert (sum (magic (3), [1 3]), [15, 15, 15])
%!assert (sum (magic (3), [1 99]), [15, 15, 15])
%!assert (sum (ones (2), 4), ones (2))
%!assert (sum (ones (2), [4, 5]), ones (2))
%!assert (sum (single (ones (2)), 4),single (ones (2)))
%!assert (sum (single (ones (2)), [4, 5]),single (ones (2)))
%!assert (sum (sparse ([1, 2; 3, 4]), 3), sparse ([1, 2; 3, 4]))
%!assert (sum (sparse ([1, 2; 3, 4]), 3, 'extra'), sparse ([1, 2; 3, 4]))
%!assert (sum (sparse ([1, 2i; 3, 4]), 3), sparse ([1, 2i; 3, 4]))
%!assert (sum (sparse ([1, 2i; 3, 4]), 3, 'extra'), sparse ([1, 2i; 3, 4]))
 
## Test nanflag
%!test
%! x = ones (3,4,5);
%! x(1) = NaN;
%! assert (sum (x)(:,:,1), [NaN, 3, 3, 3]);
%! assert (sum (x, "includenan")(:,:,1), [NaN, 3, 3, 3]);
%! assert (sum (x, "omitnan")(:,:,1), [2, 3, 3, 3]);
%! assert (sum (x, "omitmissing")(:,:,1), [2, 3, 3, 3]);
%! assert (sum (x, [2 3]), [NaN; 20; 20]);
%! assert (sum (x, [2 3], "omitnan"), [19; 20; 20]);
 
## Test sparse matrices
%!assert (sum (sparse ([NaN, NaN, 1, 4, 2; 1, 2, 1, 2, NaN])),
%!        sparse ([NaN, NaN, 2, 6, NaN]))
%!assert (sum (sparse ([NaN, NaN, 1, 4, 2; 1, 2, 1, 2, NaN]), "omitnan"),
%!        sparse ([1, 2, 2, 6, 2]))
%!assert (sum (sparse ([NaN, NaN, 1, 4, 2; 1, 2, 1, 2, NaN]), 2),
%!        sparse ([NaN; NaN]))
%!assert (sum (sparse ([NaN, NaN, 1, 4, 2; 1, 2, 1, 2, NaN]), 2, "omitnan"),
%!        sparse ([7; 6]))
%!assert (sum (sparse ([NaN, NaN, 1i, 4, 2; 1, 2, 1, 2, NaN]), 2, "omitnan"),
%!        sparse ([6+i; 6]))
%!assert (sum (sparse ([NaN, 0i, 1i, 4, 2; 1, 2, 1, 2, NaN]), 2, "omitnan"),
%!        sparse ([6+i; 6]))
%!assert (sum (sparse ([NaN, 1+i, 1i, 4, 2; 1, 2, 1, 2, NaN]), 2, "omitnan"),
%!        sparse ([7+2i; 6]))
%!assert (sum (sparse ([NaN, NaN, NaN]), "omitnan"), sparse (0))
%!assert (sum (sparse ([0, 0, 0, NaN, NaN, NaN]), "omitnan"), sparse (0))
 
## Test empty sparse matrices
%!assert (sum (sparse (ones(1, 0))), sparse (0))
%!assert (size (sum (sparse (ones(1, 0)), 1)), [1, 0])
%!assert (size (sum (sparse (ones(1, 0)), 2)), [1, 1])
%!assert (sum (sparse (ones(0, 1))), sparse (0))
%!assert (size (sum (sparse (ones(0, 1)), 1)), [1, 1])
%!assert (size (sum (sparse (ones(0, 1)), 1)), [1, 1])
%!assert (size (sum (sparse (ones(0, 1)), 2)), [0, 1])
%!assert (sum (sparse (ones(0, 0))), sparse (0))
%!assert (size (sum (sparse (ones(0, 0)), 1)), [1, 0])
%!assert (size (sum (sparse (ones(0, 0)), 2)), [0, 1])
%!assert (size (sum (sparse (ones(0, 0)), 3)), [0, 0])
 
## Test empty sparse matrices with 'extra' option
%!assert (sum (sparse (ones(1, 0)), 'extra'), sparse (0))
%!assert (size (sum (sparse (ones(1, 0)), 1, 'extra')), [1, 0])
%!assert (size (sum (sparse (ones(1, 0)), 2, 'extra')), [1, 1])
%!assert (sum (sparse (ones(0, 1)), 'extra'), sparse (0))
%!assert (size (sum (sparse (ones(0, 1)), 1, 'extra')), [1, 1])
%!assert (size (sum (sparse (ones(0, 1)), 1, 'extra')), [1, 1])
%!assert (size (sum (sparse (ones(0, 1)), 2, 'extra')), [0, 1])
%!assert (sum (sparse (ones(0, 0)), 'extra'), sparse (0))
%!assert (size (sum (sparse (ones(0, 0)), 1, 'extra')), [1, 0])
%!assert (size (sum (sparse (ones(0, 0)), 2, 'extra')), [0, 1])
%!assert (size (sum (sparse (ones(0, 0)), 3, 'extra')), [0, 0])
 
## Test 'extra' option
%!assert (sum ([1, Inf], "extra"), Inf)
%!assert (sum ([1, -Inf], "extra"), -Inf)
%!assert (sum ([Inf, -Inf], "extra"), NaN)
%!assert (sum ([realmax, 1e300], "extra"), Inf)
%!assert (sum ([realmax/2, realmax/2, 1e300], "extra"), Inf)
%!assert (sum ([realmax/2, (2 * (realmax/3))], "extra"), Inf)
%!assert (sum (sparse ([1, Inf]), "extra"), sparse (Inf))
%!assert (sum (sparse ([1, -Inf]), "extra"), sparse (-Inf))
%!assert (sum (sparse ([Inf, -Inf]), "extra"), sparse (NaN))
%!test
%! x = [flintmax("double"), 1, -1];
%! assert (sum (x, "extra") - flintmax ("double"), 0);
%! assert (sum (x) - flintmax ("double"), -1);
%!test
%! x = sparse ([flintmax("double"), 1, -1]);
%! assert (sum (x, "extra") - sparse (flintmax ("double")), sparse (0));
%! assert (sum (x) - sparse (flintmax ("double")), sparse (-1));
%!test
%! F(:,:,1) = [3, 5; -1, 2];
%! F(:,:,2) = [4, -2; Inf, -4];
%! s = sum (F, 1, "extra");
%! assert (s(:,:,1), [2, 7]);
%! assert (s(:,:,2), [Inf, -6]);
%! s = sum (F, 2, "extra");
%! assert (s(:,:,1), [8; 1]);
%! assert (s(:,:,2), [2; Inf]);
%! s = sum (F, 3, "extra");
%! assert (s, [7, 3; Inf, -2]);
%!test
%! F(:,:,1) = [NaN, 5; -1, 2];
%! F(:,:,2) = [4, -2; Inf, -4];
%! s = sum (F, 1, "extra");
%! assert (s(:,:,1), [NaN, 7]);
%! assert (s(:,:,2), [Inf, -6]);
%! s = sum (F, 2, "extra");
%! assert (s(:,:,1), [NaN; 1]);
%! assert (s(:,:,2), [2; Inf]);
%! s = sum (F, 3, "extra");
%! assert (s, [NaN, 3; Inf, -2]);
%!test
%! F(:,:,1) = [NaN, 5; -1, 2];
%! F(:,:,2) = [4, -2; -Inf, -4];
%! s = sum (F, 1, "extra");
%! assert (s(:,:,1), [NaN, 7]);
%! assert (s(:,:,2), [-Inf, -6]);
%! s = sum (F, 2, "extra");
%! assert (s(:,:,1), [NaN; 1]);
%! assert (s(:,:,2), [2; -Inf]);
%! s = sum (F, 3, "extra");
%! assert (s, [NaN, 3; -Inf, -2]);
%!test
%! F(:,:,1) = [NaN, 5; -1, 2];
%! F(:,:,2) = [Inf, -2; -Inf, -4];
%! s = sum (F, 1, "extra");
%! assert (s(:,:,1), [NaN, 7]);
%! assert (s(:,:,2), [NaN, -6]);
%! s = sum (F, 2, "extra");
%! assert (s(:,:,1), [NaN; 1]);
%! assert (s(:,:,2), [Inf; -Inf]);
%! s = sum (F, 3, "extra");
%! assert (s, [NaN, 3; -Inf, -2]);
%!test
%! F(:,:,1) = [NaN, 5; -1, 2];
%! F(:,:,2) = [4, -2; Inf, -4];
%! assert (sum (F, 1, "omitnan", "extra"), sum (F, 1, "omitnan"));
%! assert (sum (F, 2, "omitnan", "extra"), sum (F, 2, "omitnan"));
%! assert (sum (F, 3, "omitnan", "extra"), sum (F, 3, "omitnan"));
%! assert (sum (F, [1, 2], "omitnan", "extra"), sum (F, [1, 2], "omitnan"));
%! assert (sum (F, [1, 3], "omitnan", "extra"), sum (F, [1, 3], "omitnan"));
%! assert (sum (F, [2, 3], "omitnan", "extra"), sum (F, [2, 3], "omitnan"));
%! assert (sum (F, "all", "omitnan", "extra"), sum (F, [1, 2, 3], "omitnan"));
 
## Test 'extra' option with sparse matrices
%!assert (sum (sparse ([2; 3; 4; 5; 6]), "extra"), sparse (20))
%!assert (sum (sparse ([2; 3; 0; 5; 6]), "extra"), sparse (16))
%!assert (sum (sparse ([2; 3; 4; 5; 6]'), "extra"), sparse (20))
%!assert (sum (sparse ([2; 3; 0; 5; 6]'), "extra"), sparse (16))
%!assert (sum (speye (3), "extra"), sparse ([1, 1, 1]))
%!assert (sum (speye (3), 1, "extra"), sparse ([1, 1, 1]))
%!assert (sum (speye (3), 2, "extra"), sparse ([1; 1; 1]))
%!assert (sum (speye (3), 3, "extra"), speye (3))
%!assert (sum (sparse ([2; 3; 4; 5; 6] * i), "extra"), sparse (20i))
%!assert (sum (sparse ([2; 3; 0; 5; 6] * i), "extra"), sparse (16i))
%!assert (sum (sparse ([2; 3; 4; 5; 6]' * i), "extra"), sparse (20i))
%!assert (sum (sparse ([2; 3; 0; 5; 6]' * i), "extra"), sparse (16i))
%!assert (sum (speye (3) * i, "extra"), sparse ([1, 1, 1]*i))
%!assert (sum (speye (3) * i, 1, "extra"), sparse ([1, 1, 1]*i))
%!assert (sum (speye (3) * i, 2, "extra"), sparse ([1; 1; 1]*i))
%!assert (sum (speye (3) * i, 3, "extra"), speye (3) * i)
 
## Test 'extra' option with sparse matrices
%!assert (sum (sparse ([2; 3; 4; 5; 6]), "extra"), sparse (20))
%!assert (sum (sparse ([2; 3; 0; 5; 6]), "extra"), sparse (16))
%!assert (sum (sparse ([2; 3; 4; 5; 6]'), "extra"), sparse (20))
%!assert (sum (sparse ([2; 3; 0; 5; 6]'), "extra"), sparse (16))
%!assert (sum (speye (3), "extra"), sparse ([1, 1, 1]))
%!assert (sum (speye (3), 1, "extra"), sparse ([1, 1, 1]))
%!assert (sum (speye (3), 2, "extra"), sparse ([1; 1; 1]))
%!assert (sum (speye (3), 3, "extra"), speye (3))
%!assert (sum (sparse ([2; 3; 4; 5; 6] * i), "extra"), sparse (20i))
%!assert (sum (sparse ([2; 3; 0; 5; 6] * i), "extra"), sparse (16i))
%!assert (sum (sparse ([2; 3; 4; 5; 6]' * i), "extra"), sparse (20i))
%!assert (sum (sparse ([2; 3; 0; 5; 6]' * i), "extra"), sparse (16i))
%!assert (sum (speye (3) * i, "extra"), sparse ([1, 1, 1]*i))
%!assert (sum (speye (3) * i, 1, "extra"), sparse ([1, 1, 1]*i))
%!assert (sum (speye (3) * i, 2, "extra"), sparse ([1; 1; 1]*i))
%!assert (sum (speye (3) * i, 3, "extra"), speye (3) * i)
 
## Test cases for "omitnan"
%!test
%! A = [1, NaN; 2, NaN; 3, NaN];
%! assert (sum (A, 2, "omitnan"), [1; 2; 3]);
%!test
%! A = [1, 2, 3; NaN, NaN, NaN];
%! assert (sum (A, 1, "omitnan"), [1, 2, 3]);
%!test
%! A = [NaN, NaN, NaN];
%! assert (sum (A, "omitnan"), 0);
%!test
%! A = [1, NaN, 3; 2, NaN, 4; 5, NaN, 6];
%! assert (sum (A, 1, "omitnan"), [8, 0, 13]);
%!test
%! A = [1, 2, NaN; 3, 4, NaN; 5, 6, NaN];
%! assert (sum (A, 2, "omitnan"), [3; 7; 11]);
%!test
%! A = [2, NaN, NaN, 3; 4, NaN, NaN, 5; 1, NaN, NaN, 6];
%! assert (sum (A, 1, "omitnan"), [7, 0, 0, 14]);
%!test
%! A = [1, NaN, 3, NaN, 5; 2, NaN, 4, NaN, 6; 3, NaN, 5, NaN, 7];
%! assert (sum (A, 1, "omitnan"), [6, 0, 12, 0, 18]);
%!test
%! A = [1+2i, NaN; 3+4i, NaN; 5+6i, NaN];
%! assert (sum (A, 2, "omitnan"), [1+2i; 3+4i; 5+6i]);
%!test
%! A = single ([1, NaN; 2, NaN; 3, NaN]);
%! assert (sum (A, 2, "omitnan"), single ([1; 2; 3]));
%!test
%! A = single ([NaN, NaN, NaN]);
%! assert (sum (A, "omitnan"), single (0));
 
## Test boolean sum optimization
%!test
%! x = [true, false, true; false, true, false];
%! assert (sum (x, 1), [1, 1, 1]);
%! assert (sum (x, 2), [2; 1]);
 
%!test
%! x = rand (100, 100) > 0.5;
%! assert (sum (x), sum (double (x)));
%! assert (sum (x, 2), sum (double (x), 2));
 
%!assert (sum (true), 1)
%!assert (sum (false), 0)
%!assert (class (sum ([true, false])), "double")
 
## Test input validation
%!error <Invalid call> sum ()
%!error <Invalid call> sum (1,2,3)
%!error <unrecognized optional argument 'foobar'> sum (1, "foobar")
%!error <cannot set DIM or VECDIM with 'all' flag>
%! sum (ones (3,3), 1, "all");
%!error <cannot set DIM or VECDIM with 'all' flag>
%! sum (ones (3,3), [1, 2], "all");
%!error <invalid dimension DIM = 0> sum (ones (3,3), 0)
%!error <invalid dimension DIM = -1> sum (ones (3,3), -1)
%!error <invalid dimension in VECDIM = -2> sum (ones (3,3), [1 -2])
%!error <duplicate dimension in VECDIM = 2> sum (ones (3,3), [1 2 2])
%!error <duplicate dimension in VECDIM = 1> sum (ones (3,3), [1 1 2])
*/
 
DEFUN (sumsq, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{y} =} sumsq (@var{x})
@deftypefnx {} {@var{y} =} sumsq (@var{x}, @var{dim})
@deftypefnx {} {@var{y} =} sumsq (@var{x}, @var{vecdim})
@deftypefnx {} {@var{y} =} sumsq (@var{x}, "all")
@deftypefnx {} {@var{y} =} sumsq (@dots{}, @var{outtype})
@deftypefnx {} {@var{y} =} sumsq (@dots{}, @var{nanflag})
Compute the sum of squares of the elements of @var{x}.
 
If @var{x} is a vector, then @code{sumsq (@var{x})} returns the sum of the
squares of the elements in @var{x}.
 
If @var{x} is a matrix, then @code{sumsq (@var{x})} returns a row vector with
each element containing the sum of squares of the corresponding column in
@var{x}.
 
If @var{x} is an array, then @code{sumsq(@var{x})} computes the sum of squares
along the first non-singleton dimension of @var{x}.
 
This function is conceptually equivalent to computing
 
@example
sum (x .* conj (x))
@end example
 
@noindent
but it uses less memory and avoids calling @code{conj} if @var{x} is real.
 
The optional input @var{dim} specifies the dimension to operate on and must be
a positive integer.  Specifying any singleton dimension in @var{x}, including
any dimension exceeding @code{ndims (@var{x})}, will return a sum of squares
equal to @code{@var{x}.^2}.
 
Specifying multiple dimensions with input @var{vecdim}, a vector of
non-repeating dimensions, will operate along the array slice defined by
@var{vecdim}.  If @var{vecdim} indexes all dimensions of @var{x}, then it is
equivalent to the option @qcode{"all"}.  Any dimension in @var{vecdim} greater
than @code{ndims (@var{x})} is ignored.
 
Specifying the dimension as @qcode{"all"} will cause @code{prod} to operate on
all elements of @var{x}, and is equivalent to @code{sumsq (@var{x}(:))}.
 
The optional input @var{outtype} specifies the data type that is returned as
well as the class of the variable used for calculations.
@var{outtype} can take the following values:
 
@table @asis
@item @qcode{"default"}
Operations on floating point inputs (double or single) are performed in their
native data type; while operations on integer, logical, and character data
types are performed using doubles.  Output is of type double, unless the input
is single in which case the output is of type single.
 
@item @qcode{"double"}
Operations are performed in double precision even for single precision inputs.
Output is of type double.
 
@item @qcode{"native"}
Operations are performed in their native data types and output is of the same
type as the input as reported by (@code{class (@var{x})}).  When the input is
logical, @code{sumsq (@var{x}, "native")} is equivalent to
@code{all (@var{x})}.
@end table
 
The optional variable @var{nanflag} specifies whether to include or exclude
NaN values from the calculation using any of the previously specified input
argument combinations.  The default value for @var{nanflag} is
@qcode{"includenan"} which keeps NaN values in the calculation.  To exclude
NaN values set the value of @var{nanflag} to @qcode{"omitnan"}.  The output
will be @var{0}, if @var{x} consists of all NaN values in the
operating dimension.
@seealso{sum, prod}
@end deftypefn */)
{
  int nargin = args.length ();
 
  bool isnative = false;
  bool isdouble = false;
  bool do_perm = false;
  bool allflag = false;
  bool nanflag = false;
 
  while (nargin > 1 && args(nargin - 1).is_string ())
    {
      std::string str = args(nargin - 1).string_value ();
 
      if (str == "native")
        isnative = true;
      else if (str == "double")
        isdouble = true;
      else if (str == "all")
        allflag = true;
      else if (str == "omitnan" || str == "omitmissing")
        {
          if (args(0).is_double_type () || args(0).is_single_type ())
            nanflag = true;
        }
      else if (str == "includenan" || str == "includemissing")
        nanflag = false;
      else if (str != "default")
        error ("sumsq: unrecognized optional argument '%s'", str.c_str ());
 
      nargin--;
    }
 
  if (nargin < 1 || nargin > 2)
    print_usage ();
  if (allflag && nargin > 1)
    error ("sumsq: cannot set DIM or VECDIM with 'all' flag");
 
  octave_value arg = args(0);
 
  // Handle DIM, VECDIM
  int dim = -1;
  Array<int> perm_vec;
  if (nargin == 2)
    {
      octave_value dimarg = args(1);
      get_dim_vecdim_all (dimarg, arg, dim, perm_vec, do_perm, allflag, "sumsq");
    }
 
  // Handle allflag
  if (allflag)
    arg = arg.reshape (dim_vector (arg.numel (), 1));
 
  octave_value retval;
 
  switch (arg.builtin_type ())
    {
    case btyp_double:
      if (arg.issparse ())
        retval = arg.sparse_matrix_value ().sumsq (dim, nanflag);
      else
        retval = arg.array_value ().sumsq (dim, nanflag);
      break;
 
    case btyp_complex:
      if (arg.issparse ())
        retval = arg.sparse_complex_matrix_value ().sumsq (dim, nanflag);
      else
        retval = arg.complex_array_value ().sumsq (dim, nanflag);
      break;
 
    case btyp_float:
      if (isdouble)
        retval = arg.float_array_value ().dsumsq (dim, nanflag);
      else
        retval = arg.float_array_value ().sumsq (dim, nanflag);
      break;
 
    case btyp_float_complex:
      if (isdouble)
        retval = arg.float_complex_array_value ().dsumsq (dim, nanflag);
      else
        retval = arg.float_complex_array_value ().sumsq (dim, nanflag);
      break;
 
#define MAKE_INT_BRANCH(X)                               \
      case btyp_ ## X:                                   \
        if (isnative)                                    \
          retval = arg.X ## _array_value ().sumsq (dim); \
        else                                             \
          retval = arg.array_value ().sumsq (dim);       \
        break;
 
      MAKE_INT_BRANCH (int8);
      MAKE_INT_BRANCH (int16);
      MAKE_INT_BRANCH (int32);
      MAKE_INT_BRANCH (int64);
      MAKE_INT_BRANCH (uint8);
      MAKE_INT_BRANCH (uint16);
      MAKE_INT_BRANCH (uint32);
      MAKE_INT_BRANCH (uint64);
 
#undef MAKE_INT_BRANCH
 
    // GAGME: Accursed Matlab compatibility...
    case btyp_char:
      retval = arg.array_value (true).sumsq (dim);
      break;
 
    case btyp_bool:
      if (arg.issparse ())
        {
          if (isnative)
            retval = arg.sparse_bool_matrix_value ().all (dim);
          else
            retval = arg.sparse_matrix_value ().sumsq (dim);
        }
      else if (isnative)
        retval = arg.bool_array_value ().all (dim);
      else
        {
          // For booleans: sumsq (x) = sum (x), since 0^2=0, 1^2=1
          boolNDArray m = arg.bool_array_value ();
          retval = do_mx_red_op<double, bool> (m, dim, mx_inline_count);
        }
      break;
 
    default:
      err_wrong_type_arg ("sumsq", arg);
    }
 
  if (do_perm)
    retval = retval.permute (perm_vec, true);
 
  return retval;
}
 
/*
%!assert (sumsq ([1, 2, 3]), 14)
%!assert (sumsq ([-1; -2; 4i]), 21)
%!assert (sumsq ([1, 2, 3; 2, 3, 4; 4i, 6i, 2]), [21, 49, 29])
 
%!assert (sumsq (single ([1, 2, 3])), single (14))
%!assert (sumsq (single ([-1; -2; 4i])), single (21))
%!assert (sumsq (single ([1, 2, 3; 2, 3, 4; 4i, 6i, 2])),
%!        single ([21, 49, 29]))
 
%!assert (sumsq ([1, 2; 3, 4], 1), [10, 20])
%!assert (sumsq ([1, 2; 3, 4], 2), [5; 25])
 
%!assert (sumsq (single ([1, 2; 3, 4]), 1), single ([10, 20]))
%!assert (sumsq (single ([1, 2; 3, 4]), 2), single ([5; 25]))
 
## Test empty matrices
%!assert (sumsq ([]), 0)
%!assert (sumsq ([], 1), zeros (1, 0))
%!assert (sumsq ([], 2), zeros (0, 1))
%!assert (sumsq ([], 3), zeros (0, 0))
%!assert (sumsq (zeros (1, 0)), 0)
%!assert (sumsq (zeros (1, 0), 1), zeros (1, 0))
%!assert (sumsq (zeros (1, 0), 2), 0)
%!assert (sumsq (zeros (0, 1)), 0)
%!assert (sumsq (zeros (0, 1), 1), 0)
%!assert (sumsq (zeros (0, 1), 2), zeros (0, 1))
%!assert (sumsq (zeros (2, 0)),  zeros (1, 0))
%!assert (sumsq (zeros (2, 0), 1), zeros (1, 0))
%!assert (sumsq (zeros (2, 0), 2),  [0; 0])
%!assert (sumsq (zeros (0, 2)), [0, 0])
%!assert (sumsq (zeros (0, 2), 1), [0, 0])
%!assert (sumsq (zeros (0, 2), 2), zeros (0, 1))
%!assert (sumsq (zeros (2, 2, 0, 3)), zeros (1, 2, 0, 3))
%!assert (sumsq (zeros (2, 2, 0, 3), 2), zeros (2, 1, 0, 3))
%!assert (sumsq (zeros (2, 2, 0, 3), 3), zeros (2, 2, 1, 3))
%!assert (sumsq (zeros (2, 2, 0, 3), 4), zeros (2, 2, 0))
%!assert (sumsq (zeros (2, 2, 0, 3), 7), zeros (2, 2, 0, 3))
 
%!assert (sumsq (single ([])), single (0))
%!assert (sumsq (single ([]), 1), single (zeros (1, 0)))
%!assert (sumsq (single ([]), 2), single (zeros (0, 1)))
%!assert (sumsq (single ([]), 3), single (zeros (0, 0)))
%!assert (sumsq (zeros (1, 0, "single")), single (0))
%!assert (sumsq (zeros (1, 0, "single"), 1), zeros (1, 0, "single"))
%!assert (sumsq (zeros (1, 0, "single"), 2), single (0))
%!assert (sumsq (zeros (0, 1, "single")), single (0))
%!assert (sumsq (zeros (0, 1, "single"), 1), single (0))
%!assert (sumsq (zeros (0, 1, "single"), 2), zeros (0, 1, "single"))
%!assert (sumsq (zeros (2, 0, "single")),  zeros (1, 0, "single"))
%!assert (sumsq (zeros (2, 0, "single"), 1), zeros (1, 0, "single"))
%!assert (sumsq (zeros (2, 0, "single"), 2),  single ([0; 0]))
%!assert (sumsq (zeros (0, 2, "single")), single ([0, 0]))
%!assert (sumsq (zeros (0, 2, "single"), 1), single ([0, 0]))
%!assert (sumsq (zeros (0, 2, "single"), 2), zeros (0, 1, "single"))
%!assert (sumsq (zeros (2, 2, 0, 3, "single")), zeros (1, 2, 0, 3, "single"))
%!assert (sumsq (zeros (2, 2, 0, 3, "single"), 2), zeros (2, 1, 0, 3, "single"))
%!assert (sumsq (zeros (2, 2, 0, 3, "single"), 3), zeros (2, 2, 1, 3, "single"))
%!assert (sumsq (zeros (2, 2, 0, 3, "single"), 4), zeros (2, 2, 0, "single"))
%!assert (sumsq (zeros (2, 2, 0, 3, "single"), 7), zeros (2, 2, 0, 3, "single"))
 
## Test dimension indexing with vecdim in N-dimensional arrays
%!test
%! x = repmat ([1:20;6:25], [5 2 6 3]);
%! assert (size (sumsq (x, [3 2])), [10 1 1 3]);
%! assert (size (sumsq (x, [1 2])), [1 1 6 3]);
%! assert (size (sumsq (x, [1 2 4])), [1 1 6]);
%! assert (size (sumsq (x, [1 4 3])), [1 40]);
%! assert (size (sumsq (x, [1 2 3 4])), [1 1]);
 
## Test exceeding dimensions
%!assert (sumsq (ones (2), 3), ones (2))
%!assert (sumsq (ones (2, 2, 2), 99), ones (2, 2, 2))
%!assert (sumsq (magic (3), 3), magic (3) .^ 2)
%!assert (sumsq (magic (3), [3, 5]), magic (3) .^ 2)
%!assert (sumsq (magic (3), [1 3]), sum (magic (3) .^ 2))
%!assert (sumsq (magic (3), [2 99]), sum (magic (3) .^ 2, 2))
%!assert (sumsq (single (ones (2)), 4),single (ones (2)))
%!assert (sumsq (single (ones (2)), [4, 5]),single (ones (2)))
%!assert (sumsq (sparse ([1, 2; 3, 4]), 3), sparse ([1, 2; 3, 4].^2))
%!assert (sumsq (sparse ([1, 2i; 3, 4]), 3), sparse ([1, 4; 9, 16]))
 
## Test nanflag
%!test
%! x = ones (3,4,5);
%! x(1) = NaN;
%! assert (sumsq (x)(:,:,1), [NaN, 3, 3, 3]);
%! assert (sumsq (x, "includenan")(:,:,1), [NaN, 3, 3, 3]);
%! assert (sumsq (x, "omitnan")(:,:,1), [2, 3, 3, 3]);
%! assert (sumsq (x, "omitmissing")(:,:,1), [2, 3, 3, 3]);
%! assert (sumsq (x, [2 3]), [NaN; 20; 20]);
%! assert (sumsq (x, [2 3], "omitnan"), [19; 20; 20]);
 
## Test cases for "omitnan"
%!test
%! A = [1, NaN; 2, NaN; 3, NaN];
%! assert (sumsq (A, 2, "omitnan"), [1; 4; 9]);
%!test
%! A = [NaN, NaN, NaN];
%! assert (sumsq (A, "omitnan"), 0);
%!test
%! A = [2, 3, NaN; 4, 5, NaN; 1, 2, NaN];
%! assert (sumsq (A, 2, "omitnan"), [13; 41; 5]);
%!test
%! A = [2, NaN, 3; 3, NaN, 4; 1, NaN, 2];
%! assert (sumsq (A, 1, "omitnan"), [14, 0, 29]);
%!test
%! A = [1+2i, NaN; 3+4i, NaN];
%! assert (sumsq (A, 2, "omitnan"), [5; 25]);
%!test
%! A = single ([NaN, NaN, NaN]);
%! assert (sumsq (A, "omitnan"), single (0));
 
## Test sparse matrices
%!assert (sumsq (sparse ([NaN, NaN, 1, 4, 2; 1, 2, 1, 2, NaN])),
%!        sparse ([NaN, NaN, 2, 20, NaN]))
%!assert (sumsq (sparse ([NaN, NaN, 1, 4, 2; 1, 2, 1, 2, NaN]), "omitnan"),
%!        sparse ([1, 4, 2, 20, 4]))
%!assert (sumsq (sparse ([NaN, NaN, 1, 4, 2; 1, 2, 1, 2, NaN]), 2),
%!        sparse ([NaN; NaN]))
%!assert (sumsq (sparse ([NaN, NaN, 1, 4, 2; 1, 2, 1, 2, NaN]), 2, "omitnan"),
%!        sparse ([21; 10]))
%!assert (sumsq (sparse ([NaN, NaN, 1i, 4, 2; 1, 2, 1, 2, NaN]), 2, "omitnan"),
%!        sparse ([21; 10]))
%!assert (sumsq (sparse ([NaN, 0i, 1i, 4, 2; 1, 2, 1, 2, NaN]), 2, "omitnan"),
%!        sparse ([21; 10]))
%!assert (sumsq (sparse ([NaN, 1+i, 1i, 4, 2; 1, 2, 1, 2, NaN]), 2, "omitnan"),
%!        sparse ([23; 10]))
%!assert (sumsq (sparse ([NaN, NaN, NaN]), "omitnan"), sparse (0))
%!assert (sumsq (sparse ([0, 0, 0, NaN, NaN, NaN]), "omitnan"), sparse (0))
 
## Test empty sparse matrices
%!assert (sumsq (sparse (ones(1, 0))), sparse (0))
%!assert (size (sumsq (sparse (ones(1, 0)), 1)), [1, 0])
%!assert (size (sumsq (sparse (ones(1, 0)), 2)), [1, 1])
%!assert (sumsq (sparse (ones(0, 1))), sparse (0))
%!assert (size (sumsq (sparse (ones(0, 1)), 1)), [1, 1])
%!assert (size (sumsq (sparse (ones(0, 1)), 1)), [1, 1])
%!assert (size (sumsq (sparse (ones(0, 1)), 2)), [0, 1])
%!assert (sumsq (sparse (ones(0, 0))), sparse (0))
%!assert (size (sumsq (sparse (ones(0, 0)), 1)), [1, 0])
%!assert (size (sumsq (sparse (ones(0, 0)), 2)), [0, 1])
%!assert (size (sumsq (sparse (ones(0, 0)), 3)), [0, 0])
 
## Test boolean sumsq (must be equal to sum)
%!test
%! x = [true, false, true; false, true, false];
%! assert (sumsq (x), sum (x));
%! assert (sumsq (x, 1), [1, 1, 1]);
%! assert (sumsq (x, 2), [2; 1]);
 
%!test
%! x = rand (100, 100) > 0.5;
%! assert (sumsq (x), sum (x));
 
%!assert (sumsq (true), 1)
%!assert (sumsq (false), 0)
%!assert (class (sumsq ([true, false])), "double")
 
## Test input validation
%!error <Invalid call> sumsq ()
%!error <Invalid call> sumsq (1,2,3)
%!error <unrecognized optional argument 'foobar'> sumsq (1, "foobar")
%!error <cannot set DIM or VECDIM with 'all' flag>
%! sumsq (ones (3,3), 1, "all");
%!error <cannot set DIM or VECDIM with 'all' flag>
%! sumsq (ones (3,3), [1, 2], "all");
%!error <invalid dimension DIM = 0> sumsq (ones (3,3), 0)
%!error <invalid dimension DIM = -1> sumsq (ones (3,3), -1)
%!error <invalid dimension in VECDIM = -2> sumsq (ones (3,3), [1 -2])
%!error <duplicate dimension in VECDIM = 2> sumsq (ones (3,3), [1 2 2])
%!error <duplicate dimension in VECDIM = 1> sumsq (ones (3,3), [1 1 2])
*/
 
DEFUN (islogical, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{tf} =} islogical (@var{x})
@deftypefnx {} {@var{tf} =} isbool (@var{x})
Return true if @var{x} is a logical object.
 
Programming Note: @code{isbool} is an alias for @code{islogical} and can be
used interchangeably.
@seealso{ischar, isfloat, isinteger, isstring, isnumeric, isa}
@end deftypefn */)
{
  if (args.length () != 1)
    print_usage ();
 
  return ovl (args(0).islogical ());
}
 
DEFALIAS (isbool, islogical);
 
/*
%!assert (islogical (true), true)
%!assert (islogical (false), true)
%!assert (islogical ([true, false]), true)
%!assert (islogical (1), false)
%!assert (islogical (1i), false)
%!assert (islogical ([1,1]), false)
%!assert (islogical (single (1)), false)
%!assert (islogical (single (1i)), false)
%!assert (islogical (single ([1,1])), false)
%!assert (islogical (sparse ([true, false])), true)
%!assert (islogical (sparse ([1, 0])), false)
*/
 
DEFUN (isinteger, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{tf} =} isinteger (@var{x})
Return true if @var{x} is an integer object (int8, uint8, int16, etc.).
 
Note that @w{@code{isinteger (14)}}@ is false because numeric constants in
Octave are double precision floating point values.
@seealso{isfloat, ischar, islogical, isstring, isnumeric, isa}
@end deftypefn */)
{
  if (args.length () != 1)
    print_usage ();
 
  return ovl (args(0).isinteger ());
}
 
/*
%!assert (isinteger (int8 (16)))
%!assert (isinteger (int16 (16)))
%!assert (isinteger (int32 (16)))
%!assert (isinteger (int64 (16)))
 
%!assert (isinteger (uint8 (16)))
%!assert (isinteger (uint16 (16)))
%!assert (isinteger (uint32 (16)))
%!assert (isinteger (uint64 (16)))
 
%!assert (isinteger (intmax ("int8")))
%!assert (isinteger (intmax ("int16")))
%!assert (isinteger (intmax ("int32")))
%!assert (isinteger (intmax ("int64")))
 
%!assert (isinteger (intmax ("uint8")))
%!assert (isinteger (intmax ("uint16")))
%!assert (isinteger (intmax ("uint32")))
%!assert (isinteger (intmax ("uint64")))
 
%!assert (isinteger (intmin ("int8")))
%!assert (isinteger (intmin ("int16")))
%!assert (isinteger (intmin ("int32")))
%!assert (isinteger (intmin ("int64")))
 
%!assert (isinteger (intmin ("uint8")))
%!assert (isinteger (intmin ("uint16")))
%!assert (isinteger (intmin ("uint32")))
%!assert (isinteger (intmin ("uint64")))
 
%!assert (isinteger (uint8 ([1:10])))
%!assert (isinteger (uint8 ([1:10; 1:10])))
 
%!assert (! isinteger (16))
%!assert (! isinteger ("parrot"))
%!assert (! isinteger ([1, 2, 3]))
 
%!error isinteger ()
%!error isinteger ("multiple", "parameters")
*/
 
DEFUN (iscomplex, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{tf} =} iscomplex (@var{x})
Return true if @var{x} is a complex-valued numeric object.
@seealso{isreal, isnumeric, ischar, isfloat, islogical, isstring, isa}
@end deftypefn */)
{
  if (args.length () != 1)
    print_usage ();
 
  return ovl (args(0).iscomplex ());
}
 
/*
%!assert (iscomplex (4), false)
%!assert (iscomplex (i), true)
%!assert (iscomplex (4+3i), true)
%!assert (iscomplex ([1, 2, 3]), false)
%!assert (iscomplex ([1, 2i, 3]), true)
 
%!assert (iscomplex (0j), false)
%!assert (iscomplex (complex (0,0)), true)
%!assert (iscomplex ("4"), false)
%!assert (iscomplex ({i}), false)
 
## Test input validation
%!error iscomplex ()
%!error iscomplex (1, 2)
*/
 
DEFUN (isfloat, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{tf} =} isfloat (@var{x})
Return true if @var{x} is a floating-point numeric object.
 
Objects of class double or single are floating-point objects.
@seealso{isinteger, ischar, islogical, isnumeric, isstring, isa}
@end deftypefn */)
{
  if (args.length () != 1)
    print_usage ();
 
  return ovl (args(0).isfloat ());
}
 
// FIXME: perhaps this should be implemented with an
// octave_value member function?
 
DEFUN (complex, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{z} =} complex (@var{x})
@deftypefnx {} {@var{z} =} complex (@var{re}, @var{im})
Return a complex value from real arguments.
 
With 1 real argument @var{x}, return the complex result
@w{@code{@var{x} + 0i}}.
 
With 2 real arguments, return the complex result
@w{@code{@var{re} + @var{im}i}}.
@code{complex} can often be more convenient than expressions such as
@w{@code{a + b*i}}.
For example:
 
@example
@group
complex ([1, 2], [3, 4])
  @xresult{} [ 1 + 3i   2 + 4i ]
@end group
@end example
@seealso{real, imag, iscomplex, abs, arg}
@end deftypefn */)
// Programming Note: Throughout this function the coding pattern
// octave_value (new XXX)) is used.  This is done specifically because the
// default octave_value constructor would otherwise perform automatic narrowing
// (i.e., complex values with 0 for the imaginary part would be converted
// to real values).  The complex() function *must* return a complex value
// even when the imaginary part is 0.
{
  int nargin = args.length ();
 
  if (nargin < 1 || nargin > 2)
    print_usage ();
 
  octave_value retval;
 
  if (nargin == 1)
    {
      octave_value arg = args(0);
 
      if (arg.iscomplex ())
        retval = arg;
      else
        {
          if (arg.issparse ())
            {
              SparseComplexMatrix val = arg.xsparse_complex_matrix_value ("complex: invalid conversion");
 
              retval = octave_value (new octave_sparse_complex_matrix (val));
            }
          else if (arg.is_single_type ())
            {
              if (arg.numel () == 1)
                {
                  FloatComplex val = arg.xfloat_complex_value ("complex: invalid conversion");
 
                  retval = octave_value (new octave_float_complex (val));
                }
              else
                {
                  FloatComplexNDArray val = arg.xfloat_complex_array_value ("complex: invalid conversion");
 
                  retval = octave_value (new octave_float_complex_matrix (val));
                }
            }
          else
            {
              if (arg.numel () == 1)
                {
                  Complex val = arg.xcomplex_value ("complex: invalid conversion");
 
                  retval = octave_value (new octave_complex (val));
                }
              else
                {
                  ComplexNDArray val = arg.xcomplex_array_value ("complex: invalid conversion");
 
                  retval = octave_value (new octave_complex_matrix (val));
                }
            }
        }
    }
  else
    {
      octave_value re = args(0);
      octave_value im = args(1);
 
      if (re.issparse () && im.issparse ())
        {
          const SparseMatrix re_val = re.sparse_matrix_value ();
          const SparseMatrix im_val = im.sparse_matrix_value ();
 
          if (re.numel () == 1)
            {
              SparseComplexMatrix result;
              if (re_val.nnz () == 0)
                result = Complex (0, 1) * SparseComplexMatrix (im_val);
              else
                {
                  octave_idx_type nr = im_val.rows ();
                  octave_idx_type nc = im_val.cols ();
                  result = SparseComplexMatrix (nr, nc, re_val(0));
 
                  for (octave_idx_type j = 0; j < nc; j++)
                    {
                      octave_idx_type off = j * nr;
                      for (octave_idx_type i = im_val.cidx (j);
                           i < im_val.cidx (j + 1); i++)
                        result.data (im_val.ridx (i) + off)
                        += Complex (0, im_val.data (i));
                    }
                }
              retval = octave_value (new octave_sparse_complex_matrix (result));
            }
          else if (im.numel () == 1)
            {
              SparseComplexMatrix result;
              if (im_val.nnz () == 0)
                result = SparseComplexMatrix (re_val);
              else
                {
                  octave_idx_type nr = re_val.rows ();
                  octave_idx_type nc = re_val.cols ();
                  result = SparseComplexMatrix (nr, nc,
                                                Complex (0, im_val(0)));
 
                  for (octave_idx_type j = 0; j < nc; j++)
                    {
                      octave_idx_type off = j * nr;
                      for (octave_idx_type i = re_val.cidx (j);
                           i < re_val.cidx (j + 1); i++)
                        result.data (re_val.ridx (i) + off)
                        += re_val.data (i);
                    }
                }
              retval = octave_value (new octave_sparse_complex_matrix (result));
            }
          else
            {
              if (re_val.dims () != im_val.dims ())
                error ("complex: dimension mismatch");
 
              SparseComplexMatrix result;
              result = SparseComplexMatrix (re_val)
                       + Complex (0, 1) * SparseComplexMatrix (im_val);
              retval = octave_value (new octave_sparse_complex_matrix (result));
            }
        }
      else if (re.is_single_type () || im.is_single_type ())
        {
          if (re.numel () == 1)
            {
              float re_val = re.float_value ();
 
              if (im.numel () == 1)
                {
                  float im_val = im.double_value ();
 
                  retval = octave_value (new octave_float_complex
                                         (FloatComplex (re_val, im_val)));
                }
              else
                {
                  const FloatNDArray im_val = im.float_array_value ();
 
                  FloatComplexNDArray result (im_val.dims ());
 
                  for (octave_idx_type i = 0; i < im_val.numel (); i++)
                    result.xelem (i) = FloatComplex (re_val, im_val.xelem (i));
 
                  retval = octave_value (new octave_float_complex_matrix
                                         (result));
                }
            }
          else
            {
              const FloatNDArray re_val = re.float_array_value ();
 
              if (im.numel () == 1)
                {
                  float im_val = im.float_value ();
 
                  FloatComplexNDArray result (re_val.dims ());
 
                  for (octave_idx_type i = 0; i < re_val.numel (); i++)
                    result.xelem (i) = FloatComplex (re_val.xelem (i), im_val);
 
                  retval = octave_value (new octave_float_complex_matrix
                                         (result));
                }
              else
                {
                  const FloatNDArray im_val = im.float_array_value ();
 
                  if (re_val.dims () != im_val.dims ())
                    error ("complex: dimension mismatch");
 
                  FloatComplexNDArray result (re_val.dims ());
 
                  for (octave_idx_type i = 0; i < re_val.numel (); i++)
                    result.xelem (i) = FloatComplex (re_val.xelem (i),
                                                     im_val.xelem (i));
 
                  retval = octave_value (new octave_float_complex_matrix
                                         (result));
                }
            }
        }
      else if (re.numel () == 1)
        {
          double re_val = re.double_value ();
 
          if (im.numel () == 1)
            {
              double im_val = im.double_value ();
 
              retval = octave_value (new octave_complex
                                     (Complex (re_val, im_val)));
            }
          else
            {
              const NDArray im_val = im.array_value ();
 
              ComplexNDArray result (im_val.dims ());
 
              for (octave_idx_type i = 0; i < im_val.numel (); i++)
                result.xelem (i) = Complex (re_val, im_val.xelem (i));
 
              retval = octave_value (new octave_complex_matrix (result));
            }
        }
      else
        {
          const NDArray re_val = re.array_value ();
 
          if (im.numel () == 1)
            {
              double im_val = im.double_value ();
 
              ComplexNDArray result (re_val.dims ());
 
              for (octave_idx_type i = 0; i < re_val.numel (); i++)
                result.xelem (i) = Complex (re_val.xelem (i), im_val);
 
              retval = octave_value (new octave_complex_matrix (result));
            }
          else
            {
              const NDArray im_val = im.array_value ();
 
              if (re_val.dims () != im_val.dims ())
                error ("complex: dimension mismatch");
 
              ComplexNDArray result (re_val.dims (), Complex ());
 
              for (octave_idx_type i = 0; i < re_val.numel (); i++)
                result.xelem (i) = Complex (re_val.xelem (i),
                                            im_val.xelem (i));
 
              retval = octave_value (new octave_complex_matrix (result));
            }
        }
    }
 
  return retval;
}
 
/*
%!error <undefined> 1+Infj
%!error <undefined> 1+Infi
 
%!test <31974>
%! assert (Inf + Inf*i, complex (Inf, Inf));
%!
%! assert (1 + Inf*i, complex (1, Inf));
%! assert (1 + Inf*j, complex (1, Inf));
%!
%! ## whitespace should not affect parsing
%! assert (1+Inf*i, complex (1, Inf));
%! assert (1+Inf*j, complex (1, Inf));
%!
%! assert (NaN*j, complex (0, NaN));
%!
%! assert (Inf * 4j, complex (0, Inf));
 
%!test <31974>
%! x = Inf;
%! assert (x * j, complex (0, Inf));
%! j = complex (0, 1);
%! assert (Inf * j, complex (0, Inf));
 
%!test <31974>
%! exp = complex (zeros (2, 2), Inf (2, 2));
%! assert (Inf (2, 2) * j, exp);
%! assert (Inf (2, 2) .* j, exp);
%! assert (Inf * (ones (2, 2) * j), exp);
%! assert (Inf (2, 2) .* (ones (2, 2) * j), exp);
 
%!test <31974>
%! assert ([Inf; 0] * [i, 0], complex ([NaN NaN; 0 0], [Inf NaN; 0 0]));
%! assert ([Inf, 0] * [i; 0], complex (NaN, Inf));
%! assert ([Inf, 0] .* [i, 0], complex ([0 0], [Inf 0]));
 
%!test <31974>
%! m = @(x, y) x * y;
%! d = @(x, y) x / y;
%! assert (m (Inf, i), complex (0, +Inf));
%! assert (d (Inf, i), complex (0, -Inf));
*/
 
DEFUN (isreal, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{tf} =} isreal (@var{x})
Return true if @var{x} is a non-complex matrix or scalar.
 
For compatibility with @sc{matlab}, this includes logical and character
matrices.
@seealso{iscomplex, isnumeric, isa}
@end deftypefn */)
{
  if (args.length () != 1)
    print_usage ();
 
  return ovl (args(0).isreal ());
}
 
DEFUN (isempty, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{tf} =} isempty (@var{A})
Return true if @var{A} is an empty object (any one of its dimensions is
zero).
@seealso{isnull, isa}
@end deftypefn */)
{
  if (args.length () != 1)
    print_usage ();
 
  return ovl (args(0).isempty ());
}
 
/*
## Debian bug #706376
%!assert (isempty (speye (2^16)), false)
*/
 
DEFUN (isnumeric, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{tf} =} isnumeric (@var{x})
Return true if @var{x} is a numeric object, i.e., an integer, real, or
complex array.
 
Logical and character arrays are not considered to be numeric.
@seealso{isinteger, isfloat, isreal, iscomplex, ischar, islogical, isstring,
iscell, isstruct, isa}
@end deftypefn */)
{
  if (args.length () != 1)
    print_usage ();
 
  return ovl (args(0).isnumeric ());
}
 
/*
%!assert (isnumeric (1), true)
%!assert (isnumeric (1i), true)
%!assert (isnumeric ([1,1]), true)
%!assert (isnumeric (single (1)), true)
%!assert (isnumeric (single (1i)), true)
%!assert (isnumeric (single ([1,1])), true)
%!assert (isnumeric (int8 (1)), true)
%!assert (isnumeric (uint8 ([1,1])), true)
%!assert (isnumeric ("Hello World"), false)
%!assert (isnumeric (true), false)
%!assert (isnumeric (false), false)
%!assert (isnumeric ([true, false]), false)
%!assert (isnumeric (sparse ([true, false])), false)
*/
 
DEFUN (isscalar, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{tf} =} isscalar (@var{x})
Return true if @var{x} is a scalar.
 
A scalar is a single-element object of any type for which @code{size (@var{x})}
returns @w{@code{[1, 1]}}.
@seealso{isvector, ismatrix, size}
@end deftypefn */)
{
  if (args.length () != 1)
    print_usage ();
 
  // This function *must* use size() to determine the desired values to be
  // compatible with Matlab and to allow user-defined class overloading.
  Matrix sz = octave_value (args(0)).size ();
 
  return ovl (sz.numel () == 2 && sz(0) == 1 && sz(1) == 1);
}
 
/*
%!assert (isscalar (1))
%!assert (isscalar ([1, 2]), false)
%!assert (isscalar ([]), false)
%!assert (isscalar ([1, 2; 3, 4]), false)
 
%!assert (isscalar ("t"))
%!assert (isscalar ("test"), false)
%!assert (isscalar (["test"; "ing"]), false)
 
%!test
%! s.a = 1;
%! assert (isscalar (s));
 
## Test input validation
%!error isscalar ()
%!error isscalar (1, 2)
*/
 
DEFUN (isvector, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{tf} =} isvector (@var{x})
Return true if @var{x} is a vector.
 
A vector is a 2-D array of any type where one of the dimensions is equal to 1
(either @nospell{1xN} or @nospell{Nx1}).  As a consequence of this definition,
a 1x1 object (a scalar) is also a vector.
@seealso{isscalar, ismatrix, iscolumn, isrow, size}
@end deftypefn */)
{
  if (args.length () != 1)
    print_usage ();
 
  // This function *must* use size() to determine the desired values to be
  // compatible with Matlab and to allow user-defined class overloading.
  Matrix sz = octave_value (args(0)).size ();
 
  return ovl (sz.numel () == 2 && (sz(0) == 1 || sz(1) == 1));
}
 
/*
%!assert (isvector (1), true)
%!assert (isvector ([1; 2; 3]), true)
%!assert (isvector ([1, 2, 3]), true)
%!assert (isvector ([]), false)
%!assert (isvector ([1, 2; 3, 4]), false)
 
%!assert (isvector ("t"), true)
%!assert (isvector ("test"), true)
%!assert (isvector (["test"; "ing"]), false)
 
%!test
%! s.a = 1;
%! assert (isvector (s), true);
 
## Test input validation
%!error isvector ()
%!error isvector ([1, 2], 2)
*/
 
DEFUN (isrow, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{tf} =} isrow (@var{x})
Return true if @var{x} is a row vector.
 
A row vector is a 2-D array of any type for which @code{size (@var{x})} returns
@w{@code{[1, N]}}@ with non-negative N.
@seealso{iscolumn, isscalar, isvector, ismatrix, size}
@end deftypefn */)
{
  if (args.length () != 1)
    print_usage ();
 
  // This function *must* use size() to determine the desired values to be
  // compatible with Matlab and to allow user-defined class overloading.
  Matrix sz = octave_value (args(0)).size ();
 
  return ovl (sz.numel () == 2 && sz(0) == 1);
}
 
/*
%!assert (isrow ([1, 2, 3]))
%!assert (isrow ([1; 2; 3]), false)
%!assert (isrow (1))
%!assert (isrow ([]), false)
%!assert (isrow ([1, 2; 3, 4]), false)
 
%!assert (isrow (ones (1, 0)), true)
%!assert (isrow (ones (1, 1)), true)
%!assert (isrow (ones (1, 2)), true)
%!assert (isrow (ones (1, 1, 1)), true)
%!assert (isrow (ones (1, 1, 1, 1)), true)
 
%!assert (isrow (ones (0, 0)), false)
%!assert (isrow (ones (1, 1, 0)), false)
 
%!assert (isrow ("t"), true)
%!assert (isrow ("test"), true)
%!assert (isrow (["test"; "ing"]), false)
 
%!test
%! s.a = 1;
%! assert (isrow (s), true);
 
## Test input validation
%!error isrow ()
%!error isrow ([1, 2], 2)
*/
 
DEFUN (iscolumn, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{tf} =} iscolumn (@var{x})
Return true if @var{x} is a column vector.
 
A column vector is a 2-D array of any type for which @code{size (@var{x})}
returns @w{@code{[N, 1]}}@ with non-negative N.
@seealso{isrow, isscalar, isvector, ismatrix, size}
@end deftypefn */)
{
  if (args.length () != 1)
    print_usage ();
 
  // This function *must* use size() to determine the desired values to be
  // compatible with Matlab and to allow user-defined class overloading.
  Matrix sz = octave_value (args(0)).size ();
 
  return ovl (sz.numel () == 2 && sz(1) == 1);
}
 
/*
%!assert (iscolumn ([1, 2, 3]), false)
%!assert (iscolumn ([1; 2; 3]), true)
%!assert (iscolumn (1), true)
%!assert (iscolumn ([]), false)
%!assert (iscolumn ([1, 2; 3, 4]), false)
 
%!assert (iscolumn ("t"), true)
%!assert (iscolumn ("test"), false)
%!assert (iscolumn (["test"; "ing"]), false)
 
%!assert (iscolumn (ones (0, 1)), true)
%!assert (iscolumn (ones (1, 1)), true)
%!assert (iscolumn (ones (2, 1)), true)
%!assert (iscolumn (ones (1, 1, 1)), true)
%!assert (iscolumn (ones (1, 1, 1, 1)), true)
 
%!assert (iscolumn (ones (0, 0)), false)
%!assert (iscolumn (ones (0, 1, 0)), false)
 
%!test
%! s.a = 1;
%! assert (iscolumn (s));
 
## Test input validation
%!error iscolumn ()
%!error iscolumn ([1, 2], 2)
*/
 
DEFUN (ismatrix, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{tf} =} ismatrix (@var{x})
Return true if @var{x} is a 2-D array.
 
A matrix is an array of any type where @code{ndims (@var{x}) == 2} and for
which @code{size (@var{x})} returns @w{@code{[M, N]}}@ with non-negative M and
N.
@seealso{isscalar, isvector, iscell, isstruct, issparse, isa}
@end deftypefn */)
{
  if (args.length () != 1)
    print_usage ();
 
  // This function *must* use size() to determine the desired values to be
  // compatible with Matlab and to allow user-defined class overloading.
  Matrix sz = octave_value (args(0)).size ();
 
  return ovl (sz.numel () == 2 && sz(0) >= 0 && sz(1) >= 0);
}
 
/*
%!assert (ismatrix ([]), true)
%!assert (ismatrix (1), true)
%!assert (ismatrix ([1, 2, 3]), true)
%!assert (ismatrix ([1, 2; 3, 4]), true)
 
%!assert (ismatrix (zeros (0)), true)
%!assert (ismatrix (zeros (0, 0)), true)
%!assert (ismatrix (zeros (0, 0, 0)), false)
%!assert (ismatrix (zeros (3, 2, 4)), false)
 
%!assert (ismatrix (single ([])), true)
%!assert (ismatrix (single (1)), true)
%!assert (ismatrix (single ([1, 2, 3])), true)
%!assert (ismatrix (single ([1, 2; 3, 4])), true)
 
%!assert (ismatrix ("t"), true)
%!assert (ismatrix ("test"), true)
%!assert (ismatrix (["test"; "ing"]), true)
 
%!test
%! s.a = 1;
%! assert (ismatrix (s), true);
 
%!error ismatrix ()
%!error ismatrix ([1, 2; 3, 4], 2)
*/
 
DEFUN (issquare, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{tf} =} issquare (@var{x})
Return true if @var{x} is a 2-D square array.
 
A square array is a 2-D array of any type for which @code{size (@var{x})}
returns @w{@code{[N, N]}}@ where N is a non-negative integer.
@seealso{isscalar, isvector, ismatrix, size}
@end deftypefn */)
{
  if (args.length () != 1)
    print_usage ();
 
  // This function *must* use size() to determine the desired values to
  // allow user-defined class overloading.
  Matrix sz = octave_value (args(0)).size ();
 
  return ovl (sz.numel () == 2 && sz(0) == sz(1));
}
 
/*
%!assert (issquare ([]))
%!assert (issquare (1))
%!assert (! issquare ([1, 2]))
%!assert (issquare ([1, 2; 3, 4]))
%!assert (! issquare ([1, 2; 3, 4; 5, 6]))
%!assert (! issquare (ones (3,3,3)))
%!assert (issquare ("t"))
%!assert (! issquare ("test"))
%!assert (issquare (["test"; "ing"; "1"; "2"]))
%!test
%! s.a = 1;
%! assert (issquare (s));
%!assert (issquare ({1, 2; 3, 4}))
%!assert (sparse (([1, 2; 3, 4])))
 
## Test input validation
%!error issquare ()
%!error issquare ([1, 2; 3, 4], 2)
*/
 
static octave_value
fill_matrix (const octave_value_list& args, int val, const char *fcn)
{
  octave_value retval;
 
  int nargin = args.length ();
 
  oct_data_conv::data_type dt = oct_data_conv::dt_double;
 
  dim_vector dims (1, 1);
  bool issparse = false;
  bool iscomplex = false;
 
  if (nargin > 0 && args(nargin-1).is_string ())
    {
      std::string nm = args(nargin-1).string_value ();
      nargin--;
 
      dt = oct_data_conv::string_to_data_type (nm);
    }
 
  if (nargin > 1 && args(nargin-2).is_string ()
      && args(nargin-2).string_value () == "like")
    {
      std::string nm = args(nargin-1).class_name ();
      issparse = args(nargin-1).issparse ();
      iscomplex = args(nargin-1).iscomplex ();
      nargin -= 2;
      dt = oct_data_conv::string_to_data_type (nm);
    }
 
  switch (nargin)
    {
    case 0:
      break;
 
    case 1:
      get_dimensions (args(0), fcn, dims);
      break;
 
    default:
      {
        dims.resize (nargin);
 
        for (int i = 0; i < nargin; i++)
          {
            if (args(i).numel () > 1)
              error ("%s: dimensions must be scalars.", fcn);
 
            dims(i) = (args(i).isempty () ? 0 : args(i).idx_type_value (true));
          }
      }
      break;
    }
 
  dims.chop_trailing_singletons ();
 
  check_dimensions (dims, fcn);
 
  // FIXME: Perhaps this should be made extensible by using the class name
  //        to lookup a function to call to create the new value.
 
  // Note that automatic narrowing will handle conversion from
  // NDArray to scalar.
 
  if (issparse)
    {
      if (dims.ndims () > 2)
        error ("%s: sparse ND arrays not supported.", fcn);
 
      switch (dt)
        {
        case oct_data_conv::dt_double:
          if (iscomplex)
            retval = SparseComplexMatrix (dims(0), dims(1), Complex (val, 0));
          else
            retval = SparseMatrix (dims(0), dims(1), static_cast<double> (val));
          break;
 
        case oct_data_conv::dt_logical:
          retval = SparseBoolMatrix (dims(0), dims(1), static_cast<bool> (val));
          break;
 
        default:
          // FIXME: It shouldn't be possible to ever reach this.
          error ("%s: invalid class name for sparse", fcn);
        }
 
      return retval;
    }
 
  switch (dt)
    {
    case oct_data_conv::dt_int8:
      retval = int8NDArray (dims, val);
      break;
 
    case oct_data_conv::dt_uint8:
      retval = uint8NDArray (dims, val);
      break;
 
    case oct_data_conv::dt_int16:
      retval = int16NDArray (dims, val);
      break;
 
    case oct_data_conv::dt_uint16:
      retval = uint16NDArray (dims, val);
      break;
 
    case oct_data_conv::dt_int32:
      retval = int32NDArray (dims, val);
      break;
 
    case oct_data_conv::dt_uint32:
      retval = uint32NDArray (dims, val);
      break;
 
    case oct_data_conv::dt_int64:
      retval = int64NDArray (dims, val);
      break;
 
    case oct_data_conv::dt_uint64:
      retval = uint64NDArray (dims, val);
      break;
 
    case oct_data_conv::dt_single:
      if (iscomplex)
        retval = FloatComplexNDArray (dims, val);
      else
        retval = FloatNDArray (dims, val);
      break;
 
    case oct_data_conv::dt_double:
      if (iscomplex)
        retval = ComplexNDArray (dims, Complex (val, 0));
      else
        retval = NDArray (dims, val);
      break;
 
    case oct_data_conv::dt_logical:
      retval = boolNDArray (dims, val);
      break;
 
    default:
      error ("%s: invalid class name", fcn);
      break;
    }
 
  return retval;
}
 
static octave_value
fill_matrix (const octave_value_list& args, double val, float fval,
             const char *fcn)
{
  octave_value retval;
 
  int nargin = args.length ();
 
  oct_data_conv::data_type dt = oct_data_conv::dt_double;
 
  dim_vector dims (1, 1);
  bool issparse = false;
  bool iscomplex = false;
 
  if (nargin > 0 && args(nargin-1).is_string ())
    {
      std::string nm = args(nargin-1).string_value ();
      nargin--;
 
      dt = oct_data_conv::string_to_data_type (nm);
    }
 
  if (nargin > 1 && args(nargin-2).is_string ()
      && args(nargin-2).string_value () == "like"
      && (std::string(fcn) ==  "Inf"
          || std::string(fcn) == "NaN" || std::string(fcn) == "NA"))
    {
      if (! args(nargin-1).isfloat ())
        error ("%s: input followed by 'like' must be floating point", fcn);
      std::string nm = args(nargin-1).class_name ();
      issparse = args(nargin-1).issparse ();
      iscomplex = args(nargin-1).iscomplex ();
      nargin -= 2;
      dt = oct_data_conv::string_to_data_type (nm);
    }
 
  switch (nargin)
    {
    case 0:
      break;
 
    case 1:
      get_dimensions (args(0), fcn, dims);
      break;
 
    default:
      {
        dims.resize (nargin);
 
        for (int i = 0; i < nargin; i++)
          {
            if (args(i).numel () > 1)
              error ("%s: dimensions must be scalars.", fcn);
 
            dims(i) = (args(i).isempty () ? 0 : args(i).idx_type_value (true));
          }
      }
      break;
    }
 
  dims.chop_trailing_singletons ();
 
  check_dimensions (dims, fcn);
 
  // Note that automatic narrowing will handle conversion from
  // NDArray to scalar.
 
  if (issparse)
    {
      if (dims.ndims () > 2)
        error ("%s: sparse ND arrays not supported", fcn);
 
      if (iscomplex)
        retval = SparseComplexMatrix (dims(0), dims(1), Complex (val, 0));
      else
        retval = SparseMatrix (dims(0), dims(1), static_cast<double> (val));
 
      return retval;
    }
 
  switch (dt)
    {
    case oct_data_conv::dt_single:
      if (iscomplex)
        retval = FloatComplexNDArray (dims, fval);
      else
        retval = FloatNDArray (dims, fval);
      break;
 
    case oct_data_conv::dt_double:
      if (iscomplex)
        retval = ComplexNDArray (dims, Complex (val, 0));
      else
        retval = NDArray (dims, val);
      break;
 
    default:
      error ("%s: invalid class name", fcn);
      break;
    }
 
  return retval;
}
 
static octave_value
fill_matrix (const octave_value_list& args, double val, const char *fcn)
{
  octave_value retval;
 
  int nargin = args.length ();
 
  oct_data_conv::data_type dt = oct_data_conv::dt_double;
 
  dim_vector dims (1, 1);
 
  if (nargin > 0 && args(nargin-1).is_string ())
    {
      std::string nm = args(nargin-1).string_value ();
      nargin--;
 
      dt = oct_data_conv::string_to_data_type (nm);
    }
 
  switch (nargin)
    {
    case 0:
      break;
 
    case 1:
      get_dimensions (args(0), fcn, dims);
      break;
 
    default:
      {
        dims.resize (nargin);
 
        for (int i = 0; i < nargin; i++)
          {
            if (args(i).numel () > 1)
              error ("%s: dimensions must be scalars.", fcn);
 
            dims(i) = (args(i).isempty () ? 0 : args(i).idx_type_value (true));
          }
      }
      break;
    }
 
  dims.chop_trailing_singletons ();
 
  check_dimensions (dims, fcn);
 
  // Note that automatic narrowing will handle conversion from
  // NDArray to scalar.
 
  switch (dt)
    {
    case oct_data_conv::dt_single:
      retval = FloatNDArray (dims, static_cast<float> (val));
      break;
 
    case oct_data_conv::dt_double:
      retval = NDArray (dims, val);
      break;
 
    default:
      error ("%s: invalid class name", fcn);
      break;
    }
 
  return retval;
}
 
static octave_value
fill_matrix (const octave_value_list& args, const Complex& val,
             const char *fcn)
{
  octave_value retval;
 
  int nargin = args.length ();
 
  oct_data_conv::data_type dt = oct_data_conv::dt_double;
 
  dim_vector dims (1, 1);
 
  if (nargin > 0 && args(nargin-1).is_string ())
    {
      std::string nm = args(nargin-1).string_value ();
      nargin--;
 
      dt = oct_data_conv::string_to_data_type (nm);
    }
 
  switch (nargin)
    {
    case 0:
      break;
 
    case 1:
      get_dimensions (args(0), fcn, dims);
      break;
 
    default:
      {
        dims.resize (nargin);
 
        for (int i = 0; i < nargin; i++)
          {
            if (args(i).numel () > 1)
              error ("%s: dimensions must be scalars.", fcn);
 
            dims(i) = (args(i).isempty () ? 0 : args(i).idx_type_value (true));
          }
      }
      break;
    }
 
  dims.chop_trailing_singletons ();
 
  check_dimensions (dims, fcn);
 
  // Note that automatic narrowing will handle conversion from
  // NDArray to scalar.
 
  switch (dt)
    {
    case oct_data_conv::dt_single:
      retval = FloatComplexNDArray (dims,
                                    static_cast<FloatComplex> (val));
      break;
 
    case oct_data_conv::dt_double:
      retval = ComplexNDArray (dims, val);
      break;
 
    default:
      error ("%s: invalid class name", fcn);
      break;
    }
 
  return retval;
}
 
static octave_value
fill_matrix (const octave_value_list& args, bool val, const char *fcn)
{
  octave_value retval;
 
  int nargin = args.length ();
 
  dim_vector dims (1, 1);
 
  // The TYPE argument is required to be "logical" if present.  This
  // feature appears to be undocumented in Matlab.
 
  if (nargin > 0 && args(nargin-1).is_string ())
    {
      std::string nm = args(nargin-1).string_value ();
      nargin--;
 
      if (oct_data_conv::string_to_data_type (nm) != oct_data_conv::dt_logical)
        error ("%s: invalid data type '%s'", fcn, nm.c_str ());
    }
 
  bool issparse = false;
 
  if (nargin > 1 && args(nargin-2).is_string ()
      && args(nargin-2).string_value () == "like")
    {
      if (! args(nargin-1).islogical ())
        error (R"(%s: input followed by "like" must be logical)", fcn);
 
      issparse = args(nargin-1).issparse ();
      nargin -= 2;
    }
 
  switch (nargin)
    {
    case 0:
      break;
 
    case 1:
      get_dimensions (args(0), fcn, dims);
      break;
 
    default:
      {
        dims.resize (nargin);
 
        for (int i = 0; i < nargin; i++)
          {
            if (args(i).numel () > 1)
              error ("%s: dimensions must be scalars.", fcn);
 
            dims(i) = (args(i).isempty () ? 0 : args(i).idx_type_value (true));
          }
      }
      break;
    }
 
  dims.chop_trailing_singletons ();
 
  check_dimensions (dims, fcn);
 
  // Note that automatic narrowing will handle conversion from
  // NDArray to scalar.
 
  if (issparse)
    {
      if (dims.ndims () > 2)
        error ("%s: sparse ND arrays not supported", fcn);
 
      retval = SparseBoolMatrix (dims(0), dims(1), val);
    }
  else
    retval = boolNDArray (dims, val);
 
  return retval;
}
 
DEFUN (ones, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{x} =} ones ()
@deftypefnx {} {@var{x} =} ones (@var{n})
@deftypefnx {} {@var{x} =} ones (@var{m}, @var{n}, @dots{})
@deftypefnx {} {@var{x} =} ones ([@var{m}, @var{n}, @dots{}])
@deftypefnx {} {@var{x} =} ones (@dots{}, @var{class})
@deftypefnx {} {@var{x} =} ones (@dots{}, "like", @var{var})
Return a scalar, matrix, or N-dimensional array whose elements are all
@code{1}.
 
If called with no arguments, return the scalar value @code{1}.
 
If invoked with a single scalar integer argument @var{n}, return a square
@nospell{NxN} matrix.
 
If invoked with two or more scalar integer arguments, or a vector of integer
values, return an array with the given dimensions.
 
The optional argument @var{class} specifies the class of the return array
and defaults to @qcode{"double"}.
 
If a variable @var{var} is specified after @qcode{"like"}, the output @var{val}
will have the same data type, complexity, and sparsity as @var{var}.
 
Example 1 : @nospell{MxN} matrix of constant value @var{val}
 
@example
@var{C} = @var{val} * ones (@var{m}, @var{n})
@end example
 
Example 2 : @nospell{MxN} matrix of uint8
 
@example
@var{C} = ones (@var{m}, @var{n}, "uint8")
@end example
 
Programming Note: Any negative dimensions are treated as zero, and any zero
dimensions will result in an empty matrix.  This odd behavior is for
@sc{matlab} compatibility.
@seealso{zeros, true, false}
@end deftypefn */)
{
  return fill_matrix (args, 1, "ones");
}
 
/*
%!assert (ones (), 1)
%!assert (ones (3), [1, 1, 1; 1, 1, 1; 1, 1, 1])
%!assert (ones (2, 3), [1, 1, 1; 1, 1, 1])
%!assert (ones (3, 2), [1, 1; 1, 1; 1, 1])
%!assert (size (ones (3, 4, 5)), [3, 4, 5])
 
%!assert (ones ("single"), single (1))
%!assert (ones (3, "single"), single ([1, 1, 1; 1, 1, 1; 1, 1, 1]))
%!assert (ones (2, 3, "single"), single ([1, 1, 1; 1, 1, 1]))
%!assert (ones (3, 2, "single"), single ([1, 1; 1, 1; 1, 1]))
%!assert (size (ones (3, 4, 5, "single")), [3, 4, 5])
 
%!assert (ones ("int8"), int8 (1))
%!assert (ones (3, "int8"), int8 ([1, 1, 1; 1, 1, 1; 1, 1, 1]))
%!assert (ones (2, 3, "int8"), int8 ([1, 1, 1; 1, 1, 1]))
%!assert (ones (3, 2, "int8"), int8 ([1, 1; 1, 1; 1, 1]))
%!assert (size (ones (3, 4, 5, "int8")), [3, 4, 5])
 
%!assert (ones (2, 2, "like", double (1)), double ([1, 1; 1, 1]))
%!assert (ones (2, 2, "like", complex (ones (2, 2))), [1, 1; 1, 1])
%!assert (ones (1, 2, "like", single (1)), single ([1, 1]))
%!assert (ones (1, "like", single (1i)), single (1))
%!assert (ones (2, 2, "like", uint8 (8)), uint8 ([1, 1; 1, 1]))
%!assert (ones (2, "like", speye (2)), sparse ([1, 1; 1, 1]))
%!assert (ones (2, "like", sparse (1i)), sparse (complex ([1, 1; 1, 1])))
 
## Note: Matlab compatibility requires using 0 for negative dimensions.
%!assert (size (ones (1, -2, 2)), [1, 0, 2])
 
## Test input validation
%!error <invalid data type specified> ones (1, 1, "foobar")
%!error <conversion of 1.1 .*failed> ones (1.1)
%!error <conversion of 1.1 .*failed> ones (1, 1.1)
%!error <conversion of 1.1 .*failed> ones ([1, 1.1])
%!error <sparse ND .* not supported> ones (3, 3, 3, "like", speye (1))
%!error <must be scalar> ones (1:3, 1)
%!error <must be scalar> ones (1, 1:3)
%!error <must be scalar> ones (1, 2, 1:3)
%!error <must be scalar> ones (1:3, 1, "like", single (1))
*/
 
/*
## Tests for bug #47298
## Matlab requires the size to be a row vector.  In that logic, it supports
## n to be a 1x0 vector (returns 0x0) but not a 0x1 vector.  Octave supports
## row and column vectors and therefore must support 0x1, 1x0, and 0x1x1.
## Also any empty input results in a 0x0 output.
%!test <*47298>
%! fcns = {@zeros, @ones, @inf, @nan, @NA, @i, @pi, @e};
%! for idx = 1:numel (fcns)
%!   fcn = fcns{idx};
%!   assert (fcn (zeros (1, 0)), zeros (0, 0));
%!   assert (fcn (zeros (0, 1)), zeros (0, 0));
%!   assert (fcn (zeros (0, 1, 1)), zeros (0, 0));
%!   assert (fcn (zeros ([])), zeros (0, 0));
%!   assert (fcn (zeros (0, 0, 1)), zeros (0, 0));
%! endfor
*/
 
DEFUN (zeros, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{x} =} zeros ()
@deftypefnx {} {@var{x} =} zeros (@var{n})
@deftypefnx {} {@var{x} =} zeros (@var{m}, @var{n}, @dots{})
@deftypefnx {} {@var{x} =} zeros ([@var{m}, @var{n}, @dots{}])
@deftypefnx {} {@var{x} =} zeros (@dots{}, @var{class})
@deftypefnx {} {@var{x} =} zeros (@dots{}, "like", @var{var})
Return a scalar, matrix, or N-dimensional array whose elements are all
@code{0}.
 
If called with no arguments, return the scalar value @code{0}.
 
If invoked with a single scalar integer argument @var{n}, return a square
@nospell{NxN} matrix.
 
If invoked with two or more scalar integer arguments, or a vector of integer
values, return an array with the given dimensions.
 
The optional argument @var{class} specifies the class of the return array
and defaults to @qcode{"double"}.
 
If a variable @var{var} is specified after @qcode{"like"}, the output @var{val}
will have the same data type, complexity, and sparsity as @var{var}.
 
Example : @nospell{MxN} matrix of uint8
 
@example
@var{C} = ones (@var{m}, @var{n}, "uint8")
@end example
 
Programming Note: Any negative dimensions are treated as zero, and any zero
dimensions will result in an empty matrix.  This odd behavior is for
@sc{matlab} compatibility.
@seealso{ones, true, false}
@end deftypefn */)
{
  return fill_matrix (args, 0, "zeros");
}
 
/*
%!assert (zeros (), 0)
%!assert (zeros (3), [0, 0, 0; 0, 0, 0; 0, 0, 0])
%!assert (zeros (2, 3), [0, 0, 0; 0, 0, 0])
%!assert (zeros (3, 2), [0, 0; 0, 0; 0, 0])
%!assert (size (zeros (3, 4, 5)), [3, 4, 5])
 
%!assert (zeros ("single"), single (0))
%!assert (zeros (3, "single"), single ([0, 0, 0; 0, 0, 0; 0, 0, 0]))
%!assert (zeros (2, 3, "single"), single ([0, 0, 0; 0, 0, 0]))
%!assert (zeros (3, 2, "single"), single ([0, 0; 0, 0; 0, 0]))
%!assert (size (zeros (3, 4, 5, "single")), [3, 4, 5])
 
%!assert (zeros ("int8"), int8 (0))
%!assert (zeros (3, "int8"), int8 ([0, 0, 0; 0, 0, 0; 0, 0, 0]))
%!assert (zeros (2, 3, "int8"), int8 ([0, 0, 0; 0, 0, 0]))
%!assert (zeros (3, 2, "int8"), int8 ([0, 0; 0, 0; 0, 0]))
%!assert (size (zeros (3, 4, 5, "int8")), [3, 4, 5])
 
%!assert (zeros (2, 2, "like", double (1)), double ([0, 0; 0, 0]))
%!assert (zeros (2, 2, "like", complex (ones (2, 2))), [0, 0; 0, 0])
%!assert (zeros (1, 2, "like", single (1)), single ([0, 0]))
%!assert (zeros (1, 2, "like", single (1i)), single ([0, 0]))
%!assert (zeros (2, 2, "like", uint8 (8)), uint8 ([0, 0; 0, 0]))
%!assert (zeros (2, "like", speye (2)), sparse ([0, 0; 0, 0]))
 
## Test input validation
%!error <invalid data type specified> zeros (1, 1, "foobar")
%!error <conversion of 1.1 .*failed> zeros (1.1)
%!error <conversion of 1.1 .*failed> zeros (1, 1.1)
%!error <conversion of 1.1 .*failed> zeros ([1, 1.1])
%!error <sparse ND .* not supported> zeros (3, 3, 3, "like", speye (1))
%!error <must be scalar> zeros (1:3, 1)
%!error <must be scalar> zeros (1, 1:3)
%!error <must be scalar> zeros (1, 2, 1:3)
%!error <must be scalar> zeros (1:3, 1, "like", single (1))
*/
 
DEFUN (Inf, args, ,
       doc: /* -*- texinfo -*-
@c List other form of function in documentation index
@findex inf
 
@deftypefn  {} {@var{x} =} Inf
@deftypefnx {} {@var{x} =} Inf (@var{n})
@deftypefnx {} {@var{x} =} Inf (@var{m}, @var{n}, @dots{})
@deftypefnx {} {@var{x} =} Inf ([@var{m}, @var{n}, @dots{}])
@deftypefnx {} {@var{x} =} Inf (@dots{}, @var{class})
@deftypefnx {} {@var{x} =} Inf (@dots{}, "like", @var{var})
Return a scalar, matrix or N-dimensional array whose elements are all equal
to the IEEE@tie{}754 representation for positive infinity.
 
Infinity is produced when results are too large to be represented using the
IEEE@tie{}754 floating point format for numbers.  Two common examples which
produce infinity are division by zero and overflow.
 
@example
@group
[ 1/0 e^800 ]
@xresult{} Inf   Inf
@end group
@end example
 
If called with no arguments, return the scalar value @code{Inf}.
 
If invoked with a single scalar integer argument @var{n}, return a square
@nospell{NxN} matrix.
 
If invoked with two or more scalar integer arguments, or a vector of integer
values, return an array with the given dimensions.
 
The optional argument @var{class} specifies the class of the return array.
The only valid options are @qcode{"double"} (default) or @qcode{"single"}.
 
If a variable @var{var} is specified after @qcode{"like"}, the output @var{x}
will have the same data type, complexity, and sparsity as @var{var}.
@seealso{isinf, NaN}
@end deftypefn */)
{
  return fill_matrix (args, lo_ieee_inf_value (),
                      lo_ieee_float_inf_value (), "Inf");
}
 
DEFALIAS (inf, Inf);
 
/*
%!assert (Inf (3), [Inf, Inf, Inf; Inf, Inf, Inf; Inf, Inf, Inf])
%!assert (Inf (2, 3), [Inf, Inf, Inf; Inf, Inf, Inf])
%!assert (Inf (3, 2), [Inf, Inf; Inf, Inf; Inf, Inf])
%!assert (size (Inf (3, 4, 5)), [3, 4, 5])
 
%!assert (Inf (3, "single"),
%!        single ([Inf, Inf, Inf; Inf, Inf, Inf; Inf, Inf, Inf]))
%!assert (Inf (2, 3, "single"), single ([Inf, Inf, Inf; Inf, Inf, Inf]))
%!assert (Inf (3, 2, "single"), single ([Inf, Inf; Inf, Inf; Inf, Inf]))
%!assert (size (inf (3, 4, 5, "single")), [3, 4, 5])
 
## Note: Matlab compatibility requires using 0 for negative dimensions.
%!assert (size (Inf (2, -3, 2)), [2, 0, 2])
 
%!assert (Inf (2, 2, "like", speye (2)), sparse ([Inf, Inf; Inf, Inf]))
%!assert (Inf (2, 2, "like", complex (ones (2, 2))), [Inf, Inf; Inf, Inf])
%!assert (Inf (2, 2, "like", double (1)), double ([Inf, Inf; Inf, Inf]))
%!assert (Inf (3, 3, "like", single (1)),
%!        single ([Inf, Inf, Inf; Inf, Inf, Inf; Inf, Inf, Inf]))
%!assert (Inf (2, "like", single (1i)), single ([Inf, Inf; Inf, Inf]))
 
%!error Inf (3, "like", int8 (1))
 
%!error Inf (3, "int8")
%!error Inf (2, 3, "int8")
%!error Inf (3, 2, "int8")
%!error Inf (3, 4, 5, "int8")
%!error <input .* floating> Inf (3, 3, "like", true)
%!error <input .* floating> Inf (2, "like", uint8 (1))
%!error <must be scalar> Inf (1:3, 1)
%!error <must be scalar> Inf (1, 1:3)
%!error <must be scalar> Inf (1, 2, 1:3)
%!error <must be scalar> Inf (1:3, 1, "like", single (1))
*/
 
DEFUN (NaN, args, ,
       doc: /* -*- texinfo -*-
@c List other form of function in documentation index
@findex nan
 
@deftypefn  {} {@var{x} =} NaN
@deftypefnx {} {@var{x} =} NaN (@var{n})
@deftypefnx {} {@var{x} =} NaN (@var{m}, @var{n}, @dots{})
@deftypefnx {} {@var{x} =} NaN ([@var{m}, @var{n}, @dots{}])
@deftypefnx {} {@var{x} =} NaN (@dots{}, @var{class})
@deftypefnx {} {@var{x} =} NaN (@dots{}, "like", @var{var})
Return a scalar, matrix, or N-dimensional array whose elements are all equal
to the IEEE@tie{}754 symbol NaN (Not a Number).
 
@code{NaN} is the result of operations which do not produce a well defined
numerical result.  Common operations which produce a @code{NaN} are arithmetic
with infinity
@tex
($\infty - \infty$), zero divided by zero ($0/0$),
@end tex
@ifnottex
(Inf - Inf), zero divided by zero (0/0),
@end ifnottex
and any operation involving another @code{NaN} value (5 + @code{NaN}).
 
Note that @code{NaN} always compares not equal to @code{NaN}
(@code{NaN != NaN}).  This behavior is specified by the IEEE@tie{}754 standard
for floating point arithmetic.  To find @code{NaN} values, use the @code{isnan}
function.
 
If called with no arguments, return the scalar value @code{NaN}.
 
If invoked with a single scalar integer argument @var{n}, return a square
@nospell{NxN} matrix.
 
If invoked with two or more scalar integer arguments, or a vector of integer
values, return an array with the given dimensions.
 
The optional argument @var{class} specifies the class of the return array.
The only valid options are @qcode{"double"} (default) or @qcode{"single"}.
 
If a variable @var{var} is specified after @qcode{"like"}, the output @var{x}
will have the same data type, complexity, and sparsity as @var{var}.
@seealso{isnan, Inf}
@end deftypefn */)
{
  return fill_matrix (args, lo_ieee_nan_value (),
                      lo_ieee_float_nan_value (), "NaN");
}
 
DEFALIAS (nan, NaN);
 
/*
%!assert (NaN (3), [NaN, NaN, NaN; NaN, NaN, NaN; NaN, NaN, NaN])
%!assert (NaN (2, 3), [NaN, NaN, NaN; NaN, NaN, NaN])
%!assert (NaN (3, 2), [NaN, NaN; NaN, NaN; NaN, NaN])
%!assert (size (NaN (3, 4, 5)), [3, 4, 5])
 
%!assert (NaN (3, "single"),
%!        single ([NaN, NaN, NaN; NaN, NaN, NaN; NaN, NaN, NaN]))
%!assert (NaN (2, 3, "single"), single ([NaN, NaN, NaN; NaN, NaN, NaN]))
%!assert (NaN (3, 2, "single"), single ([NaN, NaN; NaN, NaN; NaN, NaN]))
%!assert (size (NaN (3, 4, 5, "single")), [3, 4, 5])
 
%!assert (NaN (2, 2, "like", double (1)), double ([NaN, NaN; NaN, NaN]))
%!assert (NaN (2, 2, "like", complex (ones(2, 2))), [NaN, NaN; NaN, NaN])
%!assert (NaN (3, 3, "like", single (1)),
%!        single ([NaN, NaN, NaN; NaN, NaN, NaN; NaN, NaN, NaN]))
%!assert (NaN (2, "like", single (1i)), single ([NaN, NaN; NaN, NaN]))
%!assert (NaN (2, 2, "like", speye (2)), sparse ([NaN, NaN; NaN, NaN]))
 
%!error NaN (3, 'like', int8 (1))
 
%!error NaN (3, "int8")
%!error NaN (2, 3, "int8")
%!error NaN (3, 2, "int8")
%!error NaN (3, 4, 5, "int8")
%!error <input .* floating> NaN (3, 3, "like", true)
%!error <input .* floating> NaN (2, "like", uint8 (1))
%!error <must be scalar> NaN (1:3, 1)
%!error <must be scalar> NaN (1, 1:3)
%!error <must be scalar> NaN (1, 2, 1:3)
%!error <must be scalar> NaN (1:3, 1, "like", single (1))
*/
 
DEFUN (e, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{x} =} e
@deftypefnx {} {@var{x} =} e (@var{n})
@deftypefnx {} {@var{x} =} e (@var{m}, @var{n}, @dots{})
@deftypefnx {} {@var{x} =} e ([@var{m}, @var{n}, @dots{}])
@deftypefnx {} {@var{x} =} e (@dots{}, @var{class})
Return a scalar, matrix, or N-dimensional array whose elements are all equal
to the base of natural logarithms.
 
The constant
@tex
$e$ satisfies the equation $\log (e) = 1$.
@end tex
@ifnottex
@samp{e} satisfies the equation @code{log} (e) = 1.
@end ifnottex
 
If called with no arguments, return the scalar value @math{e}.
 
If invoked with a single scalar integer argument @var{n}, return a square
@nospell{NxN} matrix.
 
If invoked with two or more scalar integer arguments, or a vector of integer
values, return an array with the given dimensions.
 
The optional argument @var{class} specifies the class of the return array.
The only valid options are @qcode{"double"} (default) or @qcode{"single"}.
@seealso{log, exp, pi, I}
@end deftypefn */)
{
#if defined (M_E)
  double e_val = M_E;
#else
  double e_val = exp (1.0);
#endif
 
  return fill_matrix (args, e_val, "e");
}
 
template <typename T>
T
eps (const T& x)
{
  T epsval = x.abs ();
  typedef typename T::value_type P;
  for (octave_idx_type i = 0; i < x.numel (); i++)
    {
      P val = epsval.xelem (i);
      if (math::isnan (val) || math::isinf (val))
        epsval(i) = numeric_limits<P>::NaN ();
      else if (val < std::numeric_limits<P>::min ())
        epsval(i) = std::numeric_limits<P>::denorm_min ();
      else
        {
          int exponent;
          math::frexp (val, &exponent);
          const P digits = std::numeric_limits<P>::digits;
          epsval(i) = std::pow (static_cast<P> (2.0),
                                static_cast<P> (exponent - digits));
        }
    }
  return epsval;
}
 
DEFUN (eps, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{d} =} eps
@deftypefnx {} {@var{d} =} eps (@var{x})
@deftypefnx {} {@var{d} =} eps (@var{m}, @var{n}, @dots{})
@deftypefnx {} {@var{d} =} eps ([@var{m}, @var{n}, @dots{}])
@deftypefnx {} {@var{d} =} eps (@dots{}, @var{class})
Return a scalar, matrix or N-dimensional array whose elements are eps,
the machine precision.
 
More precisely, @code{eps} is the relative spacing between any two adjacent
numbers in the machine's floating point system.  This number depends both on
the system and where the number lies in the range representable by the floating
point system.  On machines that support IEEE@tie{}754 floating point
arithmetic, @w{@code{eps (1.0)}} is approximately
@tex
$2.2204\times10^{-16}$ for double precision and $1.1921\times10^{-7}$
@end tex
@ifnottex
2.2204e-16 for double precision and 1.1921e-07
@end ifnottex
for single precision.
 
If called with no arguments, return the scalar value @w{@code{eps (1.0)}}.
 
Given a floating point argument @var{x}, return an array @var{d} of the same
size where each element is the distance between the element of @var{x} and
the next largest value.
 
If invoked with two or more scalar integer arguments, or a vector of integer
values, return an array with the given dimensions whose elements are all the
scalar value @code{eps}.
 
The optional argument @var{class} specifies the class of the return array.
The only valid options are @qcode{"double"} (default) or @qcode{"single"}.
@seealso{realmax, realmin, intmax, flintmax}
@end deftypefn */)
{
  octave_value retval;
 
  if (args.length () == 1 && ! args(0).is_string ())
    {
      octave_value arg0 = args(0);
      if (arg0.is_single_type ())
        {
          FloatNDArray epsval = eps (arg0.float_array_value ());
          retval = epsval;
        }
      else if (arg0.is_double_type ())
        {
          NDArray epsval = eps (arg0.array_value ());
          retval = epsval;
        }
      else
        error ("eps: X must be of a floating point type");
    }
  else
    retval = fill_matrix (args, std::numeric_limits<double>::epsilon (),
                          std::numeric_limits<float>::epsilon (), "eps");
 
  return retval;
}
 
/*
%!assert (eps (1/2), 2^(-53))
%!assert (eps (1), 2^(-52))
%!assert (eps (2), 2^(-51))
%!assert (eps (realmax), 2^971)
%!assert (eps (0), 2^(-1074))
%!assert (eps (realmin/2), 2^(-1074))
%!assert (eps (realmin/16), 2^(-1074))
%!assert (eps (Inf), NaN)
%!assert (eps (NaN), NaN)
%!assert (eps ([1/2 1 2 realmax 0 realmin/2 realmin/16 Inf NaN]),
%!        [2^-53 2^-52 2^-51 2^971 2^-1074 2^-1074 2^-1074 NaN NaN])
%!assert (eps (single (1/2)), single (2^(-24)))
%!assert (eps (single (1)), single (2^(-23)))
%!assert (eps (single (2)), single (2^(-22)))
%!assert (eps (realmax ("single")), single (2^104))
%!assert (eps (single (0)), single (2^(-149)))
%!assert (eps (realmin ("single")/2), single (2^(-149)))
%!assert (eps (realmin ("single")/16), single (2^(-149)))
%!assert (eps (single (Inf)), single (NaN))
%!assert (eps (single (NaN)), single (NaN))
%!assert (eps (single ([1/2 1 2 realmax("single") 0 realmin("single")/2 realmin("single")/16 Inf NaN])),
%!        single ([2^-24 2^-23 2^-22 2^104 2^-149 2^-149 2^-149 NaN NaN]))
 
## Note: Matlab compatibility requires using 0 for negative dimensions.
%!assert (size (eps (2, -3, 2)), [2, 0, 2])
 
%!error <X must be of a floating point type> eps (uint8 ([0 1 2]))
%!error <must be scalar> eps (1:3, 1)
%!error <must be scalar> eps (1, 1:3)
%!error <must be scalar> eps (1, 2, 1:3)
%!error <must be scalar> eps (1:3, 1, "single")
*/
 
DEFUN (pi, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{p} =} pi
@deftypefnx {} {@var{p} =} pi (@var{n})
@deftypefnx {} {@var{p} =} pi (@var{m}, @var{n}, @dots{})
@deftypefnx {} {@var{p} =} pi ([@var{m}, @var{n}, @dots{}])
@deftypefnx {} {@var{p} =} pi (@dots{}, @var{class})
Return a scalar, matrix, or N-dimensional array whose elements are all equal
to the ratio of the circumference of a circle to its
@tex
diameter($\pi$).
@end tex
@ifnottex
diameter.
@end ifnottex
 
If called with no arguments, return the scalar value
@tex
$\pi$.
@end tex
@ifnottex
pi.
@end ifnottex
 
If invoked with a single scalar integer argument @var{n}, return a square
@nospell{NxN} matrix.
 
If invoked with two or more scalar integer arguments, or a vector of integer
values, return an array with the given dimensions.
 
The optional argument @var{class} specifies the class of the return array.
The only valid options are @qcode{"double"} (default) or @qcode{"single"}.
@seealso{e, I}
@end deftypefn */)
{
#if defined (M_PI)
  double pi_val = M_PI;
#else
  double pi_val = 4.0 * atan (1.0);
#endif
 
  return fill_matrix (args, pi_val, "pi");
}
 
DEFUN (realmax, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{Rmax} =} realmax
@deftypefnx {} {@var{Rmax} =} realmax (@var{n})
@deftypefnx {} {@var{Rmax} =} realmax (@var{m}, @var{n}, @dots{})
@deftypefnx {} {@var{Rmax} =} realmax ([@var{m}, @var{n}, @dots{}])
@deftypefnx {} {@var{Rmax} =} realmax (@dots{}, @var{class})
@deftypefnx {} {@var{Rmax} =} realmax (@dots{}, "like", @var{var})
Return a scalar, matrix, or N-dimensional array whose elements are all equal
to the largest floating point number that is representable.
 
The actual value is system-dependent.  On machines that support IEEE@tie{}754
floating point arithmetic, @code{realmax} is approximately
@tex
$1.7977\times10^{308}$ for double precision and $3.4028\times10^{38}$
@end tex
@ifnottex
1.7977e+308 for double precision and 3.4028e+38
@end ifnottex
for single precision.
 
If called with no arguments, return the scalar value
@code{realmax (@qcode{"double"})}.
 
If invoked with a single scalar integer argument @var{n}, return a square
@nospell{NxN} matrix.
 
If invoked with two or more scalar integer arguments, or a vector of integer
values, return an array with the given dimensions.
 
The optional argument @var{class} specifies the class of the return array.
The only valid options are @qcode{"double"} (default) or @qcode{"single"}.
 
If a variable @var{var} is specified after @qcode{"like"}, the output
@var{Rmax} will have the same data type, complexity, and sparsity as @var{var}.
@seealso{realmin, intmax, flintmax, eps}
@end deftypefn */)
{
  return fill_matrix (args, std::numeric_limits<double>::max (),
                      std::numeric_limits<float>::max (), "realmax");
}
 
DEFUN (realmin, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{Rmin} =} realmin
@deftypefnx {} {@var{Rmin} =} realmin (@var{n})
@deftypefnx {} {@var{Rmin} =} realmin (@var{m}, @var{n}, @dots{})
@deftypefnx {} {@var{Rmin} =} realmin ([@var{m}, @var{n}, @dots{}])
@deftypefnx {} {@var{Rmin} =} realmin (@dots{}, @var{class})
@deftypefnx {} {@var{Rmin} =} realmin (@dots{}, "like", @var{var})
Return a scalar, matrix, or N-dimensional array whose elements are all equal
to the smallest normalized floating point number that is representable.
 
The actual value is system-dependent.  On machines that support IEEE@tie{}754
floating point arithmetic, @code{realmin} is approximately
@tex
$2.2251\times10^{-308}$ for double precision and $1.1755\times10^{-38}$
@end tex
@ifnottex
2.2251e-308 for double precision and 1.1755e-38
@end ifnottex
for single precision.
 
If called with no arguments, return the scalar value
@code{realmin (@qcode{"double"})}.
 
If invoked with a single scalar integer argument @var{n}, return a square
@nospell{NxN} matrix.
 
If invoked with two or more scalar integer arguments, or a vector of integer
values, return an array with the given dimensions.
 
The optional argument @var{class} specifies the class of the return array.
The only valid options are @qcode{"double"} (default) or @qcode{"single"}.
 
If a variable @var{var} is specified after @qcode{"like"}, the output
@var{Rmin} will have the same data type, complexity, and sparsity as @var{var}.
@seealso{realmax, intmin, eps}
@end deftypefn */)
{
  return fill_matrix (args, std::numeric_limits<double>::min (),
                      std::numeric_limits<float>::min (), "realmin");
}
 
DEFUN (I, args, ,
       doc: /* -*- texinfo -*-
@c List other forms of function in documentation index
@findex i
@findex j
@findex J
 
@deftypefn  {} {@var{x} =} I
@deftypefnx {} {@var{x} =} I (@var{n})
@deftypefnx {} {@var{x} =} I (@var{m}, @var{n}, @dots{})
@deftypefnx {} {@var{x} =} I ([@var{m}, @var{n}, @dots{}])
@deftypefnx {} {@var{x} =} I (@dots{}, @var{class})
Return a scalar, matrix, or N-dimensional array whose elements are all equal
to the pure imaginary unit, defined as
@tex
$\sqrt{-1}$.
@end tex
@ifnottex
@w{@code{sqrt (-1)}}.
@end ifnottex
 
@code{I}, and its equivalents @code{i}, @code{j}, and @code{J}, are functions
so any of the names may be reused for other purposes (such as @code{i} for a
counter variable).
 
If called with no arguments, return the scalar value @code{complex (0, 1)}.
 
If invoked with a single scalar integer argument @var{n}, return a square
@nospell{NxN} matrix.
 
If invoked with two or more scalar integer arguments, or a vector of integer
values, return an array with the given dimensions.
 
The optional argument @var{class} specifies the class of the return array.
The only valid options are @qcode{"double"} (default) or @qcode{"single"}.
@seealso{e, pi, log, exp}
@end deftypefn */)
{
  return fill_matrix (args, Complex (0.0, 1.0), "I");
}
 
DEFALIAS (i, I);
DEFALIAS (J, I);
DEFALIAS (j, I);
 
DEFUN (NA, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{x} =} NA
@deftypefnx {} {@var{x} =} NA (@var{n})
@deftypefnx {} {@var{x} =} NA (@var{m}, @var{n}, @dots{})
@deftypefnx {} {@var{x} =} NA ([@var{m}, @var{n}, @dots{}])
@deftypefnx {} {@var{x} =} NA (@dots{}, @var{class})
@deftypefnx {} {@var{x} =} NA (@dots{}, "like", @var{var})
Return a scalar, matrix, or N-dimensional array whose elements are all equal
to the special constant NA (Not Available) used to designate missing values.
 
Note that @code{NA} always compares not equal to @code{NA} (@code{NA != NA}).
To find @code{NA} values, use the @code{isna} function.
 
If called with no arguments, return the scalar value @code{NA}.
 
If invoked with a single scalar integer argument @var{n}, return a square
@nospell{NxN} matrix.
 
If invoked with two or more scalar integer arguments, or a vector of integer
values, return an array with the given dimensions.
 
The optional argument @var{class} specifies the class of the return array.
The only valid options are @qcode{"double"} (default) or @qcode{"single"}.
 
Programming Note: The missing data marker @code{NA} is a special case of the
representation of @code{NaN}.  Numerical calculations with @code{NA} will
generally "poison" the results and conclude with an output of @code{NA}.
However, this can not be guaranteed on all platforms and @code{NA} may be
replaced by @code{NaN}.  @xref{Missing Data}.
@seealso{isna}
@end deftypefn */)
{
  return fill_matrix (args, lo_ieee_na_value (),
                      lo_ieee_float_na_value (), "NA");
}
 
/*
%!testif HAVE_QNAN_WITH_PAYLOAD
%! assert (single (NA ("double")), NA ("single"));
%!testif HAVE_QNAN_WITH_PAYLOAD
%! assert (double (NA ("single")), NA ("double"));
// Duplicate from above.  Only for test statistics
%!testif ; ! __have_feature__ ("QNAN_WITH_PAYLOAD") <59830>
%! assert (single (NA ("double")), NA ("single"));
%!testif ; ! __have_feature__ ("QNAN_WITH_PAYLOAD") <59830>
%! assert (double (NA ("single")), NA ("double"));
*/
 
DEFUN (false, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{F} =} false
@deftypefnx {} {@var{F} =} false (@var{n})
@deftypefnx {} {@var{F} =} false (@var{m}, @var{n}, @dots{})
@deftypefnx {} {@var{F} =} false ([@var{m}, @var{n}, @dots{}])
@deftypefnx {} {@var{F} =} false (@dots{}, "like", @var{var})
Return a scalar, matrix, or N-dimensional array whose elements are all logical
@code{0}.
 
If called with no arguments, return the scalar value logical @code{0}.
 
If invoked with a single scalar integer argument @var{n}, return a square
@nospell{NxN} matrix.
 
If invoked with two or more scalar integer arguments, or a vector of integer
values, return an array with the given dimensions.
 
If a logical variable @var{var} is specified after @qcode{"like"}, the output
@var{F} will have the same sparsity as @var{var}.
 
Programming Note: The code @code{false (@dots{})} is faster (30X) and more
memory efficient than @code{logical (zeros (@dots{}))}.
 
Any negative dimensions are treated as zero, and any zero dimensions will
result in an empty matrix.  This odd behavior is for @sc{matlab} compatibility.
@seealso{true, logical, ones, zeros}
@end deftypefn */)
{
  return fill_matrix (args, false, "false");
}
 
/*
%!assert (false, logical (0))
%!assert (false (3), logical ([0, 0, 0; 0, 0, 0; 0, 0, 0]))
%!assert (false (2, 3), logical ([0, 0, 0; 0, 0, 0]))
%!assert (false (3, 2), logical ([0, 0; 0, 0; 0, 0]))
%!assert (size (false (3, 4, 5)), [3, 4, 5])
%!assert (false (2, 3, "logical"), logical (zeros (2, 3)))
%!assert (false (2, 1, "like", true), [false; false])
%!assert (false (2, 1, "like", sparse (true)), sparse ([false; false]))
 
## Test input validation
%!error false (2, 3, "double")
%!error <input .* must be logical> false (2, 1, "like", double (1))
%!error <must be scalar> false (1:3, 1)
%!error <must be scalar> false (1, 1:3)
%!error <must be scalar> false (1, 2, 1:3)
*/
 
DEFUN (true, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{T} =} true
@deftypefnx {} {@var{T} =} true (@var{n})
@deftypefnx {} {@var{T} =} true (@var{m}, @var{n}, @dots{})
@deftypefnx {} {@var{T} =} true ([@var{m}, @var{n}, @dots{}])
@deftypefnx {} {@var{T} =} true (@dots{}, "like", @var{var})
Return a scalar, matrix, or N-dimensional array whose elements are all logical
@code{1}.
 
If called with no arguments, return the scalar value logical @code{1}.
 
If invoked with a single scalar integer argument @var{n}, return a square
@nospell{NxN} matrix.
 
If invoked with two or more scalar integer arguments, or a vector of integer
values, return an array with the given dimensions.
 
If a logical variable @var{var} is specified after @qcode{"like"}, the output
@var{T} will have the same sparsity as @var{var}.
 
Programming Notes: The code @code{true (@dots{})} is faster (30X) and more
memory efficient than @code{logical (ones (@dots{}))}.
 
Any negative dimensions are treated as zero, and any zero dimensions will
result in an empty matrix.  This odd behavior is for @sc{matlab} compatibility.
@seealso{false, logical, ones, zeros}
@end deftypefn */)
{
  return fill_matrix (args, true, "true");
}
 
/*
 
%!assert (true, logical (1))
%!assert (true (3), logical ([1, 1, 1; 1, 1, 1; 1, 1, 1]))
%!assert (true (2, 3), logical ([1, 1, 1; 1, 1, 1]))
%!assert (true (3, 2), logical ([1, 1; 1, 1; 1, 1]))
%!assert (size (true (3, 4, 5)), [3, 4, 5])
%!assert (true (2, 3, "logical"), logical (ones (2, 3)))
%!assert (true (2, 1, "like", false), [true; true])
%!assert (true (2, 1, "like", sparse (true)), sparse ([true; true]))
 
## Test input validation
%!error true (2, 3, "double")
%!error <input .* must be logical> true (2, 1, "like", double (1))
%!error <must be scalar> true (1:3, 1)
%!error <must be scalar> true (1, 1:3)
%!error <must be scalar> true (1, 2, 1:3)
*/
 
template <typename MT>
octave_value
identity_matrix (int nr, int nc)
{
  octave_value retval;
 
  typename MT::element_type one (1);
 
  if (nr == 1 && nc == 1)
    retval = one;
  else
    {
      dim_vector dims (nr, nc);
 
      typename MT::element_type zero (0);
 
      MT m (dims, zero);
 
      if (nr > 0 && nc > 0)
        {
          int n = std::min (nr, nc);
 
          for (int i = 0; i < n; i++)
            m(i, i) = one;
        }
 
      retval = m;
    }
 
  return retval;
}
 
#define INSTANTIATE_EYE(T)                              \
  template octave_value identity_matrix<T> (int, int)
 
INSTANTIATE_EYE (int8NDArray);
INSTANTIATE_EYE (uint8NDArray);
INSTANTIATE_EYE (int16NDArray);
INSTANTIATE_EYE (uint16NDArray);
INSTANTIATE_EYE (int32NDArray);
INSTANTIATE_EYE (uint32NDArray);
INSTANTIATE_EYE (int64NDArray);
INSTANTIATE_EYE (uint64NDArray);
INSTANTIATE_EYE (FloatNDArray);
INSTANTIATE_EYE (NDArray);
INSTANTIATE_EYE (boolNDArray);
 
static octave_value
identity_matrix (int nr, int nc, oct_data_conv::data_type dt)
{
  octave_value retval;
 
  // FIXME: Perhaps this should be made extensible by using the class name
  //        to lookup a function to call to create the new value.
 
  switch (dt)
    {
    case oct_data_conv::dt_int8:
      retval = identity_matrix<int8NDArray> (nr, nc);
      break;
 
    case oct_data_conv::dt_uint8:
      retval = identity_matrix<uint8NDArray> (nr, nc);
      break;
 
    case oct_data_conv::dt_int16:
      retval = identity_matrix<int16NDArray> (nr, nc);
      break;
 
    case oct_data_conv::dt_uint16:
      retval = identity_matrix<uint16NDArray> (nr, nc);
      break;
 
    case oct_data_conv::dt_int32:
      retval = identity_matrix<int32NDArray> (nr, nc);
      break;
 
    case oct_data_conv::dt_uint32:
      retval = identity_matrix<uint32NDArray> (nr, nc);
      break;
 
    case oct_data_conv::dt_int64:
      retval = identity_matrix<int64NDArray> (nr, nc);
      break;
 
    case oct_data_conv::dt_uint64:
      retval = identity_matrix<uint64NDArray> (nr, nc);
      break;
 
    case oct_data_conv::dt_single:
      retval = FloatDiagMatrix (nr, nc, 1.0f);
      break;
 
    case oct_data_conv::dt_double:
      retval = DiagMatrix (nr, nc, 1.0);
      break;
 
    case oct_data_conv::dt_logical:
      retval = identity_matrix<boolNDArray> (nr, nc);
      break;
 
    default:
      error ("eye: invalid class name");
      break;
    }
 
  return retval;
}
 
#undef INT_EYE_MATRIX
 
DEFUN (eye, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{I} =} eye ()
@deftypefnx {} {@var{I} =} eye (@var{n})
@deftypefnx {} {@var{I} =} eye (@var{m}, @var{n})
@deftypefnx {} {@var{I} =} eye ([@var{m}, @var{n}])
@deftypefnx {} {@var{I} =} eye (@dots{}, @var{class})
Return an identity matrix.
 
If called with no arguments, return the scalar value @code{1}.
 
If invoked with a single scalar argument @var{n}, return a square @nospell{NxN}
identity matrix.
 
If supplied two scalar arguments (@var{m}, @var{n}), or a 2-element vector
@w{@code{[@var{m}, @var{n}]}}, return an @nospell{MxN} identity matrix with
@var{m} rows and @var{n} columns.
 
The optional argument @var{class} specifies the return type of the matrix and
defaults to @qcode{"double"}.
 
Example 1 : 1-input, square identity matrix
 
@example
@group
eye (3)
 @xresult{}  1  0  0
     0  1  0
     0  0  1
@end group
@end example
 
Example 2 : following expressions all produce 2x2 identity matrix
 
@example
@group
eye (2) @equiv{} eye (2, 2) @equiv{} eye (size ([1, 2; 3, 4]))
 @xresult{}  1  0
     0  1
@end group
@end example
 
Example 3 : 2x2 uint8 identity matrix
 
@example
I = eye (2, "uint8")
@end example
 
Programming Note: Calling @code{eye} with no arguments is equivalent to calling
it with an argument of @code{1}.  Any negative dimensions are treated as zero.
These odd definitions are for compatibility with @sc{matlab}.
@seealso{speye, ones, zeros}
@end deftypefn */)
{
  int nargin = args.length ();
 
  oct_data_conv::data_type dt = oct_data_conv::dt_double;
 
  // Check for type information.
 
  if (nargin > 0 && args(nargin-1).is_string ())
    {
      std::string nm = args(nargin-1).string_value ();
      nargin--;
 
      dt = oct_data_conv::string_to_data_type (nm);
    }
 
  if (nargin > 2)
    print_usage ();
 
  octave_value retval;
 
  if (nargin == 0)
    retval = identity_matrix (1, 1, dt);
  else if (nargin == 1)
    {
      octave_idx_type nr, nc;
      get_dimensions (args(0), "eye", nr, nc);
 
      retval = identity_matrix (nr, nc, dt);
    }
  else
    {
      octave_idx_type nr, nc;
      get_dimensions (args(0), args(1), "eye", nr, nc);
 
      retval = identity_matrix (nr, nc, dt);
    }
 
  return retval;
}
 
/*
%!assert (full (eye (3)), [1, 0, 0; 0, 1, 0; 0, 0, 1])
%!assert (full (eye (2, 3)), [1, 0, 0; 0, 1, 0])
 
%!assert (full (eye (3, "single")), single ([1, 0, 0; 0, 1, 0; 0, 0, 1]))
%!assert (full (eye (2, 3, "single")), single ([1, 0, 0; 0, 1, 0]))
 
%!assert (eye (3, "int8"), int8 ([1, 0, 0; 0, 1, 0; 0, 0, 1]))
%!assert (eye (2, 3, "int8"), int8 ([1, 0, 0; 0, 1, 0]))
 
## Note: Matlab compatibility requires using 0 for negative dimensions.
%!assert (size (eye (2, -3)), [2, 0])
 
## Test input validation
%!error eye (1, 2, 3)
%!error <conversion of 1.1 .*failed> eye (1.1)
%!error <conversion of 1.1 .*failed> eye (1, 1.1)
%!error <conversion of 1.1 .*failed> eye ([1, 1.1])
*/
 
template <typename MT>
static octave_value
do_linspace (const octave_value& base, const octave_value& limit,
             octave_idx_type n)
{
  typedef typename MT::column_vector_type CVT;
  typedef typename MT::element_type T;
 
  octave_value retval;
 
  if (base.is_scalar_type ())
    {
      T bs = octave_value_extract<T> (base);
      if (limit.is_scalar_type ())
        {
          T ls = octave_value_extract<T> (limit);
          retval = linspace (bs, ls, n);
        }
      else
        {
          CVT lv = octave_value_extract<CVT> (limit);
          CVT bv (lv.numel (), bs);
          retval = linspace (bv, lv, n);
        }
    }
  else
    {
      CVT bv = octave_value_extract<CVT> (base);
      if (limit.is_scalar_type ())
        {
          T ls = octave_value_extract<T> (limit);
          CVT lv (bv.numel (), ls);
          retval = linspace (bv, lv, n);
        }
      else
        {
          CVT lv = octave_value_extract<CVT> (limit);
          retval = linspace (bv, lv, n);
        }
    }
 
  return retval;
}
 
DEFUN (linspace, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{y} =} linspace (@var{start}, @var{end})
@deftypefnx {} {@var{y} =} linspace (@var{start}, @var{end}, @var{n})
Return a row vector with @var{n} linearly spaced elements between @var{start}
and @var{end}.
 
If the number of elements @var{n} is greater than one, then the endpoints
@var{start} and @var{end} are always included in the range.  If @var{start} is
greater than @var{end}, the elements are stored in decreasing order.  If the
number of points @var{n} is not specified, a value of 100 is used.
 
The @code{linspace} function returns a row vector when both @var{start} and
@var{end} are scalars.  If one, or both, inputs are vectors, then
@code{linspace} transforms them to column vectors and returns a matrix where
each row is an independent sequence between
@w{@code{@var{start}(@var{row_n}), @var{end}(@var{row_n})}}.
 
Programming Notes: For compatibility with @sc{matlab}, return the second
argument (@var{end}) when a single value (@var{n} = 1) is requested.  If
@var{n} is not an integer then @code{floor (@var{n})} is used to round the
number of elements.  If @var{n} is zero or negative then an empty 1x0 matrix
is returned.
@seealso{colon, logspace}
@end deftypefn */)
{
  int nargin = args.length ();
 
  if (nargin != 2 && nargin != 3)
    print_usage ();
 
  octave_idx_type npoints = 100;
  if (nargin == 3)
    {
      // Apparently undocumented Matlab.  If the third arg is an empty
      // numeric value, the number of points defaults to 1.
      octave_value arg_3 = args(2);
 
      if (arg_3.isnumeric () && arg_3.isempty ())
        npoints = 1;
      else if (! arg_3.is_scalar_type ())
        error ("linspace: N must be a scalar");
      else
        // Even if third arg is not an integer, it must be cast to int
        npoints = arg_3.idx_type_value ();
    }
 
  octave_value arg_1 = args(0);
  octave_value arg_2 = args(1);
 
  const dim_vector& sz1 = arg_1.dims ();
  bool isvector1 = sz1.ndims () == 2 && (sz1(0) == 1 || sz1(1) == 1);
  const dim_vector& sz2 = arg_2.dims ();
  bool isvector2 = sz2.ndims () == 2 && (sz2(0) == 1 || sz2(1) == 1);
 
  if (! isvector1 || ! isvector2)
    error ("linspace: START, END must be scalars or vectors");
 
  octave_value retval;
 
  if (arg_1.is_single_type () || arg_2.is_single_type ())
    {
      if (arg_1.iscomplex () || arg_2.iscomplex ())
        retval = do_linspace<FloatComplexMatrix> (arg_1, arg_2, npoints);
      else
        retval = do_linspace<FloatMatrix> (arg_1, arg_2, npoints);
    }
  else
    {
      if (arg_1.iscomplex () || arg_2.iscomplex ())
        retval = do_linspace<ComplexMatrix> (arg_1, arg_2, npoints);
      else
        retval = do_linspace<Matrix> (arg_1, arg_2, npoints);
    }
 
  return retval;
}
 
/*
%!test
%! x1 = linspace (1, 2);
%! x2 = linspace (1, 2, 10);
%! x3 = linspace (1, -2, 10);
%! assert (size (x1) == [1, 100] && x1(1) == 1 && x1(100) == 2);
%! assert (x1(2) - x1(1), (2 - 1)/ (100 - 1), eps);
%! assert (size (x2) == [1, 10] && x2(1) == 1 && x2(10) == 2);
%! assert (x2(2) - x2(1), (2 - 1)/ (10 - 1), eps);
%! assert (size (x3) == [1, 10] && x3(1) == 1 && x3(10) == -2);
%! assert (x3(2) - x3(1), (-2 - 1)/ (10 - 1), eps);
 
## Test complex values
%!test
%! exp = [1+0i, 2-1.25i, 3-2.5i, 4-3.75i, 5-5i];
%! obs = linspace (1, 5-5i, 5);
%! assert (obs, exp);
 
## Test support for vectors in START and END
%!assert (linspace ([1 2 3], [7 8 9]),
%!        [linspace(1, 7); linspace(2, 8); linspace(3, 9)], 10*eps)
%!assert (linspace ([1 2 3]', [7 8 9]'),
%!        [linspace(1, 7); linspace(2, 8); linspace(3, 9)], 10*eps)
%!assert (linspace ([1 2 3], 9),
%!        [linspace(1, 9); linspace(2, 9); linspace(3, 9)], 10*eps)
%!assert (linspace ([1 2 3]', 9),
%!        [linspace(1, 9); linspace(2, 9); linspace(3, 9)], 10*eps)
%!assert (linspace (1, [7 8 9]),
%!        [linspace(1, 7); linspace(1, 8); linspace(1, 9)], 10*eps)
%!assert (linspace (1, [7 8 9]'),
%!        [linspace(1, 7); linspace(1, 8); linspace(1, 9)], 10*eps)
 
## Test class of output
%!assert (class (linspace (1, 2)), "double")
%!assert (class (linspace (single (1), 2)), "single")
%!assert (class (linspace (1, single (2))), "single")
 
## Test symmetry
%!test <*56659>
%! x = linspace (-1, 1, 10);
%! assert (all (x == -fliplr (x)));
%! x = linspace (-1, 1, 11);
%! assert (all (x == -fliplr (x)));
 
%!test <*56659>
%! x = linspace (-1-1i, 1+1i, 10);
%! assert (all (x == -fliplr (x)));
%! x = linspace (-1-1i, 1+1i, 11);
%! assert (all (x == -fliplr (x)));
 
%!test <*56659>
%! x = linspace (single (-1), 1, 10);
%! assert (all (x == -fliplr (x)));
%! x = linspace (single (-1), 1, 11);
%! assert (all (x == -fliplr (x)));
 
%!test <*56659>
%! x = linspace (single (-1-1i), 1+1i, 10);
%! assert (all (x == -fliplr (x)));
%! x = linspace (single (-1-1i), 1+1i, 11);
%! assert (all (x == -fliplr (x)));
 
## Test obscure Matlab compatibility options
%!assert (linspace (0, 1, []), 1)
%!assert (linspace (10, 20, 2), [10 20])
%!assert (linspace (10, 20, 1), [20])
%!assert (linspace (10, 20, 0), zeros (1, 0))
%!assert (linspace (10, 20, -1), zeros (1, 0))
%!assert (numel (linspace (0, 1, 2+eps)), 2)
%!assert (numel (linspace (0, 1, 2-eps)), 1)
%!assert (linspace (10, 20, 2.1), [10 20])
%!assert (linspace (10, 20, 2.9), [10 20])
%!assert (linspace (Inf, Inf, 3), [Inf, Inf, Inf])
%!assert (linspace (-Inf, -Inf, 3), [-Inf, -Inf, -Inf])
%!assert (linspace (-Inf, Inf, 3), [-Inf, 0, Inf])
## Octave prefers to return NaN which indicates failure of algorithm.
%!assert (linspace (-Inf, Inf, 4), [-Inf, NaN, NaN, Inf])
%!assert (linspace (-Inf, 0, 3), [-Inf, NaN, 0])
%!assert (linspace (-Inf, 0, 4), [-Inf, NaN, NaN, 0])
%!assert (linspace (Inf + 1i, Inf + 1i, 3), [Inf + 1i, Inf + 1i, Inf + 1i])
%!assert (linspace (-Inf - 1i, Inf + 1i, 3), [-Inf - 1i, 0 + 0i, Inf + 1i])
%!assert (linspace (-Inf - 1i, Inf + 2i, 3), [-Inf - 1i, NaN + 0.5i, Inf + 2i])
%!assert (linspace (-Inf - 3i, Inf + 0i, 4),
%!        [-Inf - 3i, NaN - 2i, NaN - 1i, Inf + 0i])
%!assert (linspace (complex (-1, -Inf), complex (1, Inf), 3),
%!          [complex(-1, -Inf), 0 + 0i, complex(1, Inf)])
%!assert (linspace (complex (-1, -Inf), complex (2, Inf), 3),
%!          [complex(-1, -Inf), complex(0.5, NaN), complex(2, Inf)])
%!assert (linspace (complex (-3, -Inf), complex (0, Inf), 4),
%!        [complex(-3, -Inf) complex(-2, NaN) complex(-1, NaN) complex(0, Inf)])
 
## FIXME: Octave is not fully Matlab-compatible for some combinations of
##        Inf/-Inf endpoints.  See bug #56933.  This was dubbed "Won't Fix"
##        as Octave prefers to return NaN for some of these conditions to
##        better reflect that the algorithm has failed.  If the behavior in
##        the future is made compatible these tests can be re-instated.
##%!assert <56933> (linspace (-Inf, Inf, 4), [-Inf, -Inf, Inf, Inf])
##%!assert <56933> (linspace (-Inf, Inf, 5), [-Inf, -Inf, 0, Inf, Inf])
##%!assert <56933> (linspace (0, Inf, 4), [0, Inf, Inf, Inf])
##%!assert <56933> (linspace (0, -Inf, 4), [0, -Inf, -Inf, -Inf])
##%!assert <56933> (linspace (-Inf, 0, 4), [-Inf, NaN, NaN, 0])
##%!assert <56933> (linspace (Inf, 0, 4), [Inf, NaN, NaN, 0])
##%!assert (1 ./ linspace (-0, 0, 4), [-Inf, Inf, Inf, Inf])
 
## Test input validation
%!error <Invalid call> linspace ()
%!error <Invalid call> linspace (1, 2, 3, 4)
%!error <N must be a scalar> linspace (1, 2, [3, 4])
%!error <START, END must be scalars or vectors> linspace (ones (2,2), 2, 3)
%!error <START, END must be scalars or vectors> linspace (2, ones (2,2), 3)
%!error <START, END must be scalars or vectors> linspace (1, [], 3)
*/
 
// FIXME: should accept dimensions as separate args for N-D
// arrays as well as 1-D and 2-D arrays.
 
DEFUN (resize, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{B} =} resize (@var{A}, @var{m})
@deftypefnx {} {@var{B} =} resize (@var{A}, @var{m}, @var{n}, @dots{})
@deftypefnx {} {@var{B} =} resize (@var{A}, [@var{m} @var{n} @dots{}])
Resize @var{A} cutting off elements as necessary.
 
In the result, element with certain indices is equal to the corresponding
element of @var{A} if the indices are within the bounds of @var{A}; otherwise,
the element is set to zero.
 
In other words, the statement
 
@example
B = resize (A, dv)
@end example
 
@noindent
is equivalent to the following code:
 
@example
@group
B = zeros (dv, class (A));
sz = min (dv, size (A));
for i = 1:length (sz)
  idx@{i@} = 1:sz(i);
endfor
B(idx@{:@}) = A(idx@{:@});
@end group
@end example
 
@noindent
but is performed more efficiently.
 
If only @var{m} is supplied, and it is a scalar, the dimension of the result is
@var{m}-by-@var{m}.  If @var{m}, @var{n}, @dots{} are all scalars, then the
dimensions of the result are @var{m}-by-@var{n}-by-@enddots{}  If given a
vector as input, then the dimensions of the result are given by the elements of
that vector.
 
An object can be resized to more dimensions than it has; in such case the
missing dimensions are assumed to be 1.  Resizing an object to fewer dimensions
is not possible.
@seealso{reshape, postpad, prepad, cat}
@end deftypefn */)
{
  int nargin = args.length ();
 
  if (nargin < 2)
    print_usage ();
 
  octave_value retval;
 
  if (nargin == 2)
    {
      Array<double> vec = args(1).vector_value ();
      int ndim = vec.numel ();
      if (ndim == 1)
        {
          octave_idx_type m = static_cast<octave_idx_type> (vec(0));
          retval = args(0);
          retval = retval.resize (dim_vector (m, m), true);
        }
      else
        {
          dim_vector dv;
          dv.resize (ndim);
          for (int i = 0; i < ndim; i++)
            dv(i) = static_cast<octave_idx_type> (vec(i));
          retval = args(0);
          retval = retval.resize (dv, true);
        }
    }
  else
    {
      dim_vector dv;
      dv.resize (nargin - 1);
      for (octave_idx_type i = 1; i < nargin; i++)
        dv(i-1) = static_cast<octave_idx_type> (args(i).scalar_value ());
 
      retval = args(0);
      retval = retval.resize (dv, true);
    }
 
  return retval;
}
 
// FIXME: should use octave_idx_type for dimensions.
 
DEFUN (reshape, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{B} =} reshape (@var{A}, @var{m}, @var{n}, @dots{})
@deftypefnx {} {@var{B} =} reshape (@var{A}, [@var{m} @var{n} @dots{}])
@deftypefnx {} {@var{B} =} reshape (@var{A}, @dots{}, [], @dots{})
@deftypefnx {} {@var{B} =} reshape (@var{A}, @var{size})
Return a matrix with the specified dimensions (@var{m}, @var{n}, @dots{})
whose elements are taken from the matrix @var{A}.
 
The elements of the matrix are accessed in column-major order (like Fortran
arrays are stored).
 
The following code demonstrates reshaping a 1x4 row vector into a 2x2 square
matrix.
 
@example
@group
reshape ([1, 2, 3, 4], 2, 2)
      @xresult{}  1  3
          2  4
@end group
@end example
 
@noindent
Note that the total number of elements in the original matrix
(@code{prod (size (@var{A}))}) must match the total number of elements
in the new matrix (@code{prod ([@var{m} @var{n} @dots{}])}).
 
A single dimension of the return matrix may be left unspecified and Octave
will determine its size automatically.  An empty matrix ([]) is used to flag
the unspecified dimension.
@seealso{resize, vec, postpad, cat, squeeze}
@end deftypefn */)
{
  int nargin = args.length ();
 
  if (nargin < 2)
    print_usage ();
 
  octave_value retval;
 
  dim_vector new_dims;
 
  if (nargin == 2)
    {
      Array<octave_idx_type> new_size = args(1).octave_idx_type_vector_value ();
 
      if (new_size.numel () < 2)
        error ("reshape: SIZE must have 2 or more dimensions");
 
      new_dims = dim_vector::alloc (new_size.numel ());
 
      for (octave_idx_type i = 0; i < new_size.numel (); i++)
        {
          if (new_size(i) < 0)
            error ("reshape: SIZE must be non-negative");
 
          new_dims(i) = new_size(i);
        }
    }
  else
    {
      new_dims = dim_vector::alloc (nargin-1);
      int empty_dim = -1;
 
      for (int i = 1; i < nargin; i++)
        {
          if (args(i).isempty ())
            {
              if (empty_dim > 0)
                error ("reshape: only a single dimension can be unknown");
 
              empty_dim = i;
              new_dims(i-1) = 1;
            }
          else
            {
              new_dims(i-1) = args(i).idx_type_value ();
 
              if (new_dims(i-1) < 0)
                error ("reshape: SIZE must be non-negative");
            }
        }
 
      if (empty_dim > 0)
        {
          octave_idx_type nel = new_dims.numel ();
 
          if (nel == 0)
            new_dims(empty_dim-1) = 0;
          else
            {
              octave_idx_type a_nel = args(0).numel ();
              octave_idx_type size_empty_dim = a_nel / nel;
 
              if (a_nel != size_empty_dim * nel)
                error ("reshape: SIZE is not divisible by the product of "
                       "known dimensions (= %" OCTAVE_IDX_TYPE_FORMAT ")",
                       nel);
 
              new_dims(empty_dim-1) = size_empty_dim;
            }
        }
    }
 
  retval = args(0).reshape (new_dims);
 
  return retval;
}
 
/*
%!assert (size (reshape (ones (4, 4), 2, 8)), [2, 8])
%!assert (size (reshape (ones (4, 4), 8, 2)), [8, 2])
%!assert (size (reshape (ones (15, 4), 1, 60)), [1, 60])
%!assert (size (reshape (ones (15, 4), 60, 1)), [60, 1])
 
%!assert (size (reshape (ones (4, 4, "single"), 2, 8)), [2, 8])
%!assert (size (reshape (ones (4, 4, "single"), 8, 2)), [8, 2])
%!assert (size (reshape (ones (15, 4, "single"), 1, 60)), [1, 60])
%!assert (size (reshape (ones (15, 4, "single"), 60, 1)), [60, 1])
 
%!assert <*64080> (size (reshape (sparse (0, 1), 0, 0)), [0, 0])
 
%!test
%! s.a = 1;
%! fail ("reshape (s, 2, 3)", "can't reshape 1x1 array to 2x3 array");
 
%!error reshape ()
%!error reshape (1, 2, 3, 4)
%!error <SIZE must have 2 or more dimensions> reshape (1:3, 3)
%!error <SIZE must be non-negative> reshape (1:3, [3 -1])
%!error <only a single dimension can be unknown> reshape (1:3, 1,[],[],3)
%!error <SIZE must be non-negative> reshape (1:3, 3, -1)
%!error <SIZE is not divisible> reshape (1:3, 3, [], 2)
*/
 
DEFUN (vec, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{v} =} vec (@var{x})
@deftypefnx {} {@var{v} =} vec (@var{x}, @var{dim})
Return the vector obtained by stacking the columns of the matrix @var{x}
one above the other.
 
Without @var{dim} this is equivalent to @code{@var{x}(:)}.
 
If @var{dim} is supplied, the dimensions of @var{v} are set to @var{dim}
with all elements along the last dimension.  This is equivalent to
@code{shiftdim (@var{x}(:), 1-@var{dim})}.
@seealso{vech, resize, cat}
@end deftypefn */)
{
  int nargin = args.length ();
 
  if (nargin < 1 || nargin > 2)
    print_usage ();
 
  int dim = 1;
  if (nargin == 2)
    {
      dim = args(1).idx_type_value ();
 
      if (dim < 1)
        error ("vec: DIM must be greater than zero");
    }
 
  octave_value colon (octave_value::magic_colon_t);
  octave_value arg = args(0);
 
  octave_value retval = arg.single_subsref ("(", colon);
 
  if (dim > 1)
    {
      dim_vector new_dims = dim_vector::alloc (dim);
 
      for (int i = 0; i < dim-1; i++)
        new_dims(i) = 1;
 
      new_dims(dim-1) = retval.numel ();
 
      retval = retval.reshape (new_dims);
    }
 
  return retval;
}
 
/*
%!assert (vec ([1, 2; 3, 4]), [1; 3; 2; 4])
%!assert (vec ([1, 3, 2, 4]), [1; 3; 2; 4])
%!assert (vec ([1, 2, 3, 4], 2), [1, 2, 3, 4])
%!assert (vec ([1, 2; 3, 4]), vec ([1, 2; 3, 4], 1))
%!assert (vec ([1, 2; 3, 4], 1), [1; 3; 2; 4])
%!assert (vec ([1, 2; 3, 4], 2), [1, 3, 2, 4])
%!assert (vec ([1, 3; 2, 4], 3), reshape ([1, 2, 3, 4], 1, 1, 4))
%!assert (vec ([1, 3; 2, 4], 3), shiftdim (vec ([1, 3; 2, 4]), -2))
 
%!error vec ()
%!error vec (1, 2, 3)
%!error vec ([1, 2; 3, 4], 0)
*/
 
DEFUN (squeeze, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{B} =} squeeze (@var{A})
Remove singleton dimensions from @var{A} and return the result.
 
Note that for compatibility with @sc{matlab}, all objects have
a minimum of two dimensions and row vectors are left unchanged.
@seealso{reshape}
@end deftypefn */)
{
  if (args.length () != 1)
    print_usage ();
 
  return ovl (args(0).squeeze ());
}
 
DEFUN (full, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{FM} =} full (@var{SM})
Return a full storage matrix from a sparse, diagonal, or permutation matrix,
or from a range.
@seealso{sparse, issparse}
@end deftypefn */)
{
  if (args.length () != 1)
    print_usage ();
 
  return ovl (args(0).full_value ());
}
 
// Compute various norms of the vector X.
 
DEFUN (norm, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{n} =} norm (@var{A})
@deftypefnx {} {@var{n} =} norm (@var{A}, @var{p})
@deftypefnx {} {@var{n} =} norm (@var{A}, @var{p}, @var{opt})
Compute the p-norm of the matrix @var{A}.
 
If the second argument is not given, @w{@code{p = 2}}@ is used.
 
If @var{A} is a matrix (or sparse matrix):
 
@table @asis
@item @var{p} = @code{1}
1-norm, the largest column sum of the absolute values of @var{A}.
 
@item @var{p} = @code{2}
Largest singular value of @var{A}.
 
@item @var{p} = @code{Inf} or @qcode{"inf"}
@cindex infinity norm
Infinity norm, the largest row sum of the absolute values of @var{A}.
 
@item @var{p} = @qcode{"fro"}
@cindex @nospell{Frobenius} norm
@nospell{Frobenius} norm of @var{A},
@code{sqrt (sum (diag (@var{A}' * @var{A})))}.
 
@item other @var{p}, @code{@var{p} > 1}
@cindex general p-norm
maximum @code{norm (A*x, p)} such that @code{norm (x, p) == 1}
@end table
 
If @var{A} is a vector or a scalar:
 
@table @asis
@item @var{p} = @code{Inf} or @qcode{"inf"}
@code{max (abs (@var{A}))}.
 
@item @var{p} = @code{-Inf}
@code{min (abs (@var{A}))}.
 
@item @var{p} = @qcode{"fro"}
@nospell{Frobenius} norm of @var{A}, @code{sqrt (sumsq (abs (A)))}.
 
@item @var{p} = 0
Hamming norm---the number of nonzero elements.
 
@item other @var{p}, @code{@var{p} > 1}
p-norm of @var{A}, @code{(sum (abs (@var{A}) .^ @var{p})) ^ (1/@var{p})}.
 
@item other @var{p} @code{@var{p} < 1}
the p-pseudonorm defined as above.
@end table
 
If @var{opt} is the value @qcode{"rows"}, treat each row as a vector and
compute its norm.  The result is returned as a column vector.
Similarly, if @var{opt} is @qcode{"columns"} or @qcode{"cols"} then
compute the norms of each column and return a row vector.
@seealso{normest, normest1, vecnorm, cond, svd}
@end deftypefn */)
{
  int nargin = args.length ();
 
  if (nargin < 1 || nargin > 3)
    print_usage ();
 
  octave_value x_arg = args(0);
 
  if (x_arg.ndims () != 2)
    error ("norm: only valid for 2-D objects");
 
  enum {sfmatrix, sfcols, sfrows, sffrob, sfinf, sfneginf} strflag = sfmatrix;
  if (nargin > 1 && args(nargin-1).is_string ())
    {
      std::string str = args(nargin-1).string_value ();
      std::transform (str.begin (), str.end (), str.begin (), tolower);
      if (str == "cols" || str == "columns")
        strflag = sfcols;
      else if (str == "rows")
        strflag = sfrows;
      else if (str == "fro")
        strflag = sffrob;
      else if (str == "inf")
        strflag = sfinf;
      else if (str == "-inf")
        strflag = sfneginf;
      else
        error ("norm: unrecognized option: %s", str.c_str ());
 
      // we've handled the last parameter, so act as if it was removed
      nargin--;
    }
 
  octave_value p_arg = (nargin > 1) ? args(1) : octave_value (2);
 
  if (p_arg.isempty ())
    p_arg = octave_value (2);
  else if (p_arg.is_string ())
    {
      std::string str = p_arg.string_value ();
      std::transform (str.begin (), str.end (), str.begin (), tolower);
      if (strflag != sfcols && strflag != sfrows)
        error ("norm: invalid combination of options");
 
      if (str == "cols" || str == "columns" || str == "rows")
        error ("norm: invalid combination of options");
 
      if (str == "fro")
        p_arg = octave_value (2);
      else if (str == "inf")
        p_arg = numeric_limits<double>::Inf ();
      else if (str == "-inf")
        p_arg = -numeric_limits<double>::Inf ();
      else
        error ("norm: unrecognized option: %s", str.c_str ());
    }
  else if (! p_arg.is_scalar_type ())
    err_wrong_type_arg ("norm", p_arg);
 
  octave_value retval;
 
  switch (strflag)
    {
    case sfmatrix:
      retval = xnorm (x_arg, p_arg);
      break;
 
    case sfcols:
      retval = xcolnorms (x_arg, p_arg);
      break;
 
    case sfrows:
      retval = xrownorms (x_arg, p_arg);
      break;
 
    case sffrob:
      retval = xfrobnorm (x_arg);
      break;
 
    case sfinf:
      retval = xnorm (x_arg, numeric_limits<double>::Inf ());
      break;
 
    case sfneginf:
      retval = xnorm (x_arg, -numeric_limits<double>::Inf ());
      break;
    }
 
  return retval;
}
 
/*
%!shared x
%! x = [1, -3, 4, 5, -7];
%!assert (norm (x,0), 5)
%!assert (norm (x,1), 20)
%!assert (norm (x,2), 10)
%!assert (norm (x,3), 8.24257059961711, -4*eps)
%!assert (norm (x,Inf), 7)
%!assert (norm (x,-Inf), 1)
%!assert (norm (x,"inf"), 7)
%!assert (norm (x,"-Inf"), 1)
%!assert (norm (x,"fro"), 10, -eps)
%!assert (norm (x), 10)
%!assert (norm ([1e200, 1]), 1e200)
%!assert (norm ([3+4i, 3-4i, sqrt(31)]), 9, -4*eps)
%!shared m
%! m = magic (4);
%!assert (norm (m,1), 34)
%!assert (norm (m,2), 34, -eps)
%!assert (norm (m,3), 34, -sqrt (eps))
%!assert (norm (m,Inf), 34)
%!assert (norm (m,"inf"), 34)
%!shared m2, flo, fhi
%! m2 = [1,2;3,4];
%! flo = 1e-300;
%! fhi = 1e+300;
%!assert (norm (flo*m2,"fro"), sqrt (30)*flo, -eps)
%!assert (norm (fhi*m2,"fro"), sqrt (30)*fhi, -eps)
 
%!shared x
%! x = single ([1, -3, 4, 5, -7]);
%!assert (norm (x,0), single (5))
%!assert (norm (x,1), single (20))
%!assert (norm (x,2), single (10))
%!assert (norm (x,3), single (8.24257059961711), -4* eps ("single"))
%!assert (norm (x,Inf), single (7))
%!assert (norm (x,-Inf), single (1))
%!assert (norm (x,"inf"), single (7))
%!assert (norm (x,"-Inf"), single (1))
%!assert (norm (x,"fro"), single (10), -eps ("single"))
%!assert (norm (x), single (10))
 
%!test <67918>
%! ## fails with reference BLAS 3.10.0
%! assert (norm (single ([1e38, 1])), single (1e38));
 
%!assert (norm (single ([3+4i, 3-4i, sqrt(31)])),
%!        single (9), -4* eps ("single"))
%!shared m
%! m = single (magic (4));
%!assert (norm (m,1), single (34))
%!assert (norm (m,2), single (34), -eps ("single"))
%!assert (norm (m,3), single (34), -sqrt (eps ("single")))
%!assert (norm (m,Inf), single (34))
%!assert (norm (m,"inf"), single (34))
%!shared m2, flo, fhi
%! m2 = single ([1,2;3,4]);
%! flo = single (1e-300);
%! fhi = single (1e+300);
%!assert (norm (flo*m2,"fro"), single (sqrt (30)*flo), -eps ("single"))
%!assert (norm (fhi*m2,"fro"), single (sqrt (30)*fhi), -eps ("single"))
 
## Hamming norm (p == 0)
%!assert (norm ([1, 0, 0, 0, 1], 0), 2)
 
%!shared q
%! q = rand (1e3, 3);
%!assert (norm (q, 3, "rows"), sum (q.^3, 2).^(1/3), sqrt (eps))
%!assert (norm (q, "fro", "rows"), sum (q.^2, 2).^(1/2), sqrt (eps))
%!assert (norm (q, "fro", "rows"), sqrt (sumsq (q, 2)), sqrt (eps))
%!assert (norm (q, "fro", "cols"), sqrt (sumsq (q, 1)), sqrt (eps))
%!assert (norm (q, 3, "cols"), sum (q.^3, 1).^(1/3), sqrt (eps))
%!assert (norm (q, "inf", "rows"), norm (q, Inf, "rows"))
%!assert (norm (q, "inf", "cols"), norm (q, Inf, "cols"))
%!assert (norm (q, [], "rows"), norm (q, 2, "rows"))
%!assert (norm (q, [], "cols"), norm (q, 2, "cols"))
 
%!test <30631>
%! ## Test for norm returning NaN on sparse matrix
%! A = sparse (2,2);
%! A(2,1) = 1;
%! assert (norm (A), 1);
 
## Tests for single precision norm calculations.
## Verify that float norms accumulated in double do not overflow
## near float maximum.
##
## We need values where val^2 overflows float (~3.4e38) but
## the final norm sqrt(n*val^2) = sqrt(n)*val still fits in float.
## Using val = 1e19: val^2 = 1e38 (near float max), sqrt(1000)*1e19 ~ 3.2e20 (OK)
 
%!test <67610>
%! ## Test 2-norm with values where val^2 would overflow float output
%! ## val = 1e19, val^2 = 1e38 (would overflow float), but result fits
%! x = single (1e19) * ones (1000, 1, "single");
%! result = norm (x, 2);
%! assert (isfinite (result));
%! xd = double (x);
%! expected = norm (xd, 2);
%! assert (double (result), expected, eps ("single") * expected);
 
%!test <67610>
%! ## Test 1-norm - straightforward sum
%! ## Use moderately large values
%! x = single (1e30) * ones (1000, 1, "single");
%! result = norm (x, 1);
%! assert (isfinite (result));
%! xd = double (x);
%! expected = norm (xd, 1);
%! assert (double (result), expected, eps ("single") * expected);
 
%!test <67610>
%! ## Test p-norm (p=1.5) with large values
%! x = single (1e20) * ones (1000, 1, "single");
%! result = norm (x, 1.5);
%! assert (isfinite (result));
%! xd = double (x);
%! expected = norm (xd, 1.5);
%! assert (double (result), expected, eps ("single") * expected);
 
%!test <67610>
%! ## Test p-norm (p=0.5) - terms are val^0.5, no overflow concern
%! x = single (1e30) * ones (1000, 1, "single");
%! result = norm (x, 0.5);
%! assert (isfinite (result));
%! xd = double (x);
%! expected = norm (xd, 0.5);
%! assert (double (result), expected, eps ("single") * expected);
 
%!test <67610>
%! ## Test p-norm (p=3) with values where val^3 overflows float
%! ## val = 1e12, val^3 = 1e36 (near float max in accumulator)
%! x = single (1e12) * ones (1000, 1, "single");
%! result = norm (x, 3);
%! assert (isfinite (result));
%! xd = double (x);
%! expected = norm (xd, 3);
%! assert (double (result), expected, eps ("single") * expected);
 
%!test <67610>
%! ## Test complex single precision 2-norm
%! ## |z|^2 = re^2 + im^2, use values where this would overflow float
%! x = single (1e19) * complex (ones (1000, 1, "single"), ones (1000, 1, "single"));
%! result = norm (x, 2);
%! assert (isfinite (result));
%! xd = double (x);
%! expected = norm (xd, 2);
%! assert (double (result), expected, eps ("single") * expected);
 
%!test <67610>
%! ## Test that single and double give consistent results for normal values
%! x = single (randn (1000, 1));
%! xd = double (x);
%! for p = [0.5, 1, 1.5, 2, 3, Inf]
%!   rs = norm (x, p);
%!   rd = norm (xd, p);
%!   assert (double (rs), rd, eps ("single") * rd);
%! endfor
 
%!test <67610>
%! ## Test inf-norm (no accumulation, just max)
%! fmax = realmax ("single");
%! x = (fmax / 2) * ones (1000, 1, "single");
%! x(500) = fmax - 1;
%! result = norm (x, Inf);
%! assert (result, fmax - 1);
 
%!test <67610>
%! ## Test -inf norm (min absolute value)
%! x = single ([1, 2, 0.5, 3]);
%! result = norm (x, -Inf);
%! assert (result, single (0.5));
*/
 
/*
## Test input validation
%!error norm ()
%!error norm (1,2,3,4)
%!error <unrecognized option> norm (1, "invalid")
%!error <unrecognized option> norm (1, "rows", "invalid")
%!error <unrecognized option> norm (1, "invalid", "rows")
%!error <invalid combination of options> norm (1, "cols", "rows")
%!error <invalid combination of options> norm (1, "rows", "rows")
%!error <p must be .= 1> norm (ones (2,2), -Inf)
*/
 
static octave_value
unary_op_defun_body (octave_value::unary_op op,
                     const octave_value_list& args)
{
  if (args.length () != 1)
    print_usage ();
 
  return unary_op (op, args(0));
}
 
DEFUN (not, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{z} =} not (@var{x})
Return the logical NOT of @var{x}.
 
This function is equivalent to the operator syntax @w{@code{! @var{x}}}.
@seealso{and, or, xor}
@end deftypefn */)
{
  return unary_op_defun_body (octave_value::op_not, args);
}
 
DEFUN (uplus, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{B} =} uplus (@var{A})
This function and @w{@tcode{+ @var{A}}}@ are equivalent.
@seealso{uminus, plus}
@end deftypefn */)
{
  return unary_op_defun_body (octave_value::op_uplus, args);
}
 
DEFUN (uminus, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{B} =} uminus (@var{A})
This function and @w{@tcode{- @var{A}}}@ are equivalent.
@seealso{uplus, minus}
@end deftypefn */)
{
  return unary_op_defun_body (octave_value::op_uminus, args);
}
 
DEFUN (transpose, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{B} =} transpose (@var{A})
Return the transpose of @var{A}.
 
This function and @tcode{@var{A}.'@:}@ are equivalent.
@seealso{ctranspose}
@end deftypefn */)
{
  return unary_op_defun_body (octave_value::op_transpose, args);
}
 
/*
%!assert (2.', 2)
%!assert (2i.', 2i)
%!assert ([1:4].', [1;2;3;4])
%!assert ([1;2;3;4].', [1:4])
%!assert ([1,2;3,4].', [1,3;2,4])
%!assert ([1,2i;3,4].', [1,3;2i,4])
 
%!assert (transpose ([1,2;3,4]), [1,3;2,4])
 
%!assert (single (2).', single (2))
%!assert (single (2i).', single (2i))
%!assert (single ([1:4]).', single ([1;2;3;4]))
%!assert (single ([1;2;3;4]).', single ([1:4]))
%!assert (single ([1,2;3,4]).', single ([1,3;2,4]))
%!assert (single ([1,2i;3,4]).', single ([1,3;2i,4]))
 
%!assert (transpose (single ([1,2;3,4])), single ([1,3;2,4]))
*/
 
DEFUN (ctranspose, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{B} =} ctranspose (@var{A})
Return the complex conjugate transpose of @var{A}.
 
This function and @tcode{@var{A}'}@ are equivalent.
@seealso{transpose}
@end deftypefn */)
{
  return unary_op_defun_body (octave_value::op_hermitian, args);
}
 
/*
%!assert (2', 2)
%!assert (2i', -2i)
%!assert ([1:4]', [1;2;3;4])
%!assert ([1;2;3;4]', [1:4])
%!assert ([1,2;3,4]', [1,3;2,4])
%!assert ([1,2i;3,4]', [1,3;-2i,4])
 
%!assert (ctranspose ([1,2i;3,4]), [1,3;-2i,4])
 
%!assert (single (2)', single (2))
%!assert (single (2i)', single (-2i))
%!assert (single ([1:4])', single ([1;2;3;4]))
%!assert (single ([1;2;3;4])', single ([1:4]))
%!assert (single ([1,2;3,4])', single ([1,3;2,4]))
%!assert (single ([1,2i;3,4])', single ([1,3;-2i,4]))
 
%!assert (ctranspose (single ([1,2i;3,4])), single ([1,3;-2i,4]))
*/
 
static octave_value
binary_op_defun_body (octave_value::binary_op op,
                      const octave_value_list& args)
{
  if (args.length () != 2)
    print_usage ();
 
  return binary_op (op, args(0), args(1));
}
 
static octave_value
binary_assoc_op_defun_body (octave_value::binary_op op,
                            octave_value::assign_op aop,
                            const octave_value_list& args)
{
  int nargin = args.length ();
 
  if (nargin < 2)
    print_usage ();
 
  octave_value retval;
 
  if (nargin == 2)
    retval = binary_op (op, args(0), args(1));
  else
    {
      retval = binary_op (op, args(0), args(1));
 
      for (int i = 2; i < nargin; i++)
        retval.assign (aop, args(i));
    }
 
  return retval;
}
 
DEFUN (plus, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{C} =} plus (@var{A}, @var{B})
@deftypefnx {} {@var{C} =} plus (@var{A1}, @var{A2}, @dots{})
This function and @w{@tcode{@var{A} + @var{B}}}@ are equivalent.
 
If more arguments are given, the summation is applied
cumulatively from left to right:
 
@example
(@dots{}((@var{A1} + @var{A2}) + @var{A3}) + @dots{})
@end example
 
@seealso{minus, uplus}
@end deftypefn */)
{
  return binary_assoc_op_defun_body (octave_value::op_add,
                                     octave_value::op_add_eq, args);
}
 
/*
%!assert (plus (1,1), 2)
%!assert (plus (1:3, 1), 2:4)
%!assert (plus (1:3, 1, 3), 5:7)
%!assert (plus (1,2,3,4,5,6,7,8,9), sum (1:9))
 
## Test input validation for all functions which use binary_assoc_op_defun_body
%!error plus ()
%!error plus (1)
*/
 
DEFUN (minus, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{C} =} minus (@var{A}, @var{B})
This function and @w{@tcode{@var{A} - @var{B}}}@ are equivalent.
@seealso{plus, uminus}
@end deftypefn */)
{
  return binary_op_defun_body (octave_value::op_sub, args);
}
 
DEFUN (mtimes, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{C} =} mtimes (@var{A}, @var{B})
@deftypefnx {} {@var{C} =} mtimes (@var{A1}, @var{A2}, @dots{})
Return the matrix multiplication product of inputs.
 
This function and @w{@tcode{@var{A} * @var{B}}}@ are equivalent.
If more arguments are given, the multiplication is applied
cumulatively from left to right:
 
@example
(@dots{}((@var{A1} * @var{A2}) * @var{A3}) * @dots{})
@end example
 
@seealso{times, plus, minus, rdivide, mrdivide, mldivide, mpower, tensorprod}
@end deftypefn */)
{
  return binary_assoc_op_defun_body (octave_value::op_mul,
                                     octave_value::op_mul_eq, args);
}
 
DEFUN (mrdivide, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{C} =} mrdivide (@var{A}, @var{B})
Return the matrix right division of @var{A} and @var{B}.
 
This function and @w{@tcode{@var{A} / @var{B}}}@ are equivalent.
 
If the system is not square, or if the coefficient matrix is singular, a
minimum norm solution is computed.
@seealso{mldivide, rdivide, plus, minus}
@end deftypefn */)
{
  return binary_op_defun_body (octave_value::op_div, args);
}
 
DEFUN (mpower, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{C} =} mpower (@var{A}, @var{B})
Return the matrix power operation of @var{A} raised to the @var{B} power.
 
This function and @w{@tcode{@var{A} ^ @var{B}}}@ are equivalent.
@seealso{power, mtimes, plus, minus}
@end deftypefn */)
{
  return binary_op_defun_body (octave_value::op_pow, args);
}
/*
%!assert (complex (realmin, realmin) ^ realmax, 0)
*/
 
DEFUN (mldivide, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{C} =} mldivide (@var{A}, @var{B})
Return the matrix left division of @var{A} and @var{B}.
 
This function and @w{@tcode{@var{A} @backslashchar{} @var{B}}}@ are equivalent.
 
If the system is not square, or if the coefficient matrix is singular, a
minimum norm solution is computed.
@seealso{mrdivide, ldivide, rdivide, linsolve}
@end deftypefn */)
{
  return binary_op_defun_body (octave_value::op_ldiv, args);
}
 
DEFUN (lt, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{TF} =} lt (@var{A}, @var{B})
This function is equivalent to @w{@code{@var{A} < @var{B}}}.
@seealso{le, eq, ge, gt, ne}
@end deftypefn */)
{
  return binary_op_defun_body (octave_value::op_lt, args);
}
 
DEFUN (le, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{TF} =} le (@var{A}, @var{B})
This function is equivalent to @w{@code{@var{A} <= @var{B}}}.
@seealso{eq, ge, gt, ne, lt}
@end deftypefn */)
{
  return binary_op_defun_body (octave_value::op_le, args);
}
 
DEFUN (eq, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{TF} =} eq (@var{A}, @var{B})
Return true if the two inputs are equal.
 
This function is equivalent to @w{@code{@var{A} == @var{B}}}.
@seealso{ne, isequal, le, ge, gt, ne, lt}
@end deftypefn */)
{
  return binary_op_defun_body (octave_value::op_eq, args);
}
 
DEFUN (ge, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{TF} =} ge (@var{A}, @var{B})
This function is equivalent to @w{@code{@var{A} >= @var{B}}}.
@seealso{le, eq, gt, ne, lt}
@end deftypefn */)
{
  return binary_op_defun_body (octave_value::op_ge, args);
}
 
DEFUN (gt, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{TF} =} gt (@var{A}, @var{B})
This function is equivalent to @w{@code{@var{A} > @var{B}}}.
@seealso{le, eq, ge, ne, lt}
@end deftypefn */)
{
  return binary_op_defun_body (octave_value::op_gt, args);
}
 
DEFUN (ne, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{TF} =} ne (@var{A}, @var{B})
Return true if the two inputs are not equal.
 
This function is equivalent to @w{@code{@var{A} != @var{B}}}.
@seealso{eq, isequal, le, ge, lt}
@end deftypefn */)
{
  return binary_op_defun_body (octave_value::op_ne, args);
}
 
DEFUN (times, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{C} =} times (@var{A}, @var{B})
@deftypefnx {} {@var{C} =} times (@var{A1}, @var{A2}, @dots{})
Return the element-by-element multiplication product of inputs.
 
This function and @w{@tcode{@var{A} .* @var{B}}}@ are equivalent.
If more arguments are given, the multiplication is applied
cumulatively from left to right:
 
@example
(@dots{}((@var{A1} .* @var{A2}) .* @var{A3}) .* @dots{})
@end example
 
@seealso{mtimes, rdivide}
@end deftypefn */)
{
  return binary_assoc_op_defun_body (octave_value::op_el_mul,
                                     octave_value::op_el_mul_eq, args);
}
 
DEFUN (rdivide, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{C} =} rdivide (@var{A}, @var{B})
Return the element-by-element right division of @var{A} and @var{B}.
 
This function and @w{@tcode{@var{A} ./ @var{B}}}@ are equivalent.
@seealso{ldivide, mrdivide, times, plus}
@end deftypefn */)
{
  return binary_op_defun_body (octave_value::op_el_div, args);
}
 
DEFUN (power, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{C} =} power (@var{A}, @var{B})
Return the element-by-element operation of @var{A} raised to the
@var{B} power.
 
This function and @w{@tcode{@var{A} .^ @var{B}}}@ are equivalent.
 
If several complex results are possible, returns the one with smallest
non-negative argument (angle).  Use @code{realpow}, @code{realsqrt},
@code{cbrt}, or @code{nthroot} if a real result is preferred.
 
@seealso{mpower, realpow, realsqrt, cbrt, nthroot}
@end deftypefn */)
{
  return binary_op_defun_body (octave_value::op_el_pow, args);
}
/*
%!assert (complex (realmin, realmin) .^ realmax, 0)
*/
 
DEFUN (ldivide, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{C} =} ldivide (@var{A}, @var{B})
Return the element-by-element left division of @var{A} and @var{B}.
 
This function and @w{@tcode{@var{A} .@backslashchar{} @var{B}}}@ are
equivalent.
@seealso{rdivide, mldivide, times, plus}
@end deftypefn */)
{
  return binary_op_defun_body (octave_value::op_el_ldiv, args);
}
 
DEFUN (and, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{TF} =} and (@var{x}, @var{y})
@deftypefnx {} {@var{TF} =} and (@var{x1}, @var{x2}, @dots{})
Return the logical AND of @var{x} and @var{y}.
 
This function is equivalent to the operator syntax
@w{@code{@var{x} & @var{y}}}.  If more than two arguments are given, the
logical AND is applied cumulatively from left to right:
 
@example
(@dots{}((@var{x1} & @var{x2}) & @var{x3}) & @dots{})
@end example
 
@seealso{or, not, xor}
@end deftypefn */)
{
  return binary_assoc_op_defun_body (octave_value::op_el_and,
                                     octave_value::op_el_and_eq, args);
}
 
DEFUN (or, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{TF} =} or (@var{x}, @var{y})
@deftypefnx {} {@var{TF} =} or (@var{x1}, @var{x2}, @dots{})
Return the logical OR of @var{x} and @var{y}.
 
This function is equivalent to the operator syntax
@w{@code{@var{x} | @var{y}}}.  If more than two arguments are given, the
logical OR is applied cumulatively from left to right:
 
@example
(@dots{}((@var{x1} | @var{x2}) | @var{x3}) | @dots{})
@end example
 
@seealso{and, not, xor}
@end deftypefn */)
{
  return binary_assoc_op_defun_body (octave_value::op_el_or,
                                     octave_value::op_el_or_eq, args);
}
 
DEFUN (colon, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{r} =} colon (@var{base}, @var{limit})
@deftypefnx {} {@var{r} =} colon (@var{base}, @var{increment}, @var{limit})
Return the result of the colon expression corresponding to @var{base},
@var{limit}, and optionally, @var{increment}.
 
This function is equivalent to the operator syntax
@w{@code{@var{base} : @var{limit}}}@ or
@w{@code{@var{base} : @var{increment} : @var{limit}}}.
@seealso{linspace}
@end deftypefn */)
{
  int nargin = args.length ();
 
  if (nargin < 2 || nargin > 3)
    print_usage ();
 
  return (nargin == 2
          ? colon_op (args(0), args(1))
          : colon_op (args(0), args(1), args(2)));
}
 
static double tic_toc_timestamp = -1.0;
 
DEFUN (tic, args, nargout,
       doc: /* -*- texinfo -*-
@deftypefn  {} {} tic ()
@deftypefnx {} {@var{id} =} tic ()
Initialize a wall-clock timer.
 
Calling @code{tic} without an output argument resets the internal timer.
Subsequent calls to @code{toc} return the number of seconds since the timer was
set.
 
If called with one output argument, @code{tic} creates a new timer instance and
returns a timer identifier @var{id}.  The @var{id} is a scalar of type
@code{uint64} that may be passed to @code{toc} to check elapsed time on this
timer, rather than the default internal timer.
 
Example 1 : benchmarking code with internal timer
 
@example
@group
tic;
# many computations later@dots{}
elapsed_time = toc;
@end group
@end example
 
Example 2 : mixed timer id and internal timer
 
@example
@group
tic;
pause (1);
toc
@xresult{} Elapsed time is 1.0089 seconds.
id = tic;
pause (2);
toc (id)
@xresult{} Elapsed time is 2.01142 seconds.
toc
Elapsed time is 3.02308 seconds.
@end group
@end example
 
@noindent
Calling @code{tic} and @code{toc} in this way allows nested timing calls.
 
If you are more interested in the CPU time that your process used, you should
use the @code{cputime} function instead.  The @code{tic} and @code{toc}
functions report the actual wall clock time that elapsed between the calls.
This may include time spent processing other jobs or doing nothing at all.
@seealso{toc, cputime}
@end deftypefn */)
{
  if (args.length () != 0)
    warning ("tic: ignoring extra arguments");
 
  octave_value retval;
  sys::time now;
  double tmp = now.double_value ();
 
  if (nargout > 0)
    {
      double ip = 0.0;
      double frac = std::modf (tmp, &ip);
      uint64_t microsecs = static_cast<uint64_t> (CLOCKS_PER_SEC * frac);
      microsecs += CLOCKS_PER_SEC * static_cast<uint64_t> (ip);
      retval = octave_uint64 (microsecs);
    }
  else
    tic_toc_timestamp = tmp;
 
  return retval;
}
 
DEFUN (toc, args, nargout,
       doc: /* -*- texinfo -*-
@deftypefn  {} {} toc ()
@deftypefnx {} {} toc (@var{id})
@deftypefnx {} {@var{elapsed_time} =} toc (@dots{})
Measure elapsed time on a wall-clock timer.
 
With no arguments, return the number of seconds elapsed on the internal timer
since the last call to @code{tic}.
 
When given the identifier @var{id} of a specific timer, return the number of
seconds elapsed since the timer @var{id} was initialized.
 
@xref{XREFtic,,tic}, for examples of the use of @code{tic}/@code{toc}.
 
@seealso{tic, cputime}
@end deftypefn */)
{
  int nargin = args.length ();
 
  if (nargin > 1)
    print_usage ();
 
  double start_time = tic_toc_timestamp;
 
  if (nargin == 1)
    {
      octave_uint64 id = args(0).xuint64_scalar_value ("toc: invalid ID");
 
      uint64_t val = id.value ();
 
      start_time
        = (static_cast<double> (val / CLOCKS_PER_SEC)
           + static_cast<double> (val % CLOCKS_PER_SEC)
           / CLOCKS_PER_SEC);
 
      // FIXME: should we also check to see whether the start
      //        time is after the beginning of this Octave session?
    }
 
  if (start_time < 0)
    error ("toc: function called before timer initialization with tic()");
 
  sys::time now;
 
  double etime = now.double_value () - start_time;
 
  octave_value retval;
  if (nargout > 0)
    retval = etime;
  else
    octave_stdout << "Elapsed time is " << etime << " seconds.\n";
 
  return retval;
}
 
/*
%!shared id
%! id = tic ();
%!assert (isa (id, "uint64"))
%!assert (isa (toc (id), "double"))
*/
 
DEFUN (cputime, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {[@var{total}, @var{user}, @var{system}] =} cputime ();
Return the CPU time used by your Octave session.
 
The first output is the total time spent executing your process and is equal
to the sum of second and third outputs, which are the number of CPU seconds
spent executing in user mode and the number of CPU seconds spent executing
in system mode, respectively.
 
If your system does not have a way to report CPU time usage, @code{cputime}
returns 0 for each of its output values.
 
Note that because Octave used some CPU time to start, it is reasonable
to check to see if @code{cputime} works by checking to see if the total
CPU time used is nonzero.
@seealso{tic, toc}
@end deftypefn */)
{
  if (args.length () != 0)
    print_usage ();
 
  sys::cpu_time cpu_tm;
 
  double usr = cpu_tm.user ();
  double sys = cpu_tm.system ();
 
  return ovl (usr + sys, usr, sys);
}
 
DEFUN (sort, args, nargout,
       doc: /* -*- texinfo -*-
@deftypefn  {} {[@var{s}, @var{i}] =} sort (@var{x})
@deftypefnx {} {[@var{s}, @var{i}] =} sort (@var{x}, @var{dim})
@deftypefnx {} {[@var{s}, @var{i}] =} sort (@var{x}, @var{mode})
@deftypefnx {} {[@var{s}, @var{i}] =} sort (@var{x}, @var{dim}, @var{mode})
Return a copy of @var{x} with the elements arranged in increasing order.
 
For matrices, @code{sort} orders the elements within columns
 
For example:
 
@example
@group
sort ([1, 2; 2, 3; 3, 1])
   @xresult{}  1  1
       2  2
       3  3
@end group
@end example
 
If the optional argument @var{dim} is given, then the matrix is sorted
along the dimension defined by @var{dim}.  The optional argument @var{mode}
defines the order in which the values will be sorted.  Valid values of
@var{mode} are @qcode{"ascend"} or @qcode{"descend"}.
 
The @code{sort} function may also be used to produce a matrix
containing the original row indices of the elements in the sorted
matrix.  For example:
 
@example
@group
[s, i] = sort ([1, 2; 2, 3; 3, 1])
  @xresult{} s = 1  1
         2  2
         3  3
  @xresult{} i = 1  3
         2  1
         3  2
@end group
@end example
 
For equal elements, the indices are such that equal elements are listed
in the order in which they appeared in the original list.
 
Sorting of complex entries is done first by magnitude
(@w{@code{abs (@var{z})}})@ and for any ties by phase angle
(@w{@code{angle (z)}}).  For example:
 
@example
@group
sort ([1+i; 1; 1-i])
    @xresult{} 1 + 0i
       1 - 1i
       1 + 1i
@end group
@end example
 
NaN values are treated as being greater than any other value and are sorted
to the end of the list.
 
The @code{sort} function may also be used to sort strings and cell arrays
of strings, in which case ASCII dictionary order (uppercase 'A' precedes
lowercase 'a') of the strings is used.
 
The algorithm used in @code{sort} is optimized for the sorting of partially
ordered lists.
@seealso{sortrows, issorted}
@end deftypefn */)
{
  int nargin = args.length ();
 
  if (nargin < 1 || nargin > 3)
    print_usage ();
 
  sortmode smode = ASCENDING;
  bool return_idx = (nargout > 1);
  bool have_sortmode = (nargin > 1 && args(1).is_string ());
  octave_value arg = args(0);
 
  int dim = 0;
  if (nargin > 1)
    {
      if (have_sortmode)
        {
          std::string mode = args(1).string_value ();
          if (mode == "ascend")
            smode = ASCENDING;
          else if (mode == "descend")
            smode = DESCENDING;
          else
            error (R"(sort: MODE must be either "ascend" or "descend")");
        }
      else
        {
          // Require dim to be positive real scalar.
          if (! args(1).is_scalar_type () || args(1).iscomplex ()
              || args(1).double_value () <= 0)
            error ("sort: DIM must be a positive scalar integer");
 
          // Forbid fractional value input, also NaN input.
          dim = args(1).strict_int_value ("sort: DIM must be a positive scalar integer") - 1;
        }
    }
 
  if (nargin > 2)
    {
      if (have_sortmode)
        error ("sort: DIM argument must precede MODE argument");
 
      std::string mode = args(2).xstring_value ("sort: MODE must be a string");
 
      if (mode == "ascend")
        smode = ASCENDING;
      else if (mode == "descend")
        smode = DESCENDING;
      else
        error (R"(sort: MODE must be either "ascend" or "descend")");
    }
 
  const dim_vector dv = arg.dims ();
  if (nargin == 1 || have_sortmode)
    {
      dim = dv.first_non_singleton ();
    }
 
  octave_value_list retval (return_idx ? 2 : 1);
 
  if (return_idx)
    {
      Array<octave_idx_type> sidx;
 
      // NOTE: Can not change this to ovl() call because arg.sort changes sidx
      //       and objects are declared const in ovl prototype.
      retval(0) = arg.sort (sidx, dim, smode);
      // Check for index dimension extent. Set to 1 for dimension >= ndims ()
      retval(1) = idx_vector (sidx, (dim < arg.ndims ()) ? dv(dim) : 1);
    }
  else
    retval = ovl (arg.sort (dim, smode));
 
  return retval;
}
 
/*
## Double
%!assert (sort ([NaN, 1, -1, 2, Inf]), [-1, 1, 2, Inf, NaN])
%!assert (sort ([NaN, 1, -1, 2, Inf], 1), [NaN, 1, -1, 2, Inf])
%!assert (sort ([NaN, 1, -1, 2, Inf], 2), [-1, 1, 2, Inf, NaN])
%!assert (sort ([NaN, 1, -1, 2, Inf], 3), [NaN, 1, -1, 2, Inf])
%!assert (sort ([NaN, 1, -1, 2, Inf], "ascend"), [-1, 1, 2, Inf, NaN])
%!assert (sort ([NaN, 1, -1, 2, Inf], 2, "ascend"), [-1, 1, 2, Inf, NaN])
%!assert (sort ([NaN, 1, -1, 2, Inf], "descend"), [NaN, Inf, 2, 1, -1])
%!assert (sort ([NaN, 1, -1, 2, Inf], 2, "descend"), [NaN, Inf, 2, 1, -1])
%!assert (sort ([3, 1, 7, 5; 8, 2, 6, 4]), [3, 1, 6, 4; 8, 2, 7, 5])
%!assert (sort ([3, 1, 7, 5; 8, 2, 6, 4], 1), [3, 1, 6, 4; 8, 2, 7, 5])
%!assert (sort ([3, 1, 7, 5; 8, 2, 6, 4], 2), [1, 3, 5, 7; 2, 4, 6, 8])
%!assert (sort (1), 1)
 
%!test
%! [v, i] = sort ([NaN, 1, -1, Inf, 1]);
%! assert (v, [-1, 1, 1, Inf, NaN]);
%! assert (i, [3, 2, 5, 4, 1]);
 
## Complex
%!assert (sort ([NaN, 1i, -1, 2, Inf]), [1i, -1, 2, Inf, NaN])
%!assert (sort ([NaN, 1i, -1, 2, Inf], 1), [NaN, 1i, -1, 2, Inf])
%!assert (sort ([NaN, 1i, -1, 2, Inf], 2), [1i, -1, 2, Inf, NaN])
%!assert (sort ([NaN, 1i, -1, 2, Inf], 3), [NaN, 1i, -1, 2, Inf])
%!assert (sort ([NaN, 1i, -1, 2, Inf], "ascend"), [1i, -1, 2, Inf, NaN])
%!assert (sort ([NaN, 1i, -1, 2, Inf], 2, "ascend"), [1i, -1, 2, Inf, NaN])
%!assert (sort ([NaN, 1i, -1, 2, Inf], "descend"), [NaN, Inf, 2, -1, 1i])
%!assert (sort ([NaN, 1i, -1, 2, Inf], 2, "descend"), [NaN, Inf, 2, -1, 1i])
%!assert (sort ([3, 1i, 7, 5; 8, 2, 6, 4]), [3, 1i, 6, 4; 8, 2, 7, 5])
%!assert (sort ([3, 1i, 7, 5; 8, 2, 6, 4], 1), [3, 1i, 6, 4; 8, 2, 7, 5])
%!assert (sort ([3, 1i, 7, 5; 8, 2, 6, 4], 2), [1i, 3, 5, 7; 2, 4, 6, 8])
%!assert (sort (1i), 1i)
 
%!test
%! [v, i] = sort ([NaN, 1i, -1, Inf, 1, 1i]);
%! assert (v, [1, 1i, 1i, -1, Inf, NaN]);
%! assert (i, [5, 2, 6, 3, 4, 1]);
 
## Single
%!assert (sort (single ([NaN, 1, -1, 2, Inf])), single ([-1, 1, 2, Inf, NaN]))
%!assert (sort (single ([NaN, 1, -1, 2, Inf]), 1),
%!        single ([NaN, 1, -1, 2, Inf]))
%!assert (sort (single ([NaN, 1, -1, 2, Inf]), 2),
%!        single ([-1, 1, 2, Inf, NaN]))
%!assert (sort (single ([NaN, 1, -1, 2, Inf]), 3),
%!        single ([NaN, 1, -1, 2, Inf]))
%!assert (sort (single ([NaN, 1, -1, 2, Inf]), "ascend"),
%!        single ([-1, 1, 2, Inf, NaN]))
%!assert (sort (single ([NaN, 1, -1, 2, Inf]), 2, "ascend"),
%!        single ([-1, 1, 2, Inf, NaN]))
%!assert (sort (single ([NaN, 1, -1, 2, Inf]), "descend"),
%!        single ([NaN, Inf, 2, 1, -1]))
%!assert (sort (single ([NaN, 1, -1, 2, Inf]), 2, "descend"),
%!        single ([NaN, Inf, 2, 1, -1]))
%!assert (sort (single ([3, 1, 7, 5; 8, 2, 6, 4])),
%!        single ([3, 1, 6, 4; 8, 2, 7, 5]))
%!assert (sort (single ([3, 1, 7, 5; 8, 2, 6, 4]), 1),
%!        single ([3, 1, 6, 4; 8, 2, 7, 5]))
%!assert (sort (single ([3, 1, 7, 5; 8, 2, 6, 4]), 2),
%!        single ([1, 3, 5, 7; 2, 4, 6, 8]))
%!assert (sort (single (1)), single (1))
 
%!test
%! [v, i] = sort (single ([NaN, 1, -1, Inf, 1]));
%! assert (v, single ([-1, 1, 1, Inf, NaN]));
%! assert (i, [3, 2, 5, 4, 1]);
 
## Single Complex
%!assert (sort (single ([NaN, 1i, -1, 2, Inf])),
%!        single ([1i, -1, 2, Inf, NaN]))
%!assert (sort (single ([NaN, 1i, -1, 2, Inf]), 1),
%!        single ([NaN, 1i, -1, 2, Inf]))
%!assert (sort (single ([NaN, 1i, -1, 2, Inf]), 2),
%!        single ([1i, -1, 2, Inf, NaN]))
%!assert (sort (single ([NaN, 1i, -1, 2, Inf]), 3),
%!        single ([NaN, 1i, -1, 2, Inf]))
%!assert (sort (single ([NaN, 1i, -1, 2, Inf]), "ascend"),
%!        single ([1i, -1, 2, Inf, NaN]))
%!assert (sort (single ([NaN, 1i, -1, 2, Inf]), 2, "ascend"),
%!        single ([1i, -1, 2, Inf, NaN]))
%!assert (sort (single ([NaN, 1i, -1, 2, Inf]), "descend"),
%!        single ([NaN, Inf, 2, -1, 1i]))
%!assert (sort (single ([NaN, 1i, -1, 2, Inf]), 2, "descend"),
%!        single ([NaN, Inf, 2, -1, 1i]))
%!assert (sort (single ([3, 1i, 7, 5; 8, 2, 6, 4])),
%!        single ([3, 1i, 6, 4; 8, 2, 7, 5]))
%!assert (sort (single ([3, 1i, 7, 5; 8, 2, 6, 4]), 1),
%!        single ([3, 1i, 6, 4; 8, 2, 7, 5]))
%!assert (sort (single ([3, 1i, 7, 5; 8, 2, 6, 4]), 2),
%!        single ([1i, 3, 5, 7; 2, 4, 6, 8]))
%!assert (sort (single (1i)), single (1i))
 
%!test
%! [v, i] = sort (single ([NaN, 1i, -1, Inf, 1, 1i]));
%! assert (v, single ([1, 1i, 1i, -1, Inf, NaN]));
%! assert (i, [5, 2, 6, 3, 4, 1]);
 
## Bool
%!assert (sort ([true, false, true, false]), [false, false, true, true])
%!assert (sort ([true, false, true, false], 1), [true, false, true, false])
%!assert (sort ([true, false, true, false], 2), [false, false, true, true])
%!assert (sort ([true, false, true, false], 3), [true, false, true, false])
%!assert (sort ([true, false, true, false], "ascend"),
%!        [false, false, true, true])
%!assert (sort ([true, false, true, false], 2, "ascend"),
%!        [false, false, true, true])
%!assert (sort ([true, false, true, false], "descend"),
%!        [true, true, false, false])
%!assert (sort ([true, false, true, false], 2, "descend"),
%!        [true, true, false, false])
%!assert (sort (true), true)
 
%!test
%! [v, i] = sort ([true, false, true, false]);
%! assert (v, [false, false, true, true]);
%! assert (i, [2, 4, 1, 3]);
 
## Sparse Double
%!assert (sort (sparse ([0, NaN, 1, 0, -1, 2, Inf])),
%!        sparse ([-1, 0, 0, 1, 2, Inf, NaN]))
%!assert (sort (sparse ([0, NaN, 1, 0, -1, 2, Inf]), 1),
%!        sparse ([0, NaN, 1, 0, -1, 2, Inf]))
%!assert (sort (sparse ([0, NaN, 1, 0, -1, 2, Inf]), 2),
%!        sparse ([-1, 0, 0, 1, 2, Inf, NaN]))
%!assert (sort (sparse ([0, NaN, 1, 0, -1, 2, Inf]), 3),
%!        sparse ([0, NaN, 1, 0, -1, 2, Inf]))
%!assert (sort (sparse ([0, NaN, 1, 0, -1, 2, Inf]), "ascend"),
%!        sparse ([-1, 0, 0, 1, 2, Inf, NaN]))
%!assert (sort (sparse ([0, NaN, 1, 0, -1, 2, Inf]), 2, "ascend"),
%!        sparse ([-1, 0, 0, 1, 2, Inf, NaN]))
%!assert (sort (sparse ([0, NaN, 1, 0, -1, 2, Inf]), "descend"),
%!        sparse ([NaN, Inf, 2, 1, 0, 0, -1]))
%!assert (sort (sparse ([0, NaN, 1, 0, -1, 2, Inf]), 2, "descend"),
%!        sparse ([NaN, Inf, 2, 1, 0, 0, -1]))
 
%!shared a
%! a = randn (10, 10);
%! a(a < 0) = 0;
%!assert (sort (sparse (a)), sparse (sort (a)))
%!assert (sort (sparse (a), 1), sparse (sort (a, 1)))
%!assert (sort (sparse (a), 2), sparse (sort (a, 2)))
%!test
%! [v, i] = sort (a);
%! [vs, is] = sort (sparse (a));
%! assert (vs, sparse (v));
%! assert (is, i);
 
## Sparse Complex
%!assert (sort (sparse ([0, NaN, 1i, 0, -1, 2, Inf])),
%!        sparse ([0, 0, 1i, -1, 2, Inf, NaN]))
%!assert (sort (sparse ([0, NaN, 1i, 0, -1, 2, Inf]), 1),
%!        sparse ([0, NaN, 1i, 0, -1, 2, Inf]))
%!assert (sort (sparse ([0, NaN, 1i, 0, -1, 2, Inf]), 2),
%!        sparse ([0, 0, 1i, -1, 2, Inf, NaN]))
%!assert (sort (sparse ([0, NaN, 1i, 0, -1, 2, Inf]), 3),
%!        sparse ([0, NaN, 1i, 0, -1, 2, Inf]))
%!assert (sort (sparse ([0, NaN, 1i, 0, -1, 2, Inf]), "ascend"),
%!        sparse ([0, 0, 1i, -1, 2, Inf, NaN]))
%!assert (sort (sparse ([0, NaN, 1i, 0, -1, 2, Inf]), 2, "ascend"),
%!        sparse ([0, 0, 1i, -1, 2, Inf, NaN]))
%!assert (sort (sparse ([0, NaN, 1i, 0, -1, 2, Inf]), "descend"),
%!        sparse ([NaN, Inf, 2, -1, 1i, 0, 0]))
%!assert (sort (sparse ([0, NaN, 1i, 0, -1, 2, Inf]), 2, "descend"),
%!        sparse ([NaN, Inf, 2, -1, 1i, 0, 0]))
 
%!shared a
%! a = randn (10, 10);
%! a(a < 0) = 0;
%! a = 1i * a;
%!assert (sort (sparse (a)), sparse (sort (a)))
%!assert (sort (sparse (a), 1), sparse (sort (a, 1)))
%!assert (sort (sparse (a), 2), sparse (sort (a, 2)))
%!test
%! [v, i] = sort (a);
%! [vs, is] = sort (sparse (a));
%! assert (vs, sparse (v));
%! assert (is, i);
 
## Sparse Bool
%!assert (sort (sparse ([true, false, true, false])),
%!        sparse ([false, false, true, true]))
%!assert (sort (sparse ([true, false, true, false]), 1),
%!        sparse ([true, false, true, false]))
%!assert (sort (sparse ([true, false, true, false]), 2),
%!        sparse ([false, false, true, true]))
%!assert (sort (sparse ([true, false, true, false]), 3),
%!        sparse ([true, false, true, false]))
%!assert (sort (sparse ([true, false, true, false]), "ascend"),
%!        sparse ([false, false, true, true]))
%!assert (sort (sparse ([true, false, true, false]), 2, "ascend"),
%!        sparse ([false, false, true, true]))
%!assert (sort (sparse ([true, false, true, false]), "descend"),
%!        sparse ([true, true, false, false]))
%!assert (sort (sparse ([true, false, true, false]), 2, "descend"),
%!        sparse ([true, true, false, false]))
 
%!test
%! [v, i] = sort (sparse ([true, false, true, false]));
%! assert (v, sparse ([false, false, true, true]));
%! assert (i, [2, 4, 1, 3]);
 
## Cell string array
%!shared a, b, c
%! a = {"Alice", "Cecile", "Eric", "Barry", "David"};
%! b = {"Alice", "Barry", "Cecile", "David", "Eric"};
%! c = {"Eric", "David", "Cecile", "Barry", "Alice"};
%!assert (sort (a), b)
%!assert (sort (a, 1), a)
%!assert (sort (a, 2), b)
%!assert (sort (a, 3), a)
%!assert (sort (a, "ascend"), b)
%!assert (sort (a, 2, "ascend"), b)
%!assert (sort (a, "descend"), c)
%!assert (sort (a, 2, "descend"), c)
 
%!test
%! [v, i] = sort (a);
%! assert (i, [1, 4, 2, 5, 3]);
 
## Test sort dimension being very large
%!test <*65712>
%! A = [1 2; 3 4];
%! assert (sort (A, 100), A);
%! assert (sort (A, inf), A);
%! [B, idx] = sort (A, 100);
%! assert (B, A);
%! assert (idx, ones (2));
%! [B, idx] = sort (A, inf);
%! assert (B, A);
%! assert (idx, ones (2));
 
%!error <Invalid call> sort ()
%!error <Invalid call> sort (1, 2, 3, 4)
%!error <MODE must be either "ascend" or "descend"> sort (1, "foobar")
%!error <DIM must be a positive scalar integer> sort (1, [1 2 3])
%!error <DIM must be a positive scalar integer> sort ([1 2; 3 4], -inf)
%!error <DIM must be a positive scalar integer> sort ([1 2; 3 4], 0)
%!error <DIM must be a positive scalar integer> sort ([1 2; 3 4], 1+i)
%!error <DIM must be a positive scalar integer> sort ([1 2; 3 4], 1.234)
%!error <DIM must be a positive scalar integer> sort ([1 2; 3 4], NaN)
%!error <DIM argument must precede MODE argument> sort (1, "ascend", 1)
%!error <MODE must be a string> sort (1, 1, 1)
%!error <MODE must be either "ascend" or "descend"> sort (1, 1, "foobar")
%!error <DIM must be a positive scalar integer> sort (1, 0)
 
*/
 
// Sort the rows of the matrix @var{a} according to the order
// specified by @var{mode}, which can either be 'ascend' or 'descend'
// and return the index vector corresponding to the sort order.
//
// FIXME: This function does not yet support sparse matrices.
 
DEFUN (__sort_rows_idx__, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{idx} =} __sort_rows_idx__ (@var{A}, @var{mode})
Called internally from @file{sortrows.m}.
@end deftypefn */)
{
  int nargin = args.length ();
 
  if (nargin < 1 || nargin > 2)
    print_usage ();
 
  if (nargin == 2 && ! args(1).is_string ())
    error ("__sort_rows_idx__: second argument must be a string");
 
  sortmode smode = ASCENDING;
  if (nargin > 1)
    {
      std::string mode = args(1).string_value ();
      if (mode == "ascend")
        smode = ASCENDING;
      else if (mode == "descend")
        smode = DESCENDING;
      else
        error (R"(__sort_rows_idx__: MODE must be either "ascend" or "descend")");
    }
 
  octave_value arg = args(0);
 
  if (arg.issparse ())
    error ("__sort_rows_idx__: sparse matrices not yet supported");
 
  if (arg.ndims () != 2)
    error ("__sort_rows_idx__: needs a 2-D object");
 
  Array<octave_idx_type> idx = arg.sort_rows_idx (smode);
 
  // This cannot be ovl(), relies on special overloaded octave_value call.
  return octave_value (idx, true, true);
}
 
static sortmode
get_sort_mode_option (const octave_value& arg)
{
  // FIXME: we initialize to UNSORTED here to avoid a GCC warning
  //        about possibly using sortmode uninitialized.
  // FIXME: shouldn't these modes be scoped inside a class?
  sortmode smode = UNSORTED;
 
  std::string mode = arg.xstring_value ("issorted: MODE must be a string");
 
  if (mode == "ascend")
    smode = ASCENDING;
  else if (mode == "descend")
    smode = DESCENDING;
  else if (mode == "either" || mode == "monotonic")
    smode = UNSORTED;
  else
    error (R"(issorted: MODE must be "ascend", "descend", "monotonic", or "either")");
 
  return smode;
}
 
DEFUN (issorted, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{tf} =} issorted (@var{A})
@deftypefnx {} {@var{tf} =} issorted (@var{A}, @var{mode})
@deftypefnx {} {@var{tf} =} issorted (@var{A}, "rows", @var{mode})
Return true if the vector @var{A} is sorted according to @var{mode}, which may
be either @qcode{"ascend"}, @qcode{"descend"}, @qcode{"either"}, or
@qcode{"monotonic"} (@qcode{"either"} and @qcode{"monotonic"} are equivalent).
 
By default, @var{mode} is @qcode{"ascend"}.  NaNs are treated in the same manner
as @code{sort}.
 
If the optional argument @qcode{"rows"} is supplied, check whether the matrix
is sorted by rows as output by the function @code{sortrows} (with no options).
@emph{Note:} the @qcode{"rows"} argument can not be used with sparse matrices.
 
@seealso{sort, sortrows}
@end deftypefn */)
{
  int nargin = args.length ();
 
  if (nargin < 1 || nargin > 3)
    print_usage ();
 
  bool by_rows = false;
 
  sortmode smode = ASCENDING;
 
  if (nargin > 1)
    {
      if (nargin == 3)
        smode = get_sort_mode_option (args(2));
 
      std::string tmp = args(1).xstring_value ("issorted: second argument must be a string");
      if (tmp == "rows")
        by_rows = true;
      else
        smode = get_sort_mode_option (args(1));
    }
 
  octave_value retval;
 
  octave_value arg = args(0);
 
  if (arg.isempty ())
    retval = true;
  else if (by_rows)
    {
      if (arg.issparse ())
        error ("issorted: sparse matrices not yet supported");
 
      if (arg.ndims () != 2)
        error ("issorted: A must be a 2-D object");
 
      retval = arg.is_sorted_rows (smode) != UNSORTED;
    }
  else
    {
      if (! arg.dims ().isvector ())
        error ("issorted: needs a vector");
 
      retval = args(0).issorted (smode) != UNSORTED;
    }
 
  return retval;
}
 
/*
%!shared sm, um, sv, uv
%! sm = [1, 2; 3, 4];
%! um = [3, 1; 2, 4];
%! sv = [1, 2, 3, 4];
%! uv = [2, 1, 4, 3];
 
%!assert (issorted (sm, "rows"))
%!assert (! issorted (um, "rows"))
%!assert (issorted (sv))
%!assert (! issorted (uv))
%!assert (issorted (sv'))
%!assert (! issorted (uv'))
%!assert (issorted (sm, "rows", "ascend"))
%!assert (! issorted (um, "rows", "ascend"))
%!assert (issorted (sv, "ascend"))
%!assert (! issorted (uv, "ascend"))
%!assert (issorted (sv', "ascend"))
%!assert (! issorted (uv', "ascend"))
%!assert (! issorted (sm, "rows", "descend"))
%!assert (issorted (flipud (sm), "rows", "descend"))
%!assert (! issorted (sv, "descend"))
%!assert (issorted (fliplr (sv), "descend"))
%!assert (! issorted (sv', "descend"))
%!assert (issorted (fliplr (sv)', "descend"))
%!assert (! issorted (um, "rows", "either"))
%!assert (! issorted (uv, "either"))
%!assert (issorted (sm, "rows", "either"))
%!assert (issorted (flipud (sm), "rows", "either"))
%!assert (issorted (sv, "either"))
%!assert (issorted (fliplr (sv), "either"))
%!assert (issorted (sv', "either"))
%!assert (issorted (fliplr (sv)', "either"))
%!assert (issorted (sm, "rows", "monotonic"))
%!assert (issorted (flipud (sm), "rows", "monotonic"))
%!assert (issorted (sv, "either"))
%!assert (issorted (fliplr (sv), "monotonic"))
%!assert (issorted (sv', "either"))
%!assert (issorted (fliplr (sv)', "monotonic"))
 
%!assert (issorted ([]))
%!assert (issorted ([], "rows"))
%!assert (issorted ([], "ascend"))
%!assert (issorted ([], "rows", "ascend"))
%!assert (issorted ([], "descend"))
%!assert (issorted ([], "rows", "descend"))
%!assert (issorted ({}))
%!assert (issorted ({}, "rows"))
%!assert (issorted ({}, "ascend"))
%!assert (issorted ({}, "rows", "ascend"))
%!assert (issorted ({}, "descend"))
%!assert (issorted ({}, "rows", "descend"))
%!assert (issorted (""))
%!assert (issorted ("", "rows"))
%!assert (issorted ("", "ascend"))
%!assert (issorted ("", "rows", "ascend"))
%!assert (issorted ("", "descend"))
%!assert (issorted ("", "rows", "descend"))
 
## Test input validation
%!error issorted ()
%!error issorted (1,2,3,4)
%!error <second argument must be a string> issorted (1, 2)
%!error <second argument must be a string> issorted (1, {"rows"})
%!error <sparse matrices not yet supported> issorted (sparse ([1 2 3]), "rows")
%!error <A must be a 2-D object> issorted (rand (2,2,2), "rows")
%!error <needs a vector> issorted (ones (2,2))
*/
 
DEFUN (nth_element, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{nel} =} nth_element (@var{x}, @var{n})
@deftypefnx {} {@var{nel} =} nth_element (@var{x}, @var{n}, @var{dim})
Select the n-th smallest element of a vector, using the ordering defined by
@code{sort}.
 
The result is equivalent to @code{sort(@var{x})(@var{n})}.
 
@var{n} can also be a contiguous range, either ascending @code{l:u}
or descending @code{u:-1:l}, in which case a range of elements is returned.
 
If @var{x} is an array, @code{nth_element} operates along the dimension
defined by @var{dim}, or the first non-singleton dimension if @var{dim} is
not given.
 
Programming Note: nth_element encapsulates the C++ standard library
algorithms nth_element and partial_sort.  On average, the complexity of the
operation is O(M*log(K)), where @w{@code{M = size (@var{x}, @var{dim})}}@ and
@w{@code{K = length (@var{n})}}.  This function is intended for cases where
the ratio K/M is small; otherwise, it may be better to use @code{sort}.
@seealso{sort, min, max}
@end deftypefn */)
{
  int nargin = args.length ();
 
  if (nargin < 2 || nargin > 3)
    print_usage ();
 
  int dim = -1;
  if (nargin == 3)
    {
      dim = args(2).int_value (true) - 1;
      if (dim < 0)
        error ("nth_element: DIM must be a valid dimension");
    }
 
  octave_value argx = args(0);
  if (dim < 0)
    dim = argx.dims ().first_non_singleton ();
 
  octave_value retval;
 
  try
    {
      idx_vector n = args(1).index_vector ();
 
      switch (argx.builtin_type ())
        {
        case btyp_double:
          retval = argx.array_value ().nth_element (n, dim);
          break;
        case btyp_float:
          retval = argx.float_array_value ().nth_element (n, dim);
          break;
        case btyp_complex:
          retval = argx.complex_array_value ().nth_element (n, dim);
          break;
        case btyp_float_complex:
          retval = argx.float_complex_array_value ().nth_element (n, dim);
          break;
 
#define MAKE_INT_BRANCH(X)                                              \
          case btyp_ ## X:                                              \
            retval = argx.X ## _array_value ().nth_element (n, dim);    \
            break;
 
          MAKE_INT_BRANCH (int8);
          MAKE_INT_BRANCH (int16);
          MAKE_INT_BRANCH (int32);
          MAKE_INT_BRANCH (int64);
          MAKE_INT_BRANCH (uint8);
          MAKE_INT_BRANCH (uint16);
          MAKE_INT_BRANCH (uint32);
          MAKE_INT_BRANCH (uint64);
          MAKE_INT_BRANCH (bool);
 
#undef MAKE_INT_BRANCH
 
        default:
          if (argx.iscellstr ())
            retval = argx.cellstr_value ().nth_element (n, dim);
          else
            err_wrong_type_arg ("nth_element", argx);
        }
    }
  catch (const index_exception& ie)
    {
      error ("nth_element: invalid index %s", ie.what ());
    }
 
  return retval;
}
 
/*
%!assert (nth_element ([1:10], 1), 1)
%!assert (nth_element ([1:10], 10), 10)
%!assert (nth_element ([1:10], 1:3), [1 2 3])
%!assert (nth_element ([1:10], 1:10), [1:10])
 
%!assert <*51329> (nth_element ([1:10], [1:10]), [1:10])
 
%!error nth_element ()
%!error nth_element (1)
%!error nth_element (1, 1.5)
%!error nth_element (1, 2, 3, 4)
%!error nth_element ("abcd", 3)
*/
 
template <typename NDT>
static NDT
do_accumarray_sum (const idx_vector& idx, const NDT& vals,
                   octave_idx_type n = -1)
{
  typedef typename NDT::element_type T;
  if (n < 0)
    n = idx.extent (0);
  else if (idx.extent (n) > n)
    error ("accumarray: index out of range");
 
  NDT retval (dim_vector (n, 1), T ());
 
  if (vals.numel () == 1)
    retval.idx_add (idx, vals (0));
  else if (vals.numel () == idx.length (n))
    retval.idx_add (idx, vals);
  else
    error ("accumarray: dimensions mismatch");
 
  return retval;
}
 
DEFUN (__accumarray_sum__, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {} __accumarray_sum__ (@var{idx}, @var{vals}, @var{n})
Undocumented internal function.
@end deftypefn */)
{
  int nargin = args.length ();
 
  if (nargin < 2 || nargin > 3)
    print_usage ();
 
  if (! args(0).isnumeric ())
    error ("__accumarray_sum__: first argument must be numeric");
 
  octave_value retval;
 
  try
    {
      idx_vector idx = args(0).index_vector ();
      octave_idx_type n = -1;
      if (nargin == 3)
        n = args(2).idx_type_value (true);
 
      octave_value vals = args(1);
 
      if (vals.is_range ())
        {
          range<double> r = vals.range_value ();
          if (r.increment () == 0)
            vals = r.base ();
        }
 
      if (vals.is_single_type ())
        {
          if (vals.iscomplex ())
            retval = do_accumarray_sum (idx,
                                        vals.float_complex_array_value (),
                                        n);
          else
            retval = do_accumarray_sum (idx, vals.float_array_value (), n);
        }
      else if (vals.isnumeric () || vals.islogical ())
        {
          if (vals.iscomplex ())
            retval = do_accumarray_sum (idx,
                                        vals.complex_array_value (),
                                        n);
          else
            retval = do_accumarray_sum (idx, vals.array_value (), n);
        }
      else
        err_wrong_type_arg ("accumarray", vals);
    }
  catch (const index_exception& ie)
    {
      error ("__accumarray_sum__: invalid index %s", ie.what ());
    }
 
  return retval;
}
 
template <typename NDT>
static NDT
do_accumarray_minmax (const idx_vector& idx, const NDT& vals,
                      octave_idx_type n, bool ismin,
                      const typename NDT::element_type& zero_val)
{
  typedef typename NDT::element_type T;
  if (n < 0)
    n = idx.extent (0);
  else if (idx.extent (n) > n)
    error ("accumarray: index out of range");
 
  NDT retval (dim_vector (n, 1), zero_val);
 
  // Pick minimizer or maximizer.
  void (MArray<T>::*op) (const idx_vector&, const MArray<T>&)
    = ismin ? (&MArray<T>::idx_min) : (&MArray<T>::idx_max);
 
  octave_idx_type l = idx.length (n);
  if (vals.numel () == 1)
    (retval.*op) (idx, NDT (dim_vector (l, 1), vals(0)));
  else if (vals.numel () == l)
    (retval.*op) (idx, vals);
  else
    error ("accumarray: dimensions mismatch");
 
  return retval;
}
 
static octave_value_list
do_accumarray_minmax_fcn (const octave_value_list& args,
                          bool ismin)
{
  int nargin = args.length ();
 
  if (nargin < 3 || nargin > 4)
    print_usage ();
 
  if (! args(0).isnumeric ())
    error ("accumarray: first argument must be numeric");
 
  octave_value retval;
 
  try
    {
      idx_vector idx = args(0).index_vector ();
      octave_idx_type n = -1;
      if (nargin == 4)
        n = args(3).idx_type_value (true);
 
      octave_value vals = args(1);
      octave_value zero = args(2);
 
      switch (vals.builtin_type ())
        {
        case btyp_double:
          retval = do_accumarray_minmax (idx, vals.array_value (), n, ismin,
                                         zero.double_value ());
          break;
 
        case btyp_float:
          retval = do_accumarray_minmax (idx, vals.float_array_value (), n,
                                         ismin, zero.float_value ());
          break;
 
        case btyp_complex:
          retval = do_accumarray_minmax (idx, vals.complex_array_value (),
                                         n, ismin, zero.complex_value ());
          break;
 
        case btyp_float_complex:
          retval = do_accumarray_minmax (idx,
                                         vals.float_complex_array_value (),
                                         n, ismin,
                                         zero.float_complex_value ());
          break;
 
#define MAKE_INT_BRANCH(X)                                              \
          case btyp_ ## X:                                              \
            retval = do_accumarray_minmax (idx, vals.X ## _array_value (), \
                                           n, ismin, zero.X ## _scalar_value ()); \
            break;
 
          MAKE_INT_BRANCH (int8);
          MAKE_INT_BRANCH (int16);
          MAKE_INT_BRANCH (int32);
          MAKE_INT_BRANCH (int64);
          MAKE_INT_BRANCH (uint8);
          MAKE_INT_BRANCH (uint16);
          MAKE_INT_BRANCH (uint32);
          MAKE_INT_BRANCH (uint64);
 
#undef MAKE_INT_BRANCH
 
        case btyp_bool:
          retval = do_accumarray_minmax (idx, vals.array_value (), n, ismin,
                                         zero.bool_value ());
          break;
 
        default:
          err_wrong_type_arg ("accumarray", vals);
        }
    }
  catch (const index_exception& ie)
    {
      error ("do_accumarray_minmax_fcn: invalid index %s", ie.what ());
    }
 
  return retval;
}
 
DEFUN (__accumarray_min__, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {} __accumarray_min__ (@var{idx}, @var{vals}, @var{zero}, @var{n})
Undocumented internal function.
@end deftypefn */)
{
  return do_accumarray_minmax_fcn (args, true);
}
 
DEFUN (__accumarray_max__, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {} __accumarray_max__ (@var{idx}, @var{vals}, @var{zero}, @var{n})
Undocumented internal function.
@end deftypefn */)
{
  return do_accumarray_minmax_fcn (args, false);
}
 
template <typename NDT>
static NDT
do_accumdim_sum (const idx_vector& idx, const NDT& vals,
                 int dim = -1, octave_idx_type n = -1)
{
  typedef typename NDT::element_type T;
  if (n < 0)
    n = idx.extent (0);
  else if (idx.extent (n) > n)
    error ("accumdim: index out of range");
 
  const dim_vector& vals_dim = vals.dims ();
  dim_vector rdv = vals_dim;
 
  if (dim < 0)
    dim = vals.dims ().first_non_singleton ();
  else if (dim >= rdv.ndims ())
    rdv.resize (dim+1, 1);
 
  rdv(dim) = n;
 
  NDT retval (rdv, T ());
 
  if (idx.length () != vals_dim(dim))
    error ("accumdim: dimension mismatch");
 
  retval.idx_add_nd (idx, vals, dim);
 
  return retval;
}
 
DEFUN (__accumdim_sum__, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {} __accumdim_sum__ (@var{idx}, @var{vals}, @var{dim}, @var{n})
Undocumented internal function.
@end deftypefn */)
{
  int nargin = args.length ();
 
  if (nargin < 2 || nargin > 4)
    print_usage ();
 
  if (! args(0).isnumeric ())
    error ("__accumdim_sum__: first argument must be numeric");
 
  octave_value retval;
 
  try
    {
      idx_vector idx = args(0).index_vector ();
      int dim = -1;
      if (nargin >= 3)
        dim = args(2).int_value () - 1;
 
      octave_idx_type n = -1;
      if (nargin == 4)
        n = args(3).idx_type_value (true);
 
      octave_value vals = args(1);
 
      if (vals.is_single_type ())
        {
          if (vals.iscomplex ())
            retval = do_accumdim_sum (idx,
                                      vals.float_complex_array_value (),
                                      dim, n);
          else
            retval = do_accumdim_sum (idx, vals.float_array_value (),
                                      dim, n);
        }
      else if (vals.isnumeric () || vals.islogical ())
        {
          if (vals.iscomplex ())
            retval = do_accumdim_sum (idx, vals.complex_array_value (),
                                      dim, n);
          else
            retval = do_accumdim_sum (idx, vals.array_value (), dim, n);
        }
      else
        err_wrong_type_arg ("accumdim", vals);
    }
  catch (const index_exception& ie)
    {
      error ("__accumdim_sum__: invalid index %s", ie.what ());
    }
 
  return retval;
}
 
template <typename NDT>
static NDT
do_merge (const Array<bool>& mask,
          const NDT& tval, const NDT& fval)
{
  typedef typename NDT::element_type T;
  const dim_vector& dv = mask.dims ();
  NDT retval (dv);
 
  bool tscl = tval.numel () == 1;
  bool fscl = fval.numel () == 1;
 
  if ((! tscl && tval.dims () != dv) || (! fscl && fval.dims () != dv))
    error ("merge: MASK, TVAL, and FVAL dimensions must match");
 
  T *rv = retval.rwdata ();
  octave_idx_type n = retval.numel ();
 
  const T *tv = tval.data ();
  const T *fv = fval.data ();
  const bool *mv = mask.data ();
 
  if (tscl)
    {
      if (fscl)
        {
          T ts = tv[0];
          T fs = fv[0];
          for (octave_idx_type i = 0; i < n; i++)
            rv[i] = (mv[i] ? ts : fs);
        }
      else
        {
          T ts = tv[0];
          for (octave_idx_type i = 0; i < n; i++)
            rv[i] = (mv[i] ? ts : fv[i]);
        }
    }
  else
    {
      if (fscl)
        {
          T fs = fv[0];
          for (octave_idx_type i = 0; i < n; i++)
            rv[i] = (mv[i] ? tv[i] : fs);
        }
      else
        {
          for (octave_idx_type i = 0; i < n; i++)
            rv[i] = (mv[i] ? tv[i] : fv[i]);
        }
    }
 
  return retval;
}
 
#define MAKE_INT_BRANCH(INTX)                                           \
  else if (tval.is_ ## INTX ## _type () && fval.is_ ## INTX ## _type ()) \
    {                                                                   \
      retval = do_merge (mask,                                          \
                         tval.INTX ## _array_value (),                  \
                         fval.INTX ## _array_value ());                 \
    }
 
DEFUN (merge, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{M} =} merge (@var{mask}, @var{tval}, @var{fval})
@deftypefnx {} {@var{M} =} ifelse (@var{mask}, @var{tval}, @var{fval})
Merge elements of @var{true_val} and @var{false_val}, depending on the
value of @var{mask}.
 
If @var{mask} is a logical scalar, the other two arguments can be arbitrary
values.  Otherwise, @var{mask} must be a logical array, and @var{tval},
@var{fval} should be arrays of matching class, or cell arrays.  In the
scalar mask case, @var{tval} is returned if @var{mask} is true, otherwise
@var{fval} is returned.
 
In the array mask case, both @var{tval} and @var{fval} must be either
scalars or arrays with dimensions equal to @var{mask}.  The result is
constructed as follows:
 
@example
@group
result(mask) = tval(mask);
result(! mask) = fval(! mask);
@end group
@end example
 
@var{mask} can also be arbitrary numeric type, in which case it is first
converted to logical.
 
Programming Note: @code{ifelse} is an alias for @code{merge} and can be used
interchangeably.
@seealso{logical, diff}
@end deftypefn */)
{
  if (args.length () != 3)
    print_usage ();
 
  if (! (args(0).islogical () || args(0).isnumeric ()))
    error ("merge: first argument must be logical or numeric");
 
  octave_value retval;
 
  octave_value mask_val = args(0);
 
  if (mask_val.is_scalar_type ())
    retval = (mask_val.is_true () ? args(1) : args(2));
  else
    {
      boolNDArray mask = mask_val.bool_array_value ();
 
      octave_value tval = args(1);
      octave_value fval = args(2);
 
      if (tval.is_double_type () && fval.is_double_type ())
        {
          if (tval.iscomplex () || fval.iscomplex ())
            retval = do_merge (mask,
                               tval.complex_array_value (),
                               fval.complex_array_value ());
          else
            retval = do_merge (mask,
                               tval.array_value (),
                               fval.array_value ());
        }
      else if (tval.is_single_type () && fval.is_single_type ())
        {
          if (tval.iscomplex () || fval.iscomplex ())
            retval = do_merge (mask,
                               tval.float_complex_array_value (),
                               fval.float_complex_array_value ());
          else
            retval = do_merge (mask,
                               tval.float_array_value (),
                               fval.float_array_value ());
        }
      else if (tval.is_string () && fval.is_string ())
        {
          bool sq_string = tval.is_sq_string () || fval.is_sq_string ();
          retval = octave_value (do_merge (mask,
                                           tval.char_array_value (),
                                           fval.char_array_value ()),
                                 sq_string ? '\'' : '"');
        }
      else if (tval.iscell () && fval.iscell ())
        {
          retval = do_merge (mask,
                             tval.cell_value (),
                             fval.cell_value ());
        }
 
      MAKE_INT_BRANCH (int8)
      MAKE_INT_BRANCH (int16)
      MAKE_INT_BRANCH (int32)
      MAKE_INT_BRANCH (int64)
      MAKE_INT_BRANCH (uint8)
      MAKE_INT_BRANCH (uint16)
      MAKE_INT_BRANCH (uint32)
      MAKE_INT_BRANCH (uint64)
 
      else
        error ("merge: cannot merge %s with %s with array mask",
               tval.class_name ().c_str (),
               fval.class_name ().c_str ());
    }
 
  return retval;
}
 
DEFALIAS (ifelse, merge);
 
#undef MAKE_INT_BRANCH
 
template <typename SparseT>
static SparseT
do_sparse_diff (const SparseT& array, octave_idx_type order,
                int dim)
{
  SparseT retval = array;
  if (dim == 1)
    {
      octave_idx_type k = retval.columns ();
      while (order > 0 && k > 0)
        {
          idx_vector col1 (':'), col2 (':'), sl1 (1, k), sl2 (0, k-1);
          retval = SparseT (retval.index (col1, sl1))
                   - SparseT (retval.index (col2, sl2));
          panic_unless (retval.columns () == k-1);
          order--;
          k--;
        }
    }
  else
    {
      octave_idx_type k = retval.rows ();
      while (order > 0 && k > 0)
        {
          idx_vector col1 (':'), col2 (':'), sl1 (1, k), sl2 (0, k-1);
          retval = SparseT (retval.index (sl1, col1))
                   - SparseT (retval.index (sl2, col2));
          panic_unless (retval.rows () == k-1);
          order--;
          k--;
        }
    }
 
  return retval;
}
 
static octave_value
do_diff (const octave_value& array, octave_idx_type order,
         int dim = -1)
{
  octave_value retval;
 
  const dim_vector& dv = array.dims ();
  if (dim == -1)
    {
      dim = array.dims ().first_non_singleton ();
 
      // Bother Matlab.  This behavior is really wicked.
      if (dv(dim) <= order)
        {
          if (dv(dim) == 1)
            retval = array.resize (dim_vector (0, 0));
          else
            {
              retval = array;
              while (order > 0)
                {
                  if (dim == dv.ndims ())
                    {
                      retval = do_diff (array, order, dim - 1);
                      order = 0;
                    }
                  else if (dv(dim) == 1)
                    dim++;
                  else
                    {
                      retval = do_diff (array, dv(dim) - 1, dim);
                      order -= dv(dim) - 1;
                      dim++;
                    }
                }
            }
 
          return retval;
        }
    }
 
  if (array.isinteger ())
    {
      if (array.is_int8_type ())
        retval = array.int8_array_value ().diff (order, dim);
      else if (array.is_int16_type ())
        retval = array.int16_array_value ().diff (order, dim);
      else if (array.is_int32_type ())
        retval = array.int32_array_value ().diff (order, dim);
      else if (array.is_int64_type ())
        retval = array.int64_array_value ().diff (order, dim);
      else if (array.is_uint8_type ())
        retval = array.uint8_array_value ().diff (order, dim);
      else if (array.is_uint16_type ())
        retval = array.uint16_array_value ().diff (order, dim);
      else if (array.is_uint32_type ())
        retval = array.uint32_array_value ().diff (order, dim);
      else if (array.is_uint64_type ())
        retval = array.uint64_array_value ().diff (order, dim);
      else
        error ("diff: unexpected integer type - please report this bug");
    }
  else if (array.issparse ())
    {
      if (array.iscomplex ())
        retval = do_sparse_diff (array.sparse_complex_matrix_value (),
                                 order, dim);
      else
        retval = do_sparse_diff (array.sparse_matrix_value (), order, dim);
    }
  else if (array.is_single_type ())
    {
      if (array.iscomplex ())
        retval = array.float_complex_array_value ().diff (order, dim);
      else
        retval = array.float_array_value ().diff (order, dim);
    }
  else
    {
      if (array.iscomplex ())
        retval = array.complex_array_value ().diff (order, dim);
      else
        retval = array.array_value ().diff (order, dim);
    }
 
  return retval;
}
 
DEFUN (diff, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{y} =} diff (@var{x})
@deftypefnx {} {@var{y} =} diff (@var{x}, @var{k})
@deftypefnx {} {@var{y} =} diff (@var{x}, @var{k}, @var{dim})
If @var{x} is a vector of length @math{n}, @w{@code{diff (@var{x})}}@ is the
vector of first differences
@tex
 $x_2 - x_1, \ldots{}, x_n - x_{n-1}$.
@end tex
@ifnottex
 @var{x}(2) - @var{x}(1), @dots{}, @var{x}(n) - @var{x}(n-1).
@end ifnottex
 
If @var{x} is a matrix, @w{@code{diff (@var{x})}}@ is the matrix of column
differences along the first non-singleton dimension.
 
The second argument is optional.  If supplied,
@w{@code{diff (@var{x}, @var{k})}}, where @var{k} is a non-negative integer,
returns the @var{k}-th differences.  It is possible that @var{k} is larger than
the first non-singleton dimension of the matrix.  In this case, @code{diff}
continues to take the differences along the next non-singleton dimension.
 
The dimension along which to take the difference can be explicitly stated with
the optional variable @var{dim}.  In this case the @var{k}-th order differences
are calculated along this dimension.  In the case where @var{k} exceeds
@w{@code{size (@var{x}, @var{dim})}}@ an empty matrix is returned.
@seealso{sort, merge}
@end deftypefn */)
{
  int nargin = args.length ();
 
  if (nargin < 1 || nargin > 3)
    print_usage ();
 
  if (! (args(0).isnumeric () || args(0).islogical ()))
    error ("diff: X must be numeric or logical");
 
  int dim = -1;
  octave_idx_type order = 1;
  if (nargin > 1)
    {
      if (args(1).is_scalar_type ())
        order = args(1).idx_type_value (true, false);
      else if (! args(1).is_zero_by_zero ())
        error ("diff: order K must be a scalar or []");
      if (order < 0)
        error ("diff: order K must be non-negative");
    }
 
  if (nargin > 2)
    {
      dim = args(2).int_value (true, false);
      if (dim < 1 || dim > args(0).ndims ())
        error ("diff: DIM must be a valid dimension");
 
      dim -= 1;
    }
 
  return do_diff (args(0), order, dim);
}
 
/*
%!assert (diff ([1, 2, 3, 4]), [1, 1, 1])
%!assert (diff ([1, 3, 7, 19], 2), [2, 8])
%!assert (diff ([1, 2; 5, 4; 8, 7; 9, 6; 3, 1]), [4, 2; 3, 3; 1, -1; -6, -5])
%!assert (diff ([1, 2; 5, 4; 8, 7; 9, 6; 3, 1], 3), [-1, -5; -5, 0])
%!assert (isempty (diff (1)))
 
%!error diff ()
%!error diff (1, 2, 3, 4)
%!error diff ("foo")
%!error diff ([1, 2; 3, 4], -1)
*/
 
template <typename T>
static Array<T>
do_repelems (const Array<T>& src, const Array<octave_idx_type>& rep)
{
  Array<T> retval;
 
  if (rep.ndims () != 2 || rep.rows () != 2)
    error ("repelems: R must be a 2-row, N-column matrix of integers");
 
  octave_idx_type n = rep.columns ();
  octave_idx_type l = 0;
  for (octave_idx_type i = 0; i < n; i++)
    {
      octave_idx_type k = rep(1, i);
      if (k < 0)
        error ("repelems: second row must contain non-negative numbers");
 
      l += k;
    }
 
  retval.clear (1, l);
  T *dest = retval.rwdata ();
  l = 0;
  for (octave_idx_type i = 0; i < n; i++)
    {
      octave_idx_type k = rep(1, i);
      std::fill_n (dest, k, src.checkelem (rep(0, i) - 1));
      dest += k;
    }
 
  return retval;
}
 
DEFUN (repelems, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{y} =} repelems (@var{x}, @var{r})
Construct a vector of repeated elements from @var{x}.
 
@var{r} is a 2x@var{N} integer matrix specifying which elements to repeat
and how often to repeat each element.  Entries in the first row,
@var{r}(1,j), select an element to repeat.  The corresponding entry in the
second row, @var{r}(2,j), specifies the repeat count.  If @var{x} is a
matrix then the columns of @var{x} are imagined to be stacked on top of
each other for purposes of the selection index.  A row vector is always
returned.
 
Conceptually the result is calculated as follows:
 
@example
@group
y = [];
for i = 1:columns (@var{r})
  y = [y, @var{x}(@var{r}(1,i)*ones(1, @var{r}(2,i)))];
endfor
@end group
@end example
@seealso{repmat, cat}
@end deftypefn */)
{
  if (args.length () != 2)
    print_usage ();
 
  octave_value retval;
 
  const Matrix rm = args(1).matrix_value ();
 
  if (rm.rows () != 2 || rm.ndims () != 2)
    error ("repelems: R must be a matrix with two rows");
 
  octave_value x = args(0);
 
  Array<octave_idx_type> r (rm.dims ());
 
  for (octave_idx_type i = 0; i < rm.numel (); i++)
    {
      octave_idx_type rx = rm(i);
      if (static_cast<double> (rx) != rm(i))
        error ("repelems: R must be a matrix of integers");
 
      r.xelem (i) = rx;
    }
 
  switch (x.builtin_type ())
    {
#define BTYP_BRANCH(X, EX)                              \
      case btyp_ ## X:                                  \
        retval = do_repelems (x.EX ## _value (), r);    \
        break;
 
      BTYP_BRANCH (double, array);
      BTYP_BRANCH (float, float_array);
      BTYP_BRANCH (complex, complex_array);
      BTYP_BRANCH (float_complex, float_complex_array);
      BTYP_BRANCH (bool, bool_array);
      BTYP_BRANCH (char, char_array);
 
      BTYP_BRANCH (int8,  int8_array);
      BTYP_BRANCH (int16, int16_array);
      BTYP_BRANCH (int32, int32_array);
      BTYP_BRANCH (int64, int64_array);
      BTYP_BRANCH (uint8,  uint8_array);
      BTYP_BRANCH (uint16, uint16_array);
      BTYP_BRANCH (uint32, uint32_array);
      BTYP_BRANCH (uint64, uint64_array);
 
      case btyp_cell:
        retval = Cell (do_repelems (x.cell_value (), r));
        break;
 
      //BTYP_BRANCH (struct, map);//FIXME
 
#undef BTYP_BRANCH
 
    default:
      err_wrong_type_arg ("repelems", x);
    }
 
  return retval;
}
 
DEFUN (base64_encode, args, ,
       doc: /* -*- texinfo -*-
@deftypefn {} {@var{s} =} base64_encode (@var{x})
Encode a double matrix or array @var{x} into the base64 format string
@var{s}.
 
@seealso{base64_decode, matlab.net.base64decode, matlab.net.base64encode}
@end deftypefn */)
{
  if (args.length () != 1)
    print_usage ();
 
  if (! args(0).isnumeric ())
    error ("base64_encode: encoding is supported only for numeric arrays");
 
  if (args(0).iscomplex () || args(0).issparse ())
    error ("base64_encode: encoding complex or sparse data is not supported");
 
  octave_value_list retval;
 
  if (args(0).isinteger ())
    {
#define MAKE_INT_BRANCH(X)                                              \
      if (args(0).is_ ## X ## _type ())                                 \
        {                                                               \
          const X##NDArray in = args(0).  X## _array_value ();          \
          std::size_t inlen = in.numel () * sizeof (X## _t) / sizeof (char); \
          const char *inc = reinterpret_cast<const char *> (in.data ()); \
          char *out;                                                    \
          if (base64_encode (inc, inlen, &out))                         \
            {                                                           \
              retval(0) = octave_value (out);                           \
              ::free (out);                                             \
            }                                                           \
        }
 
      MAKE_INT_BRANCH(int8)
      else MAKE_INT_BRANCH(int16)
        else MAKE_INT_BRANCH(int32)
          else MAKE_INT_BRANCH(int64)
            else MAKE_INT_BRANCH(uint8)
              else MAKE_INT_BRANCH(uint16)
                else MAKE_INT_BRANCH(uint32)
                  else MAKE_INT_BRANCH(uint64)
 
#undef MAKE_INT_BRANCH
 
                    else
                      error ("base_64_decode: unexpected integer type - please report this bug");
    }
  else if (args(0).is_single_type ())
    {
      const Array<float> in = args(0).float_array_value ();
      std::size_t inlen;
      inlen = in.numel () * sizeof (float) / sizeof (char);
      const char *inc;
      inc = reinterpret_cast<const char *> (in.data ());
      char *out;
      if (base64_encode (inc, inlen, &out))
        {
          retval(0) = octave_value (out);
          ::free (out);
        }
    }
  else  // double_type
    {
      const Array<double> in = args(0).array_value ();
      std::size_t inlen;
      inlen = in.numel () * sizeof (double) / sizeof (char);
      const char *inc;
      inc = reinterpret_cast<const char *> (in.data ());
      char *out;
      if (base64_encode (inc, inlen, &out))
        {
          retval(0) = octave_value (out);
          ::free (out);
        }
    }
 
  return retval;
}
 
/*
%!test
%! ## FIXME: better test for endianness?
%! if (bitunpack (uint16 (1))(1) == 1)
%!   expected = "2w9JQA==";
%! else
%!   expected = "QEkP2w==";
%! endif
%! assert (base64_encode (single (pi)), expected);
 
%!assert (base64_encode (uint8 ([0 0 0])), "AAAA")
%!assert (base64_encode (uint16 ([0 0 0])), "AAAAAAAA")
%!assert (base64_encode (uint32 ([0 0 0])), "AAAAAAAAAAAAAAAA")
%!assert (base64_encode (uint64 ([0 0 0])), "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA")
%!assert (base64_encode (uint8 ([255 255 255])), "////")
 
%!error base64_encode ()
%!error base64_encode (1,2)
%!error base64_encode ("A string")
%!error base64_encode ({"A cell array"})
%!error base64_encode (struct ())
*/
 
DEFUN (base64_decode, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{x} =} base64_decode (@var{s})
@deftypefnx {} {@var{x} =} base64_decode (@var{s}, @var{dims})
Decode the double matrix or array @var{x} from the base64 encoded string
@var{s}.
 
The optional input parameter @var{dims} should be a vector containing the
dimensions of the decoded array.
@seealso{base64_encode, matlab.net.base64decode, matlab.net.base64encode}
@end deftypefn */)
{
  int nargin = args.length ();
 
  if (nargin < 1 || nargin > 2)
    print_usage ();
 
  std::string str = args(0).xstring_value ("base64_decode: first argument must be a character array");
 
  Array<double> retval = base64_decode (str);
 
  if (nargin == 2)
    {
      dim_vector dims;
 
      const Array<octave_idx_type> size
        = args(1).octave_idx_type_vector_value ();
 
      dims = dim_vector::alloc (size.numel ());
      for (octave_idx_type i = 0; i < size.numel (); i++)
        dims(i) = size(i);
 
      retval = retval.reshape (dims);
    }
 
  return ovl (retval);
}
 
/*
%!assert (base64_decode (base64_encode (pi)), pi)
%!
%!test
%! in   = randn (10);
%! outv = base64_decode (base64_encode (in));
%! outm = base64_decode (base64_encode (in), size (in));
%! assert (outv, in(:).');
%! assert (outm, in);
 
%!error base64_decode ()
%!error base64_decode (1,2,3)
%!error base64_decode (1, "this is not a valid set of dimensions")
%!error <first argument must be a character array> base64_decode (1)
%!error <input was not valid base64> base64_decode ("AQ=")
%!error <incorrect input size> base64_decode ("AQ==")
*/
 
DEFUN (__base64_decode_bytes__, args, ,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{x} =} base64_decode_bytes (@var{s})
@deftypefnx {} {@var{x} =} base64_decode_bytes (@var{s}, @var{dims})
Decode the uint8 matrix or array @var{x} from the base64 encoded string
@var{s}.
 
The optional input parameter @var{dims} should be a vector containing the
dimensions of the decoded array.
@seealso{base64_decode}
@end deftypefn */)
{
  int nargin = args.length ();
 
  if (nargin < 1 || nargin > 2)
    print_usage ();
 
  std::string str = args(0).xstring_value ("__base64_decode_bytes__: first argument must be a character array");
 
  intNDArray<octave_uint8> retval = base64_decode_bytes (str);
 
  if (nargin == 2)
    {
      dim_vector dims;
 
      const Array<octave_idx_type> size
        = args(1).octave_idx_type_vector_value ();
 
      dims = dim_vector::alloc (size.numel ());
      for (octave_idx_type i = 0; i < size.numel (); i++)
        dims(i) = size(i);
 
      retval = retval.reshape (dims);
    }
 
  return ovl (retval);
}
 
/*
%!assert (__base64_decode_bytes__ (base64_encode (uint8 (1))), uint8 (1))
 
%!test
%! in   = uint8 (rand (10)*255);
%! outv = __base64_decode_bytes__ (base64_encode (in));
%! outm = __base64_decode_bytes__ (base64_encode (in), size (in));
%! assert (outv, in(:).');
%! assert (outm, in);
 
%!error __base64_decode_bytes__ ()
%!error __base64_decode_bytes__ (1,2,3)
%!error __base64_decode_bytes__ (1, "this is not a valid set of dimensions")
%!error <first argument must be a character array> __base64_decode_bytes__ (1)
*/
 
OCTAVE_END_NAMESPACE(octave)