Defines | Functions

cellfun.cc File Reference

#include <string>
#include <vector>
#include <list>
#include <memory>
#include "caseless-str.h"
#include "lo-mappers.h"
#include "oct-locbuf.h"
#include "Cell.h"
#include "oct-map.h"
#include "defun-dld.h"
#include "parse.h"
#include "variables.h"
#include "ov-colon.h"
#include "unwind-prot.h"
#include "gripes.h"
#include "utils.h"
#include "ov-class.h"
#include "ov-scalar.h"
#include "ov-float.h"
#include "ov-complex.h"
#include "ov-flt-complex.h"
#include "ov-bool.h"
#include "ov-int8.h"
#include "ov-int16.h"
#include "ov-int32.h"
#include "ov-int64.h"
#include "ov-uint8.h"
#include "ov-uint16.h"
#include "ov-uint32.h"
#include "ov-uint64.h"
#include "ov-fcn-handle.h"
Include dependency graph for cellfun.cc:

Go to the source code of this file.

Defines

#define BTYP_BRANCH(X, Y)

Functions

 DEFUN_DLD (cellfun, args, nargout,"-*- texinfo -*-\n\ @deftypefn {Loadable Function} {} cellfun (@var{name}, @var{C})\n\ @deftypefnx {Loadable Function} {} cellfun (\"size\", @var{C}, @var{k})\n\ @deftypefnx {Loadable Function} {} cellfun (\"isclass\", @var{C}, @var{class})\n\ @deftypefnx {Loadable Function} {} cellfun (@var{func}, @var{C})\n\ @deftypefnx {Loadable Function} {} cellfun (@var{func}, @var{C}, @var{D})\n\ @deftypefnx {Loadable Function} {[@var{a}, @dots{}] =} cellfun (@dots{})\n\ @deftypefnx {Loadable Function} {} cellfun (@dots{}, 'ErrorHandler', @var{errfunc})\n\ @deftypefnx {Loadable Function} {} cellfun (@dots{}, 'UniformOutput', @var{val})\n\ \n\ Evaluate the function named @var{name} on the elements of the cell array\n\ @var{C}. Elements in @var{C} are passed on to the named function\n\ individually. The function @var{name} can be one of the functions\n\ \n\ @table @code\n\ @item isempty\n\ Return 1 for empty elements.\n\ \n\ @item islogical\n\ Return 1 for logical elements.\n\ \n\ @item isreal\n\ Return 1 for real elements.\n\ \n\ @item length\n\ Return a vector of the lengths of cell elements.\n\ \n\ @item ndims\n\ Return the number of dimensions of each element.\n\ \n\ @item numel\n\ @itemx prodofsize\n\ Return the number of elements contained within each cell element. The\n\ number is the product of the dimensions of the object at each cell element.\n\ \n\ @item size\n\ Return the size along the @var{k}-th dimension.\n\ \n\ @item isclass\n\ Return 1 for elements of @var{class}.\n\ @end table\n\ \n\ Additionally, @code{cellfun} accepts an arbitrary function @var{func}\n\ in the form of an inline function, function handle, or the name of a\n\ function (in a character string). In the case of a character string\n\ argument, the function must accept a single argument named @var{x}, and\n\ it must return a string value. The function can take one or more arguments,\n\ with the inputs arguments given by @var{C}, @var{D}, etc. Equally the\n\ function can return one or more output arguments. For example:\n\ \n\ @example\n\ @group\n\ cellfun (\"atan2\", @{1, 0@}, @{0, 1@})\n\ @result{}ans = [1.57080 0.00000]\n\ @end group\n\ @end example\n\ \n\ The number of output arguments of @code{cellfun} matches the number of output\n\ arguments of the function. The outputs of the function will be collected\n\ into the output arguments of @code{cellfun} like this:\n\ \n\ @example\n\ @group\n\ function [a, b] = twoouts (x)\n\ a = x;\n\ b = x*x;\n\ endfunction\n\ [aa, bb] = cellfun(@@twoouts, @{1, 2, 3@})\n\ @result{}\n\ aa =\n\ 1 2 3\n\ bb =\n\ 1 4 9\n\ @end group\n\ @end example\n\ \n\ Note that per default the output argument(s) are arrays of the same size as\n\ the input arguments. Input arguments that are singleton (1x1) cells will be\n\ automatically expanded to the size of the other arguments.\n\ \n\ If the parameter 'UniformOutput' is set to true (the default), then the\n\ function must return scalars which will be concatenated into the return\n\ array(s). If 'UniformOutput' is false, the outputs are concatenated into a\n\ cell array (or cell arrays). For example:\n\ \n\ @example\n\ @group\n\ cellfun (\"tolower\", @{\"Foo\", \"Bar\", \"FooBar\"@},\n\ \"UniformOutput\",false)\n\ @result{} ans = @{\"foo\", \"bar\", \"foobar\"@}\n\ @end group\n\ @end example\n\ \n\ Given the parameter 'ErrorHandler', then @var{errfunc} defines a function to\n\ call in case @var{func} generates an error. The form of the function is\n\ \n\ @example\n\ function [@dots{}] = errfunc (@var{s}, @dots{})\n\ @end example\n\ \n\ @noindent\n\ where there is an additional input argument to @var{errfunc} relative to\n\ @var{func}, given by @var{s}. This is a structure with the elements\n\ 'identifier', 'message' and 'index', giving respectively the error\n\ identifier, the error message, and the index into the input arguments\n\ of the element that caused the error. For example:\n\ \n\ @example\n\ @group\n\ function y = foo (s, x), y = NaN; endfunction\n\ cellfun (\"factorial\", @{-1,2@}, 'ErrorHandler', @@foo)\n\ @result{} ans = [NaN 2]\n\ @end group\n\ @end example\n\ \n\ Use @code{cellfun} intelligently. The @code{cellfun} function is a\n\ useful tool for avoiding loops. It is often used with anonymous\n\ function handles; however, calling an anonymous function involves an\n\ overhead quite comparable to the overhead of an m-file function.\n\ Passing a handle to a built-in function is faster, because the\n\ interpreter is not involved in the internal loop. For example:\n\ \n\ @example\n\ @group\n\ a = @{@dots{}@}\n\ v = cellfun (@@(x) det(x), a); # compute determinants\n\ v = cellfun (@@det, a); # faster\n\ @end group\n\ @end example\n\ \n\ @seealso{arrayfun, structfun, spfun}\n\ @end deftypefn")
 DEFUN_DLD (arrayfun, args, nargout,"-*- texinfo -*-\n\ @deftypefn {Function File} {} arrayfun (@var{func}, @var{A})\n\ @deftypefnx {Function File} {@var{x} =} arrayfun (@var{func}, @var{A})\n\ @deftypefnx {Function File} {@var{x} =} arrayfun (@var{func}, @var{A}, @var{b}, @dots{})\n\ @deftypefnx {Function File} {[@var{x}, @var{y}, @dots{}] =} arrayfun (@var{func}, @var{A}, @dots{})\n\ @deftypefnx {Function File} {} arrayfun (@dots{}, \"UniformOutput\", @var{val})\n\ @deftypefnx {Function File} {} arrayfun (@dots{}, \"ErrorHandler\", @var{errfunc})\n\ \n\ Execute a function on each element of an array. This is useful for\n\ functions that do not accept array arguments. If the function does\n\ accept array arguments it is better to call the function directly.\n\ \n\ The first input argument @var{func} can be a string, a function\n\ handle, an inline function, or an anonymous function. The input\n\ argument @var{A} can be a logic array, a numeric array, a string\n\ array, a structure array, or a cell array. By a call of the function\n\ @command{arrayfun} all elements of @var{A} are passed on to the named\n\ function @var{func} individually.\n\ \n\ The named function can also take more than two input arguments, with\n\ the input arguments given as third input argument @var{b}, fourth\n\ input argument @var{c}, @dots{} If given more than one array input\n\ argument then all input arguments must have the same sizes, for\n\ example:\n\ \n\ @example\n\ @group\n\ arrayfun (@@atan2, [1, 0], [0, 1])\n\ @result{} ans = [1.5708 0.0000]\n\ @end group\n\ @end example\n\ \n\ If the parameter @var{val} after a further string input argument\n\ \"UniformOutput\" is set @code{true} (the default), then the named\n\ function @var{func} must return a single element which then will be\n\ concatenated into the return value and is of type matrix. Otherwise,\n\ if that parameter is set to @code{false}, then the outputs are\n\ concatenated in a cell array. For example:\n\ \n\ @example\n\ @group\n\ arrayfun (@@(x,y) x:y, \"abc\", \"def\", \"UniformOutput\", false)\n\ @result{} ans =\n\ @{\n\ [1,1] = abcd\n\ [1,2] = bcde\n\ [1,3] = cdef\n\ @}\n\ @end group\n\ @end example\n\ \n\ If more than one output arguments are given then the named function\n\ must return the number of return values that also are expected, for\n\ example:\n\ \n\ @example\n\ @group\n\ [A, B, C] = arrayfun (@@find, [10; 0], \"UniformOutput\", false)\n\ @result{}\n\ A =\n\ @{\n\ [1,1] = 1\n\ [2,1] = [](0x0)\n\ @}\n\ B =\n\ @{\n\ [1,1] = 1\n\ [2,1] = [](0x0)\n\ @}\n\ C =\n\ @{\n\ [1,1] = 10\n\ [2,1] = [](0x0)\n\ @}\n\ @end group\n\ @end example\n\ \n\ If the parameter @var{errfunc} after a further string input argument\n\ \"ErrorHandler\" is another string, a function handle, an inline\n\ function, or an anonymous function, then @var{errfunc} defines a\n\ function to call in the case that @var{func} generates an error.\n\ The definition of the function must be of the form\n\ \n\ @example\n\ function [@dots{}] = errfunc (@var{s}, @dots{})\n\ @end example\n\ \n\ @noindent\n\ where there is an additional input argument to @var{errfunc}\n\ relative to @var{func}, given by @var{s}. This is a structure with\n\ the elements \"identifier\", \"message\", and \"index\" giving,\n\ respectively, the error identifier, the error message, and the index of\n\ the array elements that caused the error. The size of the output\n\ argument of @var{errfunc} must have the same size as the output\n\ argument of @var{func}, otherwise a real error is thrown. For\n\ example:\n\ \n\ @example\n\ @group\n\ function y = ferr (s, x), y = \"MyString\"; endfunction\n\ arrayfun (@@str2num, [1234],\n\ \"UniformOutput\", false, \"ErrorHandler\", @@ferr)\n\ @result{} ans =\n\ @{\n\ [1,1] = MyString\n\ @}\n\ @end group\n\ @end example\n\ \n\ @seealso{spfun, cellfun, structfun}\n\ @end deftypefn")
 DEFUN_DLD (mat2cell, args,,"-*- texinfo -*-\n\ @deftypefn {Loadable Function} {@var{C} =} mat2cell (@var{A}, @var{m}, @var{n})\n\ @deftypefnx {Loadable Function} {@var{C} =} mat2cell (@var{A}, @var{d1}, @var{d2}, @dots{})\n\ @deftypefnx {Loadable Function} {@var{C} =} mat2cell (@var{A}, @var{r})\n\ Convert the matrix @var{A} to a cell array. If @var{A} is 2-D, then\n\ it is required that @code{sum (@var{m}) == size (@var{A}, 1)} and\n\ @code{sum (@var{n}) == size (@var{A}, 2)}. Similarly, if @var{A} is\n\ multi-dimensional and the number of dimensional arguments is equal\n\ to the dimensions of @var{A}, then it is required that @code{sum (@var{di})\n\ == size (@var{A}, i)}.\n\ \n\ Given a single dimensional argument @var{r}, the other dimensional\n\ arguments are assumed to equal @code{size (@var{A},@var{i})}.\n\ \n\ An example of the use of mat2cell is\n\ \n\ @example\n\ mat2cell (reshape(1:16,4,4),[3,1],[3,1])\n\ @result{} @{\n\ [1,1] =\n\ \n\ 1 5 9\n\ 2 6 10\n\ 3 7 11\n\ \n\ [2,1] =\n\ \n\ 4 8 12\n\ \n\ [1,2] =\n\ \n\ 13\n\ 14\n\ 15\n\ \n\ [2,2] = 16\n\ @}\n\ @end example\n\ @seealso{num2cell, cell2mat}\n\ @end deftypefn")
 DEFUN_DLD (cellslices, args,,"-*- texinfo -*-\n\ @deftypefn {Loadable Function} {@var{sl} =} cellslices (@var{x}, @var{lb}, @var{ub}, @var{dim})\n\ Given an array @var{x}, this function produces a cell array of slices from\n\ the array determined by the index vectors @var{lb}, @var{ub}, for lower and\n\ upper bounds, respectively. In other words, it is equivalent to the\n\ following code:\n\ \n\ @example\n\ @group\n\ n = length (lb);\n\ sl = cell (1, n);\n\ for i = 1:length (lb)\n\ sl@{i@} = x(:,@dots{},lb(i):ub(i),@dots{},:);\n\ endfor\n\ @end group\n\ @end example\n\ \n\ The position of the index is determined by @var{dim}. If not specified,\n\ slicing is done along the first non-singleton dimension.\n\ @seealso{cell2mat, cellindexmat, cellfun}\n\ @end deftypefn")
 DEFUN_DLD (cellindexmat, args,,"-*- texinfo -*-\n\ @deftypefn {Loadable Function} {@var{y} =} cellindexmat (@var{x}, @var{varargin})\n\ Given a cell array of matrices @var{x}, this function computes\n\ \n\ @example\n\ @group\n\ Y = cell (size (X));\n\ for i = 1:numel (X)\n\ Y@{i@} = X@{i@}(varargin@{:@});\n\ endfor\n\ @end group\n\ @end example\n\ @seealso{cellslices, cellfun}\n\ @end deftypefn")
 DEFUN_DLD (num2cell, args,,"-*- texinfo -*-\n\ @deftypefn {Loadable Function} {@var{C} =} num2cell (@var{A})\n\ @deftypefnx {Loadable Function} {@var{C} =} num2cell (@var{A}, @var{dim})\n\ Convert the numeric matrix @var{A} to a cell array. If @var{dim} is\n\ defined, the value @var{C} is of dimension 1 in this dimension and the\n\ elements of @var{A} are placed into @var{C} in slices. For example:\n\ \n\ @example\n\ @group\n\ num2cell([1,2;3,4])\n\ @result{} ans =\n\ @{\n\ [1,1] = 1\n\ [2,1] = 3\n\ [1,2] = 2\n\ [2,2] = 4\n\ @}\n\ num2cell([1,2;3,4],1)\n\ @result{} ans =\n\ @{\n\ [1,1] =\n\ 1\n\ 3\n\ [1,2] =\n\ 2\n\ 4\n\ @}\n\ @end group\n\ @end example\n\ \n\ @seealso{mat2cell}\n\ @end deftypefn")
template<class NDA >
static Cell do_cellslices_nda (const NDA &array, const Array< octave_idx_type > &lb, const Array< octave_idx_type > &ub, int dim=-1)
template<class ArrayND >
Cell do_mat2cell (const ArrayND &a, const Array< octave_idx_type > *d, int nd)
Cell do_mat2cell (octave_value &a, const Array< octave_idx_type > *d, int nd)
template<class Array2D >
static Cell do_mat2cell_2d (const Array2D &a, const Array< octave_idx_type > *d, int nd)
template<class ArrayND >
Cell do_mat2cell_nd (const ArrayND &a, const Array< octave_idx_type > *d, int nd)
template<class NDA >
static Cell do_num2cell (const NDA &array, const Array< int > &dimv)
template<class NDA >
static NDA::element_type do_num2cell_elem (const NDA &array, octave_idx_type i)
static Cell do_num2cell_elem (const Cell &array, octave_idx_type i)
static void do_num2cell_helper (const dim_vector &dv, const Array< int > &dimv, dim_vector &celldv, dim_vector &arraydv, Array< int > &perm)
static Cell do_object2cell (const octave_value &obj, const Array< int > &dimv)
static void get_mapper_fun_options (const octave_value_list &args, int &nargin, bool &uniform_output, octave_value &error_handler)
static dim_vector get_object_dims (octave_value &obj)
static octave_value_list get_output_list (octave_idx_type count, octave_idx_type nargout, const octave_value_list &inputlist, octave_value &func, octave_value &error_handler)
static bool mat2cell_mismatch (const dim_vector &dv, const Array< octave_idx_type > *d, int nd)
template<class container >
static void prepare_idx (container *idx, int idim, int nd, const Array< octave_idx_type > *d)
static octave_value_list try_cellfun_internal_ops (const octave_value_list &args, int nargin)

Define Documentation

#define BTYP_BRANCH (   X,
  Y 
)
Value:
case btyp_ ## X: \
            retval = do_mat2cell (a.Y ## _value (), d, nargin - 1); \
          break

Function Documentation

DEFUN_DLD ( cellfun  ,
args  ,
nargout   
)
DEFUN_DLD ( arrayfun  ,
args  ,
nargout   
)
DEFUN_DLD ( mat2cell  ,
args   
)
DEFUN_DLD ( cellslices  ,
args   
)
DEFUN_DLD ( cellindexmat  ,
args   
)
DEFUN_DLD ( num2cell  ,
args   
)
template<class NDA >
static Cell do_cellslices_nda ( const NDA &  array,
const Array< octave_idx_type > &  lb,
const Array< octave_idx_type > &  ub,
int  dim = -1 
) [static]
template<class ArrayND >
Cell do_mat2cell ( const ArrayND &  a,
const Array< octave_idx_type > *  d,
int  nd 
)

Definition at line 2078 of file cellfun.cc.

References do_mat2cell_2d(), and do_mat2cell_nd().

Referenced by DEFUN_DLD().

Cell do_mat2cell ( octave_value a,
const Array< octave_idx_type > *  d,
int  nd 
)
template<class Array2D >
static Cell do_mat2cell_2d ( const Array2D &  a,
const Array< octave_idx_type > *  d,
int  nd 
) [static]

Definition at line 1970 of file cellfun.cc.

References Array< T >::length(), mat2cell_mismatch(), OCTAVE_LOCAL_BUFFER, and prepare_idx().

Referenced by DEFUN_DLD(), and do_mat2cell().

template<class ArrayND >
Cell do_mat2cell_nd ( const ArrayND &  a,
const Array< octave_idx_type > *  d,
int  nd 
)
template<class NDA >
static Cell do_num2cell ( const NDA &  array,
const Array< int > &  dimv 
) [static]
template<class NDA >
static NDA::element_type do_num2cell_elem ( const NDA &  array,
octave_idx_type  i 
) [inline, static]

Definition at line 1706 of file cellfun.cc.

Referenced by do_num2cell().

static Cell do_num2cell_elem ( const Cell array,
octave_idx_type  i 
) [inline, static]

Definition at line 1710 of file cellfun.cc.

static void do_num2cell_helper ( const dim_vector dv,
const Array< int > &  dimv,
dim_vector celldv,
dim_vector arraydv,
Array< int > &  perm 
) [static]
static Cell do_object2cell ( const octave_value obj,
const Array< int > &  dimv 
) [static]
static void get_mapper_fun_options ( const octave_value_list args,
int nargin,
bool uniform_output,
octave_value error_handler 
) [static]
static dim_vector get_object_dims ( octave_value obj  )  [static]

Definition at line 1755 of file cellfun.cc.

References Array< T >::numel(), dim_vector::resize(), and octave_value::size().

Referenced by do_object2cell().

static octave_value_list get_output_list ( octave_idx_type  count,
octave_idx_type  nargout,
const octave_value_list inputlist,
octave_value func,
octave_value error_handler 
) [static]
static bool mat2cell_mismatch ( const dim_vector dv,
const Array< octave_idx_type > *  d,
int  nd 
) [static]

Definition at line 1923 of file cellfun.cc.

References error(), dim_vector::length(), and Array< T >::length().

Referenced by do_mat2cell(), do_mat2cell_2d(), and do_mat2cell_nd().

template<class container >
static void prepare_idx ( container *  idx,
int  idim,
int  nd,
const Array< octave_idx_type > *  d 
) [static]

Definition at line 1947 of file cellfun.cc.

References idx_vector::colon, and Array< T >::numel().

Referenced by do_mat2cell(), do_mat2cell_2d(), and do_mat2cell_nd().

static octave_value_list try_cellfun_internal_ops ( const octave_value_list args,
int  nargin 
) [static]
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Defines