Mercurial > octave

comparison src/DLD-FUNCTIONS/cellfun.cc @ 11553:01f703952eff

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Improve docstrings for functions in DLD-FUNCTIONS directory. Use same variable names in error() strings and in documentation.
author Rik <octave@nomad.inbox5.com>
date Sun, 16 Jan 2011 22:13:23 -0800
parents fd0a3ac60b0e
children 57632dea2446
comparison
equal deleted inserted replaced
11552:6b6e9051ecb8 11553:01f703952eff
91 return tmp; 91 return tmp;
92 } 92 }
93 93
94 DEFUN_DLD (cellfun, args, nargout, 94 DEFUN_DLD (cellfun, args, nargout,
95 "-*- texinfo -*-\n\ 95 "-*- texinfo -*-\n\
96 @deftypefn {Loadable Function} {} cellfun (@var{name}, @var{c})\n\ 96 @deftypefn {Loadable Function} {} cellfun (@var{name}, @var{C})\n\
97 @deftypefnx {Loadable Function} {} cellfun (\"size\", @var{c}, @var{k})\n\ 97 @deftypefnx {Loadable Function} {} cellfun (\"size\", @var{C}, @var{k})\n\
98 @deftypefnx {Loadable Function} {} cellfun (\"isclass\", @var{c}, @var{class})\n\ 98 @deftypefnx {Loadable Function} {} cellfun (\"isclass\", @var{C}, @var{class})\n\
99 @deftypefnx {Loadable Function} {} cellfun (@var{func}, @var{c})\n\ 99 @deftypefnx {Loadable Function} {} cellfun (@var{func}, @var{C})\n\
100 @deftypefnx {Loadable Function} {} cellfun (@var{func}, @var{c}, @var{d})\n\ 100 @deftypefnx {Loadable Function} {} cellfun (@var{func}, @var{C}, @var{D})\n\
101 @deftypefnx {Loadable Function} {[@var{a}, @dots{}] =} cellfun (@dots{})\n\ 101 @deftypefnx {Loadable Function} {[@var{a}, @dots{}] =} cellfun (@dots{})\n\
102 @deftypefnx {Loadable Function} {} cellfun (@dots{}, 'ErrorHandler', @var{errfunc})\n\ 102 @deftypefnx {Loadable Function} {} cellfun (@dots{}, 'ErrorHandler', @var{errfunc})\n\
103 @deftypefnx {Loadable Function} {} cellfun (@dots{}, 'UniformOutput', @var{val})\n\ 103 @deftypefnx {Loadable Function} {} cellfun (@dots{}, 'UniformOutput', @var{val})\n\
104 \n\ 104 \n\
105 Evaluate the function named @var{name} on the elements of the cell array\n\ 105 Evaluate the function named @var{name} on the elements of the cell array\n\
106 @var{c}. Elements in @var{c} are passed on to the named function\n\ 106 @var{C}. Elements in @var{C} are passed on to the named function\n\
107 individually. The function @var{name} can be one of the functions\n\ 107 individually. The function @var{name} can be one of the functions\n\
108 \n\ 108 \n\
109 @table @code\n\ 109 @table @code\n\
110 @item isempty\n\ 110 @item isempty\n\
111 Return 1 for empty elements.\n\ 111 Return 1 for empty elements.\n\
135 Additionally, @code{cellfun} accepts an arbitrary function @var{func}\n\ 135 Additionally, @code{cellfun} accepts an arbitrary function @var{func}\n\
136 in the form of an inline function, function handle, or the name of a\n\ 136 in the form of an inline function, function handle, or the name of a\n\
137 function (in a character string). In the case of a character string\n\ 137 function (in a character string). In the case of a character string\n\
138 argument, the function must accept a single argument named @var{x}, and\n\ 138 argument, the function must accept a single argument named @var{x}, and\n\
139 it must return a string value. The function can take one or more arguments,\n\ 139 it must return a string value. The function can take one or more arguments,\n\
140 with the inputs arguments given by @var{c}, @var{d}, etc. Equally the\n\ 140 with the inputs arguments given by @var{C}, @var{D}, etc. Equally the\n\
141 function can return one or more output arguments. For example:\n\ 141 function can return one or more output arguments. For example:\n\
142 \n\ 142 \n\
143 @example\n\ 143 @example\n\
144 @group\n\ 144 @group\n\
145 cellfun (@@atan2, @{1, 0@}, @{0, 1@})\n\ 145 cellfun (@@atan2, @{1, 0@}, @{0, 1@})\n\
221 221
222 octave_value func = args(0); 222 octave_value func = args(0);
223 223
224 if (! args(1).is_cell ()) 224 if (! args(1).is_cell ())
225 { 225 {
226 error ("cellfun: second argument must be a cell array"); 226 error ("cellfun: C must be a cell array");
227 227
228 return retval; 228 return retval;
229 } 229 }
230 230
231 if (func.is_string ()) 231 if (func.is_string ())
283 if (nargin == 3) 283 if (nargin == 3)
284 { 284 {
285 int d = args(2).nint_value () - 1; 285 int d = args(2).nint_value () - 1;
286 286
287 if (d < 0) 287 if (d < 0)
288 error ("cellfun: third argument must be a positive integer"); 288 error ("cellfun: K must be a positive integer");
289 289
290 if (! error_state) 290 if (! error_state)
291 { 291 {
292 NDArray result (f_args.dims ()); 292 NDArray result (f_args.dims ());
293 for (octave_idx_type count = 0; count < k ; count++) 293 for (octave_idx_type count = 0; count < k ; count++)
300 } 300 }
301 retval(0) = result; 301 retval(0) = result;
302 } 302 }
303 } 303 }
304 else 304 else
305 error ("not enough arguments for `size'"); 305 error ("cellfun: not enough arguments for \"size\"");
306 } 306 }
307 else if (name == "isclass") 307 else if (name == "isclass")
308 { 308 {
309 if (nargin == 3) 309 if (nargin == 3)
310 { 310 {
314 result(count) = (f_args.elem(count).class_name() == class_name); 314 result(count) = (f_args.elem(count).class_name() == class_name);
315 315
316 retval(0) = result; 316 retval(0) = result;
317 } 317 }
318 else 318 else
319 error ("not enough arguments for `isclass'"); 319 error ("cellfun: not enough arguments for \"isclass\"");
320 } 320 }
321 else 321 else
322 { 322 {
323 if (! valid_identifier (name)) 323 if (! valid_identifier (name))
324 { 324 {
334 } 334 }
335 else 335 else
336 { 336 {
337 func = symbol_table::find_function (name); 337 func = symbol_table::find_function (name);
338 if (func.is_undefined ()) 338 if (func.is_undefined ())
339 error ("cellfun: invalid function name: %s", name.c_str ()); 339 error ("cellfun: invalid function NAME: %s", name.c_str ());
340 } 340 }
341 } 341 }
342 } 342 }
343 343
344 if (error_state || ! retval.empty ()) 344 if (error_state || ! retval.empty ())
373 { 373 {
374 std::string err_name = args(nargin-1).string_value (); 374 std::string err_name = args(nargin-1).string_value ();
375 error_handler = symbol_table::find_function (err_name); 375 error_handler = symbol_table::find_function (err_name);
376 if (error_handler.is_undefined ()) 376 if (error_handler.is_undefined ())
377 { 377 {
378 error ("cellfun: invalid function name: %s", err_name.c_str ()); 378 error ("cellfun: invalid function NAME: %s", err_name.c_str ());
379 break; 379 break;
380 } 380 }
381 } 381 }
382 else 382 else
383 { 383 {
384 error ("invalid errorhandler value"); 384 error ("cellfun: invalid value for 'ErrorHandler' function");
385 break; 385 break;
386 } 386 }
387 } 387 }
388 else 388 else
389 { 389 {
488 488
489 if (val.numel () == 1) 489 if (val.numel () == 1)
490 retv[j] = val.resize (fdims); 490 retv[j] = val.resize (fdims);
491 else 491 else
492 { 492 {
493 error ("cellfun: expecting all values to be scalars for UniformOutput = true"); 493 error ("cellfun: all values must be scalars when UniformOutput = true");
494 break; 494 break;
495 } 495 }
496 } 496 }
497 } 497 }
498 else 498 else
512 if (error_state) 512 if (error_state)
513 break; 513 break;
514 } 514 }
515 else 515 else
516 { 516 {
517 error ("cellfun: expecting all values to be scalars for UniformOutput = true"); 517 error ("cellfun: all values must be scalars when UniformOutput = true");
518 break; 518 break;
519 } 519 }
520 } 520 }
521 } 521 }
522 } 522 }
574 for (int j = 0; j < nargout1; j++) 574 for (int j = 0; j < nargout1; j++)
575 retval(j) = results[j]; 575 retval(j) = results[j];
576 } 576 }
577 } 577 }
578 else 578 else
579 error ("cellfun: first argument must be a string or function handle"); 579 error ("cellfun: argument NAME must be a string or function handle");
580 580
581 return retval; 581 return retval;
582 } 582 }
583 583
584 /* 584 /*
946 } 946 }
947 947
948 948
949 DEFUN_DLD (num2cell, args, , 949 DEFUN_DLD (num2cell, args, ,
950 "-*- texinfo -*-\n\ 950 "-*- texinfo -*-\n\
951 @deftypefn {Loadable Function} {@var{c} =} num2cell (@var{m})\n\ 951 @deftypefn {Loadable Function} {@var{C} =} num2cell (@var{A})\n\
952 @deftypefnx {Loadable Function} {@var{c} =} num2cell (@var{m}, @var{dim})\n\ 952 @deftypefnx {Loadable Function} {@var{C} =} num2cell (@var{A}, @var{dim})\n\
953 Convert the matrix @var{m} to a cell array. If @var{dim} is defined, the\n\ 953 Convert the numeric matrix @var{A} to a cell array. If @var{dim} is\n\
954 value @var{c} is of dimension 1 in this dimension and the elements of\n\ 954 defined, the value @var{C} is of dimension 1 in this dimension and the\n\
955 @var{m} are placed into @var{c} in slices. For example:\n\ 955 elements of @var{A} are placed into @var{C} in slices. For example:\n\
956 \n\ 956 \n\
957 @example\n\ 957 @example\n\
958 @group\n\ 958 @group\n\
959 num2cell([1,2;3,4])\n\ 959 num2cell([1,2;3,4])\n\
960 @result{} ans =\n\ 960 @result{} ans =\n\
1273 return retval; 1273 return retval;
1274 } 1274 }
1275 1275
1276 DEFUN_DLD (mat2cell, args, , 1276 DEFUN_DLD (mat2cell, args, ,
1277 "-*- texinfo -*-\n\ 1277 "-*- texinfo -*-\n\
1278 @deftypefn {Loadable Function} {@var{b} =} mat2cell (@var{a}, @var{m}, @var{n})\n\ 1278 @deftypefn {Loadable Function} {@var{C} =} mat2cell (@var{A}, @var{m}, @var{n})\n\
1279 @deftypefnx {Loadable Function} {@var{b} =} mat2cell (@var{a}, @var{d1}, @var{d2}, @dots{})\n\ 1279 @deftypefnx {Loadable Function} {@var{C} =} mat2cell (@var{A}, @var{d1}, @var{d2}, @dots{})\n\
1280 @deftypefnx {Loadable Function} {@var{b} =} mat2cell (@var{a}, @var{r})\n\ 1280 @deftypefnx {Loadable Function} {@var{C} =} mat2cell (@var{A}, @var{r})\n\
1281 Convert the matrix @var{a} to a cell array. If @var{a} is 2-D, then\n\ 1281 Convert the matrix @var{A} to a cell array. If @var{A} is 2-D, then\n\
1282 it is required that @code{sum (@var{m}) == size (@var{a}, 1)} and\n\ 1282 it is required that @code{sum (@var{m}) == size (@var{A}, 1)} and\n\
1283 @code{sum (@var{n}) == size (@var{a}, 2)}. Similarly, if @var{a} is\n\ 1283 @code{sum (@var{n}) == size (@var{A}, 2)}. Similarly, if @var{A} is\n\
1284 a multi-dimensional and the number of dimensional arguments is equal\n\ 1284 multi-dimensional and the number of dimensional arguments is equal\n\
1285 to the dimensions of @var{a}, then it is required that @code{sum (@var{di})\n\ 1285 to the dimensions of @var{A}, then it is required that @code{sum (@var{di})\n\
1286 == size (@var{a}, i)}.\n\ 1286 == size (@var{A}, i)}.\n\
1287 \n\ 1287 \n\
1288 Given a single dimensional argument @var{r}, the other dimensional\n\ 1288 Given a single dimensional argument @var{r}, the other dimensional\n\
1289 arguments are assumed to equal @code{size (@var{a},@var{i})}.\n\ 1289 arguments are assumed to equal @code{size (@var{A},@var{i})}.\n\
1290 \n\ 1290 \n\
1291 An example of the use of mat2cell is\n\ 1291 An example of the use of mat2cell is\n\
1292 \n\ 1292 \n\
1293 @example\n\ 1293 @example\n\
1294 mat2cell (reshape(1:16,4,4),[3,1],[3,1])\n\ 1294 mat2cell (reshape(1:16,4,4),[3,1],[3,1])\n\
1476 int dim = -1; 1476 int dim = -1;
1477 if (nargin == 4) 1477 if (nargin == 4)
1478 { 1478 {
1479 dim = args(3).int_value () - 1; 1479 dim = args(3).int_value () - 1;
1480 if (dim < 0) 1480 if (dim < 0)
1481 error ("cellslices: dim must be a valid dimension"); 1481 error ("cellslices: DIM must be a valid dimension");
1482 } 1482 }
1483 1483
1484 if (! error_state) 1484 if (! error_state)
1485 { 1485 {
1486 if (lb.length () != ub.length ()) 1486 if (lb.length () != ub.length ())
1487 error ("cellslices: the lengths of lb and ub must match"); 1487 error ("cellslices: the lengths of LB and UB must match");
1488 else 1488 else
1489 { 1489 {
1490 Cell retcell; 1490 Cell retcell;
1491 if (! x.is_sparse_type () && x.is_matrix_type ()) 1491 if (! x.is_sparse_type () && x.is_matrix_type ())
1492 { 1492 {
1566 1566
1567 DEFUN_DLD (cellindexmat, args, , 1567 DEFUN_DLD (cellindexmat, args, ,
1568 "-*- texinfo -*-\n\ 1568 "-*- texinfo -*-\n\
1569 @deftypefn {Loadable Function} {@var{y} =} cellindexmat (@var{x}, @var{varargin})\n\ 1569 @deftypefn {Loadable Function} {@var{y} =} cellindexmat (@var{x}, @var{varargin})\n\
1570 Given a cell array of matrices @var{x}, this function computes\n\ 1570 Given a cell array of matrices @var{x}, this function computes\n\
1571 \n\
1571 @example\n\ 1572 @example\n\
1573 @group\n\
1572 Y = cell (size (X));\n\ 1574 Y = cell (size (X));\n\
1573 for i = 1:numel (X)\n\ 1575 for i = 1:numel (X)\n\
1574 Y@{i@} = X@{i@}(varargin@{:@});\n\ 1576 Y@{i@} = X@{i@}(varargin@{:@});\n\
1575 endfor\n\ 1577 endfor\n\
1578 @end group\n\
1576 @end example\n\ 1579 @end example\n\
1577 @seealso{cellfun, cellslices}\n\ 1580 @seealso{cellfun, cellslices}\n\
1578 @end deftypefn") 1581 @end deftypefn")
1579 { 1582 {
1580 octave_value retval; 1583 octave_value retval;
1597 } 1600 }
1598 1601
1599 retval = y; 1602 retval = y;
1600 } 1603 }
1601 else 1604 else
1602 error ("cellindexmat: first argument must be a cell"); 1605 error ("cellindexmat: X must be a cell");
1603 } 1606 }
1604 else 1607 else
1605 print_usage (); 1608 print_usage ();
1606 1609
1607 return retval; 1610 return retval;