Mercurial > octave
changeset 21966:112b20240c87
move docstrings in C++ files out of C strings and into comments
* __contourc__.cc, __dispatch__.cc, __dsearchn__.cc, __ichol__.cc,
__ilu__.cc, __lin_interpn__.cc, __luinc__.cc, __magick_read__.cc,
__pchip_deriv__.cc, __qp__.cc, balance.cc, besselj.cc, betainc.cc,
bitfcns.cc, bsxfun.cc, cellfun.cc, colloc.cc, conv2.cc, daspk.cc,
dasrt.cc, dassl.cc, data.cc, debug.cc, defaults.cc, det.cc, dirfns.cc,
dlmread.cc, dot.cc, eig.cc, ellipj.cc, error.cc, fft.cc, fft2.cc,
fftn.cc, file-io.cc, filter.cc, find.cc, gammainc.cc, gcd.cc,
getgrent.cc, getpwent.cc, getrusage.cc, givens.cc, graphics.cc,
hash.cc, help.cc, hess.cc, hex2num.cc, input.cc, inv.cc, kron.cc,
load-path.cc, load-save.cc, lookup.cc, ls-oct-text.cc, lsode.cc,
lu.cc, mappers.cc, matrix_type.cc, max.cc, mgorth.cc, nproc.cc,
oct-hist.cc, octave-link.cc, ordschur.cc, pager.cc, pinv.cc,
pr-output.cc, profiler.cc, psi.cc, pt-jit.cc, quad.cc, quadcc.cc,
qz.cc, rand.cc, rcond.cc, regexp.cc, schur.cc, sighandlers.cc,
sparse.cc, spparms.cc, sqrtm.cc, str2double.cc, strfind.cc, strfns.cc,
sub2ind.cc, svd.cc, sylvester.cc, symtab.cc, syscalls.cc, sysdep.cc,
time.cc, toplev.cc, tril.cc, tsearch.cc, typecast.cc, urlwrite.cc,
utils.cc, variables.cc, __delaunayn__.cc, __eigs__.cc,
__fltk_uigetfile__.cc, __glpk__.cc, __init_fltk__.cc,
__init_gnuplot__.cc, __osmesa_print__.cc, __voronoi__.cc, amd.cc,
audiodevinfo.cc, audioread.cc, ccolamd.cc, chol.cc, colamd.cc,
convhulln.cc, dmperm.cc, fftw.cc, qr.cc, symbfact.cc, symrcm.cc,
ov-base.cc, ov-bool-mat.cc, ov-cell.cc, ov-class.cc, ov-classdef.cc,
ov-fcn-handle.cc, ov-fcn-inline.cc, ov-flt-re-mat.cc, ov-int16.cc,
ov-int32.cc, ov-int64.cc, ov-int8.cc, ov-java.cc, ov-null-mat.cc,
ov-oncleanup.cc, ov-range.cc, ov-re-mat.cc, ov-struct.cc,
ov-typeinfo.cc, ov-uint16.cc, ov-uint32.cc, ov-uint64.cc, ov-uint8.cc,
ov-usr-fcn.cc, ov.cc, octave.cc, pt-arg-list.cc, pt-binop.cc,
pt-eval.cc, pt-mat.cc, lex.ll, oct-parse.in.yy:
Docstrings are now comments instead of C strings.
* build-aux/mk-opts.pl: Emit docstrings as comments instead of C
strings.
* DASPK-opts.in, LSODE-opts.in: Don't quote " in docstring fragments.
* builtins.h: Include builtin-defun-decls.h unconditionally.
* defun.h (DEFUN, DEFUNX, DEFCONSTFUN): Simply emit declaration.
(DEFALIAS): Always expand to nothing.
* defun-dld.h: No special macro expansions for MAKE_BUILTINS.
(DEFUN_DLD): Use FORWARD_DECLARE_FUN.
(DEFUNX_DLD): Use FORWARD_DECLARE_FUNX.
* defun-int.h: No special macro expansions for MAKE_BUILTINS.
(FORWARD_DECLARE_FUN, FORWARD_DECLARE_FUNX): New macros.
(DEFINE_FUN_INSTALLER_FUN): If compiling an Octave source file, pass
"external-doc" to DEFINE_FUNX_INSTALLER_FUN.
(DEFUN_INTERNAL, DEFCONSTFUN_INTERNAL, DEFUNX_INTERNAL,
DEFALIAS_INTERNAL): Delete.
* common.mk (move_if_change_rule): New macro.
(simple_move_if_change_rule): Define using move_if_change_rule.
* find-defun-files.sh (DEFUN_PATTERN): Update. Don't transform file
name extension to ".df".
* libinterp/mk-pkg-add, gendoc.pl: Operate directly on source files.
* mkbuiltins: New argument, SRCDIR. Operate directly on source files.
* mkdefs: Delete.
* libinterp/module.mk (BUILT_SOURCES): Update list to contain only
files included in other source files.
(GENERATED_MAKE_BUILTINS_INCS, DEF_FILES): Delete.
(LIBINTERP_BUILT_DISTFILES): Include $(OPT_HANDLERS) here.
(LIBINTERP_BUILT_NODISTFILES): Not here. Remove $(ALL_DEF_FILES from
the list.
(libinterp_EXTRA_DIST): Remove mkdefs from the list.
(FOUND_DEFUN_FILES): Rename from SRC_DEF_FILES.
(DLDFCN_DEFUN_FILES): Rename from DLDFCN_DEF_FILES.
(SRC_DEFUN_FILES): Rename from SRC_DEF_FILES.
(ALL_DEFUN_FILES): Rename from ALL_DEF_FILES.
(%.df: %.cc): Delete pattern rule.
(libinterp/build-env-features.cc, libinterp/builtins.cc,
libinterp/dldfcn/PKG_ADD): Use mv instead of move-if-change.
(libinterp/builtins.cc, libinterp/builtin-defun-decls.h):
Update mkbuiltins command.
($(srcdir)/libinterp/DOCSTRINGS): Update gendoc.pl command.
* liboctave/module.mk (BUILT_SOURCES): Don't include
liboctave-build-info.cc in the list.
line wrap: on
line diff
--- a/build-aux/common.mk Tue Jun 21 13:08:25 2016 -0700 +++ b/build-aux/common.mk Tue Jun 21 16:07:51 2016 -0400 @@ -70,16 +70,20 @@ # The following pattern rules and the substitution functions require # GNU make. If you don't have it, get it! -define simple_move_if_change_rule - if [ -s $@-t ]; then \ - ${SHELL} ${top_srcdir}/build-aux/move-if-change $@-t $@; \ +define move_if_change_rule + if [ -s $(1) ]; then \ + ${SHELL} ${top_srcdir}/build-aux/move-if-change $(1) $(2); \ else \ - echo "$@-t is empty!" 1>&2; \ - rm -f $@-t; \ + echo "$(1) is empty!" 1>&2; \ + rm -f $(1); \ exit 1; \ fi endef +define simple_move_if_change_rule + $(call move_if_change_rule,$@-t,$@) +endef + define cp_update_rule if [ "x${srcdir}" != "x." ] && [ -f ${srcdir}/$@ ] && [ ! -f $@ ]; then \ cp ${srcdir}/$@ $@; \
--- a/build-aux/mk-opts.pl Tue Jun 21 13:08:25 2016 -0700 +++ b/build-aux/mk-opts.pl Tue Jun 21 16:07:51 2016 -0400 @@ -155,7 +155,6 @@ { $DOC_ITEM[$OPT_NUM] .= $_; } - $DOC_ITEM[$OPT_NUM] =~ s/\n/\\n\\\n/g; } elsif (/^\s*TYPE\s*=\s*"(.*)"\s*$/) { @@ -231,14 +230,14 @@ if (not defined $DOC_STRING) { - $DOC_STRING = "Query or set options for the function \@code{$FCN_NAME}.\\n\\ -\\n\\ -When called with no arguments, the names of all available options and\\n\\ -their current values are displayed.\\n\\ -\\n\\ -Given one argument, return the value of the option \@var{opt}.\\n\\ -\\n\\ -When called with two arguments, \@code{$OPT_FCN_NAME} sets the option\\n\\ + $DOC_STRING = "Query or set options for the function \@code{$FCN_NAME}. + +When called with no arguments, the names of all available options and +their current values are displayed. + +Given one argument, return the value of the option \@var{opt}. + +When called with two arguments, \@code{$OPT_FCN_NAME} sets the option \@var{opt} to value \@var{val}."; } } @@ -906,27 +905,27 @@ { print <<"_END_EMIT_OPTIONS_FUNCTION_HDR_"; DEFUN ($OPT_FCN_NAME, args, , - "-*- texinfo -*-\\n\\ -\@deftypefn {} {} $OPT_FCN_NAME ()\\n\\ -\@deftypefnx {} {val =} $OPT_FCN_NAME (\@var{opt})\\n\\ -\@deftypefnx {} {} $OPT_FCN_NAME (\@var{opt}, \@var{val})\\n\\ -$DOC_STRING\\n\\ -\\n\\ -Options include\\n\\ -\\n\\ -\@table \@code\\n\\ + doc: /* -*- texinfo -*- +\@deftypefn {} {} $OPT_FCN_NAME () +\@deftypefnx {} {val =} $OPT_FCN_NAME (\@var{opt}) +\@deftypefnx {} {} $OPT_FCN_NAME (\@var{opt}, \@var{val}) +$DOC_STRING + +Options include + +\@table \@code _END_EMIT_OPTIONS_FUNCTION_HDR_ # FIXME: Add extra newline above for (my $i = 0; $i < $OPT_NUM; $i++) { - print '@item @qcode{\"', $NAME[$i], '\"}\n\\', "\n"; + print '@item @qcode{"', $NAME[$i], '"}', "\n"; print $DOC_ITEM[$i] if $DOC_ITEM[$i]; } print <<"_END_EMIT_OPTIONS_FUNCTION_BODY_"; -\@end table\\n\\ -\@end deftypefn") +\@end table +\@end deftypefn */) { octave_value_list retval;
--- a/libinterp/builtins.h Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/builtins.h Tue Jun 21 16:07:51 2016 -0400 @@ -25,9 +25,7 @@ #include "octave-config.h" -#if ! defined (MAKE_BUILTINS) -# include "builtin-defun-decls.h" -#endif +#include "builtin-defun-decls.h" extern OCTINTERP_API void install_builtins (void);
--- a/libinterp/corefcn/__contourc__.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/__contourc__.cc Tue Jun 21 16:07:51 2016 -0400 @@ -299,10 +299,10 @@ } DEFUN (__contourc__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __contourc__ (@var{x}, @var{y}, @var{z}, @var{levels})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __contourc__ (@var{x}, @var{y}, @var{z}, @var{levels}) +Undocumented internal function. +@end deftypefn */) { if (args.length () != 4) print_usage ();
--- a/libinterp/corefcn/__dispatch__.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/__dispatch__.cc Tue Jun 21 16:07:51 2016 -0400 @@ -40,7 +40,10 @@ #include "variables.h" DEFUN (__dispatch__, args, nargout, - "Undocumented internal function") + doc: /* -*- texinfo -*- +@deftypefn {} {} __dispatch__ () +Undocumented internal function. +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/__dsearchn__.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/__dsearchn__.cc Tue Jun 21 16:07:51 2016 -0400 @@ -35,10 +35,10 @@ #include "ovl.h" DEFUN (__dsearchn__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{idx}, @var{d}] =} dsearch (@var{x}, @var{xi})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{idx}, @var{d}] =} dsearch (@var{x}, @var{xi}) +Undocumented internal function. +@end deftypefn */) { if (args.length () != 2) print_usage ();
--- a/libinterp/corefcn/__ichol__.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/__ichol__.cc Tue Jun 21 16:07:51 2016 -0400 @@ -180,11 +180,11 @@ } DEFUN (__ichol0__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{L} =} __ichol0__ (@var{A})\n\ -@deftypefnx {} {@var{L} =} __ichol0__ (@var{A}, @var{michol})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{L} =} __ichol0__ (@var{A}) +@deftypefnx {} {@var{L} =} __ichol0__ (@var{A}, @var{michol}) +Undocumented internal function. +@end deftypefn */) { std::string michol = "off"; if (args.length ()) @@ -415,12 +415,12 @@ } DEFUN (__icholt__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{L} =} __icholt__ (@var{A})\n\ -@deftypefnx {} {@var{L} =} __icholt__ (@var{A}, @var{droptol})\n\ -@deftypefnx {} {@var{L} =} __icholt__ (@var{A}, @var{droptol}, @var{michol})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{L} =} __icholt__ (@var{A}) +@deftypefnx {} {@var{L} =} __icholt__ (@var{A}, @var{droptol}) +@deftypefnx {} {@var{L} =} __icholt__ (@var{A}, @var{droptol}, @var{michol}) +Undocumented internal function. +@end deftypefn */) { int nargin = args.length (); // Default values of parameters
--- a/libinterp/corefcn/__ilu__.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/__ilu__.cc Tue Jun 21 16:07:51 2016 -0400 @@ -134,12 +134,12 @@ } DEFUN (__ilu0__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{L}, @var{U}] =} __ilu0__ (@var{A})\n\ -@deftypefnx {} {[@var{L}, @var{U}] =} __ilu0__ (@var{A}, @var{milu})\n\ -@deftypefnx {} {[@var{L}, @var{U}, @var{P}] =} __ilu0__ (@var{A}, @dots{})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{L}, @var{U}] =} __ilu0__ (@var{A}) +@deftypefnx {} {[@var{L}, @var{U}] =} __ilu0__ (@var{A}, @var{milu}) +@deftypefnx {} {[@var{L}, @var{U}, @var{P}] =} __ilu0__ (@var{A}, @dots{}) +Undocumented internal function. +@end deftypefn */) { int nargin = args.length (); @@ -468,12 +468,12 @@ } DEFUN (__iluc__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{L}, @var{U}] =} __iluc__ (@var{A})\n\ -@deftypefnx {} {[@var{L}, @var{U}] =} __iluc__ (@var{A}, @var{droptol})\n\ -@deftypefnx {} {[@var{L}, @var{U}] =} __iluc__ (@var{A}, @var{droptol}, @var{milu})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{L}, @var{U}] =} __iluc__ (@var{A}) +@deftypefnx {} {[@var{L}, @var{U}] =} __iluc__ (@var{A}, @var{droptol}) +@deftypefnx {} {[@var{L}, @var{U}] =} __iluc__ (@var{A}, @var{droptol}, @var{milu}) +Undocumented internal function. +@end deftypefn */) { int nargin = args.length (); @@ -926,15 +926,15 @@ } DEFUN (__ilutp__, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{L}, @var{U}] =} __ilutp__ (@var{A})\n\ -@deftypefnx {} {[@var{L}, @var{U}] =} __ilutp__ (@var{A}, @var{droptol})\n\ -@deftypefnx {} {[@var{L}, @var{U}] =} __ilutp__ (@var{A}, @var{droptol}, @var{thresh})\n\ -@deftypefnx {} {[@var{L}, @var{U}] =} __ilutp__ (@var{A}, @var{droptol}, @var{thresh}, @var{milu})\n\ -@deftypefnx {} {[@var{L}, @var{U}] =} __ilutp__ (@var{A}, @var{droptol}, @var{thresh}, @var{milu}, @var{udiag})\n\ -@deftypefnx {} {[@var{L}, @var{U}, @var{P}] =} __ilutp__ (@var{A}, @dots{})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{L}, @var{U}] =} __ilutp__ (@var{A}) +@deftypefnx {} {[@var{L}, @var{U}] =} __ilutp__ (@var{A}, @var{droptol}) +@deftypefnx {} {[@var{L}, @var{U}] =} __ilutp__ (@var{A}, @var{droptol}, @var{thresh}) +@deftypefnx {} {[@var{L}, @var{U}] =} __ilutp__ (@var{A}, @var{droptol}, @var{thresh}, @var{milu}) +@deftypefnx {} {[@var{L}, @var{U}] =} __ilutp__ (@var{A}, @var{droptol}, @var{thresh}, @var{milu}, @var{udiag}) +@deftypefnx {} {[@var{L}, @var{U}, @var{P}] =} __ilutp__ (@var{A}, @dots{}) +Undocumented internal function. +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/__lin_interpn__.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/__lin_interpn__.cc Tue Jun 21 16:07:51 2016 -0400 @@ -260,10 +260,10 @@ //This function only performs linear interpolation. DEFUN (__lin_interpn__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{vi} =} __lin_interpn__ (@var{x1}, @var{x2}, @dots{}, @var{xn}, @var{v}, @var{y1}, @var{y2}, @dots{}, @var{yn})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{vi} =} __lin_interpn__ (@var{x1}, @var{x2}, @dots{}, @var{xn}, @var{v}, @var{y1}, @var{y2}, @dots{}, @var{yn}) +Undocumented internal function. +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/__luinc__.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/__luinc__.cc Tue Jun 21 16:07:51 2016 -0400 @@ -38,15 +38,15 @@ // FIXME: Deprecated in 4.0 and should be removed in 4.4. DEFUN (__luinc__, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{L}, @var{U}, @var{P}, @var{Q}] =} __luinc__ (@var{A}, '0')\n\ -@deftypefnx {} {[@var{L}, @var{U}, @var{P}, @var{Q}] =} __luinc__ (@var{A}, @var{droptol})\n\ -@deftypefnx {} {[@var{L}, @var{U}, @var{P}, @var{Q}] =} __luinc__ (@var{A}, @var{opts})\n\ -Internal implementation of @code{luinc}.\n\ -\n\ -See documentation for @code{luinc}.\n\ -@seealso{luinc}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{L}, @var{U}, @var{P}, @var{Q}] =} __luinc__ (@var{A}, '0') +@deftypefnx {} {[@var{L}, @var{U}, @var{P}, @var{Q}] =} __luinc__ (@var{A}, @var{droptol}) +@deftypefnx {} {[@var{L}, @var{U}, @var{P}, @var{Q}] =} __luinc__ (@var{A}, @var{opts}) +Internal implementation of @code{luinc}. + +See documentation for @code{luinc}. +@seealso{luinc} +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/__magick_read__.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/__magick_read__.cc Tue Jun 21 16:07:51 2016 -0400 @@ -744,15 +744,15 @@ #endif DEFUN (__magick_read__, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{img}, @var{map}, @var{alpha}] =} __magick_read__ (@var{fname}, @var{options})\n\ -Read image with GraphicsMagick or ImageMagick.\n\ -\n\ -This is a private internal function not intended for direct use.\n\ -Use @code{imread} instead.\n\ -\n\ -@seealso{imfinfo, imformats, imread, imwrite}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{img}, @var{map}, @var{alpha}] =} __magick_read__ (@var{fname}, @var{options}) +Read image with GraphicsMagick or ImageMagick. + +This is a private internal function not intended for direct use. +Use @code{imread} instead. + +@seealso{imfinfo, imformats, imread, imwrite} +@end deftypefn */) { #if defined (HAVE_MAGICK) @@ -1387,15 +1387,15 @@ #endif DEFUN (__magick_write__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __magick_write__ (@var{fname}, @var{fmt}, @var{img}, @var{map}, @var{options})\n\ -Write image with GraphicsMagick or ImageMagick.\n\ -\n\ -This is a private internal function not intended for direct use.\n\ -Use @code{imwrite} instead.\n\ -\n\ -@seealso{imfinfo, imformats, imread, imwrite}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __magick_write__ (@var{fname}, @var{fmt}, @var{img}, @var{map}, @var{options}) +Write image with GraphicsMagick or ImageMagick. + +This is a private internal function not intended for direct use. +Use @code{imwrite} instead. + +@seealso{imfinfo, imformats, imread, imwrite} +@end deftypefn */) { #if defined (HAVE_MAGICK) @@ -1566,14 +1566,14 @@ // this, we need to read the image once for imfinfo to set defaults (which is // done in Octave language), and then again for the actual reading. DEFUN (__magick_ping__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __magick_ping__ (@var{fname}, @var{idx})\n\ -Ping image information with GraphicsMagick or ImageMagick.\n\ -\n\ -This is a private internal function not intended for direct use.\n\ -\n\ -@seealso{imfinfo}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __magick_ping__ (@var{fname}, @var{idx}) +Ping image information with GraphicsMagick or ImageMagick. + +This is a private internal function not intended for direct use. + +@seealso{imfinfo} +@end deftypefn */) { #if defined (HAVE_MAGICK) @@ -1791,15 +1791,15 @@ #endif DEFUN (__magick_finfo__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __magick_finfo__ (@var{fname})\n\ -Read image information with GraphicsMagick or ImageMagick.\n\ -\n\ -This is a private internal function not intended for direct use.\n\ -Use @code{imfinfo} instead.\n\ -\n\ -@seealso{imfinfo, imformats, imread, imwrite}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __magick_finfo__ (@var{fname}) +Read image information with GraphicsMagick or ImageMagick. + +This is a private internal function not intended for direct use. +Use @code{imfinfo} instead. + +@seealso{imfinfo, imformats, imread, imwrite} +@end deftypefn */) { #if defined (HAVE_MAGICK) @@ -2242,12 +2242,12 @@ */ DEFUN (__magick_formats__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __magick_imformats__ (@var{formats})\n\ -Fill formats info with GraphicsMagick CoderInfo.\n\ -\n\ -@seealso{imfinfo, imformats, imread, imwrite}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __magick_imformats__ (@var{formats}) +Fill formats info with GraphicsMagick CoderInfo. + +@seealso{imfinfo, imformats, imread, imwrite} +@end deftypefn */) { if (args.length () != 1 || ! args(0).is_map ()) print_usage ();
--- a/libinterp/corefcn/__pchip_deriv__.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/__pchip_deriv__.cc Tue Jun 21 16:07:51 2016 -0400 @@ -51,10 +51,10 @@ // for piecewise polynomials. DEFUN (__pchip_deriv__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __pchip_deriv__ (@var{x}, @var{y}, @var{dim})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __pchip_deriv__ (@var{x}, @var{y}, @var{dim}) +Undocumented internal function. +@end deftypefn */) { octave_value retval; int nargin = args.length ();
--- a/libinterp/corefcn/__qp__.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/__qp__.cc Tue Jun 21 16:07:51 2016 -0400 @@ -486,10 +486,10 @@ } DEFUN (__qp__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{x}, @var{lambda}, @var{info}, @var{iter}] =} __qp__ (@var{x0}, @var{H}, @var{q}, @var{Aeq}, @var{beq}, @var{Ain}, @var{bin}, @var{maxit})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{x}, @var{lambda}, @var{info}, @var{iter}] =} __qp__ (@var{x0}, @var{H}, @var{q}, @var{Aeq}, @var{beq}, @var{Ain}, @var{bin}, @var{maxit}) +Undocumented internal function. +@end deftypefn */) { if (args.length () != 8) print_usage ();
--- a/libinterp/corefcn/balance.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/balance.cc Tue Jun 21 16:07:51 2016 -0400 @@ -45,49 +45,49 @@ #include "utils.h" DEFUN (balance, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{AA} =} balance (@var{A})\n\ -@deftypefnx {} {@var{AA} =} balance (@var{A}, @var{opt})\n\ -@deftypefnx {} {[@var{DD}, @var{AA}] =} balance (@var{A}, @var{opt})\n\ -@deftypefnx {} {[@var{D}, @var{P}, @var{AA}] =} balance (@var{A}, @var{opt})\n\ -@deftypefnx {} {[@var{CC}, @var{DD}, @var{AA}, @var{BB}] =} balance (@var{A}, @var{B}, @var{opt})\n\ -\n\ -Balance the matrix @var{A} to reduce numerical errors in future\n\ -calculations.\n\ -\n\ -Compute @code{@var{AA} = @var{DD} \\ @var{A} * @var{DD}} in which @var{AA}\n\ -is a matrix whose row and column norms are roughly equal in magnitude, and\n\ -@code{@var{DD} = @var{P} * @var{D}}, in which @var{P} is a permutation\n\ -matrix and @var{D} is a diagonal matrix of powers of two. This allows the\n\ -equilibration to be computed without round-off. Results of eigenvalue\n\ -calculation are typically improved by balancing first.\n\ -\n\ -If two output values are requested, @code{balance} returns\n\ -the diagonal @var{D} and the permutation @var{P} separately as vectors.\n\ -In this case, @code{@var{DD} = eye(n)(:,@var{P}) * diag (@var{D})}, where\n\ -@math{n} is the matrix size.\n\ -\n\ -If four output values are requested, compute @code{@var{AA} =\n\ -@var{CC}*@var{A}*@var{DD}} and @code{@var{BB} = @var{CC}*@var{B}*@var{DD}},\n\ -in which @var{AA} and @var{BB} have nonzero elements of approximately the\n\ -same magnitude and @var{CC} and @var{DD} are permuted diagonal matrices as\n\ -in @var{DD} for the algebraic eigenvalue problem.\n\ -\n\ -The eigenvalue balancing option @var{opt} may be one of:\n\ -\n\ -@table @asis\n\ -@item @qcode{\"noperm\"}, @qcode{\"S\"}\n\ -Scale only; do not permute.\n\ -\n\ -@item @qcode{\"noscal\"}, @qcode{\"P\"}\n\ -Permute only; do not scale.\n\ -@end table\n\ -\n\ -Algebraic eigenvalue balancing uses standard @sc{lapack} routines.\n\ -\n\ -Generalized eigenvalue problem balancing uses Ward's algorithm\n\ -(SIAM Journal on Scientific and Statistical Computing, 1981).\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{AA} =} balance (@var{A}) +@deftypefnx {} {@var{AA} =} balance (@var{A}, @var{opt}) +@deftypefnx {} {[@var{DD}, @var{AA}] =} balance (@var{A}, @var{opt}) +@deftypefnx {} {[@var{D}, @var{P}, @var{AA}] =} balance (@var{A}, @var{opt}) +@deftypefnx {} {[@var{CC}, @var{DD}, @var{AA}, @var{BB}] =} balance (@var{A}, @var{B}, @var{opt}) + +Balance the matrix @var{A} to reduce numerical errors in future +calculations. + +Compute @code{@var{AA} = @var{DD} \ @var{A} * @var{DD}} in which @var{AA} +is a matrix whose row and column norms are roughly equal in magnitude, and +@code{@var{DD} = @var{P} * @var{D}}, in which @var{P} is a permutation +matrix and @var{D} is a diagonal matrix of powers of two. This allows the +equilibration to be computed without round-off. Results of eigenvalue +calculation are typically improved by balancing first. + +If two output values are requested, @code{balance} returns +the diagonal @var{D} and the permutation @var{P} separately as vectors. +In this case, @code{@var{DD} = eye(n)(:,@var{P}) * diag (@var{D})}, where +@math{n} is the matrix size. + +If four output values are requested, compute @code{@var{AA} = +@var{CC}*@var{A}*@var{DD}} and @code{@var{BB} = @var{CC}*@var{B}*@var{DD}}, +in which @var{AA} and @var{BB} have nonzero elements of approximately the +same magnitude and @var{CC} and @var{DD} are permuted diagonal matrices as +in @var{DD} for the algebraic eigenvalue problem. + +The eigenvalue balancing option @var{opt} may be one of: + +@table @asis +@item @qcode{"noperm"}, @qcode{"S"} +Scale only; do not permute. + +@item @qcode{"noscal"}, @qcode{"P"} +Permute only; do not scale. +@end table + +Algebraic eigenvalue balancing uses standard @sc{lapack} routines. + +Generalized eigenvalue problem balancing uses Ward's algorithm +(SIAM Journal on Scientific and Statistical Computing, 1981). +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/besselj.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/besselj.cc Tue Jun 21 16:07:51 2016 -0400 @@ -300,75 +300,75 @@ } DEFUN (besselj, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{j}, @var{ierr}] =} besselj (@var{alpha}, @var{x}, @var{opt})\n\ -@deftypefnx {} {[@var{y}, @var{ierr}] =} bessely (@var{alpha}, @var{x}, @var{opt})\n\ -@deftypefnx {} {[@var{i}, @var{ierr}] =} besseli (@var{alpha}, @var{x}, @var{opt})\n\ -@deftypefnx {} {[@var{k}, @var{ierr}] =} besselk (@var{alpha}, @var{x}, @var{opt})\n\ -@deftypefnx {} {[@var{h}, @var{ierr}] =} besselh (@var{alpha}, @var{k}, @var{x}, @var{opt})\n\ -Compute Bessel or Hankel functions of various kinds:\n\ -\n\ -@table @code\n\ -@item besselj\n\ -Bessel functions of the first kind. If the argument @var{opt} is 1 or true,\n\ -the result is multiplied by @w{@code{exp (-abs (imag (@var{x})))}}.\n\ -\n\ -@item bessely\n\ -Bessel functions of the second kind. If the argument @var{opt} is 1 or\n\ -true, the result is multiplied by @code{exp (-abs (imag (@var{x})))}.\n\ -\n\ -@item besseli\n\ -\n\ -Modified Bessel functions of the first kind. If the argument @var{opt} is 1\n\ -or true, the result is multiplied by @code{exp (-abs (real (@var{x})))}.\n\ -\n\ -@item besselk\n\ -\n\ -Modified Bessel functions of the second kind. If the argument @var{opt} is\n\ -1 or true, the result is multiplied by @code{exp (@var{x})}.\n\ -\n\ -@item besselh\n\ -Compute Hankel functions of the first (@var{k} = 1) or second (@var{k}\n\ -= 2) kind. If the argument @var{opt} is 1 or true, the result is multiplied\n\ -by @code{exp (-I*@var{x})} for @var{k} = 1 or @code{exp (I*@var{x})} for\n\ -@var{k} = 2.\n\ -@end table\n\ -\n\ -If @var{alpha} is a scalar, the result is the same size as @var{x}.\n\ -If @var{x} is a scalar, the result is the same size as @var{alpha}.\n\ -If @var{alpha} is a row vector and @var{x} is a column vector, the\n\ -result is a matrix with @code{length (@var{x})} rows and\n\ -@code{length (@var{alpha})} columns. Otherwise, @var{alpha} and\n\ -@var{x} must conform and the result will be the same size.\n\ -\n\ -The value of @var{alpha} must be real. The value of @var{x} may be\n\ -complex.\n\ -\n\ -If requested, @var{ierr} contains the following status information\n\ -and is the same size as the result.\n\ -\n\ -@enumerate 0\n\ -@item\n\ -Normal return.\n\ -\n\ -@item\n\ -Input error, return @code{NaN}.\n\ -\n\ -@item\n\ -Overflow, return @code{Inf}.\n\ -\n\ -@item\n\ -Loss of significance by argument reduction results in less than\n\ -half of machine accuracy.\n\ -\n\ -@item\n\ -Complete loss of significance by argument reduction, return @code{NaN}.\n\ -\n\ -@item\n\ -Error---no computation, algorithm termination condition not met,\n\ -return @code{NaN}.\n\ -@end enumerate\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{j}, @var{ierr}] =} besselj (@var{alpha}, @var{x}, @var{opt}) +@deftypefnx {} {[@var{y}, @var{ierr}] =} bessely (@var{alpha}, @var{x}, @var{opt}) +@deftypefnx {} {[@var{i}, @var{ierr}] =} besseli (@var{alpha}, @var{x}, @var{opt}) +@deftypefnx {} {[@var{k}, @var{ierr}] =} besselk (@var{alpha}, @var{x}, @var{opt}) +@deftypefnx {} {[@var{h}, @var{ierr}] =} besselh (@var{alpha}, @var{k}, @var{x}, @var{opt}) +Compute Bessel or Hankel functions of various kinds: + +@table @code +@item besselj +Bessel functions of the first kind. If the argument @var{opt} is 1 or true, +the result is multiplied by @w{@code{exp (-abs (imag (@var{x})))}}. + +@item bessely +Bessel functions of the second kind. If the argument @var{opt} is 1 or +true, the result is multiplied by @code{exp (-abs (imag (@var{x})))}. + +@item besseli + +Modified Bessel functions of the first kind. If the argument @var{opt} is 1 +or true, the result is multiplied by @code{exp (-abs (real (@var{x})))}. + +@item besselk + +Modified Bessel functions of the second kind. If the argument @var{opt} is +1 or true, the result is multiplied by @code{exp (@var{x})}. + +@item besselh +Compute Hankel functions of the first (@var{k} = 1) or second (@var{k} += 2) kind. If the argument @var{opt} is 1 or true, the result is multiplied +by @code{exp (-I*@var{x})} for @var{k} = 1 or @code{exp (I*@var{x})} for +@var{k} = 2. +@end table + +If @var{alpha} is a scalar, the result is the same size as @var{x}. +If @var{x} is a scalar, the result is the same size as @var{alpha}. +If @var{alpha} is a row vector and @var{x} is a column vector, the +result is a matrix with @code{length (@var{x})} rows and +@code{length (@var{alpha})} columns. Otherwise, @var{alpha} and +@var{x} must conform and the result will be the same size. + +The value of @var{alpha} must be real. The value of @var{x} may be +complex. + +If requested, @var{ierr} contains the following status information +and is the same size as the result. + +@enumerate 0 +@item +Normal return. + +@item +Input error, return @code{NaN}. + +@item +Overflow, return @code{Inf}. + +@item +Loss of significance by argument reduction results in less than +half of machine accuracy. + +@item +Complete loss of significance by argument reduction, return @code{NaN}. + +@item +Error---no computation, algorithm termination condition not met, +return @code{NaN}. +@end enumerate +@end deftypefn */) { return do_bessel (BESSEL_J, "besselj", args, nargout); } @@ -378,10 +378,10 @@ */ DEFUN (bessely, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{y}, @var{ierr}] =} bessely (@var{alpha}, @var{x}, @var{opt})\n\ -See besselj.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{y}, @var{ierr}] =} bessely (@var{alpha}, @var{x}, @var{opt}) +See besselj. +@end deftypefn */) { return do_bessel (BESSEL_Y, "bessely", args, nargout); } @@ -391,10 +391,10 @@ */ DEFUN (besseli, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{i}, @var{ierr}] =} besseli (@var{alpha}, @var{x}, @var{opt})\n\ -See besselj.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{i}, @var{ierr}] =} besseli (@var{alpha}, @var{x}, @var{opt}) +See besselj. +@end deftypefn */) { return do_bessel (BESSEL_I, "besseli", args, nargout); } @@ -404,10 +404,10 @@ */ DEFUN (besselk, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{k}, @var{ierr}] =} besselk (@var{alpha}, @var{x}, @var{opt})\n\ -See besselj.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{k}, @var{ierr}] =} besselk (@var{alpha}, @var{x}, @var{opt}) +See besselj. +@end deftypefn */) { return do_bessel (BESSEL_K, "besselk", args, nargout); } @@ -417,10 +417,10 @@ */ DEFUN (besselh, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{h}, @var{ierr}] =} besselh (@var{alpha}, @var{k}, @var{x}, @var{opt})\n\ -See besselj.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{h}, @var{ierr}] =} besselh (@var{alpha}, @var{k}, @var{x}, @var{opt}) +See besselj. +@end deftypefn */) { int nargin = args.length (); @@ -461,51 +461,51 @@ */ DEFUN (airy, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{a}, @var{ierr}] =} airy (@var{k}, @var{z}, @var{opt})\n\ -Compute Airy functions of the first and second kind, and their derivatives.\n\ -\n\ -@example\n\ -@group\n\ - K Function Scale factor (if \"opt\" is supplied)\n\ ---- -------- ---------------------------------------\n\ - 0 Ai (Z) exp ((2/3) * Z * sqrt (Z))\n\ - 1 dAi(Z)/dZ exp ((2/3) * Z * sqrt (Z))\n\ - 2 Bi (Z) exp (-abs (real ((2/3) * Z * sqrt (Z))))\n\ - 3 dBi(Z)/dZ exp (-abs (real ((2/3) * Z * sqrt (Z))))\n\ -@end group\n\ -@end example\n\ -\n\ -The function call @code{airy (@var{z})} is equivalent to\n\ -@code{airy (0, @var{z})}.\n\ -\n\ -The result is the same size as @var{z}.\n\ -\n\ -If requested, @var{ierr} contains the following status information and\n\ -is the same size as the result.\n\ -\n\ -@enumerate 0\n\ -@item\n\ -Normal return.\n\ -\n\ -@item\n\ -Input error, return @code{NaN}.\n\ -\n\ -@item\n\ -Overflow, return @code{Inf}.\n\ -\n\ -@item\n\ -Loss of significance by argument reduction results in less than half\n\ - of machine accuracy.\n\ -\n\ -@item\n\ -Complete loss of significance by argument reduction, return @code{NaN}.\n\ -\n\ -@item\n\ -Error---no computation, algorithm termination condition not met,\n\ -return @code{NaN}.\n\ -@end enumerate\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{a}, @var{ierr}] =} airy (@var{k}, @var{z}, @var{opt}) +Compute Airy functions of the first and second kind, and their derivatives. + +@example +@group + K Function Scale factor (if "opt" is supplied) +--- -------- --------------------------------------- + 0 Ai (Z) exp ((2/3) * Z * sqrt (Z)) + 1 dAi(Z)/dZ exp ((2/3) * Z * sqrt (Z)) + 2 Bi (Z) exp (-abs (real ((2/3) * Z * sqrt (Z)))) + 3 dBi(Z)/dZ exp (-abs (real ((2/3) * Z * sqrt (Z)))) +@end group +@end example + +The function call @code{airy (@var{z})} is equivalent to +@code{airy (0, @var{z})}. + +The result is the same size as @var{z}. + +If requested, @var{ierr} contains the following status information and +is the same size as the result. + +@enumerate 0 +@item +Normal return. + +@item +Input error, return @code{NaN}. + +@item +Overflow, return @code{Inf}. + +@item +Loss of significance by argument reduction results in less than half + of machine accuracy. + +@item +Complete loss of significance by argument reduction, return @code{NaN}. + +@item +Error---no computation, algorithm termination condition not met, +return @code{NaN}. +@end enumerate +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/betainc.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/betainc.cc Tue Jun 21 16:07:51 2016 -0400 @@ -34,36 +34,36 @@ DEFUN (betainc, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} betainc (@var{x}, @var{a}, @var{b})\n\ -Compute the regularized incomplete Beta function.\n\ -\n\ -The regularized incomplete Beta function is defined by\n\ -@tex\n\ -$$\n\ - I (x, a, b) = {1 \\over {B (a, b)}} \\int_0^x t^{(a-z)} (1-t)^{(b-1)} dt.\n\ -$$\n\ -@end tex\n\ -@ifnottex\n\ -@c Set example in small font to prevent overfull line\n\ -\n\ -@smallexample\n\ -@group\n\ - x\n\ - 1 /\n\ -betainc (x, a, b) = ----------- | t^(a-1) (1-t)^(b-1) dt.\n\ - beta (a, b) /\n\ - t=0\n\ -@end group\n\ -@end smallexample\n\ -\n\ -@end ifnottex\n\ -\n\ -If @var{x} has more than one component, both @var{a} and @var{b} must be\n\ -scalars. If @var{x} is a scalar, @var{a} and @var{b} must be of\n\ -compatible dimensions.\n\ -@seealso{betaincinv, beta, betaln}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} betainc (@var{x}, @var{a}, @var{b}) +Compute the regularized incomplete Beta function. + +The regularized incomplete Beta function is defined by +@tex +$$ + I (x, a, b) = {1 \over {B (a, b)}} \int_0^x t^{(a-z)} (1-t)^{(b-1)} dt. +$$ +@end tex +@ifnottex +@c Set example in small font to prevent overfull line + +@smallexample +@group + x + 1 / +betainc (x, a, b) = ----------- | t^(a-1) (1-t)^(b-1) dt. + beta (a, b) / + t=0 +@end group +@end smallexample + +@end ifnottex + +If @var{x} has more than one component, both @var{a} and @var{b} must be +scalars. If @var{x} is a scalar, @var{a} and @var{b} must be of +compatible dimensions. +@seealso{betaincinv, beta, betaln} +@end deftypefn */) { if (args.length () != 3) print_usage (); @@ -286,17 +286,17 @@ */ DEFUN (betaincinv, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} betaincinv (@var{y}, @var{a}, @var{b})\n\ -Compute the inverse of the incomplete Beta function.\n\ -\n\ -The inverse is the value @var{x} such that\n\ -\n\ -@example\n\ -@var{y} == betainc (@var{x}, @var{a}, @var{b})\n\ -@end example\n\ -@seealso{betainc, beta, betaln}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} betaincinv (@var{y}, @var{a}, @var{b}) +Compute the inverse of the incomplete Beta function. + +The inverse is the value @var{x} such that + +@example +@var{y} == betainc (@var{x}, @var{a}, @var{b}) +@end example +@seealso{betainc, beta, betaln} +@end deftypefn */) { if (args.length () != 3) print_usage ();
--- a/libinterp/corefcn/bitfcns.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/bitfcns.cc Tue Jun 21 16:07:51 2016 -0400 @@ -355,13 +355,13 @@ } DEFUN (bitand, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} bitand (@var{x}, @var{y})\n\ -Return the bitwise AND of non-negative integers.\n\ -\n\ -@var{x}, @var{y} must be in the range [0,intmax]\n\ -@seealso{bitor, bitxor, bitset, bitget, bitcmp, bitshift, intmax, flintmax}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} bitand (@var{x}, @var{y}) +Return the bitwise AND of non-negative integers. + +@var{x}, @var{y} must be in the range [0,intmax] +@seealso{bitor, bitxor, bitset, bitget, bitcmp, bitshift, intmax, flintmax} +@end deftypefn */) { return bitop ("bitand", args); } @@ -371,12 +371,12 @@ */ DEFUN (bitor, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} bitor (@var{x}, @var{y})\n\ -Return the bitwise OR of non-negative integers @var{x} and @var{y}.\n\ -\n\ -@seealso{bitor, bitxor, bitset, bitget, bitcmp, bitshift, intmax, flintmax}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} bitor (@var{x}, @var{y}) +Return the bitwise OR of non-negative integers @var{x} and @var{y}. + +@seealso{bitor, bitxor, bitset, bitget, bitcmp, bitshift, intmax, flintmax} +@end deftypefn */) { return bitop ("bitor", args); } @@ -386,12 +386,12 @@ */ DEFUN (bitxor, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} bitxor (@var{x}, @var{y})\n\ -Return the bitwise XOR of non-negative integers @var{x} and @var{y}.\n\ -\n\ -@seealso{bitand, bitor, bitset, bitget, bitcmp, bitshift, intmax, flintmax}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} bitxor (@var{x}, @var{y}) +Return the bitwise XOR of non-negative integers @var{x} and @var{y}. + +@seealso{bitand, bitor, bitset, bitget, bitcmp, bitshift, intmax, flintmax} +@end deftypefn */) { return bitop ("bitxor", args); } @@ -529,37 +529,37 @@ while (0) DEFUN (bitshift, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} bitshift (@var{a}, @var{k})\n\ -@deftypefnx {} {} bitshift (@var{a}, @var{k}, @var{n})\n\ -Return a @var{k} bit shift of @var{n}-digit unsigned integers in @var{a}.\n\ -\n\ -A positive @var{k} leads to a left shift; A negative value to a right shift.\n\ -\n\ -If @var{n} is omitted it defaults to 64.\n\ -@var{n} must be in the range [1,64].\n\ -\n\ -@example\n\ -@group\n\ -bitshift (eye (3), 1)\n\ -@result{}\n\ -@group\n\ -2 0 0\n\ -0 2 0\n\ -0 0 2\n\ -@end group\n\ -\n\ -bitshift (10, [-2, -1, 0, 1, 2])\n\ -@result{} 2 5 10 20 40\n\ -@c FIXME: restore this example when third arg is allowed to be an array.\n\ -@c\n\ -@c\n\ -@c bitshift ([1, 10], 2, [3,4])\n\ -@c @result{} 4 8\n\ -@end group\n\ -@end example\n\ -@seealso{bitand, bitor, bitxor, bitset, bitget, bitcmp, intmax, flintmax}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} bitshift (@var{a}, @var{k}) +@deftypefnx {} {} bitshift (@var{a}, @var{k}, @var{n}) +Return a @var{k} bit shift of @var{n}-digit unsigned integers in @var{a}. + +A positive @var{k} leads to a left shift; A negative value to a right shift. + +If @var{n} is omitted it defaults to 64. +@var{n} must be in the range [1,64]. + +@example +@group +bitshift (eye (3), 1) +@result{} +@group +2 0 0 +0 2 0 +0 0 2 +@end group + +bitshift (10, [-2, -1, 0, 1, 2]) +@result{} 2 5 10 20 40 +@c FIXME: restore this example when third arg is allowed to be an array. +@c +@c +@c bitshift ([1, 10], 2, [3,4]) +@c @result{} 4 8 +@end group +@end example +@seealso{bitand, bitor, bitxor, bitset, bitget, bitcmp, intmax, flintmax} +@end deftypefn */) { int nargin = args.length (); @@ -655,19 +655,19 @@ */ DEFUN (flintmax, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} flintmax ()\n\ -@deftypefnx {} {} flintmax (\"double\")\n\ -@deftypefnx {} {} flintmax (\"single\")\n\ -Return the largest integer that can be represented consecutively in a\n\ -floating point value.\n\ -\n\ -The default class is @qcode{\"double\"}, but @qcode{\"single\"} is a valid\n\ -option. On IEEE 754 compatible systems, @code{flintmax} is\n\ -@w{@math{2^{53}}} for @qcode{\"double\"} and @w{@math{2^{24}}} for\n\ -@qcode{\"single\"}.\n\ -@seealso{intmax, realmax, realmin}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} flintmax () +@deftypefnx {} {} flintmax ("double") +@deftypefnx {} {} flintmax ("single") +Return the largest integer that can be represented consecutively in a +floating point value. + +The default class is @qcode{"double"}, but @qcode{"single"} is a valid +option. On IEEE 754 compatible systems, @code{flintmax} is +@w{@math{2^{53}}} for @qcode{"double"} and @w{@math{2^{24}}} for +@qcode{"single"}. +@seealso{intmax, realmax, realmin} +@end deftypefn */) { int nargin = args.length (); @@ -698,41 +698,41 @@ */ DEFUN (intmax, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} intmax (@var{type})\n\ -Return the largest integer that can be represented in an integer type.\n\ -\n\ -The variable @var{type} can be\n\ -\n\ -@table @code\n\ -@item int8\n\ -signed 8-bit integer.\n\ -\n\ -@item int16\n\ -signed 16-bit integer.\n\ -\n\ -@item int32\n\ -signed 32-bit integer.\n\ -\n\ -@item int64\n\ -signed 64-bit integer.\n\ -\n\ -@item uint8\n\ -unsigned 8-bit integer.\n\ -\n\ -@item uint16\n\ -unsigned 16-bit integer.\n\ -\n\ -@item uint32\n\ -unsigned 32-bit integer.\n\ -\n\ -@item uint64\n\ -unsigned 64-bit integer.\n\ -@end table\n\ -\n\ -The default for @var{type} is @code{int32}.\n\ -@seealso{intmin, flintmax}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} intmax (@var{type}) +Return the largest integer that can be represented in an integer type. + +The variable @var{type} can be + +@table @code +@item int8 +signed 8-bit integer. + +@item int16 +signed 16-bit integer. + +@item int32 +signed 32-bit integer. + +@item int64 +signed 64-bit integer. + +@item uint8 +unsigned 8-bit integer. + +@item uint16 +unsigned 16-bit integer. + +@item uint32 +unsigned 32-bit integer. + +@item uint64 +unsigned 64-bit integer. +@end table + +The default for @var{type} is @code{int32}. +@seealso{intmin, flintmax} +@end deftypefn */) { int nargin = args.length (); @@ -785,41 +785,41 @@ */ DEFUN (intmin, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} intmin (@var{type})\n\ -Return the smallest integer that can be represented in an integer type.\n\ -\n\ -The variable @var{type} can be\n\ -\n\ -@table @code\n\ -@item int8\n\ -signed 8-bit integer.\n\ -\n\ -@item int16\n\ -signed 16-bit integer.\n\ -\n\ -@item int32\n\ -signed 32-bit integer.\n\ -\n\ -@item int64\n\ -signed 64-bit integer.\n\ -\n\ -@item uint8\n\ -unsigned 8-bit integer.\n\ -\n\ -@item uint16\n\ -unsigned 16-bit integer.\n\ -\n\ -@item uint32\n\ -unsigned 32-bit integer.\n\ -\n\ -@item uint64\n\ -unsigned 64-bit integer.\n\ -@end table\n\ -\n\ -The default for @var{type} is @code{int32}.\n\ -@seealso{intmax, flintmax}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} intmin (@var{type}) +Return the smallest integer that can be represented in an integer type. + +The variable @var{type} can be + +@table @code +@item int8 +signed 8-bit integer. + +@item int16 +signed 16-bit integer. + +@item int32 +signed 32-bit integer. + +@item int64 +signed 64-bit integer. + +@item uint8 +unsigned 8-bit integer. + +@item uint16 +unsigned 16-bit integer. + +@item uint32 +unsigned 32-bit integer. + +@item uint64 +unsigned 64-bit integer. +@end table + +The default for @var{type} is @code{int32}. +@seealso{intmax, flintmax} +@end deftypefn */) { int nargin = args.length (); @@ -872,16 +872,16 @@ */ DEFUN (sizemax, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} sizemax ()\n\ -Return the largest value allowed for the size of an array.\n\ -\n\ -If Octave is compiled with 64-bit indexing, the result is of class int64,\n\ -otherwise it is of class int32. The maximum array size is slightly\n\ -smaller than the maximum value allowable for the relevant class as reported\n\ -by @code{intmax}.\n\ -@seealso{intmax}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} sizemax () +Return the largest value allowed for the size of an array. + +If Octave is compiled with 64-bit indexing, the result is of class int64, +otherwise it is of class int32. The maximum array size is slightly +smaller than the maximum value allowable for the relevant class as reported +by @code{intmax}. +@seealso{intmax} +@end deftypefn */) { if (args.length () != 0) print_usage ();
--- a/libinterp/corefcn/bsxfun.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/bsxfun.cc Tue Jun 21 16:07:51 2016 -0400 @@ -317,23 +317,23 @@ } DEFUN (bsxfun, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} bsxfun (@var{f}, @var{A}, @var{B})\n\ -The binary singleton expansion function performs broadcasting,\n\ -that is, it applies a binary function @var{f} element-by-element to two\n\ -array arguments @var{A} and @var{B}, and expands as necessary\n\ -singleton dimensions in either input argument.\n\ -\n\ -@var{f} is a function handle, inline function, or string containing the name\n\ -of the function to evaluate. The function @var{f} must be capable of\n\ -accepting two column-vector arguments of equal length, or one column vector\n\ -argument and a scalar.\n\ -\n\ -The dimensions of @var{A} and @var{B} must be equal or singleton. The\n\ -singleton dimensions of the arrays will be expanded to the same\n\ -dimensionality as the other array.\n\ -@seealso{arrayfun, cellfun}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} bsxfun (@var{f}, @var{A}, @var{B}) +The binary singleton expansion function performs broadcasting, +that is, it applies a binary function @var{f} element-by-element to two +array arguments @var{A} and @var{B}, and expands as necessary +singleton dimensions in either input argument. + +@var{f} is a function handle, inline function, or string containing the name +of the function to evaluate. The function @var{f} must be capable of +accepting two column-vector arguments of equal length, or one column vector +argument and a scalar. + +The dimensions of @var{A} and @var{B} must be equal or singleton. The +singleton dimensions of the arrays will be expanded to the same +dimensionality as the other array. +@seealso{arrayfun, cellfun} +@end deftypefn */) { if (args.length () != 3) print_usage ();
--- a/libinterp/corefcn/cellfun.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/cellfun.cc Tue Jun 21 16:07:51 2016 -0400 @@ -260,142 +260,142 @@ } DEFUN (cellfun, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} cellfun (@var{name}, @var{C})\n\ -@deftypefnx {} {} cellfun (\"size\", @var{C}, @var{k})\n\ -@deftypefnx {} {} cellfun (\"isclass\", @var{C}, @var{class})\n\ -@deftypefnx {} {} cellfun (@var{func}, @var{C})\n\ -@deftypefnx {} {} cellfun (@var{func}, @var{C}, @var{D})\n\ -@deftypefnx {} {[@var{a}, @dots{}] =} cellfun (@dots{})\n\ -@deftypefnx {} {} cellfun (@dots{}, \"ErrorHandler\", @var{errfunc})\n\ -@deftypefnx {} {} cellfun (@dots{}, \"UniformOutput\", @var{val})\n\ -\n\ -Evaluate the function named @var{name} on the elements of the cell array\n\ -@var{C}.\n\ -\n\ -Elements in @var{C} are passed on to the named function individually. The\n\ -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 isnumeric\n\ -Return 1 for numeric 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). The function can take one or more\n\ -arguments, with the inputs arguments given by @var{C}, @var{D}, etc.\n\ -Equally the function can return one or more output arguments. For example:\n\ -\n\ -@example\n\ -@group\n\ -cellfun (\"atan2\", @{1, 0@}, @{0, 1@})\n\ - @result{} [ 1.57080 0.00000 ]\n\ -@end group\n\ -@end example\n\ -\n\ -The number of output arguments of @code{cellfun} matches the number of\n\ -output arguments of the function. The outputs of the function will be\n\ -collected 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 @qcode{\"UniformOutput\"} is set to true (the default),\n\ -then the function must return scalars which will be concatenated into the\n\ -return array(s). If @qcode{\"UniformOutput\"} is false, the outputs are\n\ -concatenated into a cell array (or cell arrays). For example:\n\ -\n\ -@example\n\ -@group\n\ -cellfun (\"tolower\", @{\"Foo\", \"Bar\", \"FooBar\"@},\n\ - \"UniformOutput\", false)\n\ -@result{} @{\"foo\", \"bar\", \"foobar\"@}\n\ -@end group\n\ -@end example\n\ -\n\ -Given the parameter @qcode{\"ErrorHandler\"}, then @var{errfunc} defines a\n\ -function to call in case @var{func} generates an error. The form of the\n\ -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\ -@qcode{\"identifier\"}, @qcode{\"message\"}, and @qcode{\"index\"} giving\n\ -respectively the error identifier, the error message, and the index into the\n\ -input arguments 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{} [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") + doc: /* -*- texinfo -*- +@deftypefn {} {} cellfun (@var{name}, @var{C}) +@deftypefnx {} {} cellfun ("size", @var{C}, @var{k}) +@deftypefnx {} {} cellfun ("isclass", @var{C}, @var{class}) +@deftypefnx {} {} cellfun (@var{func}, @var{C}) +@deftypefnx {} {} cellfun (@var{func}, @var{C}, @var{D}) +@deftypefnx {} {[@var{a}, @dots{}] =} cellfun (@dots{}) +@deftypefnx {} {} cellfun (@dots{}, "ErrorHandler", @var{errfunc}) +@deftypefnx {} {} cellfun (@dots{}, "UniformOutput", @var{val}) + +Evaluate the function named @var{name} on the elements of the cell array +@var{C}. + +Elements in @var{C} are passed on to the named function individually. The +function @var{name} can be one of the functions + +@table @code +@item isempty +Return 1 for empty elements. + +@item islogical +Return 1 for logical elements. + +@item isnumeric +Return 1 for numeric elements. + +@item isreal +Return 1 for real elements. + +@item length +Return a vector of the lengths of cell elements. + +@item ndims +Return the number of dimensions of each element. + +@item numel +@itemx prodofsize +Return the number of elements contained within each cell element. The +number is the product of the dimensions of the object at each cell element. + +@item size +Return the size along the @var{k}-th dimension. + +@item isclass +Return 1 for elements of @var{class}. +@end table + +Additionally, @code{cellfun} accepts an arbitrary function @var{func} +in the form of an inline function, function handle, or the name of a +function (in a character string). The function can take one or more +arguments, with the inputs arguments given by @var{C}, @var{D}, etc. +Equally the function can return one or more output arguments. For example: + +@example +@group +cellfun ("atan2", @{1, 0@}, @{0, 1@}) + @result{} [ 1.57080 0.00000 ] +@end group +@end example + +The number of output arguments of @code{cellfun} matches the number of +output arguments of the function. The outputs of the function will be +collected into the output arguments of @code{cellfun} like this: + +@example +@group +function [a, b] = twoouts (x) + a = x; + b = x*x; +endfunction +[aa, bb] = cellfun (@@twoouts, @{1, 2, 3@}) + @result{} + aa = + 1 2 3 + bb = + 1 4 9 +@end group +@end example + +Note that per default the output argument(s) are arrays of the same size as +the input arguments. Input arguments that are singleton (1x1) cells will be +automatically expanded to the size of the other arguments. + +If the parameter @qcode{"UniformOutput"} is set to true (the default), +then the function must return scalars which will be concatenated into the +return array(s). If @qcode{"UniformOutput"} is false, the outputs are +concatenated into a cell array (or cell arrays). For example: + +@example +@group +cellfun ("tolower", @{"Foo", "Bar", "FooBar"@}, + "UniformOutput", false) +@result{} @{"foo", "bar", "foobar"@} +@end group +@end example + +Given the parameter @qcode{"ErrorHandler"}, then @var{errfunc} defines a +function to call in case @var{func} generates an error. The form of the +function is + +@example +function [@dots{}] = errfunc (@var{s}, @dots{}) +@end example + +@noindent +where there is an additional input argument to @var{errfunc} relative to +@var{func}, given by @var{s}. This is a structure with the elements +@qcode{"identifier"}, @qcode{"message"}, and @qcode{"index"} giving +respectively the error identifier, the error message, and the index into the +input arguments of the element that caused the error. For example: + +@example +@group +function y = foo (s, x), y = NaN; endfunction +cellfun ("factorial", @{-1,2@}, "ErrorHandler", @@foo) +@result{} [NaN 2] +@end group +@end example + +Use @code{cellfun} intelligently. The @code{cellfun} function is a +useful tool for avoiding loops. It is often used with anonymous +function handles; however, calling an anonymous function involves an +overhead quite comparable to the overhead of an m-file function. +Passing a handle to a built-in function is faster, because the +interpreter is not involved in the internal loop. For example: + +@example +@group +a = @{@dots{}@} +v = cellfun (@@(x) det (x), a); # compute determinants +v = cellfun (@@det, a); # faster +@end group +@end example + +@seealso{arrayfun, structfun, spfun} +@end deftypefn */) { int nargin = args.length (); @@ -998,119 +998,119 @@ // handle the nargout = 0 case. DEFUN (arrayfun, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} arrayfun (@var{func}, @var{A})\n\ -@deftypefnx {} {@var{x} =} arrayfun (@var{func}, @var{A})\n\ -@deftypefnx {} {@var{x} =} arrayfun (@var{func}, @var{A}, @var{b}, @dots{})\n\ -@deftypefnx {} {[@var{x}, @var{y}, @dots{}] =} arrayfun (@var{func}, @var{A}, @dots{})\n\ -@deftypefnx {} {} arrayfun (@dots{}, \"UniformOutput\", @var{val})\n\ -@deftypefnx {} {} arrayfun (@dots{}, \"ErrorHandler\", @var{errfunc})\n\ -\n\ -Execute a function on each element of an array.\n\ -\n\ -This is useful for functions that do not accept array arguments. If the\n\ -function does accept array arguments it is better to call the function\n\ -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{} [ 1.5708 0.0000 ]\n\ -@end group\n\ -@end example\n\ -\n\ -If the parameter @var{val} after a further string input argument\n\ -@qcode{\"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{}\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\ -@qcode{\"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 @qcode{\"identifier\"}, @qcode{\"message\"}, and\n\ -@qcode{\"index\"} giving, respectively, the error identifier, the error\n\ -message, and the index of the array elements that caused the error. The\n\ -size of the output argument of @var{errfunc} must have the same size as the\n\ -output 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{}\n\ - @{\n\ - [1,1] = MyString\n\ - @}\n\ -@end group\n\ -@end example\n\ -\n\ -@seealso{spfun, cellfun, structfun}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} arrayfun (@var{func}, @var{A}) +@deftypefnx {} {@var{x} =} arrayfun (@var{func}, @var{A}) +@deftypefnx {} {@var{x} =} arrayfun (@var{func}, @var{A}, @var{b}, @dots{}) +@deftypefnx {} {[@var{x}, @var{y}, @dots{}] =} arrayfun (@var{func}, @var{A}, @dots{}) +@deftypefnx {} {} arrayfun (@dots{}, "UniformOutput", @var{val}) +@deftypefnx {} {} arrayfun (@dots{}, "ErrorHandler", @var{errfunc}) + +Execute a function on each element of an array. + +This is useful for functions that do not accept array arguments. If the +function does accept array arguments it is better to call the function +directly. + +The first input argument @var{func} can be a string, a function +handle, an inline function, or an anonymous function. The input +argument @var{A} can be a logic array, a numeric array, a string +array, a structure array, or a cell array. By a call of the function +@command{arrayfun} all elements of @var{A} are passed on to the named +function @var{func} individually. + +The named function can also take more than two input arguments, with +the input arguments given as third input argument @var{b}, fourth +input argument @var{c}, @dots{} If given more than one array input +argument then all input arguments must have the same sizes, for +example: + +@example +@group +arrayfun (@@atan2, [1, 0], [0, 1]) + @result{} [ 1.5708 0.0000 ] +@end group +@end example + +If the parameter @var{val} after a further string input argument +@qcode{"UniformOutput"} is set @code{true} (the default), then the named +function @var{func} must return a single element which then will be +concatenated into the return value and is of type matrix. Otherwise, +if that parameter is set to @code{false}, then the outputs are +concatenated in a cell array. For example: + +@example +@group +arrayfun (@@(x,y) x:y, "abc", "def", "UniformOutput", false) +@result{} + @{ + [1,1] = abcd + [1,2] = bcde + [1,3] = cdef + @} +@end group +@end example + +If more than one output arguments are given then the named function +must return the number of return values that also are expected, for +example: + +@example +@group +[A, B, C] = arrayfun (@@find, [10; 0], "UniformOutput", false) +@result{} +A = +@{ + [1,1] = 1 + [2,1] = [](0x0) +@} +B = +@{ + [1,1] = 1 + [2,1] = [](0x0) +@} +C = +@{ + [1,1] = 10 + [2,1] = [](0x0) +@} +@end group +@end example + +If the parameter @var{errfunc} after a further string input argument +@qcode{"ErrorHandler"} is another string, a function handle, an inline +function, or an anonymous function, then @var{errfunc} defines a +function to call in the case that @var{func} generates an error. +The definition of the function must be of the form + +@example +function [@dots{}] = errfunc (@var{s}, @dots{}) +@end example + +@noindent +where there is an additional input argument to @var{errfunc} +relative to @var{func}, given by @var{s}. This is a structure with +the elements @qcode{"identifier"}, @qcode{"message"}, and +@qcode{"index"} giving, respectively, the error identifier, the error +message, and the index of the array elements that caused the error. The +size of the output argument of @var{errfunc} must have the same size as the +output argument of @var{func}, otherwise a real error is thrown. For +example: + +@example +@group +function y = ferr (s, x), y = "MyString"; endfunction +arrayfun (@@str2num, [1234], + "UniformOutput", false, "ErrorHandler", @@ferr) +@result{} + @{ + [1,1] = MyString + @} +@end group +@end example + +@seealso{spfun, cellfun, structfun} +@end deftypefn */) { int nargin = args.length (); @@ -1736,40 +1736,40 @@ } DEFUN (num2cell, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{C} =} num2cell (@var{A})\n\ -@deftypefnx {} {@var{C} =} num2cell (@var{A}, @var{dim})\n\ -Convert the numeric matrix @var{A} to a cell array.\n\ -\n\ -If @var{dim} is defined, the value @var{C} is of dimension 1 in this\n\ -dimension and the elements of @var{A} are placed into @var{C} in slices.\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -num2cell ([1,2;3,4])\n\ - @result{}\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{}\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") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{C} =} num2cell (@var{A}) +@deftypefnx {} {@var{C} =} num2cell (@var{A}, @var{dim}) +Convert the numeric matrix @var{A} to a cell array. + +If @var{dim} is defined, the value @var{C} is of dimension 1 in this +dimension and the elements of @var{A} are placed into @var{C} in slices. +For example: + +@example +@group +num2cell ([1,2;3,4]) + @result{} + @{ + [1,1] = 1 + [2,1] = 3 + [1,2] = 2 + [2,2] = 4 + @} +num2cell ([1,2;3,4],1) + @result{} + @{ + [1,1] = + 1 + 3 + [1,2] = + 2 + 4 + @} +@end group +@end example + +@seealso{mat2cell} +@end deftypefn */) { int nargin = args.length (); @@ -2057,49 +2057,49 @@ } DEFUN (mat2cell, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{C} =} mat2cell (@var{A}, @var{m}, @var{n})\n\ -@deftypefnx {} {@var{C} =} mat2cell (@var{A}, @var{d1}, @var{d2}, @dots{})\n\ -@deftypefnx {} {@var{C} =} mat2cell (@var{A}, @var{r})\n\ -Convert the matrix @var{A} to a cell array.\n\ -\n\ -If @var{A} is 2-D, then it is required that\n\ -@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 to the\n\ -dimensions of @var{A}, then it is required that\n\ -@code{sum (@var{di}) == 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\ -@{\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") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{C} =} mat2cell (@var{A}, @var{m}, @var{n}) +@deftypefnx {} {@var{C} =} mat2cell (@var{A}, @var{d1}, @var{d2}, @dots{}) +@deftypefnx {} {@var{C} =} mat2cell (@var{A}, @var{r}) +Convert the matrix @var{A} to a cell array. + +If @var{A} is 2-D, then it is required that +@code{sum (@var{m}) == size (@var{A}, 1)} and +@code{sum (@var{n}) == size (@var{A}, 2)}. Similarly, if @var{A} is +multi-dimensional and the number of dimensional arguments is equal to the +dimensions of @var{A}, then it is required that +@code{sum (@var{di}) == size (@var{A}, i)}. + +Given a single dimensional argument @var{r}, the other dimensional +arguments are assumed to equal @code{size (@var{A},@var{i})}. + +An example of the use of mat2cell is + +@example +mat2cell (reshape (1:16,4,4), [3,1], [3,1]) +@result{} +@{ + [1,1] = + + 1 5 9 + 2 6 10 + 3 7 11 + + [2,1] = + + 4 8 12 + + [1,2] = + + 13 + 14 + 15 + + [2,2] = 16 +@} +@end example +@seealso{num2cell, cell2mat} +@end deftypefn */) { int nargin = args.length (); @@ -2227,28 +2227,28 @@ } DEFUN (cellslices, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@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.\n\ -\n\ -In other words, it is equivalent to the 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") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{sl} =} cellslices (@var{x}, @var{lb}, @var{ub}, @var{dim}) +Given an array @var{x}, this function produces a cell array of slices from +the array determined by the index vectors @var{lb}, @var{ub}, for lower and +upper bounds, respectively. + +In other words, it is equivalent to the following code: + +@example +@group +n = length (lb); +sl = cell (1, n); +for i = 1:length (lb) + sl@{i@} = x(:,@dots{},lb(i):ub(i),@dots{},:); +endfor +@end group +@end example + +The position of the index is determined by @var{dim}. If not specified, +slicing is done along the first non-singleton dimension. +@seealso{cell2mat, cellindexmat, cellfun} +@end deftypefn */) { int nargin = args.length (); @@ -2354,22 +2354,22 @@ */ DEFUN (cellindexmat, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{y} =} cellindexmat (@var{x}, @var{varargin})\n\ -Perform indexing of matrices in a cell array.\n\ -\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") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{y} =} cellindexmat (@var{x}, @var{varargin}) +Perform indexing of matrices in a cell array. + +Given a cell array of matrices @var{x}, this function computes + +@example +@group +Y = cell (size (X)); +for i = 1:numel (X) + Y@{i@} = X@{i@}(varargin@{:@}); +endfor +@end group +@end example +@seealso{cellslices, cellfun} +@end deftypefn */) { if (args.length () == 0) print_usage ();
--- a/libinterp/corefcn/colloc.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/colloc.cc Tue Jun 21 16:07:51 2016 -0400 @@ -35,13 +35,13 @@ #include "utils.h" DEFUN (colloc, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{r}, @var{amat}, @var{bmat}, @var{q}] =} colloc (@var{n}, \"left\", \"right\")\n\ -Compute derivative and integral weight matrices for orthogonal collocation.\n\ -\n\ -Reference: @nospell{J. Villadsen}, @nospell{M. L. Michelsen},\n\ -@cite{Solution of Differential Equation Models by Polynomial Approximation}.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{r}, @var{amat}, @var{bmat}, @var{q}] =} colloc (@var{n}, "left", "right") +Compute derivative and integral weight matrices for orthogonal collocation. + +Reference: @nospell{J. Villadsen}, @nospell{M. L. Michelsen}, +@cite{Solution of Differential Equation Models by Polynomial Approximation}. +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/conv2.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/conv2.cc Tue Jun 21 16:07:51 2016 -0400 @@ -35,34 +35,34 @@ enum Shape { SHAPE_FULL, SHAPE_SAME, SHAPE_VALID }; DEFUN (conv2, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} conv2 (@var{A}, @var{B})\n\ -@deftypefnx {} {} conv2 (@var{v1}, @var{v2}, @var{m})\n\ -@deftypefnx {} {} conv2 (@dots{}, @var{shape})\n\ -Return the 2-D convolution of @var{A} and @var{B}.\n\ -\n\ -The size of the result is determined by the optional @var{shape} argument\n\ -which takes the following values\n\ -\n\ -@table @asis\n\ -@item @var{shape} = @qcode{\"full\"}\n\ -Return the full convolution. (default)\n\ -\n\ -@item @var{shape} = @qcode{\"same\"}\n\ -Return the central part of the convolution with the same size as @var{A}.\n\ -The central part of the convolution begins at the indices\n\ -@code{floor ([size(@var{B})/2] + 1)}.\n\ -\n\ -@item @var{shape} = @qcode{\"valid\"}\n\ -Return only the parts which do not include zero-padded edges.\n\ -The size of the result is @code{max (size (A) - size (B) + 1, 0)}.\n\ -@end table\n\ -\n\ -When the third argument is a matrix, return the convolution of the matrix\n\ -@var{m} by the vector @var{v1} in the column direction and by the vector\n\ -@var{v2} in the row direction.\n\ -@seealso{conv, convn}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} conv2 (@var{A}, @var{B}) +@deftypefnx {} {} conv2 (@var{v1}, @var{v2}, @var{m}) +@deftypefnx {} {} conv2 (@dots{}, @var{shape}) +Return the 2-D convolution of @var{A} and @var{B}. + +The size of the result is determined by the optional @var{shape} argument +which takes the following values + +@table @asis +@item @var{shape} = @qcode{"full"} +Return the full convolution. (default) + +@item @var{shape} = @qcode{"same"} +Return the central part of the convolution with the same size as @var{A}. +The central part of the convolution begins at the indices +@code{floor ([size(@var{B})/2] + 1)}. + +@item @var{shape} = @qcode{"valid"} +Return only the parts which do not include zero-padded edges. +The size of the result is @code{max (size (A) - size (B) + 1, 0)}. +@end table + +When the third argument is a matrix, return the convolution of the matrix +@var{m} by the vector @var{v1} in the column direction and by the vector +@var{v2} in the row direction. +@seealso{conv, convn} +@end deftypefn */) { int nargin = args.length (); @@ -280,30 +280,30 @@ */ DEFUN (convn, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{C} =} convn (@var{A}, @var{B})\n\ -@deftypefnx {} {@var{C} =} convn (@var{A}, @var{B}, @var{shape})\n\ -Return the n-D convolution of @var{A} and @var{B}.\n\ -\n\ -The size of the result is determined by the optional @var{shape} argument\n\ -which takes the following values\n\ -\n\ -@table @asis\n\ -@item @var{shape} = @qcode{\"full\"}\n\ -Return the full convolution. (default)\n\ -\n\ -@item @var{shape} = @qcode{\"same\"}\n\ -Return central part of the convolution with the same size as @var{A}.\n\ -The central part of the convolution begins at the indices\n\ -@code{floor ([size(@var{B})/2] + 1)}.\n\ -\n\ -@item @var{shape} = @qcode{\"valid\"}\n\ -Return only the parts which do not include zero-padded edges.\n\ -The size of the result is @code{max (size (A) - size (B) + 1, 0)}.\n\ -@end table\n\ -\n\ -@seealso{conv2, conv}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{C} =} convn (@var{A}, @var{B}) +@deftypefnx {} {@var{C} =} convn (@var{A}, @var{B}, @var{shape}) +Return the n-D convolution of @var{A} and @var{B}. + +The size of the result is determined by the optional @var{shape} argument +which takes the following values + +@table @asis +@item @var{shape} = @qcode{"full"} +Return the full convolution. (default) + +@item @var{shape} = @qcode{"same"} +Return central part of the convolution with the same size as @var{A}. +The central part of the convolution begins at the indices +@code{floor ([size(@var{B})/2] + 1)}. + +@item @var{shape} = @qcode{"valid"} +Return only the parts which do not include zero-padded edges. +The size of the result is @code{max (size (A) - size (B) + 1, 0)}. +@end table + +@seealso{conv2, conv} +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/daspk.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/daspk.cc Tue Jun 21 16:07:51 2016 -0400 @@ -154,105 +154,105 @@ } DEFUN (daspk, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{x}, @var{xdot}, @var{istate}, @var{msg}] =} daspk (@var{fcn}, @var{x_0}, @var{xdot_0}, @var{t}, @var{t_crit})\n\ -Solve the set of differential-algebraic equations\n\ -@tex\n\ -$$ 0 = f (x, \\dot{x}, t) $$\n\ -with\n\ -$$ x(t_0) = x_0, \\dot{x}(t_0) = \\dot{x}_0 $$\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ -0 = f (x, xdot, t)\n\ -@end example\n\ -\n\ -@noindent\n\ -with\n\ -\n\ -@example\n\ -x(t_0) = x_0, xdot(t_0) = xdot_0\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -The solution is returned in the matrices @var{x} and @var{xdot},\n\ -with each row in the result matrices corresponding to one of the\n\ -elements in the vector @var{t}. The first element of @var{t}\n\ -should be @math{t_0} and correspond to the initial state of the\n\ -system @var{x_0} and its derivative @var{xdot_0}, so that the first\n\ -row of the output @var{x} is @var{x_0} and the first row\n\ -of the output @var{xdot} is @var{xdot_0}.\n\ -\n\ -The first argument, @var{fcn}, is a string, inline, or function handle\n\ -that names the function @math{f} to call to compute the vector of\n\ -residuals for the set of equations. It must have the form\n\ -\n\ -@example\n\ -@var{res} = f (@var{x}, @var{xdot}, @var{t})\n\ -@end example\n\ -\n\ -@noindent\n\ -in which @var{x}, @var{xdot}, and @var{res} are vectors, and @var{t} is a\n\ -scalar.\n\ -\n\ -If @var{fcn} is a two-element string array or a two-element cell array\n\ -of strings, inline functions, or function handles, the first element names\n\ -the function @math{f} described above, and the second element names a\n\ -function to compute the modified Jacobian\n\ -@tex\n\ -$$\n\ -J = {\\partial f \\over \\partial x}\n\ - + c {\\partial f \\over \\partial \\dot{x}}\n\ -$$\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ -@group\n\ - df df\n\ -jac = -- + c ------\n\ - dx d xdot\n\ -@end group\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -\n\ -The modified Jacobian function must have the form\n\ -\n\ -@example\n\ -@group\n\ -\n\ -@var{jac} = j (@var{x}, @var{xdot}, @var{t}, @var{c})\n\ -\n\ -@end group\n\ -@end example\n\ -\n\ -The second and third arguments to @code{daspk} specify the initial\n\ -condition of the states and their derivatives, and the fourth argument\n\ -specifies a vector of output times at which the solution is desired,\n\ -including the time corresponding to the initial condition.\n\ -\n\ -The set of initial states and derivatives are not strictly required to\n\ -be consistent. If they are not consistent, you must use the\n\ -@code{daspk_options} function to provide additional information so\n\ -that @code{daspk} can compute a consistent starting point.\n\ -\n\ -The fifth argument is optional, and may be used to specify a set of\n\ -times that the DAE solver should not integrate past. It is useful for\n\ -avoiding difficulties with singularities and points where there is a\n\ -discontinuity in the derivative.\n\ -\n\ -After a successful computation, the value of @var{istate} will be\n\ -greater than zero (consistent with the Fortran version of @sc{daspk}).\n\ -\n\ -If the computation is not successful, the value of @var{istate} will be\n\ -less than zero and @var{msg} will contain additional information.\n\ -\n\ -You can use the function @code{daspk_options} to set optional\n\ -parameters for @code{daspk}.\n\ -@seealso{dassl}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{x}, @var{xdot}, @var{istate}, @var{msg}] =} daspk (@var{fcn}, @var{x_0}, @var{xdot_0}, @var{t}, @var{t_crit}) +Solve the set of differential-algebraic equations +@tex +$$ 0 = f (x, \dot{x}, t) $$ +with +$$ x(t_0) = x_0, \dot{x}(t_0) = \dot{x}_0 $$ +@end tex +@ifnottex + +@example +0 = f (x, xdot, t) +@end example + +@noindent +with + +@example +x(t_0) = x_0, xdot(t_0) = xdot_0 +@end example + +@end ifnottex +The solution is returned in the matrices @var{x} and @var{xdot}, +with each row in the result matrices corresponding to one of the +elements in the vector @var{t}. The first element of @var{t} +should be @math{t_0} and correspond to the initial state of the +system @var{x_0} and its derivative @var{xdot_0}, so that the first +row of the output @var{x} is @var{x_0} and the first row +of the output @var{xdot} is @var{xdot_0}. + +The first argument, @var{fcn}, is a string, inline, or function handle +that names the function @math{f} to call to compute the vector of +residuals for the set of equations. It must have the form + +@example +@var{res} = f (@var{x}, @var{xdot}, @var{t}) +@end example + +@noindent +in which @var{x}, @var{xdot}, and @var{res} are vectors, and @var{t} is a +scalar. + +If @var{fcn} is a two-element string array or a two-element cell array +of strings, inline functions, or function handles, the first element names +the function @math{f} described above, and the second element names a +function to compute the modified Jacobian +@tex +$$ +J = {\partial f \over \partial x} + + c {\partial f \over \partial \dot{x}} +$$ +@end tex +@ifnottex + +@example +@group + df df +jac = -- + c ------ + dx d xdot +@end group +@end example + +@end ifnottex + +The modified Jacobian function must have the form + +@example +@group + +@var{jac} = j (@var{x}, @var{xdot}, @var{t}, @var{c}) + +@end group +@end example + +The second and third arguments to @code{daspk} specify the initial +condition of the states and their derivatives, and the fourth argument +specifies a vector of output times at which the solution is desired, +including the time corresponding to the initial condition. + +The set of initial states and derivatives are not strictly required to +be consistent. If they are not consistent, you must use the +@code{daspk_options} function to provide additional information so +that @code{daspk} can compute a consistent starting point. + +The fifth argument is optional, and may be used to specify a set of +times that the DAE solver should not integrate past. It is useful for +avoiding difficulties with singularities and points where there is a +discontinuity in the derivative. + +After a successful computation, the value of @var{istate} will be +greater than zero (consistent with the Fortran version of @sc{daspk}). + +If the computation is not successful, the value of @var{istate} will be +less than zero and @var{msg} will contain additional information. + +You can use the function @code{daspk_options} to set optional +parameters for @code{daspk}. +@seealso{dassl} +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/dasrt.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/dasrt.cc Tue Jun 21 16:07:51 2016 -0400 @@ -191,145 +191,145 @@ } DEFUN (dasrt, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{x}, @var{xdot}, @var{t_out}, @var{istat}, @var{msg}] =} dasrt (@var{fcn}, [], @var{x_0}, @var{xdot_0}, @var{t})\n\ -@deftypefnx {} {@dots{} =} dasrt (@var{fcn}, @var{g}, @var{x_0}, @var{xdot_0}, @var{t})\n\ -@deftypefnx {} {@dots{} =} dasrt (@var{fcn}, [], @var{x_0}, @var{xdot_0}, @var{t}, @var{t_crit})\n\ -@deftypefnx {} {@dots{} =} dasrt (@var{fcn}, @var{g}, @var{x_0}, @var{xdot_0}, @var{t}, @var{t_crit})\n\ -Solve the set of differential-algebraic equations\n\ -@tex\n\ -$$ 0 = f (x, \\dot{x}, t) $$\n\ -with\n\ -$$ x(t_0) = x_0, \\dot{x}(t_0) = \\dot{x}_0 $$\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ -0 = f (x, xdot, t)\n\ -@end example\n\ -\n\ -@noindent\n\ -with\n\ -\n\ -@example\n\ -x(t_0) = x_0, xdot(t_0) = xdot_0\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -with functional stopping criteria (root solving).\n\ -\n\ -The solution is returned in the matrices @var{x} and @var{xdot},\n\ -with each row in the result matrices corresponding to one of the\n\ -elements in the vector @var{t_out}. The first element of @var{t}\n\ -should be @math{t_0} and correspond to the initial state of the\n\ -system @var{x_0} and its derivative @var{xdot_0}, so that the first\n\ -row of the output @var{x} is @var{x_0} and the first row\n\ -of the output @var{xdot} is @var{xdot_0}.\n\ -\n\ -The vector @var{t} provides an upper limit on the length of the\n\ -integration. If the stopping condition is met, the vector\n\ -@var{t_out} will be shorter than @var{t}, and the final element of\n\ -@var{t_out} will be the point at which the stopping condition was met,\n\ -and may not correspond to any element of the vector @var{t}.\n\ -\n\ -The first argument, @var{fcn}, is a string, inline, or function handle\n\ -that names the function @math{f} to call to compute the vector of\n\ -residuals for the set of equations. It must have the form\n\ -\n\ -@example\n\ -@var{res} = f (@var{x}, @var{xdot}, @var{t})\n\ -@end example\n\ -\n\ -@noindent\n\ -in which @var{x}, @var{xdot}, and @var{res} are vectors, and @var{t} is a\n\ -scalar.\n\ -\n\ -If @var{fcn} is a two-element string array or a two-element cell array\n\ -of strings, inline functions, or function handles, the first element names\n\ -the function @math{f} described above, and the second element names a\n\ -function to compute the modified Jacobian\n\ -\n\ -@tex\n\ -$$\n\ -J = {\\partial f \\over \\partial x}\n\ - + c {\\partial f \\over \\partial \\dot{x}}\n\ -$$\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ -@group\n\ - df df\n\ -jac = -- + c ------\n\ - dx d xdot\n\ -@end group\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -\n\ -The modified Jacobian function must have the form\n\ -\n\ -@example\n\ -@group\n\ -\n\ -@var{jac} = j (@var{x}, @var{xdot}, @var{t}, @var{c})\n\ -\n\ -@end group\n\ -@end example\n\ -\n\ -The optional second argument names a function that defines the\n\ -constraint functions whose roots are desired during the integration.\n\ -This function must have the form\n\ -\n\ -@example\n\ -@var{g_out} = g (@var{x}, @var{t})\n\ -@end example\n\ -\n\ -@noindent\n\ -and return a vector of the constraint function values.\n\ -If the value of any of the constraint functions changes sign, @sc{dasrt}\n\ -will attempt to stop the integration at the point of the sign change.\n\ -\n\ -If the name of the constraint function is omitted, @code{dasrt} solves\n\ -the same problem as @code{daspk} or @code{dassl}.\n\ -\n\ -Note that because of numerical errors in the constraint functions\n\ -due to round-off and integration error, @sc{dasrt} may return false\n\ -roots, or return the same root at two or more nearly equal values of\n\ -@var{T}. If such false roots are suspected, the user should consider\n\ -smaller error tolerances or higher precision in the evaluation of the\n\ -constraint functions.\n\ -\n\ -If a root of some constraint function defines the end of the problem,\n\ -the input to @sc{dasrt} should nevertheless allow integration to a\n\ -point slightly past that root, so that @sc{dasrt} can locate the root\n\ -by interpolation.\n\ -\n\ -The third and fourth arguments to @code{dasrt} specify the initial\n\ -condition of the states and their derivatives, and the fourth argument\n\ -specifies a vector of output times at which the solution is desired,\n\ -including the time corresponding to the initial condition.\n\ -\n\ -The set of initial states and derivatives are not strictly required to\n\ -be consistent. In practice, however, @sc{dassl} is not very good at\n\ -determining a consistent set for you, so it is best if you ensure that\n\ -the initial values result in the function evaluating to zero.\n\ -\n\ -The sixth argument is optional, and may be used to specify a set of\n\ -times that the DAE solver should not integrate past. It is useful for\n\ -avoiding difficulties with singularities and points where there is a\n\ -discontinuity in the derivative.\n\ -\n\ -After a successful computation, the value of @var{istate} will be\n\ -greater than zero (consistent with the Fortran version of @sc{dassl}).\n\ -\n\ -If the computation is not successful, the value of @var{istate} will be\n\ -less than zero and @var{msg} will contain additional information.\n\ -\n\ -You can use the function @code{dasrt_options} to set optional\n\ -parameters for @code{dasrt}.\n\ -@seealso{dasrt_options, daspk, dasrt, lsode}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{x}, @var{xdot}, @var{t_out}, @var{istat}, @var{msg}] =} dasrt (@var{fcn}, [], @var{x_0}, @var{xdot_0}, @var{t}) +@deftypefnx {} {@dots{} =} dasrt (@var{fcn}, @var{g}, @var{x_0}, @var{xdot_0}, @var{t}) +@deftypefnx {} {@dots{} =} dasrt (@var{fcn}, [], @var{x_0}, @var{xdot_0}, @var{t}, @var{t_crit}) +@deftypefnx {} {@dots{} =} dasrt (@var{fcn}, @var{g}, @var{x_0}, @var{xdot_0}, @var{t}, @var{t_crit}) +Solve the set of differential-algebraic equations +@tex +$$ 0 = f (x, \dot{x}, t) $$ +with +$$ x(t_0) = x_0, \dot{x}(t_0) = \dot{x}_0 $$ +@end tex +@ifnottex + +@example +0 = f (x, xdot, t) +@end example + +@noindent +with + +@example +x(t_0) = x_0, xdot(t_0) = xdot_0 +@end example + +@end ifnottex +with functional stopping criteria (root solving). + +The solution is returned in the matrices @var{x} and @var{xdot}, +with each row in the result matrices corresponding to one of the +elements in the vector @var{t_out}. The first element of @var{t} +should be @math{t_0} and correspond to the initial state of the +system @var{x_0} and its derivative @var{xdot_0}, so that the first +row of the output @var{x} is @var{x_0} and the first row +of the output @var{xdot} is @var{xdot_0}. + +The vector @var{t} provides an upper limit on the length of the +integration. If the stopping condition is met, the vector +@var{t_out} will be shorter than @var{t}, and the final element of +@var{t_out} will be the point at which the stopping condition was met, +and may not correspond to any element of the vector @var{t}. + +The first argument, @var{fcn}, is a string, inline, or function handle +that names the function @math{f} to call to compute the vector of +residuals for the set of equations. It must have the form + +@example +@var{res} = f (@var{x}, @var{xdot}, @var{t}) +@end example + +@noindent +in which @var{x}, @var{xdot}, and @var{res} are vectors, and @var{t} is a +scalar. + +If @var{fcn} is a two-element string array or a two-element cell array +of strings, inline functions, or function handles, the first element names +the function @math{f} described above, and the second element names a +function to compute the modified Jacobian + +@tex +$$ +J = {\partial f \over \partial x} + + c {\partial f \over \partial \dot{x}} +$$ +@end tex +@ifnottex + +@example +@group + df df +jac = -- + c ------ + dx d xdot +@end group +@end example + +@end ifnottex + +The modified Jacobian function must have the form + +@example +@group + +@var{jac} = j (@var{x}, @var{xdot}, @var{t}, @var{c}) + +@end group +@end example + +The optional second argument names a function that defines the +constraint functions whose roots are desired during the integration. +This function must have the form + +@example +@var{g_out} = g (@var{x}, @var{t}) +@end example + +@noindent +and return a vector of the constraint function values. +If the value of any of the constraint functions changes sign, @sc{dasrt} +will attempt to stop the integration at the point of the sign change. + +If the name of the constraint function is omitted, @code{dasrt} solves +the same problem as @code{daspk} or @code{dassl}. + +Note that because of numerical errors in the constraint functions +due to round-off and integration error, @sc{dasrt} may return false +roots, or return the same root at two or more nearly equal values of +@var{T}. If such false roots are suspected, the user should consider +smaller error tolerances or higher precision in the evaluation of the +constraint functions. + +If a root of some constraint function defines the end of the problem, +the input to @sc{dasrt} should nevertheless allow integration to a +point slightly past that root, so that @sc{dasrt} can locate the root +by interpolation. + +The third and fourth arguments to @code{dasrt} specify the initial +condition of the states and their derivatives, and the fourth argument +specifies a vector of output times at which the solution is desired, +including the time corresponding to the initial condition. + +The set of initial states and derivatives are not strictly required to +be consistent. In practice, however, @sc{dassl} is not very good at +determining a consistent set for you, so it is best if you ensure that +the initial values result in the function evaluating to zero. + +The sixth argument is optional, and may be used to specify a set of +times that the DAE solver should not integrate past. It is useful for +avoiding difficulties with singularities and points where there is a +discontinuity in the derivative. + +After a successful computation, the value of @var{istate} will be +greater than zero (consistent with the Fortran version of @sc{dassl}). + +If the computation is not successful, the value of @var{istate} will be +less than zero and @var{msg} will contain additional information. + +You can use the function @code{dasrt_options} to set optional +parameters for @code{dasrt}. +@seealso{dasrt_options, daspk, dasrt, lsode} +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/dassl.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/dassl.cc Tue Jun 21 16:07:51 2016 -0400 @@ -154,106 +154,106 @@ } DEFUN (dassl, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{x}, @var{xdot}, @var{istate}, @var{msg}] =} dassl (@var{fcn}, @var{x_0}, @var{xdot_0}, @var{t}, @var{t_crit})\n\ -Solve the set of differential-algebraic equations\n\ -@tex\n\ -$$ 0 = f (x, \\dot{x}, t) $$\n\ -with\n\ -$$ x(t_0) = x_0, \\dot{x}(t_0) = \\dot{x}_0 $$\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ -0 = f (x, xdot, t)\n\ -@end example\n\ -\n\ -@noindent\n\ -with\n\ -\n\ -@example\n\ -x(t_0) = x_0, xdot(t_0) = xdot_0\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -The solution is returned in the matrices @var{x} and @var{xdot},\n\ -with each row in the result matrices corresponding to one of the\n\ -elements in the vector @var{t}. The first element of @var{t}\n\ -should be @math{t_0} and correspond to the initial state of the\n\ -system @var{x_0} and its derivative @var{xdot_0}, so that the first\n\ -row of the output @var{x} is @var{x_0} and the first row\n\ -of the output @var{xdot} is @var{xdot_0}.\n\ -\n\ -The first argument, @var{fcn}, is a string, inline, or function handle\n\ -that names the function @math{f} to call to compute the vector of\n\ -residuals for the set of equations. It must have the form\n\ -\n\ -@example\n\ -@var{res} = f (@var{x}, @var{xdot}, @var{t})\n\ -@end example\n\ -\n\ -@noindent\n\ -in which @var{x}, @var{xdot}, and @var{res} are vectors, and @var{t} is a\n\ -scalar.\n\ -\n\ -If @var{fcn} is a two-element string array or a two-element cell array\n\ -of strings, inline functions, or function handles, the first element names\n\ -the function @math{f} described above, and the second element names a\n\ -function to compute the modified Jacobian\n\ -\n\ -@tex\n\ -$$\n\ -J = {\\partial f \\over \\partial x}\n\ - + c {\\partial f \\over \\partial \\dot{x}}\n\ -$$\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ -@group\n\ - df df\n\ -jac = -- + c ------\n\ - dx d xdot\n\ -@end group\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -\n\ -The modified Jacobian function must have the form\n\ -\n\ -@example\n\ -@group\n\ -\n\ -@var{jac} = j (@var{x}, @var{xdot}, @var{t}, @var{c})\n\ -\n\ -@end group\n\ -@end example\n\ -\n\ -The second and third arguments to @code{dassl} specify the initial\n\ -condition of the states and their derivatives, and the fourth argument\n\ -specifies a vector of output times at which the solution is desired,\n\ -including the time corresponding to the initial condition.\n\ -\n\ -The set of initial states and derivatives are not strictly required to\n\ -be consistent. In practice, however, @sc{dassl} is not very good at\n\ -determining a consistent set for you, so it is best if you ensure that\n\ -the initial values result in the function evaluating to zero.\n\ -\n\ -The fifth argument is optional, and may be used to specify a set of\n\ -times that the DAE solver should not integrate past. It is useful for\n\ -avoiding difficulties with singularities and points where there is a\n\ -discontinuity in the derivative.\n\ -\n\ -After a successful computation, the value of @var{istate} will be\n\ -greater than zero (consistent with the Fortran version of @sc{dassl}).\n\ -\n\ -If the computation is not successful, the value of @var{istate} will be\n\ -less than zero and @var{msg} will contain additional information.\n\ -\n\ -You can use the function @code{dassl_options} to set optional\n\ -parameters for @code{dassl}.\n\ -@seealso{daspk, dasrt, lsode}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{x}, @var{xdot}, @var{istate}, @var{msg}] =} dassl (@var{fcn}, @var{x_0}, @var{xdot_0}, @var{t}, @var{t_crit}) +Solve the set of differential-algebraic equations +@tex +$$ 0 = f (x, \dot{x}, t) $$ +with +$$ x(t_0) = x_0, \dot{x}(t_0) = \dot{x}_0 $$ +@end tex +@ifnottex + +@example +0 = f (x, xdot, t) +@end example + +@noindent +with + +@example +x(t_0) = x_0, xdot(t_0) = xdot_0 +@end example + +@end ifnottex +The solution is returned in the matrices @var{x} and @var{xdot}, +with each row in the result matrices corresponding to one of the +elements in the vector @var{t}. The first element of @var{t} +should be @math{t_0} and correspond to the initial state of the +system @var{x_0} and its derivative @var{xdot_0}, so that the first +row of the output @var{x} is @var{x_0} and the first row +of the output @var{xdot} is @var{xdot_0}. + +The first argument, @var{fcn}, is a string, inline, or function handle +that names the function @math{f} to call to compute the vector of +residuals for the set of equations. It must have the form + +@example +@var{res} = f (@var{x}, @var{xdot}, @var{t}) +@end example + +@noindent +in which @var{x}, @var{xdot}, and @var{res} are vectors, and @var{t} is a +scalar. + +If @var{fcn} is a two-element string array or a two-element cell array +of strings, inline functions, or function handles, the first element names +the function @math{f} described above, and the second element names a +function to compute the modified Jacobian + +@tex +$$ +J = {\partial f \over \partial x} + + c {\partial f \over \partial \dot{x}} +$$ +@end tex +@ifnottex + +@example +@group + df df +jac = -- + c ------ + dx d xdot +@end group +@end example + +@end ifnottex + +The modified Jacobian function must have the form + +@example +@group + +@var{jac} = j (@var{x}, @var{xdot}, @var{t}, @var{c}) + +@end group +@end example + +The second and third arguments to @code{dassl} specify the initial +condition of the states and their derivatives, and the fourth argument +specifies a vector of output times at which the solution is desired, +including the time corresponding to the initial condition. + +The set of initial states and derivatives are not strictly required to +be consistent. In practice, however, @sc{dassl} is not very good at +determining a consistent set for you, so it is best if you ensure that +the initial values result in the function evaluating to zero. + +The fifth argument is optional, and may be used to specify a set of +times that the DAE solver should not integrate past. It is useful for +avoiding difficulties with singularities and points where there is a +discontinuity in the derivative. + +After a successful computation, the value of @var{istate} will be +greater than zero (consistent with the Fortran version of @sc{dassl}). + +If the computation is not successful, the value of @var{istate} will be +less than zero and @var{msg} will contain additional information. + +You can use the function @code{dassl_options} to set optional +parameters for @code{dassl}. +@seealso{daspk, dasrt, lsode} +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/data.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/data.cc Tue Jun 21 16:07:51 2016 -0400 @@ -76,27 +76,27 @@ } DEFUN (all, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} all (@var{x})\n\ -@deftypefnx {} {} all (@var{x}, @var{dim})\n\ -For a vector argument, return true (logical 1) if all elements of the vector\n\ -are nonzero.\n\ -\n\ -For a matrix argument, return a row vector of logical ones and\n\ -zeros with each element indicating whether all of the elements of the\n\ -corresponding column of the matrix are nonzero. For example:\n\ -\n\ -@example\n\ -@group\n\ -all ([2, 3; 1, 0])\n\ - @result{} [ 1, 0 ]\n\ -@end group\n\ -@end example\n\ -\n\ -If the optional argument @var{dim} is supplied, work along dimension\n\ -@var{dim}.\n\ -@seealso{any}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} all (@var{x}) +@deftypefnx {} {} all (@var{x}, @var{dim}) +For a vector argument, return true (logical 1) if all elements of the vector +are nonzero. + +For a matrix argument, return a row vector of logical ones and +zeros with each element indicating whether all of the elements of the +corresponding column of the matrix are nonzero. For example: + +@example +@group +all ([2, 3; 1, 0]) + @result{} [ 1, 0 ] +@end group +@end example + +If the optional argument @var{dim} is supplied, work along dimension +@var{dim}. +@seealso{any} +@end deftypefn */) { int nargin = args.length (); @@ -134,34 +134,34 @@ */ DEFUN (any, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} any (@var{x})\n\ -@deftypefnx {} {} any (@var{x}, @var{dim})\n\ -For a vector argument, return true (logical 1) if any element of the vector\n\ -is nonzero.\n\ -\n\ -For a matrix argument, return a row vector of logical ones and\n\ -zeros with each element indicating whether any of the elements of the\n\ -corresponding column of the matrix are nonzero. For example:\n\ -\n\ -@example\n\ -@group\n\ -any (eye (2, 4))\n\ - @result{} [ 1, 1, 0, 0 ]\n\ -@end group\n\ -@end example\n\ -\n\ -If the optional argument @var{dim} is supplied, work along dimension\n\ -@var{dim}. For example:\n\ -\n\ -@example\n\ -@group\n\ -any (eye (2, 4), 2)\n\ - @result{} [ 1; 1 ]\n\ -@end group\n\ -@end example\n\ -@seealso{all}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} any (@var{x}) +@deftypefnx {} {} any (@var{x}, @var{dim}) +For a vector argument, return true (logical 1) if any element of the vector +is nonzero. + +For a matrix argument, return a row vector of logical ones and +zeros with each element indicating whether any of the elements of the +corresponding column of the matrix are nonzero. For example: + +@example +@group +any (eye (2, 4)) + @result{} [ 1, 1, 0, 0 ] +@end group +@end example + +If the optional argument @var{dim} is supplied, work along dimension +@var{dim}. For example: + +@example +@group +any (eye (2, 4), 2) + @result{} [ 1; 1 ] +@end group +@end example +@seealso{all} +@end deftypefn */) { int nargin = args.length (); @@ -201,18 +201,18 @@ // These mapping functions may also be useful in other places, eh? DEFUN (atan2, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} atan2 (@var{y}, @var{x})\n\ -Compute atan (@var{y} / @var{x}) for corresponding elements of @var{y}\n\ -and @var{x}.\n\ -\n\ -@var{y} and @var{x} must match in size and orientation. The signs of\n\ -elements of @var{y} and @var{x} are used to determine the quadrats of each\n\ -resulting value.\n\ -\n\ -This function is equivalent to @code{arg (complex (@var{x}, @var{y}))}.\n\ -@seealso{tan, tand, tanh, atanh}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} 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 quadrats 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 (); @@ -372,26 +372,26 @@ } DEFUN (hypot, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} hypot (@var{x}, @var{y})\n\ -@deftypefnx {} {} hypot (@var{x}, @var{y}, @var{z}, @dots{})\n\ -Compute the element-by-element square root of the sum of the squares of\n\ -@var{x} and @var{y}.\n\ -\n\ -This is equivalent to\n\ -@code{sqrt (@var{x}.^2 + @var{y}.^2)}, but is calculated in a manner that\n\ -avoids overflows for large values of @var{x} or @var{y}.\n\ -\n\ -@code{hypot} can also be called with more than 2 arguments; in this case,\n\ -the arguments are accumulated from left to right:\n\ -\n\ -@example\n\ -@group\n\ -hypot (hypot (@var{x}, @var{y}), @var{z})\n\ -hypot (hypot (hypot (@var{x}, @var{y}), @var{z}), @var{w}), etc.\n\ -@end group\n\ -@end example\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} hypot (@var{x}, @var{y}) +@deftypefnx {} {} 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 (); @@ -467,28 +467,28 @@ } DEFUN (log2, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} log2 (@var{x})\n\ -@deftypefnx {} {[@var{f}, @var{e}] =} log2 (@var{x})\n\ -Compute the base-2 logarithm of each element of @var{x}.\n\ -\n\ -If called with two output arguments, split @var{x} into\n\ -binary mantissa and exponent so that\n\ -@tex\n\ -${1 \\over 2} \\le \\left| f \\right| < 1$\n\ -@end tex\n\ -@ifnottex\n\ -@w{@code{1/2 <= abs(f) < 1}}\n\ -@end ifnottex\n\ -and @var{e} is an integer. If\n\ -@tex\n\ -$x = 0$, $f = e = 0$.\n\ -@end tex\n\ -@ifnottex\n\ -@w{@code{x = 0}}, @w{@code{f = e = 0}}.\n\ -@end ifnottex\n\ -@seealso{pow2, log, log10, exp}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} 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 two output arguments, split @var{x} into +binary mantissa and exponent so that +@tex +${1 \over 2} \le \left| f \right| < 1$ +@end tex +@ifnottex +@w{@code{1/2 <= abs(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 (); @@ -564,39 +564,39 @@ */ DEFUN (rem, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} rem (@var{x}, @var{y})\n\ -Return the remainder of the division @code{@var{x} / @var{y}}.\n\ -\n\ -The remainder is computed using the expression\n\ -\n\ -@example\n\ -x - y .* fix (x ./ y)\n\ -@end example\n\ -\n\ -An error message is printed if the dimensions of the arguments do not agree,\n\ -or if either argument is complex.\n\ -\n\ -Programming Notes: Floating point numbers within a few eps of an integer\n\ -will be rounded to an integer before computation for compatibility with\n\ -@sc{matlab}.\n\ -\n\ -By convention,\n\ -\n\ -@example\n\ -@group\n\ -rem (@var{x}, 0) = NaN if @var{x} is a floating point variable\n\ -rem (@var{x}, 0) = 0 if @var{x} is an integer variable\n\ -rem (@var{x}, @var{y}) returns a value with the signbit from @var{x}\n\ -@end group\n\ -@end example\n\ -\n\ -For the opposite conventions see the @code{mod} function. In general,\n\ -@code{rem} is best when computing the remainder after division of two\n\ -@emph{positive} numbers. For negative numbers, or when the values are\n\ -periodic, @code{mod} is a better choice.\n\ -@seealso{mod}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} 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: Floating point numbers within a few eps of an integer +will be rounded to an integer before computation for compatibility with +@sc{matlab}. + +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 (); @@ -742,42 +742,42 @@ */ DEFUN (mod, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} mod (@var{x}, @var{y})\n\ -Compute the modulo of @var{x} and @var{y}.\n\ -\n\ -Conceptually this is given by\n\ -\n\ -@example\n\ -x - y .* floor (x ./ y)\n\ -@end example\n\ -\n\ -@noindent\n\ -and is written such that the correct modulus is returned for integer types.\n\ -This function handles negative values correctly. That is,\n\ -@w{@code{mod (-1, 3)}} is 2, not -1, as @w{@code{rem (-1, 3)}} returns.\n\ -\n\ -An error results if the dimensions of the arguments do not agree, or if\n\ -either of the arguments is complex.\n\ -\n\ -Programming Notes: Floating point numbers within a few eps of an integer\n\ -will be rounded to an integer before computation for compatibility with\n\ -@sc{matlab}.\n\ -\n\ -By convention,\n\ -\n\ -@example\n\ -@group\n\ -mod (@var{x}, 0) = @var{x}\n\ -mod (@var{x}, @var{y}) returns a value with the signbit from @var{y}\n\ -@end group\n\ -@end example\n\ -\n\ -For the opposite conventions see the @code{rem} function. In general,\n\ -@code{mod} is a better choice than @code{rem} when any of the inputs are\n\ -negative numbers or when the values are periodic.\n\ -@seealso{rem}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} 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: Floating point numbers within a few eps of an integer +will be rounded to an integer before computation for compatibility with +@sc{matlab}. + +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 (); @@ -1134,24 +1134,24 @@ return retval DEFUN (cumprod, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} cumprod (@var{x})\n\ -@deftypefnx {} {} cumprod (@var{x}, @var{dim})\n\ -Cumulative product of elements along dimension @var{dim}.\n\ -\n\ -If @var{dim} is omitted, it defaults to the first non-singleton dimension.\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -cumprod ([1, 2; 3, 4; 5, 6])\n\ - @result{} 1 2\n\ - 3 8\n\ - 15 48\n\ -@end group\n\ -@end example\n\ -@seealso{prod, cumsum}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} cumprod (@var{x}) +@deftypefnx {} {} cumprod (@var{x}, @var{dim}) +Cumulative product of elements along dimension @var{dim}. + +If @var{dim} is omitted, it defaults to the first non-singleton dimension. +For example: + +@example +@group +cumprod ([1, 2; 3, 4; 5, 6]) + @result{} 1 2 + 3 8 + 15 48 +@end group +@end example +@seealso{prod, cumsum} +@end deftypefn */) { DATA_REDUCTION (cumprod); } @@ -1177,30 +1177,30 @@ */ DEFUN (cumsum, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} cumsum (@var{x})\n\ -@deftypefnx {} {} cumsum (@var{x}, @var{dim})\n\ -@deftypefnx {} {} cumsum (@dots{}, \"native\")\n\ -@deftypefnx {} {} cumsum (@dots{}, \"double\")\n\ -@deftypefnx {} {} cumsum (@dots{}, \"extra\")\n\ -Cumulative sum of elements along dimension @var{dim}.\n\ -\n\ -If @var{dim} is omitted, it defaults to the first non-singleton dimension.\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -cumsum ([1, 2; 3, 4; 5, 6])\n\ - @result{} 1 2\n\ - 4 6\n\ - 9 12\n\ -@end group\n\ -@end example\n\ -\n\ -See @code{sum} for an explanation of the optional parameters\n\ -@qcode{\"native\"}, @qcode{\"double\"}, and @qcode{\"extra\"}.\n\ -@seealso{sum, cumprod}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} cumsum (@var{x}) +@deftypefnx {} {} cumsum (@var{x}, @var{dim}) +@deftypefnx {} {} cumsum (@dots{}, "native") +@deftypefnx {} {} cumsum (@dots{}, "double") +@deftypefnx {} {} cumsum (@dots{}, "extra") +Cumulative sum of elements along dimension @var{dim}. + +If @var{dim} is omitted, it defaults to the first non-singleton dimension. +For example: + +@example +@group +cumsum ([1, 2; 3, 4; 5, 6]) + @result{} 1 2 + 4 6 + 9 12 +@end group +@end example + +See @code{sum} for an explanation of the optional parameters +@qcode{"native"}, @qcode{"double"}, and @qcode{"extra"}. +@seealso{sum, cumprod} +@end deftypefn */) { int nargin = args.length (); @@ -1328,37 +1328,37 @@ */ DEFUN (diag, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{M} =} diag (@var{v})\n\ -@deftypefnx {} {@var{M} =} diag (@var{v}, @var{k})\n\ -@deftypefnx {} {@var{M} =} diag (@var{v}, @var{m}, @var{n})\n\ -@deftypefnx {} {@var{v} =} diag (@var{M})\n\ -@deftypefnx {} {@var{v} =} diag (@var{M}, @var{k})\n\ -Return a diagonal matrix with vector @var{v} on diagonal @var{k}.\n\ -\n\ -The second argument is optional. If it is positive, the vector is placed on\n\ -the @var{k}-th superdiagonal. If it is negative, it is placed on the\n\ -@var{-k}-th subdiagonal. The default value of @var{k} is 0, and the vector\n\ -is placed on the main diagonal. For example:\n\ -\n\ -@example\n\ -@group\n\ -diag ([1, 2, 3], 1)\n\ - @result{} 0 1 0 0\n\ - 0 0 2 0\n\ - 0 0 0 3\n\ - 0 0 0 0\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -The 3-input form returns a diagonal matrix with vector @var{v} on the main\n\ -diagonal and the resulting matrix being of size @var{m} rows x @var{n}\n\ -columns.\n\ -\n\ -Given a matrix argument, instead of a vector, @code{diag} extracts the\n\ -@var{k}-th diagonal of the matrix.\n\ -@end deftypefn") + 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) + @result{} 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 (); @@ -1458,35 +1458,35 @@ */ DEFUN (prod, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} prod (@var{x})\n\ -@deftypefnx {} {} prod (@var{x}, @var{dim})\n\ -@deftypefnx {} {} prod (@dots{}, \"native\")\n\ -@deftypefnx {} {} prod (@dots{}, \"double\")\n\ -Product of elements along dimension @var{dim}.\n\ -\n\ -If @var{dim} is omitted, it defaults to the first non-singleton dimension.\n\ -\n\ -The optional @qcode{\"type\"} input determines the class of the variable\n\ -used for calculations. If the argument @qcode{\"native\"} is given, then\n\ -the operation is performed in the same type as the original argument, rather\n\ -than the default double type.\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -prod ([true, true])\n\ - @result{} 1\n\ -prod ([true, true], \"native\")\n\ - @result{} true\n\ -@end group\n\ -@end example\n\ -\n\ -On the contrary, if @qcode{\"double\"} is given, the operation is performed\n\ -in double precision even for single precision inputs.\n\ -@seealso{cumprod, sum}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} prod (@var{x}) +@deftypefnx {} {} prod (@var{x}, @var{dim}) +@deftypefnx {} {} prod (@dots{}, "native") +@deftypefnx {} {} prod (@dots{}, "double") +Product of elements along dimension @var{dim}. + +If @var{dim} is omitted, it defaults to the first non-singleton dimension. + +The optional @qcode{"type"} input determines the class of the variable +used for calculations. If the argument @qcode{"native"} is given, then +the operation is performed in the same type as the original argument, rather +than the default double type. + +For example: + +@example +@group +prod ([true, true]) + @result{} 1 +prod ([true, true], "native") + @result{} true +@end group +@end example + +On the contrary, if @qcode{"double"} is given, the operation is performed +in double precision even for single precision inputs. +@seealso{cumprod, sum} +@end deftypefn */) { int nargin = args.length (); @@ -2118,19 +2118,19 @@ } DEFUN (horzcat, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} horzcat (@var{array1}, @var{array2}, @dots{}, @var{arrayN})\n\ -Return the horizontal concatenation of N-D array objects, @var{array1},\n\ -@var{array2}, @dots{}, @var{arrayN} along dimension 2.\n\ -\n\ -Arrays may also be concatenated horizontally using the syntax for creating\n\ -new matrices. For example:\n\ -\n\ -@example\n\ -@var{hcat} = [ @var{array1}, @var{array2}, @dots{} ]\n\ -@end example\n\ -@seealso{cat, vertcat}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} 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{hcat} = [ @var{array1}, @var{array2}, @dots{} ] +@end example +@seealso{cat, vertcat} +@end deftypefn */) { return do_cat (args, -2, "horzcat"); } @@ -2354,19 +2354,19 @@ */ DEFUN (vertcat, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} vertcat (@var{array1}, @var{array2}, @dots{}, @var{arrayN})\n\ -Return the vertical concatenation of N-D array objects, @var{array1},\n\ -@var{array2}, @dots{}, @var{arrayN} along dimension 1.\n\ -\n\ -Arrays may also be concatenated vertically using the syntax for creating\n\ -new matrices. For example:\n\ -\n\ -@example\n\ -@var{vcat} = [ @var{array1}; @var{array2}; @dots{} ]\n\ -@end example\n\ -@seealso{cat, horzcat}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} 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{vcat} = [ @var{array1}; @var{array2}; @dots{} ] +@end example +@seealso{cat, horzcat} +@end deftypefn */) { return do_cat (args, -1, "vertcat"); } @@ -2378,50 +2378,50 @@ */ DEFUN (cat, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} cat (@var{dim}, @var{array1}, @var{array2}, @dots{}, @var{arrayN})\n\ -Return the concatenation of N-D array objects, @var{array1},\n\ -@var{array2}, @dots{}, @var{arrayN} along dimension @var{dim}.\n\ -\n\ -@example\n\ -@group\n\ -A = ones (2, 2);\n\ -B = zeros (2, 2);\n\ -cat (2, A, B)\n\ - @result{} 1 1 0 0\n\ - 1 1 0 0\n\ -@end group\n\ -@end example\n\ -\n\ -Alternatively, we can concatenate @var{A} and @var{B} along the\n\ -second dimension in the following way:\n\ -\n\ -@example\n\ -@group\n\ -[A, B]\n\ -@end group\n\ -@end example\n\ -\n\ -@var{dim} can be larger than the dimensions of the N-D array objects\n\ -and the result will thus have @var{dim} dimensions as the\n\ -following example shows:\n\ -\n\ -@example\n\ -@group\n\ -cat (4, ones (2, 2), zeros (2, 2))\n\ - @result{} ans(:,:,1,1) =\n\ -\n\ - 1 1\n\ - 1 1\n\ -\n\ - ans(:,:,1,2) =\n\ -\n\ - 0 0\n\ - 0 0\n\ -@end group\n\ -@end example\n\ -@seealso{horzcat, vertcat}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} 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) + @result{} 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)) + @result{} 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 (); @@ -2595,68 +2595,68 @@ } DEFUN (permute, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} permute (@var{A}, @var{perm})\n\ -Return the generalized transpose for an N-D array object @var{A}.\n\ -\n\ -The permutation vector @var{perm} must contain the elements\n\ -@w{@code{1:ndims (A)}} (in any order, but each element must appear only\n\ -once). The @var{N}th dimension of @var{A} gets remapped to dimension\n\ -@code{@var{PERM}(@var{N})}. For example:\n\ -\n\ -@example\n\ -@group\n\ -@var{x} = zeros ([2, 3, 5, 7]);\n\ -size (@var{x})\n\ - @result{} 2 3 5 7\n\ -\n\ -size (permute (@var{x}, [2, 1, 3, 4]))\n\ - @result{} 3 2 5 7\n\ -\n\ -size (permute (@var{x}, [1, 3, 4, 2]))\n\ - @result{} 2 5 7 3\n\ -\n\ -## The identity permutation\n\ -size (permute (@var{x}, [1, 2, 3, 4]))\n\ - @result{} 2 3 5 7\n\ -@end group\n\ -@end example\n\ -@seealso{ipermute}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} 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}) + @result{} 2 3 5 7 + +size (permute (@var{x}, [2, 1, 3, 4])) + @result{} 3 2 5 7 + +size (permute (@var{x}, [1, 3, 4, 2])) + @result{} 2 5 7 3 + +## The identity permutation +size (permute (@var{x}, [1, 2, 3, 4])) + @result{} 2 3 5 7 +@end group +@end example +@seealso{ipermute} +@end deftypefn */) { return do_permute (args, false); } DEFUN (ipermute, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} ipermute (@var{A}, @var{iperm})\n\ -The inverse of the @code{permute} function.\n\ -\n\ -The expression\n\ -\n\ -@example\n\ -ipermute (permute (A, perm), perm)\n\ -@end example\n\ -\n\ -@noindent\n\ -returns the original array @var{A}.\n\ -@seealso{permute}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} ipermute (@var{A}, @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, , - "-*- texinfo -*-\n\ -@deftypefn {} {} length (@var{a})\n\ -Return the length of the object @var{a}.\n\ -\n\ -The length is 0 for empty objects, 1 for scalars, and the number of elements\n\ -for vectors. For matrix or N-dimensional objects, the length is the number\n\ -of elements along the largest dimension\n\ -(equivalent to @w{@code{max (size (@var{a}))}}).\n\ -@seealso{numel, size}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} 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 (); @@ -2665,21 +2665,21 @@ } DEFUN (ndims, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} ndims (@var{a})\n\ -Return the number of dimensions of @var{a}.\n\ -\n\ -For any array, the result will always be greater than or equal to 2.\n\ -Trailing singleton dimensions are not counted.\n\ -\n\ -@example\n\ -@group\n\ -ndims (ones (4, 1, 2, 1))\n\ - @result{} 3\n\ -@end group\n\ -@end example\n\ -@seealso{size}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} 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. + +@example +@group +ndims (ones (4, 1, 2, 1)) + @result{} 3 +@end group +@end example +@seealso{size} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -2688,47 +2688,47 @@ } DEFUN (numel, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} numel (@var{a})\n\ -@deftypefnx {} {} numel (@var{a}, @var{idx1}, @var{idx2}, @dots{})\n\ -Return the number of elements in the object @var{a}.\n\ -\n\ -Optionally, if indices @var{idx1}, @var{idx2}, @dots{} are supplied,\n\ -return the number of elements that would result from the indexing\n\ -\n\ -@example\n\ -@var{a}(@var{idx1}, @var{idx2}, @dots{})\n\ -@end example\n\ -\n\ -Note that the indices do not have to be scalar numbers. For example,\n\ -\n\ -@example\n\ -@group\n\ -@var{a} = 1;\n\ -@var{b} = ones (2, 3);\n\ -numel (@var{a}, @var{b})\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -will return 6, as this is the number of ways to index with @var{b}.\n\ -Or the index could be the string @qcode{\":\"} which represents the colon\n\ -operator. For example,\n\ -\n\ -@example\n\ -@group\n\ -@var{a} = ones (5, 3);\n\ -numel (@var{a}, 2, \":\")\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -will return 3 as the second row has three column entries.\n\ -\n\ -This method is also called when an object appears as lvalue with cs-list\n\ -indexing, i.e., @code{object@{@dots{}@}} or @code{object(@dots{}).field}.\n\ -@seealso{size}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} numel (@var{a}) +@deftypefnx {} {} 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} +@end deftypefn */) { int nargin = args.length (); @@ -2750,41 +2750,41 @@ } DEFUN (size, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} size (@var{a})\n\ -@deftypefnx {} {} size (@var{a}, @var{dim})\n\ -Return the number of rows and columns of @var{a}.\n\ -\n\ -With one input argument and one output argument, the result is returned\n\ -in a row vector. If there are multiple output arguments, the number of\n\ -rows is assigned to the first, and the number of columns to the second,\n\ -etc. For example:\n\ -\n\ -@example\n\ -@group\n\ -size ([1, 2; 3, 4; 5, 6])\n\ - @result{} [ 3, 2 ]\n\ -\n\ -[nr, nc] = size ([1, 2; 3, 4; 5, 6])\n\ - @result{} nr = 3\n\ - @result{} nc = 2\n\ -@end group\n\ -@end example\n\ -\n\ -If given a second argument, @code{size} will return the size of the\n\ -corresponding dimension. For example,\n\ -\n\ -@example\n\ -@group\n\ -size ([1, 2; 3, 4; 5, 6], 2)\n\ - @result{} 2\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -returns the number of columns in the given matrix.\n\ -@seealso{numel, ndims, length, rows, columns}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} size (@var{a}) +@deftypefnx {} {} size (@var{a}, @var{dim}) +Return the number of rows and columns of @var{a}. + +With one input argument and one output argument, the result is returned +in a row vector. If there are multiple output arguments, the number of +rows is assigned to the first, and the number of columns to the second, +etc. For example: + +@example +@group +size ([1, 2; 3, 4; 5, 6]) + @result{} [ 3, 2 ] + +[nr, nc] = size ([1, 2; 3, 4; 5, 6]) + @result{} nr = 3 + @result{} nc = 2 +@end group +@end example + +If given a second argument, @code{size} will return the size of the +corresponding dimension. For example, + +@example +@group +size ([1, 2; 3, 4; 5, 6], 2) + @result{} 2 +@end group +@end example + +@noindent +returns the number of columns in the given matrix. +@seealso{numel, ndims, length, rows, columns} +@end deftypefn */) { octave_value_list retval; @@ -2834,14 +2834,14 @@ } DEFUN (size_equal, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} size_equal (@var{a}, @var{b}, @dots{})\n\ -Return true if the dimensions of all arguments agree.\n\ -\n\ -Trailing singleton dimensions are ignored.\n\ -When called with a single or no argument @code{size_equal} returns true.\n\ -@seealso{size, numel, ndims}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} 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 or no argument @code{size_equal} returns true. +@seealso{size, numel, ndims} +@end deftypefn */) { int nargin = args.length (); @@ -2862,11 +2862,11 @@ } DEFUN (nnz, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{n} =} nnz (@var{a})\n\ -Return the number of nonzero elements in @var{a}.\n\ -@seealso{nzmax, nonzeros, find}\n\ -@end deftypefn") + 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 (); @@ -2875,15 +2875,15 @@ } DEFUN (nzmax, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{n} =} nzmax (@var{SM})\n\ -Return the amount of storage allocated to the sparse matrix @var{SM}.\n\ -\n\ -Note that Octave tends to crop unused memory at the first opportunity\n\ -for sparse objects. Thus, in general the value of @code{nzmax} will be the\n\ -same as @code{nnz} except for some cases of user-created sparse objects.\n\ -@seealso{nnz, spalloc, sparse}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{n} =} nzmax (@var{SM}) +Return the amount of storage allocated to the sparse matrix @var{SM}. + +Note that 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. +@seealso{nnz, spalloc, sparse} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -2892,11 +2892,11 @@ } DEFUN (rows, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} rows (@var{a})\n\ -Return the number of rows of @var{a}.\n\ -@seealso{columns, size, length, numel, isscalar, isvector, ismatrix}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} rows (@var{a}) +Return the number of rows of @var{a}. +@seealso{columns, size, length, numel, isscalar, isvector, ismatrix} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -2932,11 +2932,11 @@ */ DEFUN (columns, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} columns (@var{a})\n\ -Return the number of columns of @var{a}.\n\ -@seealso{rows, size, length, numel, isscalar, isvector, ismatrix}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} columns (@var{a}) +Return the number of columns of @var{a}. +@seealso{rows, size, length, numel, isscalar, isvector, ismatrix} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -2945,41 +2945,41 @@ } DEFUN (sum, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} sum (@var{x})\n\ -@deftypefnx {} {} sum (@var{x}, @var{dim})\n\ -@deftypefnx {} {} sum (@dots{}, \"native\")\n\ -@deftypefnx {} {} sum (@dots{}, \"double\")\n\ -@deftypefnx {} {} sum (@dots{}, \"extra\")\n\ -Sum of elements along dimension @var{dim}.\n\ -\n\ -If @var{dim} is omitted, it defaults to the first non-singleton dimension.\n\ -\n\ -The optional @qcode{\"type\"} input determines the class of the variable\n\ -used for calculations. If the argument @qcode{\"native\"} is given, then\n\ -the operation is performed in the same type as the original argument, rather\n\ -than the default double type.\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -sum ([true, true])\n\ - @result{} 2\n\ -sum ([true, true], \"native\")\n\ - @result{} true\n\ -@end group\n\ -@end example\n\ -\n\ -On the contrary, if @qcode{\"double\"} is given, the sum is performed in\n\ -double precision even for single precision inputs.\n\ -\n\ -For double precision inputs, the @qcode{\"extra\"} option will use a more\n\ -accurate algorithm than straightforward summation. For single precision\n\ -inputs, @qcode{\"extra\"} is the same as @qcode{\"double\"}. Otherwise,\n\ -@qcode{\"extra\"} has no effect.\n\ -@seealso{cumsum, sumsq, prod}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} sum (@var{x}) +@deftypefnx {} {} sum (@var{x}, @var{dim}) +@deftypefnx {} {} sum (@dots{}, "native") +@deftypefnx {} {} sum (@dots{}, "double") +@deftypefnx {} {} sum (@dots{}, "extra") +Sum of elements along dimension @var{dim}. + +If @var{dim} is omitted, it defaults to the first non-singleton dimension. + +The optional @qcode{"type"} input determines the class of the variable +used for calculations. If the argument @qcode{"native"} is given, then +the operation is performed in the same type as the original argument, rather +than the default double type. + +For example: + +@example +@group +sum ([true, true]) + @result{} 2 +sum ([true, true], "native") + @result{} true +@end group +@end example + +On the contrary, if @qcode{"double"} is given, the sum is performed in +double precision even for single precision inputs. + +For double precision inputs, the @qcode{"extra"} option will use a more +accurate algorithm than straightforward summation. For single precision +inputs, @qcode{"extra"} is the same as @qcode{"double"}. Otherwise, +@qcode{"extra"} has no effect. +@seealso{cumsum, sumsq, prod} +@end deftypefn */) { int nargin = args.length (); @@ -3173,23 +3173,23 @@ */ DEFUN (sumsq, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} sumsq (@var{x})\n\ -@deftypefnx {} {} sumsq (@var{x}, @var{dim})\n\ -Sum of squares of elements along dimension @var{dim}.\n\ -\n\ -If @var{dim} is omitted, it defaults to the first non-singleton dimension.\n\ -\n\ -This function is conceptually equivalent to computing\n\ -\n\ -@example\n\ -sum (x .* conj (x), dim)\n\ -@end example\n\ -\n\ -@noindent\n\ -but it uses less memory and avoids calling @code{conj} if @var{x} is real.\n\ -@seealso{sum, prod}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} sumsq (@var{x}) +@deftypefnx {} {} sumsq (@var{x}, @var{dim}) +Sum of squares of elements along dimension @var{dim}. + +If @var{dim} is omitted, it defaults to the first non-singleton dimension. + +This function is conceptually equivalent to computing + +@example +sum (x .* conj (x), dim) +@end example + +@noindent +but it uses less memory and avoids calling @code{conj} if @var{x} is real. +@seealso{sum, prod} +@end deftypefn */) { DATA_REDUCTION (sumsq); } @@ -3213,12 +3213,12 @@ */ DEFUN (islogical, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} islogical (@var{x})\n\ -@deftypefnx {} {} isbool (@var{x})\n\ -Return true if @var{x} is a logical object.\n\ -@seealso{isfloat, isinteger, ischar, isnumeric, isa}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} islogical (@var{x}) +@deftypefnx {} {} isbool (@var{x}) +Return true if @var{x} is a logical object. +@seealso{isfloat, isinteger, ischar, isnumeric, isa} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -3243,14 +3243,14 @@ */ DEFUN (isinteger, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isinteger (@var{x})\n\ -Return true if @var{x} is an integer object (int8, uint8, int16, etc.).\n\ -\n\ -Note that @w{@code{isinteger (14)}} is false because numeric constants in\n\ -Octave are double precision floating point values.\n\ -@seealso{isfloat, ischar, islogical, isnumeric, isa}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} 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, isnumeric, isa} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -3259,11 +3259,11 @@ } DEFUN (iscomplex, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} iscomplex (@var{x})\n\ -Return true if @var{x} is a complex-valued numeric object.\n\ -@seealso{isreal, isnumeric, islogical, ischar, isfloat, isa}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} iscomplex (@var{x}) +Return true if @var{x} is a complex-valued numeric object. +@seealso{isreal, isnumeric, islogical, ischar, isfloat, isa} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -3272,13 +3272,13 @@ } DEFUN (isfloat, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isfloat (@var{x})\n\ -Return true if @var{x} is a floating-point numeric object.\n\ -\n\ -Objects of class double or single are floating-point objects.\n\ -@seealso{isinteger, ischar, islogical, isnumeric, isa}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} 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, isa} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -3290,28 +3290,28 @@ // octave_value member function? DEFUN (complex, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} complex (@var{x})\n\ -@deftypefnx {} {} complex (@var{re}, @var{im})\n\ -Return a complex value from real arguments.\n\ -\n\ -With 1 real argument @var{x}, return the complex result\n\ -@w{@code{@var{x} + 0i}}.\n\ -\n\ -With 2 real arguments, return the complex result\n\ -@w{@code{@var{re} + @var{im}}}.\n\ -@code{complex} can often be more convenient than expressions such as\n\ -@w{@code{a + i*b}}.\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -complex ([1, 2], [3, 4])\n\ - @result{} [ 1 + 3i 2 + 4i ]\n\ -@end group\n\ -@end example\n\ -@seealso{real, imag, iscomplex, abs, arg}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} complex (@var{x}) +@deftypefnx {} {} 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}}}. +@code{complex} can often be more convenient than expressions such as +@w{@code{a + i*b}}. +For example: + +@example +@group +complex ([1, 2], [3, 4]) + @result{} [ 1 + 3i 2 + 4i ] +@end group +@end example +@seealso{real, imag, iscomplex, abs, arg} +@end deftypefn */) { int nargin = args.length (); @@ -3554,14 +3554,14 @@ } DEFUN (isreal, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isreal (@var{x})\n\ -Return true if @var{x} is a non-complex matrix or scalar.\n\ -\n\ -For compatibility with @sc{matlab}, this includes logical and character\n\ -matrices.\n\ -@seealso{iscomplex, isnumeric, isa}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} 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 (); @@ -3570,12 +3570,12 @@ } DEFUN (isempty, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isempty (@var{a})\n\ -Return true if @var{a} is an empty matrix (any one of its dimensions is\n\ -zero).\n\ -@seealso{isnull, isa}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isempty (@var{a}) +Return true if @var{a} is an empty matrix (any one of its dimensions is +zero). +@seealso{isnull, isa} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -3589,14 +3589,14 @@ */ DEFUN (isnumeric, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isnumeric (@var{x})\n\ -Return true if @var{x} is a numeric object, i.e., an integer, real, or\n\ -complex array.\n\ -\n\ -Logical and character arrays are not considered to be numeric.\n\ -@seealso{isinteger, isfloat, isreal, iscomplex, islogical, ischar, iscell, isstruct, isa}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} 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, islogical, ischar, iscell, isstruct, isa} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -3621,11 +3621,11 @@ */ DEFUN (isscalar, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isscalar (@var{x})\n\ -Return true if @var{x} is a scalar.\n\ -@seealso{isvector, ismatrix}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isscalar (@var{x}) +Return true if @var{x} is a scalar. +@seealso{isvector, ismatrix} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -3653,14 +3653,14 @@ */ DEFUN (isvector, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isvector (@var{x})\n\ -Return true if @var{x} is a vector.\n\ -\n\ -A vector is a 2-D array where one of the dimensions is equal to 1. As a\n\ -consequence a 1x1 array, or scalar, is also a vector.\n\ -@seealso{isscalar, ismatrix, size, rows, columns, length}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isvector (@var{x}) +Return true if @var{x} is a vector. + +A vector is a 2-D array where one of the dimensions is equal to 1. As a +consequence a 1x1 array, or scalar, is also a vector. +@seealso{isscalar, ismatrix, size, rows, columns, length} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -3691,11 +3691,11 @@ */ DEFUN (isrow, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isrow (@var{x})\n\ -Return true if @var{x} is a row vector 1xN with non-negative N.\n\ -@seealso{iscolumn, isscalar, isvector, ismatrix}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isrow (@var{x}) +Return true if @var{x} is a row vector 1xN with non-negative N. +@seealso{iscolumn, isscalar, isvector, ismatrix} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -3736,11 +3736,11 @@ */ DEFUN (iscolumn, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} iscolumn (@var{x})\n\ -Return true if @var{x} is a column vector Nx1 with non-negative N.\n\ -@seealso{isrow, isscalar, isvector, ismatrix}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} iscolumn (@var{x}) +Return true if @var{x} is a column vector Nx1 with non-negative N. +@seealso{isrow, isscalar, isvector, ismatrix} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -3780,11 +3780,11 @@ */ DEFUN (ismatrix, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} ismatrix (@var{a})\n\ -Return true if @var{a} is a 2-D array.\n\ -@seealso{isscalar, isvector, iscell, isstruct, issparse, isa}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} ismatrix (@var{a}) +Return true if @var{a} is a 2-D array. +@seealso{isscalar, isvector, iscell, isstruct, issparse, isa} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -3823,11 +3823,11 @@ */ DEFUN (issquare, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} issquare (@var{x})\n\ -Return true if @var{x} is a square matrix.\n\ -@seealso{isscalar, isvector, ismatrix, size}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} issquare (@var{x}) +Return true if @var{x} is a square matrix. +@seealso{isscalar, isvector, ismatrix, size} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -4204,35 +4204,35 @@ } DEFUN (ones, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} ones (@var{n})\n\ -@deftypefnx {} {} ones (@var{m}, @var{n})\n\ -@deftypefnx {} {} ones (@var{m}, @var{n}, @var{k}, @dots{})\n\ -@deftypefnx {} {} ones ([@var{m} @var{n} @dots{}])\n\ -@deftypefnx {} {} ones (@dots{}, @var{class})\n\ -Return a matrix or N-dimensional array whose elements are all 1.\n\ -\n\ -If invoked with a single scalar integer argument @var{n}, return a square\n\ -@nospell{NxN} matrix.\n\ -\n\ -If invoked with two or more scalar integer arguments, or a vector of integer\n\ -values, return an array with the given dimensions.\n\ -\n\ -To create a constant matrix whose values are all the same use an expression\n\ -such as\n\ -\n\ -@example\n\ -val_matrix = val * ones (m, n)\n\ -@end example\n\ -\n\ -The optional argument @var{class} specifies the class of the return array\n\ -and defaults to double. For example:\n\ -\n\ -@example\n\ -val = ones (m,n, \"uint8\")\n\ -@end example\n\ -@seealso{zeros}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} ones (@var{n}) +@deftypefnx {} {} ones (@var{m}, @var{n}) +@deftypefnx {} {} ones (@var{m}, @var{n}, @var{k}, @dots{}) +@deftypefnx {} {} ones ([@var{m} @var{n} @dots{}]) +@deftypefnx {} {} ones (@dots{}, @var{class}) +Return a matrix or N-dimensional array whose elements are all 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. + +To create a constant matrix whose values are all the same use an expression +such as + +@example +val_matrix = val * ones (m, n) +@end example + +The optional argument @var{class} specifies the class of the return array +and defaults to double. For example: + +@example +val = ones (m,n, "uint8") +@end example +@seealso{zeros} +@end deftypefn */) { return fill_matrix (args, 1, "ones"); } @@ -4272,28 +4272,28 @@ */ DEFUN (zeros, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} zeros (@var{n})\n\ -@deftypefnx {} {} zeros (@var{m}, @var{n})\n\ -@deftypefnx {} {} zeros (@var{m}, @var{n}, @var{k}, @dots{})\n\ -@deftypefnx {} {} zeros ([@var{m} @var{n} @dots{}])\n\ -@deftypefnx {} {} zeros (@dots{}, @var{class})\n\ -Return a matrix or N-dimensional array whose elements are all 0.\n\ -\n\ -If invoked with a single scalar integer argument, return a square\n\ -@nospell{NxN} matrix.\n\ -\n\ -If invoked with two or more scalar integer arguments, or a vector of integer\n\ -values, return an array with the given dimensions.\n\ -\n\ -The optional argument @var{class} specifies the class of the return array\n\ -and defaults to double. For example:\n\ -\n\ -@example\n\ -val = zeros (m,n, \"uint8\")\n\ -@end example\n\ -@seealso{ones}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} zeros (@var{n}) +@deftypefnx {} {} zeros (@var{m}, @var{n}) +@deftypefnx {} {} zeros (@var{m}, @var{n}, @var{k}, @dots{}) +@deftypefnx {} {} zeros ([@var{m} @var{n} @dots{}]) +@deftypefnx {} {} zeros (@dots{}, @var{class}) +Return a matrix or N-dimensional array whose elements are all 0. + +If invoked with a single scalar integer argument, 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 double. For example: + +@example +val = zeros (m,n, "uint8") +@end example +@seealso{ones} +@end deftypefn */) { return fill_matrix (args, 0, "zeros"); } @@ -4316,42 +4316,42 @@ */ DEFUN (Inf, args, , - "-*- texinfo -*-\n\ -@c List other form of function in documentation index\n\ -@findex inf\n\ -\n\ -@deftypefn {} {} Inf\n\ -@deftypefnx {} {} Inf (@var{n})\n\ -@deftypefnx {} {} Inf (@var{n}, @var{m})\n\ -@deftypefnx {} {} Inf (@var{n}, @var{m}, @var{k}, @dots{})\n\ -@deftypefnx {} {} Inf (@dots{}, @var{class})\n\ -Return a scalar, matrix or N-dimensional array whose elements are all equal\n\ -to the IEEE representation for positive infinity.\n\ -\n\ -Infinity is produced when results are too large to be represented using the\n\ -IEEE floating point format for numbers. Two common examples which produce\n\ -infinity are division by zero and overflow.\n\ -\n\ -@example\n\ -@group\n\ -[ 1/0 e^800 ]\n\ -@result{} Inf Inf\n\ -@end group\n\ -@end example\n\ -\n\ -When called with no arguments, return a scalar with the value @samp{Inf}.\n\ -\n\ -When called with a single argument, return a square matrix with the\n\ -dimension specified.\n\ -\n\ -When called with more than one scalar argument the first two arguments are\n\ -taken as the number of rows and columns and any further arguments specify\n\ -additional matrix dimensions.\n\ -\n\ -The optional argument @var{class} specifies the return type and may be\n\ -either @qcode{\"double\"} or @qcode{\"single\"}.\n\ -@seealso{isinf, NaN}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@c List other form of function in documentation index +@findex inf + +@deftypefn {} {} Inf +@deftypefnx {} {} Inf (@var{n}) +@deftypefnx {} {} Inf (@var{n}, @var{m}) +@deftypefnx {} {} Inf (@var{n}, @var{m}, @var{k}, @dots{}) +@deftypefnx {} {} Inf (@dots{}, @var{class}) +Return a scalar, matrix or N-dimensional array whose elements are all equal +to the IEEE representation for positive infinity. + +Infinity is produced when results are too large to be represented using the +IEEE floating point format for numbers. Two common examples which produce +infinity are division by zero and overflow. + +@example +@group +[ 1/0 e^800 ] +@result{} Inf Inf +@end group +@end example + +When called with no arguments, return a scalar with the value @samp{Inf}. + +When called with a single argument, return a square matrix with the +dimension specified. + +When called with more than one scalar argument the first two arguments are +taken as the number of rows and columns and any further arguments specify +additional matrix dimensions. + +The optional argument @var{class} specifies the return type and may be +either @qcode{"double"} or @qcode{"single"}. +@seealso{isinf, NaN} +@end deftypefn */) { return fill_matrix (args, lo_ieee_inf_value (), lo_ieee_float_inf_value (), "Inf"); @@ -4377,47 +4377,47 @@ */ DEFUN (NaN, args, , - "-*- texinfo -*-\n\ -@c List other form of function in documentation index\n\ -@findex nan\n\ -\n\ -@deftypefn {} {} NaN\n\ -@deftypefnx {} {} NaN (@var{n})\n\ -@deftypefnx {} {} NaN (@var{n}, @var{m})\n\ -@deftypefnx {} {} NaN (@var{n}, @var{m}, @var{k}, @dots{})\n\ -@deftypefnx {} {} NaN (@dots{}, @var{class})\n\ -Return a scalar, matrix, or N-dimensional array whose elements are all equal\n\ -to the IEEE symbol NaN (Not a Number).\n\ -\n\ -NaN is the result of operations which do not produce a well defined\n\ -numerical result. Common operations which produce a NaN are arithmetic\n\ -with infinity\n\ -@tex\n\ -($\\infty - \\infty$), zero divided by zero ($0/0$),\n\ -@end tex\n\ -@ifnottex\n\ -(Inf - Inf), zero divided by zero (0/0),\n\ -@end ifnottex\n\ -and any operation involving another NaN value (5 + NaN).\n\ -\n\ -Note that NaN always compares not equal to NaN (NaN != NaN). This behavior\n\ -is specified by the IEEE standard for floating point arithmetic. To find\n\ -NaN values, use the @code{isnan} function.\n\ -\n\ -When called with no arguments, return a scalar with the value @samp{NaN}.\n\ -\n\ -When called with a single argument, return a square matrix with the\n\ -dimension specified.\n\ -\n\ -When called with more than one scalar argument the first two arguments are\n\ -taken as the number of rows and columns and any further arguments specify\n\ -additional matrix dimensions.\n\ -\n\ -\n\ -The optional argument @var{class} specifies the return type and may be\n\ -either @qcode{\"double\"} or @qcode{\"single\"}.\n\ -@seealso{isnan, Inf}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@c List other form of function in documentation index +@findex nan + +@deftypefn {} {} NaN +@deftypefnx {} {} NaN (@var{n}) +@deftypefnx {} {} NaN (@var{n}, @var{m}) +@deftypefnx {} {} NaN (@var{n}, @var{m}, @var{k}, @dots{}) +@deftypefnx {} {} NaN (@dots{}, @var{class}) +Return a scalar, matrix, or N-dimensional array whose elements are all equal +to the IEEE symbol NaN (Not a Number). + +NaN is the result of operations which do not produce a well defined +numerical result. Common operations which produce a 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 NaN value (5 + NaN). + +Note that NaN always compares not equal to NaN (NaN != NaN). This behavior +is specified by the IEEE standard for floating point arithmetic. To find +NaN values, use the @code{isnan} function. + +When called with no arguments, return a scalar with the value @samp{NaN}. + +When called with a single argument, return a square matrix with the +dimension specified. + +When called with more than one scalar argument the first two arguments are +taken as the number of rows and columns and any further arguments specify +additional matrix dimensions. + + +The optional argument @var{class} specifies the return type and may be +either @qcode{"double"} or @qcode{"single"}. +@seealso{isnan, Inf} +@end deftypefn */) { return fill_matrix (args, lo_ieee_nan_value (), lo_ieee_float_nan_value (), "NaN"); @@ -4443,36 +4443,36 @@ */ DEFUN (e, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} e\n\ -@deftypefnx {} {} e (@var{n})\n\ -@deftypefnx {} {} e (@var{n}, @var{m})\n\ -@deftypefnx {} {} e (@var{n}, @var{m}, @var{k}, @dots{})\n\ -@deftypefnx {} {} e (@dots{}, @var{class})\n\ -Return a scalar, matrix, or N-dimensional array whose elements are all equal\n\ -to the base of natural logarithms.\n\ -\n\ -The constant\n\ -@tex\n\ -$e$ satisfies the equation $\\log (e) = 1$.\n\ -@end tex\n\ -@ifnottex\n\ -@samp{e} satisfies the equation @code{log} (e) = 1.\n\ -@end ifnottex\n\ -\n\ -When called with no arguments, return a scalar with the value @math{e}.\n\ -\n\ -When called with a single argument, return a square matrix with the\n\ -dimension specified.\n\ -\n\ -When called with more than one scalar argument the first two arguments are\n\ -taken as the number of rows and columns and any further arguments specify\n\ -additional matrix dimensions.\n\ -\n\ -The optional argument @var{class} specifies the return type and may be\n\ -either @qcode{\"double\"} or @qcode{\"single\"}.\n\ -@seealso{log, exp, pi, I}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} e +@deftypefnx {} {} e (@var{n}) +@deftypefnx {} {} e (@var{n}, @var{m}) +@deftypefnx {} {} e (@var{n}, @var{m}, @var{k}, @dots{}) +@deftypefnx {} {} 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 + +When called with no arguments, return a scalar with the value @math{e}. + +When called with a single argument, return a square matrix with the +dimension specified. + +When called with more than one scalar argument the first two arguments are +taken as the number of rows and columns and any further arguments specify +additional matrix dimensions. + +The optional argument @var{class} specifies the return type and may be +either @qcode{"double"} or @qcode{"single"}. +@seealso{log, exp, pi, I} +@end deftypefn */) { #if defined (M_E) double e_val = M_E; @@ -4484,39 +4484,39 @@ } DEFUN (eps, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} eps\n\ -@deftypefnx {} {} eps (@var{x})\n\ -@deftypefnx {} {} eps (@var{n}, @var{m})\n\ -@deftypefnx {} {} eps (@var{n}, @var{m}, @var{k}, @dots{})\n\ -@deftypefnx {} {} eps (@dots{}, @var{class})\n\ -Return a scalar, matrix or N-dimensional array whose elements are all eps,\n\ -the machine precision.\n\ -\n\ -More precisely, @code{eps} is the relative spacing between any two adjacent\n\ -numbers in the machine's floating point system. This number is obviously\n\ -system dependent. On machines that support IEEE floating point arithmetic,\n\ -@code{eps} is approximately\n\ -@tex\n\ -$2.2204\\times10^{-16}$ for double precision and $1.1921\\times10^{-7}$\n\ -@end tex\n\ -@ifnottex\n\ -2.2204e-16 for double precision and 1.1921e-07\n\ -@end ifnottex\n\ -for single precision.\n\ -\n\ -When called with no arguments, return a scalar with the value\n\ -@code{eps (1.0)}.\n\ -\n\ -Given a single argument @var{x}, return the distance between @var{x} and the\n\ -next largest value.\n\ -\n\ -When called with more than one argument the first two arguments are taken as\n\ -the number of rows and columns and any further arguments specify additional\n\ -matrix dimensions. The optional argument @var{class} specifies the return\n\ -type and may be either @qcode{\"double\"} or @qcode{\"single\"}.\n\ -@seealso{realmax, realmin, intmax, flintmax}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} eps +@deftypefnx {} {} eps (@var{x}) +@deftypefnx {} {} eps (@var{n}, @var{m}) +@deftypefnx {} {} eps (@var{n}, @var{m}, @var{k}, @dots{}) +@deftypefnx {} {} eps (@dots{}, @var{class}) +Return a scalar, matrix or N-dimensional array whose elements are all 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 is obviously +system dependent. On machines that support IEEE floating point arithmetic, +@code{eps} 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. + +When called with no arguments, return a scalar with the value +@code{eps (1.0)}. + +Given a single argument @var{x}, return the distance between @var{x} and the +next largest value. + +When called with more than one argument the first two arguments are taken as +the number of rows and columns and any further arguments specify additional +matrix dimensions. The optional argument @var{class} specifies the return +type and may be either @qcode{"double"} or @qcode{"single"}. +@seealso{realmax, realmin, intmax, flintmax} +@end deftypefn */) { octave_value retval; @@ -4605,42 +4605,42 @@ */ DEFUN (pi, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} pi\n\ -@deftypefnx {} {} pi (@var{n})\n\ -@deftypefnx {} {} pi (@var{n}, @var{m})\n\ -@deftypefnx {} {} pi (@var{n}, @var{m}, @var{k}, @dots{})\n\ -@deftypefnx {} {} pi (@dots{}, @var{class})\n\ -Return a scalar, matrix, or N-dimensional array whose elements are all equal\n\ -to the ratio of the circumference of a circle to its\n\ -@tex\n\ -diameter($\\pi$).\n\ -@end tex\n\ -@ifnottex\n\ -diameter.\n\ -@end ifnottex\n\ -\n\ -Internally, @code{pi} is computed as @samp{4.0 * atan (1.0)}.\n\ -\n\ -When called with no arguments, return a scalar with the value of\n\ -@tex\n\ -$\\pi$.\n\ -@end tex\n\ -@ifnottex\n\ -pi.\n\ -@end ifnottex\n\ -\n\ -When called with a single argument, return a square matrix with the\n\ -dimension specified.\n\ -\n\ -When called with more than one scalar argument the first two arguments are\n\ -taken as the number of rows and columns and any further arguments specify\n\ -additional matrix dimensions.\n\ -\n\ -The optional argument @var{class} specifies the return type and may be\n\ -either @qcode{\"double\"} or @qcode{\"single\"}.\n\ -@seealso{e, I}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} pi +@deftypefnx {} {} pi (@var{n}) +@deftypefnx {} {} pi (@var{n}, @var{m}) +@deftypefnx {} {} pi (@var{n}, @var{m}, @var{k}, @dots{}) +@deftypefnx {} {} 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 + +Internally, @code{pi} is computed as @samp{4.0 * atan (1.0)}. + +When called with no arguments, return a scalar with the value of +@tex +$\pi$. +@end tex +@ifnottex +pi. +@end ifnottex + +When called with a single argument, return a square matrix with the +dimension specified. + +When called with more than one scalar argument the first two arguments are +taken as the number of rows and columns and any further arguments specify +additional matrix dimensions. + +The optional argument @var{class} specifies the return type and may be +either @qcode{"double"} or @qcode{"single"}. +@seealso{e, I} +@end deftypefn */) { #if defined (M_PI) double pi_val = M_PI; @@ -4652,120 +4652,120 @@ } DEFUN (realmax, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} realmax\n\ -@deftypefnx {} {} realmax (@var{n})\n\ -@deftypefnx {} {} realmax (@var{n}, @var{m})\n\ -@deftypefnx {} {} realmax (@var{n}, @var{m}, @var{k}, @dots{})\n\ -@deftypefnx {} {} realmax (@dots{}, @var{class})\n\ -Return a scalar, matrix, or N-dimensional array whose elements are all equal\n\ -to the largest floating point number that is representable.\n\ -\n\ -The actual value is system dependent. On machines that support IEEE\n\ -floating point arithmetic, @code{realmax} is approximately\n\ -@tex\n\ -$1.7977\\times10^{308}$ for double precision and $3.4028\\times10^{38}$\n\ -@end tex\n\ -@ifnottex\n\ -1.7977e+308 for double precision and 3.4028e+38\n\ -@end ifnottex\n\ -for single precision.\n\ -\n\ -When called with no arguments, return a scalar with the value\n\ -@code{realmax (@qcode{\"double\"})}.\n\ -\n\ -When called with a single argument, return a square matrix with the\n\ -dimension specified.\n\ -\n\ -When called with more than one scalar argument the first two arguments are\n\ -taken as the number of rows and columns and any further arguments specify\n\ -additional matrix dimensions.\n\ -\n\ -The optional argument @var{class} specifies the return type and may be\n\ -either @qcode{\"double\"} or @qcode{\"single\"}.\n\ -@seealso{realmin, intmax, flintmax, eps}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} realmax +@deftypefnx {} {} realmax (@var{n}) +@deftypefnx {} {} realmax (@var{n}, @var{m}) +@deftypefnx {} {} realmax (@var{n}, @var{m}, @var{k}, @dots{}) +@deftypefnx {} {} realmax (@dots{}, @var{class}) +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 +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. + +When called with no arguments, return a scalar with the value +@code{realmax (@qcode{"double"})}. + +When called with a single argument, return a square matrix with the +dimension specified. + +When called with more than one scalar argument the first two arguments are +taken as the number of rows and columns and any further arguments specify +additional matrix dimensions. + +The optional argument @var{class} specifies the return type and may be +either @qcode{"double"} or @qcode{"single"}. +@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, , - "-*- texinfo -*-\n\ -@deftypefn {} {} realmin\n\ -@deftypefnx {} {} realmin (@var{n})\n\ -@deftypefnx {} {} realmin (@var{n}, @var{m})\n\ -@deftypefnx {} {} realmin (@var{n}, @var{m}, @var{k}, @dots{})\n\ -@deftypefnx {} {} realmin (@dots{}, @var{class})\n\ -Return a scalar, matrix, or N-dimensional array whose elements are all equal\n\ -to the smallest normalized floating point number that is representable.\n\ -\n\ -The actual value is system dependent. On machines that support\n\ -IEEE floating point arithmetic, @code{realmin} is approximately\n\ -@tex\n\ -$2.2251\\times10^{-308}$ for double precision and $1.1755\\times10^{-38}$\n\ -@end tex\n\ -@ifnottex\n\ -2.2251e-308 for double precision and 1.1755e-38\n\ -@end ifnottex\n\ -for single precision.\n\ -\n\ -When called with no arguments, return a scalar with the value\n\ -@code{realmin (@qcode{\"double\"})}.\n\ -\n\ -When called with a single argument, return a square matrix with the\n\ -dimension specified.\n\ -\n\ -When called with more than one scalar argument the first two arguments are\n\ -taken as the number of rows and columns and any further arguments specify\n\ -additional matrix dimensions.\n\ -\n\ -The optional argument @var{class} specifies the return type and may be\n\ -either @qcode{\"double\"} or @qcode{\"single\"}.\n\ -@seealso{realmax, intmin, eps}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} realmin +@deftypefnx {} {} realmin (@var{n}) +@deftypefnx {} {} realmin (@var{n}, @var{m}) +@deftypefnx {} {} realmin (@var{n}, @var{m}, @var{k}, @dots{}) +@deftypefnx {} {} realmin (@dots{}, @var{class}) +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 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. + +When called with no arguments, return a scalar with the value +@code{realmin (@qcode{"double"})}. + +When called with a single argument, return a square matrix with the +dimension specified. + +When called with more than one scalar argument the first two arguments are +taken as the number of rows and columns and any further arguments specify +additional matrix dimensions. + +The optional argument @var{class} specifies the return type and may be +either @qcode{"double"} or @qcode{"single"}. +@seealso{realmax, intmin, eps} +@end deftypefn */) { return fill_matrix (args, std::numeric_limits<double>::min (), std::numeric_limits<float>::min (), "realmin"); } DEFUN (I, args, , - "-*- texinfo -*-\n\ -@c List other forms of function in documentation index\n\ -@findex i\n\ -@findex j\n\ -@findex J\n\ -\n\ -@deftypefn {} {} I\n\ -@deftypefnx {} {} I (@var{n})\n\ -@deftypefnx {} {} I (@var{n}, @var{m})\n\ -@deftypefnx {} {} I (@var{n}, @var{m}, @var{k}, @dots{})\n\ -@deftypefnx {} {} I (@dots{}, @var{class})\n\ -Return a scalar, matrix, or N-dimensional array whose elements are all equal\n\ -to the pure imaginary unit, defined as\n\ -@tex\n\ -$\\sqrt{-1}$.\n\ -@end tex\n\ -@ifnottex\n\ -@w{@code{sqrt (-1)}}.\n\ -@end ifnottex\n\ -\n\ -I, and its equivalents i, j, and J, are functions so any of the names may\n\ -be reused for other purposes (such as i for a counter variable).\n\ -\n\ -When called with no arguments, return a scalar with the value @math{i}.\n\ -\n\ -When called with a single argument, return a square matrix with the\n\ -dimension specified.\n\ -\n\ -When called with more than one scalar argument the first two arguments are\n\ -taken as the number of rows and columns and any further arguments specify\n\ -additional matrix dimensions.\n\ -\n\ -The optional argument @var{class} specifies the return type and may be\n\ -either @qcode{\"double\"} or @qcode{\"single\"}.\n\ -@seealso{e, pi, log, exp}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@c List other forms of function in documentation index +@findex i +@findex j +@findex J + +@deftypefn {} {} I +@deftypefnx {} {} I (@var{n}) +@deftypefnx {} {} I (@var{n}, @var{m}) +@deftypefnx {} {} I (@var{n}, @var{m}, @var{k}, @dots{}) +@deftypefnx {} {} 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 + +I, and its equivalents i, j, and J, are functions so any of the names may +be reused for other purposes (such as i for a counter variable). + +When called with no arguments, return a scalar with the value @math{i}. + +When called with a single argument, return a square matrix with the +dimension specified. + +When called with more than one scalar argument the first two arguments are +taken as the number of rows and columns and any further arguments specify +additional matrix dimensions. + +The optional argument @var{class} specifies the return type and may be +either @qcode{"double"} or @qcode{"single"}. +@seealso{e, pi, log, exp} +@end deftypefn */) { return fill_matrix (args, Complex (0.0, 1.0), "I"); } @@ -4775,31 +4775,31 @@ DEFALIAS (j, I); DEFUN (NA, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} NA\n\ -@deftypefnx {} {} NA (@var{n})\n\ -@deftypefnx {} {} NA (@var{n}, @var{m})\n\ -@deftypefnx {} {} NA (@var{n}, @var{m}, @var{k}, @dots{})\n\ -@deftypefnx {} {} NA (@dots{}, @var{class})\n\ -Return a scalar, matrix, or N-dimensional array whose elements are all equal\n\ -to the special constant used to designate missing values.\n\ -\n\ -Note that NA always compares not equal to NA (NA != NA).\n\ -To find NA values, use the @code{isna} function.\n\ -\n\ -When called with no arguments, return a scalar with the value @samp{NA}.\n\ -\n\ -When called with a single argument, return a square matrix with the\n\ -dimension specified.\n\ -\n\ -When called with more than one scalar argument the first two arguments are\n\ -taken as the number of rows and columns and any further arguments specify\n\ -additional matrix dimensions.\n\ -\n\ -The optional argument @var{class} specifies the return type and may be\n\ -either @qcode{\"double\"} or @qcode{\"single\"}.\n\ -@seealso{isna}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} NA +@deftypefnx {} {} NA (@var{n}) +@deftypefnx {} {} NA (@var{n}, @var{m}) +@deftypefnx {} {} NA (@var{n}, @var{m}, @var{k}, @dots{}) +@deftypefnx {} {} NA (@dots{}, @var{class}) +Return a scalar, matrix, or N-dimensional array whose elements are all equal +to the special constant used to designate missing values. + +Note that NA always compares not equal to NA (NA != NA). +To find NA values, use the @code{isna} function. + +When called with no arguments, return a scalar with the value @samp{NA}. + +When called with a single argument, return a square matrix with the +dimension specified. + +When called with more than one scalar argument the first two arguments are +taken as the number of rows and columns and any further arguments specify +additional matrix dimensions. + +The optional argument @var{class} specifies the return type and may be +either @qcode{"double"} or @qcode{"single"}. +@seealso{isna} +@end deftypefn */) { return fill_matrix (args, lo_ieee_na_value (), lo_ieee_float_na_value (), "NA"); @@ -4811,37 +4811,37 @@ */ DEFUN (false, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} false (@var{x})\n\ -@deftypefnx {} {} false (@var{n}, @var{m})\n\ -@deftypefnx {} {} false (@var{n}, @var{m}, @var{k}, @dots{})\n\ -Return a matrix or N-dimensional array whose elements are all logical 0.\n\ -\n\ -If invoked with a single scalar integer argument, return a square\n\ -matrix of the specified size.\n\ -\n\ -If invoked with two or more scalar integer arguments, or a vector of integer\n\ -values, return an array with given dimensions.\n\ -@seealso{true}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} false (@var{x}) +@deftypefnx {} {} false (@var{n}, @var{m}) +@deftypefnx {} {} false (@var{n}, @var{m}, @var{k}, @dots{}) +Return a matrix or N-dimensional array whose elements are all logical 0. + +If invoked with a single scalar integer argument, return a square +matrix of the specified size. + +If invoked with two or more scalar integer arguments, or a vector of integer +values, return an array with given dimensions. +@seealso{true} +@end deftypefn */) { return fill_matrix (args, false, "false"); } DEFUN (true, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} true (@var{x})\n\ -@deftypefnx {} {} true (@var{n}, @var{m})\n\ -@deftypefnx {} {} true (@var{n}, @var{m}, @var{k}, @dots{})\n\ -Return a matrix or N-dimensional array whose elements are all logical 1.\n\ -\n\ -If invoked with a single scalar integer argument, return a square\n\ -matrix of the specified size.\n\ -\n\ -If invoked with two or more scalar integer arguments, or a vector of integer\n\ -values, return an array with given dimensions.\n\ -@seealso{false}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} true (@var{x}) +@deftypefnx {} {} true (@var{n}, @var{m}) +@deftypefnx {} {} true (@var{n}, @var{m}, @var{k}, @dots{}) +Return a matrix or N-dimensional array whose elements are all logical 1. + +If invoked with a single scalar integer argument, return a square +matrix of the specified size. + +If invoked with two or more scalar integer arguments, or a vector of integer +values, return an array with given dimensions. +@seealso{false} +@end deftypefn */) { return fill_matrix (args, true, "true"); } @@ -4959,54 +4959,54 @@ #undef INT_EYE_MATRIX DEFUN (eye, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} eye (@var{n})\n\ -@deftypefnx {} {} eye (@var{m}, @var{n})\n\ -@deftypefnx {} {} eye ([@var{m} @var{n}])\n\ -@deftypefnx {} {} eye (@dots{}, @var{class})\n\ -Return an identity matrix.\n\ -\n\ -If invoked with a single scalar argument @var{n}, return a square\n\ -@nospell{NxN} identity matrix.\n\ -\n\ -If supplied two scalar arguments (@var{m}, @var{n}), @code{eye} takes them\n\ -to be the number of rows and columns. If given a vector with two elements,\n\ -@code{eye} uses the values of the elements as the number of rows and\n\ -columns, respectively. For example:\n\ -\n\ -@example\n\ -@group\n\ -eye (3)\n\ - @result{} 1 0 0\n\ - 0 1 0\n\ - 0 0 1\n\ -@end group\n\ -@end example\n\ -\n\ -The following expressions all produce the same result:\n\ -\n\ -@example\n\ -@group\n\ -eye (2)\n\ -@equiv{}\n\ -eye (2, 2)\n\ -@equiv{}\n\ -eye (size ([1, 2; 3, 4]))\n\ -@end group\n\ -@end example\n\ -\n\ -The optional argument @var{class}, allows @code{eye} to return an array of\n\ -the specified type, like\n\ -\n\ -@example\n\ -val = zeros (n,m, \"uint8\")\n\ -@end example\n\ -\n\ -Calling @code{eye} with no arguments is equivalent to calling it with an\n\ -argument of 1. Any negative dimensions are treated as zero. These odd\n\ -definitions are for compatibility with @sc{matlab}.\n\ -@seealso{speye, ones, zeros}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} eye (@var{n}) +@deftypefnx {} {} eye (@var{m}, @var{n}) +@deftypefnx {} {} eye ([@var{m} @var{n}]) +@deftypefnx {} {} eye (@dots{}, @var{class}) +Return an identity matrix. + +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}), @code{eye} takes them +to be the number of rows and columns. If given a vector with two elements, +@code{eye} uses the values of the elements as the number of rows and +columns, respectively. For example: + +@example +@group +eye (3) + @result{} 1 0 0 + 0 1 0 + 0 0 1 +@end group +@end example + +The following expressions all produce the same result: + +@example +@group +eye (2) +@equiv{} +eye (2, 2) +@equiv{} +eye (size ([1, 2; 3, 4])) +@end group +@end example + +The optional argument @var{class}, allows @code{eye} to return an array of +the specified type, like + +@example +val = zeros (n,m, "uint8") +@end example + +Calling @code{eye} with no arguments is equivalent to calling it with an +argument of 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 (); @@ -5105,27 +5105,27 @@ } DEFUN (linspace, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} linspace (@var{base}, @var{limit})\n\ -@deftypefnx {} {} linspace (@var{base}, @var{limit}, @var{n})\n\ -Return a row vector with @var{n} linearly spaced elements between\n\ -@var{base} and @var{limit}.\n\ -\n\ -If the number of elements is greater than one, then the endpoints @var{base}\n\ -and @var{limit} are always included in the range. If @var{base} is greater\n\ -than @var{limit}, the elements are stored in decreasing order. If the\n\ -number of points is not specified, a value of 100 is used.\n\ -\n\ -The @code{linspace} function returns a row vector when both @var{base}\n\ -and @var{limit} are scalars. If one, or both, inputs are vectors, then\n\ -@code{linspace} transforms them to column vectors and returns a matrix where\n\ -each row is an independent sequence between\n\ -@w{@code{@var{base}(@var{row_n}), @var{limit}(@var{row_n})}}.\n\ -\n\ -For compatibility with @sc{matlab}, return the second argument (@var{limit})\n\ -if fewer than two values are requested.\n\ -@seealso{logspace}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} linspace (@var{base}, @var{limit}) +@deftypefnx {} {} linspace (@var{base}, @var{limit}, @var{n}) +Return a row vector with @var{n} linearly spaced elements between +@var{base} and @var{limit}. + +If the number of elements is greater than one, then the endpoints @var{base} +and @var{limit} are always included in the range. If @var{base} is greater +than @var{limit}, the elements are stored in decreasing order. If the +number of points is not specified, a value of 100 is used. + +The @code{linspace} function returns a row vector when both @var{base} +and @var{limit} 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{base}(@var{row_n}), @var{limit}(@var{row_n})}}. + +For compatibility with @sc{matlab}, return the second argument (@var{limit}) +if fewer than two values are requested. +@seealso{logspace} +@end deftypefn */) { int nargin = args.length (); @@ -5237,51 +5237,51 @@ // arrays as well as 1-D and 2-D arrays. DEFUN (resize, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} resize (@var{x}, @var{m})\n\ -@deftypefnx {} {} resize (@var{x}, @var{m}, @var{n}, @dots{})\n\ -@deftypefnx {} {} resize (@var{x}, [@var{m} @var{n} @dots{}])\n\ -Resize @var{x} cutting off elements as necessary.\n\ -\n\ -In the result, element with certain indices is equal to the corresponding\n\ -element of @var{x} if the indices are within the bounds of @var{x};\n\ -otherwise, the element is set to zero.\n\ -\n\ -In other words, the statement\n\ -\n\ -@example\n\ -y = resize (x, dv)\n\ -@end example\n\ -\n\ -@noindent\n\ -is equivalent to the following code:\n\ -\n\ -@example\n\ -@group\n\ -y = zeros (dv, class (x));\n\ -sz = min (dv, size (x));\n\ -for i = 1:length (sz)\n\ - idx@{i@} = 1:sz(i);\n\ -endfor\n\ -y(idx@{:@}) = x(idx@{:@});\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -but is performed more efficiently.\n\ -\n\ -If only @var{m} is supplied, and it is a scalar, the dimension of the\n\ -result is @var{m}-by-@var{m}.\n\ -If @var{m}, @var{n}, @dots{} are all scalars, then the dimensions of\n\ -the result are @var{m}-by-@var{n}-by-@dots{}.\n\ -If given a vector as input, then the\n\ -dimensions of the result are given by the elements of that vector.\n\ -\n\ -An object can be resized to more dimensions than it has;\n\ -in such case the missing dimensions are assumed to be 1.\n\ -Resizing an object to fewer dimensions is not possible.\n\ -@seealso{reshape, postpad, prepad, cat}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} resize (@var{x}, @var{m}) +@deftypefnx {} {} resize (@var{x}, @var{m}, @var{n}, @dots{}) +@deftypefnx {} {} resize (@var{x}, [@var{m} @var{n} @dots{}]) +Resize @var{x} cutting off elements as necessary. + +In the result, element with certain indices is equal to the corresponding +element of @var{x} if the indices are within the bounds of @var{x}; +otherwise, the element is set to zero. + +In other words, the statement + +@example +y = resize (x, dv) +@end example + +@noindent +is equivalent to the following code: + +@example +@group +y = zeros (dv, class (x)); +sz = min (dv, size (x)); +for i = 1:length (sz) + idx@{i@} = 1:sz(i); +endfor +y(idx@{:@}) = x(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-@dots{}. +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 (); @@ -5327,38 +5327,38 @@ // FIXME: should use octave_idx_type for dimensions. DEFUN (reshape, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} reshape (@var{A}, @var{m}, @var{n}, @dots{})\n\ -@deftypefnx {} {} reshape (@var{A}, [@var{m} @var{n} @dots{}])\n\ -@deftypefnx {} {} reshape (@var{A}, @dots{}, [], @dots{})\n\ -@deftypefnx {} {} reshape (@var{A}, @var{size})\n\ -Return a matrix with the specified dimensions (@var{m}, @var{n}, @dots{})\n\ -whose elements are taken from the matrix @var{A}.\n\ -\n\ -The elements of the matrix are accessed in column-major order (like Fortran\n\ -arrays are stored).\n\ -\n\ -The following code demonstrates reshaping a 1x4 row vector into a 2x2 square\n\ -matrix.\n\ -\n\ -@example\n\ -@group\n\ -reshape ([1, 2, 3, 4], 2, 2)\n\ - @result{} 1 3\n\ - 2 4\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -Note that the total number of elements in the original matrix\n\ -(@code{prod (size (@var{A}))}) must match the total number of elements\n\ -in the new matrix (@code{prod ([@var{m} @var{n} @dots{}])}).\n\ -\n\ -A single dimension of the return matrix may be left unspecified and Octave\n\ -will determine its size automatically. An empty matrix ([]) is used to flag\n\ -the unspecified dimension.\n\ -@seealso{resize, vec, postpad, cat, squeeze}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} reshape (@var{A}, @var{m}, @var{n}, @dots{}) +@deftypefnx {} {} reshape (@var{A}, [@var{m} @var{n} @dots{}]) +@deftypefnx {} {} reshape (@var{A}, @dots{}, [], @dots{}) +@deftypefnx {} {} 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) + @result{} 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 (); @@ -5460,19 +5460,19 @@ */ DEFUN (vec, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{v} =} vec (@var{x})\n\ -@deftypefnx {} {@var{v} =} vec (@var{x}, @var{dim})\n\ -Return the vector obtained by stacking the columns of the matrix @var{x}\n\ -one above the other.\n\ -\n\ -Without @var{dim} this is equivalent to @code{@var{x}(:)}.\n\ -\n\ -If @var{dim} is supplied, the dimensions of @var{v} are set to @var{dim}\n\ -with all elements along the last dimension. This is equivalent to\n\ -@code{shiftdim (@var{x}(:), 1-@var{dim})}.\n\ -@seealso{vech, resize, cat}\n\ -@end deftypefn") + 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 (); @@ -5524,14 +5524,14 @@ */ DEFUN (squeeze, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} squeeze (@var{x})\n\ -Remove singleton dimensions from @var{x} and return the result.\n\ -\n\ -Note that for compatibility with @sc{matlab}, all objects have\n\ -a minimum of two dimensions and row vectors are left unchanged.\n\ -@seealso{reshape}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} squeeze (@var{x}) +Remove singleton dimensions from @var{x} 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 (); @@ -5540,12 +5540,12 @@ } DEFUN (full, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{FM} =} full (@var{SM})\n\ -Return a full storage matrix from a sparse, diagonal, or permutation matrix,\n\ -or a range.\n\ -@seealso{sparse, issparse}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{FM} =} full (@var{SM}) +Return a full storage matrix from a sparse, diagonal, or permutation matrix, +or a range. +@seealso{sparse, issparse} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -5556,64 +5556,64 @@ // Compute various norms of the vector X. DEFUN (norm, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} norm (@var{A})\n\ -@deftypefnx {} {} norm (@var{A}, @var{p})\n\ -@deftypefnx {} {} norm (@var{A}, @var{p}, @var{opt})\n\ -Compute the p-norm of the matrix @var{A}.\n\ -\n\ -If the second argument is missing, @w{@code{p = 2}} is assumed.\n\ -\n\ -If @var{A} is a matrix (or sparse matrix):\n\ -\n\ -@table @asis\n\ -@item @var{p} = @code{1}\n\ -1-norm, the largest column sum of the absolute values of @var{A}.\n\ -\n\ -@item @var{p} = @code{2}\n\ -Largest singular value of @var{A}.\n\ -\n\ -@item @var{p} = @code{Inf} or @qcode{\"inf\"}\n\ -@cindex infinity norm\n\ -Infinity norm, the largest row sum of the absolute values of @var{A}.\n\ -\n\ -@item @var{p} = @qcode{\"fro\"}\n\ -@cindex Frobenius norm\n\ -Frobenius norm of @var{A}, @code{sqrt (sum (diag (@var{A}' * @var{A})))}.\n\ -\n\ -@item other @var{p}, @code{@var{p} > 1}\n\ -@cindex general p-norm\n\ -maximum @code{norm (A*x, p)} such that @code{norm (x, p) == 1}\n\ -@end table\n\ -\n\ -If @var{A} is a vector or a scalar:\n\ -\n\ -@table @asis\n\ -@item @var{p} = @code{Inf} or @qcode{\"inf\"}\n\ -@code{max (abs (@var{A}))}.\n\ -\n\ -@item @var{p} = @code{-Inf}\n\ -@code{min (abs (@var{A}))}.\n\ -\n\ -@item @var{p} = @qcode{\"fro\"}\n\ -Frobenius norm of @var{A}, @code{sqrt (sumsq (abs (A)))}.\n\ -\n\ -@item @var{p} = 0\n\ -Hamming norm - the number of nonzero elements.\n\ -\n\ -@item other @var{p}, @code{@var{p} > 1}\n\ -p-norm of @var{A}, @code{(sum (abs (@var{A}) .^ @var{p})) ^ (1/@var{p})}.\n\ -\n\ -@item other @var{p} @code{@var{p} < 1}\n\ -the p-pseudonorm defined as above.\n\ -@end table\n\ -\n\ -If @var{opt} is the value @qcode{\"rows\"}, treat each row as a vector and\n\ -compute its norm. The result is returned as a column vector.\n\ -Similarly, if @var{opt} is @qcode{\"columns\"} or @qcode{\"cols\"} then\n\ -compute the norms of each column and return a row vector.\n\ -@seealso{cond, svd}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} norm (@var{A}) +@deftypefnx {} {} norm (@var{A}, @var{p}) +@deftypefnx {} {} norm (@var{A}, @var{p}, @var{opt}) +Compute the p-norm of the matrix @var{A}. + +If the second argument is missing, @w{@code{p = 2}} is assumed. + +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 Frobenius norm +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"} +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{cond, svd} +@end deftypefn */) { int nargin = args.length (); @@ -5776,45 +5776,45 @@ } DEFUN (not, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{z} =} not (@var{x})\n\ -Return the logical NOT of @var{x}.\n\ -\n\ -This function is equivalent to the operator syntax @w{@code{! x}}.\n\ -@seealso{and, or, xor}\n\ -@end deftypefn") + 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{! x}}. +@seealso{and, or, xor} +@end deftypefn */) { return unary_op_defun_body (octave_value::op_not, args); } DEFUN (uplus, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} uplus (@var{x})\n\ -This function and @w{@tcode{+ x}} are equivalent.\n\ -@seealso{uminus, plus, minus}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} uplus (@var{x}) +This function and @w{@tcode{+ x}} are equivalent. +@seealso{uminus, plus, minus} +@end deftypefn */) { return unary_op_defun_body (octave_value::op_uplus, args); } DEFUN (uminus, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} uminus (@var{x})\n\ -This function and @w{@tcode{- x}} are equivalent.\n\ -@seealso{uplus, minus}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} uminus (@var{x}) +This function and @w{@tcode{- x}} are equivalent. +@seealso{uplus, minus} +@end deftypefn */) { return unary_op_defun_body (octave_value::op_uminus, args); } DEFUN (transpose, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} transpose (@var{x})\n\ -Return the transpose of @var{x}.\n\ -\n\ -This function and @tcode{x.'} are equivalent.\n\ -@seealso{ctranspose}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} transpose (@var{x}) +Return the transpose of @var{x}. + +This function and @tcode{x.'} are equivalent. +@seealso{ctranspose} +@end deftypefn */) { return unary_op_defun_body (octave_value::op_transpose, args); } @@ -5840,13 +5840,13 @@ */ DEFUN (ctranspose, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} ctranspose (@var{x})\n\ -Return the complex conjugate transpose of @var{x}.\n\ -\n\ -This function and @tcode{x'} are equivalent.\n\ -@seealso{transpose}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} ctranspose (@var{x}) +Return the complex conjugate transpose of @var{x}. + +This function and @tcode{x'} are equivalent. +@seealso{transpose} +@end deftypefn */) { return unary_op_defun_body (octave_value::op_hermitian, args); } @@ -5909,276 +5909,276 @@ } DEFUN (plus, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} plus (@var{x}, @var{y})\n\ -@deftypefnx {} {} plus (@var{x1}, @var{x2}, @dots{})\n\ -This function and @w{@tcode{x + y}} are equivalent.\n\ -\n\ -If more arguments are given, the summation is applied\n\ -cumulatively from left to right:\n\ -\n\ -@example\n\ -(@dots{}((x1 + x2) + x3) + @dots{})\n\ -@end example\n\ -\n\ -At least one argument is required.\n\ -@seealso{minus, uplus}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} plus (@var{x}, @var{y}) +@deftypefnx {} {} plus (@var{x1}, @var{x2}, @dots{}) +This function and @w{@tcode{x + y}} are equivalent. + +If more arguments are given, the summation is applied +cumulatively from left to right: + +@example +(@dots{}((x1 + x2) + x3) + @dots{}) +@end example + +At least one argument is required. +@seealso{minus, uplus} +@end deftypefn */) { return binary_assoc_op_defun_body (octave_value::op_add, octave_value::op_add_eq, args); } DEFUN (minus, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} minus (@var{x}, @var{y})\n\ -This function and @w{@tcode{x - y}} are equivalent.\n\ -@seealso{plus, uminus}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} minus (@var{x}, @var{y}) +This function and @w{@tcode{x - y}} are equivalent. +@seealso{plus, uminus} +@end deftypefn */) { return binary_op_defun_body (octave_value::op_sub, args); } DEFUN (mtimes, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} mtimes (@var{x}, @var{y})\n\ -@deftypefnx {} {} mtimes (@var{x1}, @var{x2}, @dots{})\n\ -Return the matrix multiplication product of inputs.\n\ -\n\ -This function and @w{@tcode{x * y}} are equivalent.\n\ -If more arguments are given, the multiplication is applied\n\ -cumulatively from left to right:\n\ -\n\ -@example\n\ -(@dots{}((x1 * x2) * x3) * @dots{})\n\ -@end example\n\ -\n\ -At least one argument is required.\n\ -@seealso{times, plus, minus, rdivide, mrdivide, mldivide, mpower}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} mtimes (@var{x}, @var{y}) +@deftypefnx {} {} mtimes (@var{x1}, @var{x2}, @dots{}) +Return the matrix multiplication product of inputs. + +This function and @w{@tcode{x * y}} are equivalent. +If more arguments are given, the multiplication is applied +cumulatively from left to right: + +@example +(@dots{}((x1 * x2) * x3) * @dots{}) +@end example + +At least one argument is required. +@seealso{times, plus, minus, rdivide, mrdivide, mldivide, mpower} +@end deftypefn */) { return binary_assoc_op_defun_body (octave_value::op_mul, octave_value::op_mul_eq, args); } DEFUN (mrdivide, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} mrdivide (@var{x}, @var{y})\n\ -Return the matrix right division of @var{x} and @var{y}.\n\ -\n\ -This function and @w{@tcode{x / y}} are equivalent.\n\ -@seealso{mldivide, rdivide, plus, minus}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} mrdivide (@var{x}, @var{y}) +Return the matrix right division of @var{x} and @var{y}. + +This function and @w{@tcode{x / y}} are equivalent. +@seealso{mldivide, rdivide, plus, minus} +@end deftypefn */) { return binary_op_defun_body (octave_value::op_div, args); } DEFUN (mpower, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} mpower (@var{x}, @var{y})\n\ -Return the matrix power operation of @var{x} raised to the @var{y} power.\n\ -\n\ -This function and @w{@tcode{x ^ y}} are equivalent.\n\ -@seealso{power, mtimes, plus, minus}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} mpower (@var{x}, @var{y}) +Return the matrix power operation of @var{x} raised to the @var{y} power. + +This function and @w{@tcode{x ^ y}} are equivalent. +@seealso{power, mtimes, plus, minus} +@end deftypefn */) { return binary_op_defun_body (octave_value::op_pow, args); } DEFUN (mldivide, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} mldivide (@var{x}, @var{y})\n\ -Return the matrix left division of @var{x} and @var{y}.\n\ -\n\ -This function and @w{@tcode{x @xbackslashchar{} y}} are equivalent.\n\ -@seealso{mrdivide, ldivide, rdivide}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} mldivide (@var{x}, @var{y}) +Return the matrix left division of @var{x} and @var{y}. + +This function and @w{@tcode{x @xbackslashchar{} y}} are equivalent. +@seealso{mrdivide, ldivide, rdivide} +@end deftypefn */) { return binary_op_defun_body (octave_value::op_ldiv, args); } DEFUN (lt, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} lt (@var{x}, @var{y})\n\ -This function is equivalent to @w{@code{x < y}}.\n\ -@seealso{le, eq, ge, gt, ne}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} lt (@var{x}, @var{y}) +This function is equivalent to @w{@code{x < y}}. +@seealso{le, eq, ge, gt, ne} +@end deftypefn */) { return binary_op_defun_body (octave_value::op_lt, args); } DEFUN (le, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} le (@var{x}, @var{y})\n\ -This function is equivalent to @w{@code{x <= y}}.\n\ -@seealso{eq, ge, gt, ne, lt}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} le (@var{x}, @var{y}) +This function is equivalent to @w{@code{x <= y}}. +@seealso{eq, ge, gt, ne, lt} +@end deftypefn */) { return binary_op_defun_body (octave_value::op_le, args); } DEFUN (eq, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} eq (@var{x}, @var{y})\n\ -Return true if the two inputs are equal.\n\ -\n\ -This function is equivalent to @w{@code{x == y}}.\n\ -@seealso{ne, isequal, le, ge, gt, ne, lt}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} eq (@var{x}, @var{y}) +Return true if the two inputs are equal. + +This function is equivalent to @w{@code{x == y}}. +@seealso{ne, isequal, le, ge, gt, ne, lt} +@end deftypefn */) { return binary_op_defun_body (octave_value::op_eq, args); } DEFUN (ge, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} ge (@var{x}, @var{y})\n\ -This function is equivalent to @w{@code{x >= y}}.\n\ -@seealso{le, eq, gt, ne, lt}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} ge (@var{x}, @var{y}) +This function is equivalent to @w{@code{x >= y}}. +@seealso{le, eq, gt, ne, lt} +@end deftypefn */) { return binary_op_defun_body (octave_value::op_ge, args); } DEFUN (gt, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} gt (@var{x}, @var{y})\n\ -This function is equivalent to @w{@code{x > y}}.\n\ -@seealso{le, eq, ge, ne, lt}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} gt (@var{x}, @var{y}) +This function is equivalent to @w{@code{x > y}}. +@seealso{le, eq, ge, ne, lt} +@end deftypefn */) { return binary_op_defun_body (octave_value::op_gt, args); } DEFUN (ne, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} ne (@var{x}, @var{y})\n\ -Return true if the two inputs are not equal.\n\ -\n\ -This function is equivalent to @w{@code{x != y}}.\n\ -@seealso{eq, isequal, le, ge, lt}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} ne (@var{x}, @var{y}) +Return true if the two inputs are not equal. + +This function is equivalent to @w{@code{x != y}}. +@seealso{eq, isequal, le, ge, lt} +@end deftypefn */) { return binary_op_defun_body (octave_value::op_ne, args); } DEFUN (times, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} times (@var{x}, @var{y})\n\ -@deftypefnx {} {} times (@var{x1}, @var{x2}, @dots{})\n\ -Return the element-by-element multiplication product of inputs.\n\ -\n\ -This function and @w{@tcode{x .* y}} are equivalent.\n\ -If more arguments are given, the multiplication is applied\n\ -cumulatively from left to right:\n\ -\n\ -@example\n\ -(@dots{}((x1 .* x2) .* x3) .* @dots{})\n\ -@end example\n\ -\n\ -At least one argument is required.\n\ -@seealso{mtimes, rdivide}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} times (@var{x}, @var{y}) +@deftypefnx {} {} times (@var{x1}, @var{x2}, @dots{}) +Return the element-by-element multiplication product of inputs. + +This function and @w{@tcode{x .* y}} are equivalent. +If more arguments are given, the multiplication is applied +cumulatively from left to right: + +@example +(@dots{}((x1 .* x2) .* x3) .* @dots{}) +@end example + +At least one argument is required. +@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, , - "-*- texinfo -*-\n\ -@deftypefn {} {} rdivide (@var{x}, @var{y})\n\ -Return the element-by-element right division of @var{x} and @var{y}.\n\ -\n\ -This function and @w{@tcode{x ./ y}} are equivalent.\n\ -@seealso{ldivide, mrdivide, times, plus}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} rdivide (@var{x}, @var{y}) +Return the element-by-element right division of @var{x} and @var{y}. + +This function and @w{@tcode{x ./ y}} are equivalent. +@seealso{ldivide, mrdivide, times, plus} +@end deftypefn */) { return binary_op_defun_body (octave_value::op_el_div, args); } DEFUN (power, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} power (@var{x}, @var{y})\n\ -Return the element-by-element operation of @var{x} raised to the\n\ -@var{y} power.\n\ -\n\ -This function and @w{@tcode{x .^ y}} are equivalent.\n\ -\n\ -If several complex results are possible, returns the one with smallest\n\ -non-negative argument (angle). Use @code{realpow}, @code{realsqrt},\n\ -@code{cbrt}, or @code{nthroot} if a real result is preferred.\n\ -\n\ -@seealso{mpower, realpow, realsqrt, cbrt, nthroot}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} power (@var{x}, @var{y}) +Return the element-by-element operation of @var{x} raised to the +@var{y} power. + +This function and @w{@tcode{x .^ y}} 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); } DEFUN (ldivide, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} ldivide (@var{x}, @var{y})\n\ -Return the element-by-element left division of @var{x} and @var{y}.\n\ -\n\ -This function and @w{@tcode{x .@xbackslashchar{} y}} are equivalent.\n\ -@seealso{rdivide, mldivide, times, plus}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} ldivide (@var{x}, @var{y}) +Return the element-by-element left division of @var{x} and @var{y}. + +This function and @w{@tcode{x .@xbackslashchar{} y}} are equivalent. +@seealso{rdivide, mldivide, times, plus} +@end deftypefn */) { return binary_op_defun_body (octave_value::op_el_ldiv, args); } DEFUN (and, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{z} =} and (@var{x}, @var{y})\n\ -@deftypefnx {} {@var{z} =} and (@var{x1}, @var{x2}, @dots{})\n\ -Return the logical AND of @var{x} and @var{y}.\n\ -\n\ -This function is equivalent to the operator syntax @w{@code{x & y}}. If\n\ -more than two arguments are given, the logical AND is applied cumulatively\n\ -from left to right:\n\ -\n\ -@example\n\ -(@dots{}((x1 & x2) & x3) & @dots{})\n\ -@end example\n\ -\n\ -At least one argument is required.\n\ -@seealso{or, not, xor}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{z} =} and (@var{x}, @var{y}) +@deftypefnx {} {@var{z} =} 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{x & y}}. If +more than two arguments are given, the logical AND is applied cumulatively +from left to right: + +@example +(@dots{}((x1 & x2) & x3) & @dots{}) +@end example + +At least one argument is required. +@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, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{z} =} or (@var{x}, @var{y})\n\ -@deftypefnx {} {@var{z} =} or (@var{x1}, @var{x2}, @dots{})\n\ -Return the logical OR of @var{x} and @var{y}.\n\ -\n\ -This function is equivalent to the operator syntax @w{@code{x | y}}. If\n\ -more than two arguments are given, the logical OR is applied cumulatively\n\ -from left to right:\n\ -\n\ -@example\n\ -(@dots{}((x1 | x2) | x3) | @dots{})\n\ -@end example\n\ -\n\ -At least one argument is required.\n\ -@seealso{and, not, xor}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{z} =} or (@var{x}, @var{y}) +@deftypefnx {} {@var{z} =} 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{x | y}}. If +more than two arguments are given, the logical OR is applied cumulatively +from left to right: + +@example +(@dots{}((x1 | x2) | x3) | @dots{}) +@end example + +At least one argument is required. +@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, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{r} =} colon (@var{base}, @var{limit})\n\ -@deftypefnx {} {@var{r} =} colon (@var{base}, @var{increment}, @var{limit})\n\ -Return the result of the colon expression corresponding to @var{base},\n\ -@var{limit}, and optionally, @var{increment}.\n\ -\n\ -This function is equivalent to the operator syntax @w{@code{base : limit}}\n\ -or @w{@code{base : increment : limit}}.\n\ -@end deftypefn") + 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{base : limit}} +or @w{@code{base : increment : limit}}. +@end deftypefn */) { int nargin = args.length (); @@ -6192,50 +6192,50 @@ static double tic_toc_timestamp = -1.0; DEFUN (tic, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} tic ()\n\ -@deftypefnx {} {@var{id} =} tic ()\n\ -@deftypefnx {} {} toc ()\n\ -@deftypefnx {} {} toc (@var{id})\n\ -@deftypefnx {} {@var{val} =} toc (@dots{})\n\ -Set or check a wall-clock timer.\n\ -\n\ -Calling @code{tic} without an output argument sets the internal timer state.\n\ -Subsequent calls to @code{toc} return the number of seconds since the timer\n\ -was set.\n\ -For example,\n\ -\n\ -@example\n\ -@group\n\ -tic ();\n\ -# many computations later@dots{}\n\ -elapsed_time = toc ();\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -will set the variable @code{elapsed_time} to the number of seconds since\n\ -the most recent call to the function @code{tic}.\n\ -\n\ -If called with one output argument, @code{tic} returns a scalar\n\ -of type @code{uint64} that may be later passed to @code{toc}.\n\ -\n\ -@example\n\ -@group\n\ -id = tic; pause (5); toc (id)\n\ - @result{} 5.0010\n\ -@end group\n\ -@end example\n\ -\n\ -Calling @code{tic} and @code{toc} this way allows nested timing calls.\n\ -\n\ -If you are more interested in the CPU time that your process used, you\n\ -should use the @code{cputime} function instead. The @code{tic} and\n\ -@code{toc} functions report the actual wall clock time that elapsed\n\ -between the calls. This may include time spent processing other jobs or\n\ -doing nothing at all.\n\ -@seealso{toc, cputime}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} tic () +@deftypefnx {} {@var{id} =} tic () +@deftypefnx {} {} toc () +@deftypefnx {} {} toc (@var{id}) +@deftypefnx {} {@var{val} =} toc (@dots{}) +Set or check a wall-clock timer. + +Calling @code{tic} without an output argument sets the internal timer state. +Subsequent calls to @code{toc} return the number of seconds since the timer +was set. +For example, + +@example +@group +tic (); +# many computations later@dots{} +elapsed_time = toc (); +@end group +@end example + +@noindent +will set the variable @code{elapsed_time} to the number of seconds since +the most recent call to the function @code{tic}. + +If called with one output argument, @code{tic} returns a scalar +of type @code{uint64} that may be later passed to @code{toc}. + +@example +@group +id = tic; pause (5); toc (id) + @result{} 5.0010 +@end group +@end example + +Calling @code{tic} and @code{toc} 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"); @@ -6259,12 +6259,12 @@ } DEFUN (toc, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} toc ()\n\ -@deftypefnx {} {} toc (@var{id})\n\ -@deftypefnx {} {@var{val} =} toc (@dots{})\n\ -@seealso{tic, cputime}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} toc () +@deftypefnx {} {} toc (@var{id}) +@deftypefnx {} {@var{val} =} toc (@dots{}) +@seealso{tic, cputime} +@end deftypefn */) { int nargin = args.length (); @@ -6312,23 +6312,23 @@ */ DEFUN (cputime, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{total}, @var{user}, @var{system}] =} cputime ();\n\ -Return the CPU time used by your Octave session.\n\ -\n\ -The first output is the total time spent executing your process and is equal\n\ -to the sum of second and third outputs, which are the number of CPU seconds\n\ -spent executing in user mode and the number of CPU seconds spent executing\n\ -in system mode, respectively.\n\ -\n\ -If your system does not have a way to report CPU time usage, @code{cputime}\n\ -returns 0 for each of its output values.\n\ -\n\ -Note that because Octave used some CPU time to start, it is reasonable\n\ -to check to see if @code{cputime} works by checking to see if the total\n\ -CPU time used is nonzero.\n\ -@seealso{tic, toc}\n\ -@end deftypefn") + 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 (); @@ -6342,74 +6342,74 @@ } DEFUN (sort, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{s}, @var{i}] =} sort (@var{x})\n\ -@deftypefnx {} {[@var{s}, @var{i}] =} sort (@var{x}, @var{dim})\n\ -@deftypefnx {} {[@var{s}, @var{i}] =} sort (@var{x}, @var{mode})\n\ -@deftypefnx {} {[@var{s}, @var{i}] =} sort (@var{x}, @var{dim}, @var{mode})\n\ -Return a copy of @var{x} with the elements arranged in increasing order.\n\ -\n\ -For matrices, @code{sort} orders the elements within columns\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -sort ([1, 2; 2, 3; 3, 1])\n\ - @result{} 1 1\n\ - 2 2\n\ - 3 3\n\ -@end group\n\ -@end example\n\ -\n\ -If the optional argument @var{dim} is given, then the matrix is sorted\n\ -along the dimension defined by @var{dim}. The optional argument @code{mode}\n\ -defines the order in which the values will be sorted. Valid values of\n\ -@code{mode} are @qcode{\"ascend\"} or @qcode{\"descend\"}.\n\ -\n\ -The @code{sort} function may also be used to produce a matrix\n\ -containing the original row indices of the elements in the sorted\n\ -matrix. For example:\n\ -\n\ -@example\n\ -@group\n\ -[s, i] = sort ([1, 2; 2, 3; 3, 1])\n\ - @result{} s = 1 1\n\ - 2 2\n\ - 3 3\n\ - @result{} i = 1 3\n\ - 2 1\n\ - 3 2\n\ -@end group\n\ -@end example\n\ -\n\ -For equal elements, the indices are such that equal elements are listed\n\ -in the order in which they appeared in the original list.\n\ -\n\ -Sorting of complex entries is done first by magnitude\n\ -(@w{@code{abs (@var{z})}}) and for any ties by phase angle\n\ -(@w{@code{angle (z)}}). For example:\n\ -\n\ -@example\n\ -@group\n\ -sort ([1+i; 1; 1-i])\n\ - @result{} 1 + 0i\n\ - 1 - 1i\n\ - 1 + 1i\n\ -@end group\n\ -@end example\n\ -\n\ -NaN values are treated as being greater than any other value and are sorted\n\ -to the end of the list.\n\ -\n\ -The @code{sort} function may also be used to sort strings and cell arrays\n\ -of strings, in which case ASCII dictionary order (uppercase 'A' precedes\n\ -lowercase 'a') of the strings is used.\n\ -\n\ -The algorithm used in @code{sort} is optimized for the sorting of partially\n\ -ordered lists.\n\ -@seealso{sortrows, issorted}\n\ -@end deftypefn") + 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]) + @result{} 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 @code{mode} +defines the order in which the values will be sorted. Valid values of +@code{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]) + @result{} s = 1 1 + 2 2 + 3 3 + @result{} 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]) + @result{} 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 (); @@ -6664,10 +6664,10 @@ // FIXME: Is this function used anymore? 12/14/2015 DEFUN (__sort_rows_idx__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __sort_rows_idx__ (@var{a}, @var{mode})\n\ -Undocumented internal function.\n\ -@end deftypefn\n") + doc: /* -*- texinfo -*- +@deftypefn {} {} __sort_rows_idx__ (@var{a}, @var{mode}) +Undocumented internal function. +@end deftypefn */) { int nargin = args.length (); @@ -6726,24 +6726,24 @@ } DEFUN (issorted, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} issorted (@var{a})\n\ -@deftypefnx {} {} issorted (@var{a}, @var{mode})\n\ -@deftypefnx {} {} issorted (@var{a}, \"rows\", @var{mode})\n\ -Return true if the array is sorted according to @var{mode}, which\n\ -may be either @qcode{\"ascending\"}, @qcode{\"descending\"}, or\n\ -@qcode{\"either\"}.\n\ -\n\ -By default, @var{mode} is @qcode{\"ascending\"}. NaNs are treated in the\n\ -same manner as @code{sort}.\n\ -\n\ -If the optional argument @qcode{\"rows\"} is supplied, check whether\n\ -the array is sorted by rows as output by the function @code{sortrows}\n\ -(with no options).\n\ -\n\ -This function does not support sparse matrices.\n\ -@seealso{sort, sortrows}\n\ -@end deftypefn\n") + doc: /* -*- texinfo -*- +@deftypefn {} {} issorted (@var{a}) +@deftypefnx {} {} issorted (@var{a}, @var{mode}) +@deftypefnx {} {} issorted (@var{a}, "rows", @var{mode}) +Return true if the array is sorted according to @var{mode}, which +may be either @qcode{"ascending"}, @qcode{"descending"}, or +@qcode{"either"}. + +By default, @var{mode} is @qcode{"ascending"}. NaNs are treated in the +same manner as @code{sort}. + +If the optional argument @qcode{"rows"} is supplied, check whether +the array is sorted by rows as output by the function @code{sortrows} +(with no options). + +This function does not support sparse matrices. +@seealso{sort, sortrows} +@end deftypefn */) { int nargin = args.length (); @@ -6838,28 +6838,28 @@ */ DEFUN (nth_element, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} nth_element (@var{x}, @var{n})\n\ -@deftypefnx {} {} nth_element (@var{x}, @var{n}, @var{dim})\n\ -Select the n-th smallest element of a vector, using the ordering defined by\n\ -@code{sort}.\n\ -\n\ -The result is equivalent to @code{sort(@var{x})(@var{n})}.\n\ -\n\ -@var{n} can also be a contiguous range, either ascending @code{l:u}\n\ -or descending @code{u:-1:l}, in which case a range of elements is returned.\n\ -\n\ -If @var{x} is an array, @code{nth_element} operates along the dimension\n\ -defined by @var{dim}, or the first non-singleton dimension if @var{dim} is\n\ -not given.\n\ -\n\ -Programming Note: nth_element encapsulates the C++ standard library\n\ -algorithms nth_element and partial_sort. On average, the complexity of the\n\ -operation is O(M*log(K)), where @w{@code{M = size (@var{x}, @var{dim})}} and\n\ -@w{@code{K = length (@var{n})}}. This function is intended for cases where\n\ -the ratio K/M is small; otherwise, it may be better to use @code{sort}.\n\ -@seealso{sort, min, max}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} nth_element (@var{x}, @var{n}) +@deftypefnx {} {} 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 (); @@ -6953,10 +6953,10 @@ } DEFUN (__accumarray_sum__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __accumarray_sum__ (@var{idx}, @var{vals}, @var{n})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __accumarray_sum__ (@var{idx}, @var{vals}, @var{n}) +Undocumented internal function. +@end deftypefn */) { int nargin = args.length (); @@ -7127,19 +7127,19 @@ } DEFUN (__accumarray_min__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __accumarray_min__ (@var{idx}, @var{vals}, @var{zero}, @var{n})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __accumarray_min__ (@var{idx}, @var{vals}, @var{zero}, @var{n}) +Undocumented internal function. +@end deftypefn */) { return do_accumarray_minmax_fun (args, true); } DEFUN (__accumarray_max__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __accumarray_max__ (@var{idx}, @var{vals}, @var{zero}, @var{n})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __accumarray_max__ (@var{idx}, @var{vals}, @var{zero}, @var{n}) +Undocumented internal function. +@end deftypefn */) { return do_accumarray_minmax_fun (args, false); } @@ -7176,10 +7176,10 @@ } DEFUN (__accumdim_sum__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __accumdim_sum__ (@var{idx}, @var{vals}, @var{dim}, @var{n})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __accumdim_sum__ (@var{idx}, @var{vals}, @var{dim}, @var{n}) +Undocumented internal function. +@end deftypefn */) { int nargin = args.length (); @@ -7299,33 +7299,33 @@ } DEFUN (merge, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} merge (@var{mask}, @var{tval}, @var{fval})\n\ -@deftypefnx {} {} ifelse (@var{mask}, @var{tval}, @var{fval})\n\ -Merge elements of @var{true_val} and @var{false_val}, depending on the\n\ -value of @var{mask}.\n\ -\n\ -If @var{mask} is a logical scalar, the other two arguments can be arbitrary\n\ -values. Otherwise, @var{mask} must be a logical array, and @var{tval},\n\ -@var{fval} should be arrays of matching class, or cell arrays. In the\n\ -scalar mask case, @var{tval} is returned if @var{mask} is true, otherwise\n\ -@var{fval} is returned.\n\ -\n\ -In the array mask case, both @var{tval} and @var{fval} must be either\n\ -scalars or arrays with dimensions equal to @var{mask}. The result is\n\ -constructed as follows:\n\ -\n\ -@example\n\ -@group\n\ -result(mask) = tval(mask);\n\ -result(! mask) = fval(! mask);\n\ -@end group\n\ -@end example\n\ -\n\ -@var{mask} can also be arbitrary numeric type, in which case it is first\n\ -converted to logical.\n\ -@seealso{logical, diff}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} merge (@var{mask}, @var{tval}, @var{fval}) +@deftypefnx {} {} 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. +@seealso{logical, diff} +@end deftypefn */) { if (args.length () != 3) print_usage (); @@ -7530,36 +7530,36 @@ } DEFUN (diff, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} diff (@var{x})\n\ -@deftypefnx {} {} diff (@var{x}, @var{k})\n\ -@deftypefnx {} {} diff (@var{x}, @var{k}, @var{dim})\n\ -If @var{x} is a vector of length @math{n}, @w{@code{diff (@var{x})}} is the\n\ -vector of first differences\n\ -@tex\n\ - $x_2 - x_1, \\ldots{}, x_n - x_{n-1}$.\n\ -@end tex\n\ -@ifnottex\n\ - @var{x}(2) - @var{x}(1), @dots{}, @var{x}(n) - @var{x}(n-1).\n\ -@end ifnottex\n\ -\n\ -If @var{x} is a matrix, @w{@code{diff (@var{x})}} is the matrix of column\n\ -differences along the first non-singleton dimension.\n\ -\n\ -The second argument is optional. If supplied,\n\ -@w{@code{diff (@var{x}, @var{k})}}, where @var{k} is a non-negative integer,\n\ -returns the @var{k}-th differences. It is possible that @var{k} is larger\n\ -than the first non-singleton dimension of the matrix. In this case,\n\ -@code{diff} continues to take the differences along the next\n\ -non-singleton dimension.\n\ -\n\ -The dimension along which to take the difference can be explicitly\n\ -stated with the optional variable @var{dim}. In this case the\n\ -@var{k}-th order differences are calculated along this dimension.\n\ -In the case where @var{k} exceeds @w{@code{size (@var{x}, @var{dim})}}\n\ -an empty matrix is returned.\n\ -@seealso{sort, merge}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} diff (@var{x}) +@deftypefnx {} {} diff (@var{x}, @var{k}) +@deftypefnx {} {} 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 (); @@ -7639,30 +7639,30 @@ } DEFUN (repelems, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} repelems (@var{x}, @var{r})\n\ -Construct a vector of repeated elements from @var{x}.\n\ -\n\ -@var{r} is a 2x@var{N} integer matrix specifying which elements to repeat\n\ -and how often to repeat each element. Entries in the first row,\n\ -@var{r}(1,j), select an element to repeat. The corresponding entry in the\n\ -second row, @var{r}(2,j), specifies the repeat count. If @var{x} is a\n\ -matrix then the columns of @var{x} are imagined to be stacked on top of\n\ -each other for purposes of the selection index. A row vector is always\n\ -returned.\n\ -\n\ -Conceptually the result is calculated as follows:\n\ -\n\ -@example\n\ -@group\n\ -y = [];\n\ -for i = 1:columns (@var{r})\n\ - y = [y, @var{x}(@var{r}(1,i)*ones(1, @var{r}(2,i)))];\n\ -endfor\n\ -@end group\n\ -@end example\n\ -@seealso{repmat, cat}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} 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 (); @@ -7722,13 +7722,13 @@ } DEFUN (base64_encode, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{s} =} base64_encode (@var{x})\n\ -Encode a double matrix or array @var{x} into the base64 format string\n\ -@var{s}.\n\ -\n\ -@seealso{base64_decode}\n\ -@end deftypefn") + 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} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -7826,16 +7826,16 @@ */ DEFUN (base64_decode, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{x} =} base64_decode (@var{s})\n\ -@deftypefnx {} {@var{x} =} base64_decode (@var{s}, @var{dims})\n\ -Decode the double matrix or array @var{x} from the base64 encoded string\n\ -@var{s}.\n\ -\n\ -The optional input parameter @var{dims} should be a vector containing the\n\ -dimensions of the decoded array.\n\ -@seealso{base64_encode}\n\ -@end deftypefn") + 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} +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/debug.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/debug.cc Tue Jun 21 16:07:51 2016 -0400 @@ -997,94 +997,94 @@ } DEFUN (dbstop, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} dbstop @var{func}\n\ -@deftypefnx {} {} dbstop @var{func} @var{line}\n\ -@deftypefnx {} {} dbstop @var{func} @var{line1} @var{line2} @dots{}\n\ -@deftypefnx {} {} dbstop @var{line1} @dots{}\n\ -@deftypefnx {} {} dbstop in @var{func}\n\ -@deftypefnx {} {} dbstop in @var{func} at @var{line}\n\ -@deftypefnx {} {} dbstop in @var{func} at @var{line} if \"@var{condition}\"\n\ -@deftypefnx {} {} dbstop if @var{event}\n\ -@deftypefnx {} {} dbstop if @var{event} @var{ID}\n\ -@deftypefnx {} {} dbstop (@var{bp_struct})\n\ -@deftypefnx {} {@var{rline} =} dbstop @dots{}\n\ -\n\ -Set breakpoints for the built-in debugger.\n\ -\n\ -@var{func} is the name of a function on the current @code{path}. When\n\ -already in debug mode the @var{func} argument can be omitted and the current\n\ -function will be used. Breakpoints at subfunctions are set with the scope\n\ -operator @samp{>}. For example, If @file{file.m} has a subfunction\n\ -@code{func2}, then a breakpoint in @code{func2} can be specified by\n\ -@code{file>func2}.\n\ -\n\ -@var{line} is the line number at which to break. If @var{line} is not\n\ -specified, it defaults to the first executable line in the file\n\ -@file{func.m}. Multiple lines can be specified in a single command; when\n\ -function syntax is used, the lines may also be passed as a single vector\n\ -argument (@code{[@var{line1}, @var{line2}, @dots{}]}).\n\ -\n\ -@var{condition} is any Octave expression that can be evaluated in the code\n\ -context that exists at the breakpoint. When the breakpoint is encountered,\n\ -@var{condition} will be evaluated, and execution will stop if\n\ -@var{condition} is true. If @var{condition} cannot be evaluated, for\n\ -example because it refers to an undefined variable, an error will be thrown.\n\ - Expressions with side effects (such as @code{y++ > 1}) will alter\n\ -variables, and should generally be avoided. Conditions containing quotes\n\ -(@samp{\"}, @samp{'}) or comment characters (@samp{#}, @samp{%}) must be\n\ -enclosed in quotes. (This does not apply to conditions entered from the\n\ -editor's context menu.) For example:\n\ -\n\ -@example\n\ -dbstop in strread at 209 if 'any (format == \"%f\")'\n\ -@end example\n\ -\n\ -The form specifying @var{event} does not cause a specific breakpoint at a\n\ -given function and line number. Instead it causes debug mode to be entered\n\ -when certain unexpected events are encountered. Possible values are\n\ -\n\ -@table @code\n\ -@item error\n\ -Stop when an error is reported. This is equivalent to specifying\n\ -both @code{debug_on_error (true)} and @code{debug_on_interrupt (true)}.\n\ -\n\ -@item caught error\n\ -Stop when an error is caught by a try-catch block (not yet implemented).\n\ -\n\ -@item interrupt\n\ -Stop when an interrupt (@kbd{Ctrl-C}) occurs.\n\ -\n\ -@item naninf\n\ -Stop when code returns a non-finite value (not yet implemented).\n\ -\n\ -@item warning\n\ -Stop when a warning is reported. This is equivalent to specifying\n\ -@code{debug_on_warning (true)}.\n\ -@end table\n\ -\n\ -The events @code{error}, @code{caught error}, and @code{warning} can all be\n\ -followed by a string specifying an error ID or warning ID@. If that is\n\ -done, only errors with the specified ID will cause execution to stop. To\n\ -stop on one of a set of IDs, multiple @code{dbstop} commands must be\n\ -issued.\n\ -\n\ -Breakpoints and events can be removed using the @code{dbclear} command with\n\ -the same syntax.\n\ -\n\ -It is possible to save all breakpoints and restore them at once by issuing\n\ -the commands @code{bp_state = dbstatus; @dots{}; dbstop (bp_state)}.\n\ -\n\ -The optional output @var{rline} is the real line number where the breakpoint\n\ -was set. This can differ from the specified line if the line is not\n\ -executable. For example, if a breakpoint attempted on a blank line then\n\ -Octave will set the real breakpoint at the next executable line.\n\ -\n\ -When a file is re-parsed, such as when it is modified outside the GUI,\n\ -all breakpoints within the file are cleared.\n\ -\n\ -@seealso{dbclear, dbstatus, dbstep, debug_on_error, debug_on_warning, debug_on_interrupt}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} dbstop @var{func} +@deftypefnx {} {} dbstop @var{func} @var{line} +@deftypefnx {} {} dbstop @var{func} @var{line1} @var{line2} @dots{} +@deftypefnx {} {} dbstop @var{line1} @dots{} +@deftypefnx {} {} dbstop in @var{func} +@deftypefnx {} {} dbstop in @var{func} at @var{line} +@deftypefnx {} {} dbstop in @var{func} at @var{line} if "@var{condition}" +@deftypefnx {} {} dbstop if @var{event} +@deftypefnx {} {} dbstop if @var{event} @var{ID} +@deftypefnx {} {} dbstop (@var{bp_struct}) +@deftypefnx {} {@var{rline} =} dbstop @dots{} + +Set breakpoints for the built-in debugger. + +@var{func} is the name of a function on the current @code{path}. When +already in debug mode the @var{func} argument can be omitted and the current +function will be used. Breakpoints at subfunctions are set with the scope +operator @samp{>}. For example, If @file{file.m} has a subfunction +@code{func2}, then a breakpoint in @code{func2} can be specified by +@code{file>func2}. + +@var{line} is the line number at which to break. If @var{line} is not +specified, it defaults to the first executable line in the file +@file{func.m}. Multiple lines can be specified in a single command; when +function syntax is used, the lines may also be passed as a single vector +argument (@code{[@var{line1}, @var{line2}, @dots{}]}). + +@var{condition} is any Octave expression that can be evaluated in the code +context that exists at the breakpoint. When the breakpoint is encountered, +@var{condition} will be evaluated, and execution will stop if +@var{condition} is true. If @var{condition} cannot be evaluated, for +example because it refers to an undefined variable, an error will be thrown. + Expressions with side effects (such as @code{y++ > 1}) will alter +variables, and should generally be avoided. Conditions containing quotes +(@samp{"}, @samp{'}) or comment characters (@samp{#}, @samp{%}) must be +enclosed in quotes. (This does not apply to conditions entered from the +editor's context menu.) For example: + +@example +dbstop in strread at 209 if 'any (format == "%f")' +@end example + +The form specifying @var{event} does not cause a specific breakpoint at a +given function and line number. Instead it causes debug mode to be entered +when certain unexpected events are encountered. Possible values are + +@table @code +@item error +Stop when an error is reported. This is equivalent to specifying +both @code{debug_on_error (true)} and @code{debug_on_interrupt (true)}. + +@item caught error +Stop when an error is caught by a try-catch block (not yet implemented). + +@item interrupt +Stop when an interrupt (@kbd{Ctrl-C}) occurs. + +@item naninf +Stop when code returns a non-finite value (not yet implemented). + +@item warning +Stop when a warning is reported. This is equivalent to specifying +@code{debug_on_warning (true)}. +@end table + +The events @code{error}, @code{caught error}, and @code{warning} can all be +followed by a string specifying an error ID or warning ID@. If that is +done, only errors with the specified ID will cause execution to stop. To +stop on one of a set of IDs, multiple @code{dbstop} commands must be +issued. + +Breakpoints and events can be removed using the @code{dbclear} command with +the same syntax. + +It is possible to save all breakpoints and restore them at once by issuing +the commands @code{bp_state = dbstatus; @dots{}; dbstop (bp_state)}. + +The optional output @var{rline} is the real line number where the breakpoint +was set. This can differ from the specified line if the line is not +executable. For example, if a breakpoint attempted on a blank line then +Octave will set the real breakpoint at the next executable line. + +When a file is re-parsed, such as when it is modified outside the GUI, +all breakpoints within the file are cleared. + +@seealso{dbclear, dbstatus, dbstep, debug_on_error, debug_on_warning, debug_on_interrupt} +@end deftypefn */) { bp_table::intmap retmap; std::string symbol_name = ""; // stays empty for "dbstop if error" etc @@ -1165,48 +1165,48 @@ } DEFUN (dbclear, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} dbclear @var{func}\n\ -@deftypefnx {} {} dbclear @var{func} @var{line}\n\ -@deftypefnx {} {} dbclear @var{func} @var{line1} @var{line2} @dots{}\n\ -@deftypefnx {} {} dbclear @var{line} @dots{}\n\ -@deftypefnx {} {} dbclear all\n\ -@deftypefnx {} {} dbclear in @var{func}\n\ -@deftypefnx {} {} dbclear in @var{func} at @var{line}\n\ -@deftypefnx {} {} dbclear if @var{event}\n\ -@deftypefnx {} {} dbclear (\"@var{func}\")\n\ -@deftypefnx {} {} dbclear (\"@var{func}\", @var{line})\n\ -@deftypefnx {} {} dbclear (\"@var{func}\", @var{line1}, @var{line2}, @dots{})\n\ -@deftypefnx {} {} dbclear (\"@var{func}\", @var{line1}, @dots{})\n\ -@deftypefnx {} {} dbclear (@var{line}, @dots{})\n\ -@deftypefnx {} {} dbclear (\"all\")\n\ -Delete a breakpoint at line number @var{line} in the function @var{func}.\n\ -\n\ -Arguments are\n\ -\n\ -@table @var\n\ -@item func\n\ -Function name as a string variable. When already in debug mode this\n\ -argument can be omitted and the current function will be used.\n\ -\n\ -@item line\n\ -Line number from which to remove a breakpoint. Multiple lines may be given\n\ -as separate arguments or as a vector.\n\ -\n\ -@item event\n\ -An event such as @code{error}, @code{interrupt}, or @code{warning}\n\ -(@pxref{XREFdbstop,,dbstop} for details).\n\ -@end table\n\ -\n\ -When called without a line number specification all breakpoints in the named\n\ -function are cleared.\n\ -\n\ -If the requested line is not a breakpoint no action is performed.\n\ -\n\ -The special keyword @qcode{\"all\"} will clear all breakpoints from all\n\ -files.\n\ -@seealso{dbstop, dbstatus, dbwhere}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} dbclear @var{func} +@deftypefnx {} {} dbclear @var{func} @var{line} +@deftypefnx {} {} dbclear @var{func} @var{line1} @var{line2} @dots{} +@deftypefnx {} {} dbclear @var{line} @dots{} +@deftypefnx {} {} dbclear all +@deftypefnx {} {} dbclear in @var{func} +@deftypefnx {} {} dbclear in @var{func} at @var{line} +@deftypefnx {} {} dbclear if @var{event} +@deftypefnx {} {} dbclear ("@var{func}") +@deftypefnx {} {} dbclear ("@var{func}", @var{line}) +@deftypefnx {} {} dbclear ("@var{func}", @var{line1}, @var{line2}, @dots{}) +@deftypefnx {} {} dbclear ("@var{func}", @var{line1}, @dots{}) +@deftypefnx {} {} dbclear (@var{line}, @dots{}) +@deftypefnx {} {} dbclear ("all") +Delete a breakpoint at line number @var{line} in the function @var{func}. + +Arguments are + +@table @var +@item func +Function name as a string variable. When already in debug mode this +argument can be omitted and the current function will be used. + +@item line +Line number from which to remove a breakpoint. Multiple lines may be given +as separate arguments or as a vector. + +@item event +An event such as @code{error}, @code{interrupt}, or @code{warning} +(@pxref{XREFdbstop,,dbstop} for details). +@end table + +When called without a line number specification all breakpoints in the named +function are cleared. + +If the requested line is not a breakpoint no action is performed. + +The special keyword @qcode{"all"} will clear all breakpoints from all +files. +@seealso{dbstop, dbstatus, dbwhere} +@end deftypefn */) { std::string symbol_name = ""; // stays empty for "dbclear if error" etc bp_table::intmap lines; @@ -1336,49 +1336,49 @@ } DEFUN (dbstatus, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} dbstatus\n\ -@deftypefnx {} {} dbstatus @var{func}\n\ -@deftypefnx {} {@var{bp_list} =} dbstatus @dots{}\n\ -Report the location of active breakpoints.\n\ -\n\ -When called with no input or output arguments, print the list of all\n\ -functions with breakpoints and the line numbers where those breakpoints are\n\ -set.\n\ -\n\ -If a function name @var{func} is specified then only report breakpoints\n\ -for the named function and its subfunctions.\n\ -\n\ -The optional return argument @var{bp_list} is a struct array with the\n\ -following fields.\n\ -\n\ -@table @asis\n\ -@item name\n\ -The name of the function with a breakpoint. A subfunction, say @code{func2}\n\ -within an m-file, say @file{file.m}, is specified as @code{file>func2}.\n\ -\n\ -@item file\n\ -The name of the m-file where the function code is located.\n\ -\n\ -@item line\n\ -The line number with the breakpoint.\n\ -\n\ -@item cond\n\ -The condition that must be satisfied for the breakpoint to be active, or\n\ -the empty string for unconditional breakpoints.\n\ -@end table\n\ -\n\ -@c Note: When @code{dbstatus} is called from the debug prompt within a function,\n\ -@c the list of breakpoints is automatically trimmed to the breakpoints in the\n\ -@c current function.\n\ -If @code{dbstop if error} is true but no explicit IDs are specified, the\n\ -return value will have an empty field called @qcode{\"errs\"}. If IDs are\n\ -specified, the @code{errs} field will have one row per ID@. If\n\ -@code{dbstop if error} is false, there is no @qcode{\"errs\"} field.\n\ -The @qcode{\"warn\"} field is set similarly by @code{dbstop if warning}.\n\ -\n\ -@seealso{dbstop, dbclear, dbwhere, dblist, dbstack}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} dbstatus +@deftypefnx {} {} dbstatus @var{func} +@deftypefnx {} {@var{bp_list} =} dbstatus @dots{} +Report the location of active breakpoints. + +When called with no input or output arguments, print the list of all +functions with breakpoints and the line numbers where those breakpoints are +set. + +If a function name @var{func} is specified then only report breakpoints +for the named function and its subfunctions. + +The optional return argument @var{bp_list} is a struct array with the +following fields. + +@table @asis +@item name +The name of the function with a breakpoint. A subfunction, say @code{func2} +within an m-file, say @file{file.m}, is specified as @code{file>func2}. + +@item file +The name of the m-file where the function code is located. + +@item line +The line number with the breakpoint. + +@item cond +The condition that must be satisfied for the breakpoint to be active, or +the empty string for unconditional breakpoints. +@end table + +@c Note: When @code{dbstatus} is called from the debug prompt within a function, +@c the list of breakpoints is automatically trimmed to the breakpoints in the +@c current function. +If @code{dbstop if error} is true but no explicit IDs are specified, the +return value will have an empty field called @qcode{"errs"}. If IDs are +specified, the @code{errs} field will have one row per ID@. If +@code{dbstop if error} is false, there is no @qcode{"errs"} field. +The @qcode{"warn"} field is set similarly by @code{dbstop if warning}. + +@seealso{dbstop, dbclear, dbwhere, dblist, dbstack} +@end deftypefn */) { int nargin = args.length (); @@ -1541,12 +1541,12 @@ */ DEFUN (dbwhere, , , - "-*- texinfo -*-\n\ -@deftypefn {} {} dbwhere\n\ -In debugging mode, report the current file and line number where execution\n\ -is stopped.\n\ -@seealso{dbstack, dblist, dbstatus, dbcont, dbstep, dbup, dbdown}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} dbwhere +In debugging mode, report the current file and line number where execution +is stopped. +@seealso{dbstack, dblist, dbstatus, dbcont, dbstep, dbup, dbdown} +@end deftypefn */) { octave_user_code *dbg_fcn = get_user_code (); @@ -1616,28 +1616,28 @@ } DEFUN (dbtype, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} dbtype\n\ -@deftypefnx {} {} dbtype @var{lineno}\n\ -@deftypefnx {} {} dbtype @var{startl:endl}\n\ -@deftypefnx {} {} dbtype @var{startl:end}\n\ -@deftypefnx {} {} dbtype @var{func}\n\ -@deftypefnx {} {} dbtype @var{func} @var{lineno}\n\ -@deftypefnx {} {} dbtype @var{func} @var{startl:endl}\n\ -@deftypefnx {} {} dbtype @var{func} @var{startl:end}\n\ -Display a script file with line numbers.\n\ -\n\ -When called with no arguments in debugging mode, display the script file\n\ -currently being debugged.\n\ -\n\ -An optional range specification can be used to list only a portion of the\n\ -file. The special keyword @qcode{\"end\"} is a valid line number\n\ -specification for the last line of the file.\n\ -\n\ -When called with the name of a function, list that script file with line\n\ -numbers.\n\ -@seealso{dblist, dbwhere, dbstatus, dbstop}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} dbtype +@deftypefnx {} {} dbtype @var{lineno} +@deftypefnx {} {} dbtype @var{startl:endl} +@deftypefnx {} {} dbtype @var{startl:end} +@deftypefnx {} {} dbtype @var{func} +@deftypefnx {} {} dbtype @var{func} @var{lineno} +@deftypefnx {} {} dbtype @var{func} @var{startl:endl} +@deftypefnx {} {} dbtype @var{func} @var{startl:end} +Display a script file with line numbers. + +When called with no arguments in debugging mode, display the script file +currently being debugged. + +An optional range specification can be used to list only a portion of the +file. The special keyword @qcode{"end"} is a valid line number +specification for the last line of the file. + +When called with the name of a function, list that script file with line +numbers. +@seealso{dblist, dbwhere, dbstatus, dbstop} +@end deftypefn */) { octave_user_code *dbg_fcn; @@ -1763,15 +1763,15 @@ } DEFUN (dblist, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} dblist\n\ -@deftypefnx {} {} dblist @var{n}\n\ -In debugging mode, list @var{n} lines of the function being debugged\n\ -centered around the current line to be executed.\n\ -\n\ -If unspecified @var{n} defaults to 10 (+/- 5 lines)\n\ -@seealso{dbwhere, dbtype, dbstack}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} dblist +@deftypefnx {} {} dblist @var{n} +In debugging mode, list @var{n} lines of the function being debugged +centered around the current line to be executed. + +If unspecified @var{n} defaults to 10 (+/- 5 lines) +@seealso{dbwhere, dbtype, dbstack} +@end deftypefn */) { int n = 10; @@ -1946,48 +1946,48 @@ } DEFUN (dbstack, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} dbstack\n\ -@deftypefnx {} {} dbstack @var{n}\n\ -@deftypefnx {} {} dbstack @var{-completenames}\n\ -@deftypefnx {} {[@var{stack}, @var{idx}] =} dbstack (@dots{})\n\ -Display or return current debugging function stack information.\n\ -\n\ -With optional argument @var{n}, omit the @var{n} innermost stack frames.\n\ -\n\ -Although accepted, the argument @var{-completenames} is silently ignored.\n\ -Octave always returns absolute filenames.\n\ -\n\ -The arguments @var{n} and @var{-completenames} can be both specified in any\n\ -order.\n\ -\n\ -The optional return argument @var{stack} is a struct array with the\n\ -following fields:\n\ -\n\ -@table @asis\n\ -@item file\n\ -The name of the m-file where the function code is located.\n\ -\n\ -@item name\n\ -The name of the function with a breakpoint.\n\ -\n\ -@item line\n\ -The line number of an active breakpoint.\n\ -\n\ -@item column\n\ -The column number of the line where the breakpoint begins.\n\ -\n\ -@item scope\n\ -Undocumented.\n\ -\n\ -@item context\n\ -Undocumented.\n\ -@end table\n\ -\n\ -The return argument @var{idx} specifies which element of the @var{stack}\n\ -struct array is currently active.\n\ -@seealso{dbup, dbdown, dbwhere, dblist, dbstatus}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} dbstack +@deftypefnx {} {} dbstack @var{n} +@deftypefnx {} {} dbstack @var{-completenames} +@deftypefnx {} {[@var{stack}, @var{idx}] =} dbstack (@dots{}) +Display or return current debugging function stack information. + +With optional argument @var{n}, omit the @var{n} innermost stack frames. + +Although accepted, the argument @var{-completenames} is silently ignored. +Octave always returns absolute filenames. + +The arguments @var{n} and @var{-completenames} can be both specified in any +order. + +The optional return argument @var{stack} is a struct array with the +following fields: + +@table @asis +@item file +The name of the m-file where the function code is located. + +@item name +The name of the function with a breakpoint. + +@item line +The line number of an active breakpoint. + +@item column +The column number of the line where the breakpoint begins. + +@item scope +Undocumented. + +@item context +Undocumented. +@end table + +The return argument @var{idx} specifies which element of the @var{stack} +struct array is currently active. +@seealso{dbup, dbdown, dbwhere, dblist, dbstatus} +@end deftypefn */) { return do_dbstack (args, nargout, octave_stdout); } @@ -2019,14 +2019,14 @@ } DEFUN (dbup, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} dbup\n\ -@deftypefnx {} {} dbup @var{n}\n\ -In debugging mode, move up the execution stack @var{n} frames.\n\ -\n\ -If @var{n} is omitted, move up one frame.\n\ -@seealso{dbstack, dbdown}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} dbup +@deftypefnx {} {} dbup @var{n} +In debugging mode, move up the execution stack @var{n} frames. + +If @var{n} is omitted, move up one frame. +@seealso{dbstack, dbdown} +@end deftypefn */) { do_dbupdown (args, "dbup"); @@ -2034,14 +2034,14 @@ } DEFUN (dbdown, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} dbdown\n\ -@deftypefnx {} {} dbdown @var{n}\n\ -In debugging mode, move down the execution stack @var{n} frames.\n\ -\n\ -If @var{n} is omitted, move down one frame.\n\ -@seealso{dbstack, dbup}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} dbdown +@deftypefnx {} {} dbdown @var{n} +In debugging mode, move down the execution stack @var{n} frames. + +If @var{n} is omitted, move down one frame. +@seealso{dbstack, dbup} +@end deftypefn */) { do_dbupdown (args, "dbdown"); @@ -2049,27 +2049,27 @@ } DEFUN (dbstep, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} dbstep\n\ -@deftypefnx {} {} dbstep @var{n}\n\ -@deftypefnx {} {} dbstep in\n\ -@deftypefnx {} {} dbstep out\n\ -@deftypefnx {} {} dbnext @dots{}\n\ -In debugging mode, execute the next @var{n} lines of code.\n\ -\n\ -If @var{n} is omitted, execute the next single line of code. If the next\n\ -line of code is itself defined in terms of an m-file remain in the existing\n\ -function.\n\ -\n\ -Using @code{dbstep in} will cause execution of the next line to step into\n\ -any m-files defined on the next line.\n\ -\n\ -Using @code{dbstep out} will cause execution to continue until the current\n\ -function returns.\n\ -\n\ -@code{dbnext} is an alias for @code{dbstep}.\n\ -@seealso{dbcont, dbquit}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} dbstep +@deftypefnx {} {} dbstep @var{n} +@deftypefnx {} {} dbstep in +@deftypefnx {} {} dbstep out +@deftypefnx {} {} dbnext @dots{} +In debugging mode, execute the next @var{n} lines of code. + +If @var{n} is omitted, execute the next single line of code. If the next +line of code is itself defined in terms of an m-file remain in the existing +function. + +Using @code{dbstep in} will cause execution of the next line to step into +any m-files defined on the next line. + +Using @code{dbstep out} will cause execution to continue until the current +function returns. + +@code{dbnext} is an alias for @code{dbstep}. +@seealso{dbcont, dbquit} +@end deftypefn */) { if (! Vdebugging) error ("dbstep: can only be called in debug mode"); @@ -2120,11 +2120,11 @@ DEFALIAS (dbnext, dbstep); DEFUN (dbcont, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} dbcont\n\ -Leave command-line debugging mode and continue code execution normally.\n\ -@seealso{dbstep, dbquit}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} dbcont +Leave command-line debugging mode and continue code execution normally. +@seealso{dbstep, dbquit} +@end deftypefn */) { if (! Vdebugging) error ("dbcont: can only be called in debug mode"); @@ -2140,12 +2140,12 @@ } DEFUN (dbquit, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} dbquit\n\ -Quit debugging mode immediately without further code execution and return to\n\ -the Octave prompt.\n\ -@seealso{dbcont, dbstep}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} dbquit +Quit debugging mode immediately without further code execution and return to +the Octave prompt. +@seealso{dbcont, dbstep} +@end deftypefn */) { if (! Vdebugging) error ("dbquit: can only be called in debug mode"); @@ -2163,11 +2163,11 @@ } DEFUN (isdebugmode, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isdebugmode ()\n\ -Return true if in debugging mode, otherwise false.\n\ -@seealso{dbwhere, dbstack, dbstatus}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isdebugmode () +Return true if in debugging mode, otherwise false. +@seealso{dbwhere, dbstack, dbstatus} +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -2176,13 +2176,13 @@ } DEFUN (__db_next_breakpoint_quiet__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __db_next_breakpoint_quiet__ ()\n\ -@deftypefnx {} {} __db_next_breakpoint_quiet__ (@var{flag})\n\ -Disable line info printing at the next breakpoint.\n\ -\n\ -With a logical argument @var{flag}, set the state on or off.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __db_next_breakpoint_quiet__ () +@deftypefnx {} {} __db_next_breakpoint_quiet__ (@var{flag}) +Disable line info printing at the next breakpoint. + +With a logical argument @var{flag}, set the state on or off. +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/defaults.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/defaults.cc Tue Jun 21 16:07:51 2016 -0400 @@ -472,22 +472,22 @@ } DEFUN (EDITOR, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} EDITOR ()\n\ -@deftypefnx {} {@var{old_val} =} EDITOR (@var{new_val})\n\ -@deftypefnx {} {} EDITOR (@var{new_val}, \"local\")\n\ -Query or set the internal variable that specifies the default text editor.\n\ -\n\ -The default value is taken from the environment variable @w{@env{EDITOR}}\n\ -when Octave starts. If the environment variable is not initialized,\n\ -@w{@env{EDITOR}} will be set to @qcode{\"emacs\"}.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -\n\ -@seealso{edit, edit_history}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} EDITOR () +@deftypefnx {} {@var{old_val} =} EDITOR (@var{new_val}) +@deftypefnx {} {} EDITOR (@var{new_val}, "local") +Query or set the internal variable that specifies the default text editor. + +The default value is taken from the environment variable @w{@env{EDITOR}} +when Octave starts. If the environment variable is not initialized, +@w{@env{EDITOR}} will be set to @qcode{"emacs"}. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. + +@seealso{edit, edit_history} +@end deftypefn */) { return SET_NONEMPTY_INTERNAL_STRING_VARIABLE (EDITOR); } @@ -505,24 +505,24 @@ */ DEFUN (EXEC_PATH, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} EXEC_PATH ()\n\ -@deftypefnx {} {@var{old_val} =} EXEC_PATH (@var{new_val})\n\ -@deftypefnx {} {} EXEC_PATH (@var{new_val}, \"local\")\n\ -Query or set the internal variable that specifies a colon separated\n\ -list of directories to append to the shell PATH when executing external\n\ -programs.\n\ -\n\ -The initial value of is taken from the environment variable\n\ -@w{@env{OCTAVE_EXEC_PATH}}, but that value can be overridden by the command\n\ -line argument @option{--exec-path PATH}.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -\n\ -@seealso{IMAGE_PATH, OCTAVE_HOME}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} EXEC_PATH () +@deftypefnx {} {@var{old_val} =} EXEC_PATH (@var{new_val}) +@deftypefnx {} {} EXEC_PATH (@var{new_val}, "local") +Query or set the internal variable that specifies a colon separated +list of directories to append to the shell PATH when executing external +programs. + +The initial value of is taken from the environment variable +@w{@env{OCTAVE_EXEC_PATH}}, but that value can be overridden by the command +line argument @option{--exec-path PATH}. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. + +@seealso{IMAGE_PATH, OCTAVE_HOME} +@end deftypefn */) { octave_value retval = SET_NONEMPTY_INTERNAL_STRING_VARIABLE (EXEC_PATH); @@ -545,19 +545,19 @@ */ DEFUN (IMAGE_PATH, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} IMAGE_PATH ()\n\ -@deftypefnx {} {@var{old_val} =} IMAGE_PATH (@var{new_val})\n\ -@deftypefnx {} {} IMAGE_PATH (@var{new_val}, \"local\")\n\ -Query or set the internal variable that specifies a colon separated\n\ -list of directories in which to search for image files.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -\n\ -@seealso{EXEC_PATH, OCTAVE_HOME}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} IMAGE_PATH () +@deftypefnx {} {@var{old_val} =} IMAGE_PATH (@var{new_val}) +@deftypefnx {} {} IMAGE_PATH (@var{new_val}, "local") +Query or set the internal variable that specifies a colon separated +list of directories in which to search for image files. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. + +@seealso{EXEC_PATH, OCTAVE_HOME} +@end deftypefn */) { return SET_NONEMPTY_INTERNAL_STRING_VARIABLE (IMAGE_PATH); } @@ -575,11 +575,11 @@ */ DEFUN (OCTAVE_HOME, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} OCTAVE_HOME ()\n\ -Return the name of the top-level Octave installation directory.\n\ -@seealso{EXEC_PATH, IMAGE_PATH}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} OCTAVE_HOME () +Return the name of the top-level Octave installation directory. +@seealso{EXEC_PATH, IMAGE_PATH} +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -593,11 +593,11 @@ */ DEFUNX ("OCTAVE_VERSION", FOCTAVE_VERSION, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} OCTAVE_VERSION ()\n\ -Return the version number of Octave as a string.\n\ -@seealso{ver, version}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} OCTAVE_VERSION () +Return the version number of Octave as a string. +@seealso{ver, version} +@end deftypefn */) { if (args.length () != 0) print_usage ();
--- a/libinterp/corefcn/defun-dld.h Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/defun-dld.h Tue Jun 21 16:07:51 2016 -0400 @@ -38,36 +38,18 @@ // functions, this is the same as DEFUN, except that it will generate // an extra externally visible function. // -// The first DECLARE_FUN is for the benefit of the installer function -// and the second is for the definition of the function. - -#if defined (MAKE_BUILTINS) +// The FORWARD_DECLARE_FUN is for the benefit of the installer function. +// +// The DECLARE_FUN is for the definition of the function. #define DEFUN_DLD(name, args_name, nargout_name, doc) \ - DEFUN_DLD_INTERNAL (name, args_name, nargout_name, doc) - -// This one can be used when 'name' cannot be used directly (if it is -// already defined as a macro). In that case, name is already a -// quoted string, and the internal name of the function must be passed -// too (the convention is to use a prefix of "F", so "foo" becomes -// "Ffoo") as well as the name of the generated installer function -// (the convention is to use a prefix of "G", so "foo" becomes "Gfoo"). - -#define DEFUNX_DLD(name, fname, gname, args_name, nargout_name, doc) \ - DEFUNX_DLD_INTERNAL (name, fname, args_name, nargout_name, doc) - -#else - -#define DEFUN_DLD(name, args_name, nargout_name, doc) \ - DECLARE_FUN (name, args_name, nargout_name); \ + FORWARD_DECLARE_FUN (name); \ DEFINE_FUN_INSTALLER_FUN (name, doc) \ DECLARE_FUN (name, args_name, nargout_name) #define DEFUNX_DLD(name, fname, gname, args_name, nargout_name, doc) \ - DECLARE_FUNX (fname, args_name, nargout_name); \ + FORWARD_DECLARE_FUNX (fname); \ DEFINE_FUNX_INSTALLER_FUN (name, fname, gname, doc) \ DECLARE_FUNX (fname, args_name, nargout_name) #endif - -#endif
--- a/libinterp/corefcn/defun-int.h Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/defun-int.h Tue Jun 21 16:07:51 2016 -0400 @@ -80,6 +80,13 @@ extern OCTINTERP_API void defun_isargout (int, int, bool *); +#define FORWARD_DECLARE_FUNX(name) \ + extern OCTAVE_EXPORT octave_value_list \ + name (const octave_value_list& = octave_value_list (), int = 0) + +#define FORWARD_DECLARE_FUN(name) \ + FORWARD_DECLARE_FUNX (F ## name) + #define DECLARE_FUNX(name, args_name, nargout_name) \ OCTAVE_EXPORT octave_value_list \ name (const octave_value_list& args_name, int nargout_name) @@ -96,8 +103,13 @@ typedef octave_function * (*octave_dld_fcn_getter) (const octave::dynamic_library&, bool relative); -#define DEFINE_FUN_INSTALLER_FUN(name, doc) \ - DEFINE_FUNX_INSTALLER_FUN(#name, F ## name, G ## name, doc) +#if defined (OCTAVE_SOURCE) +# define DEFINE_FUN_INSTALLER_FUN(name, doc) \ + DEFINE_FUNX_INSTALLER_FUN(#name, F ## name, G ## name, "external-doc") +#else +# define DEFINE_FUN_INSTALLER_FUN(name, doc) \ + DEFINE_FUNX_INSTALLER_FUN(#name, F ## name, G ## name, doc) +#endif #define DEFINE_FUNX_INSTALLER_FUN(name, fname, gname, doc) \ extern "C" \ @@ -115,70 +127,4 @@ return fcn; \ } -// MAKE_BUILTINS is defined to extract function names and related -// information and create the *.df files that are eventually used to -// create the builtins.cc file. - -#if defined (MAKE_BUILTINS) - -// Generate code to install name in the symbol table. The script -// mkdefs will create a .def file for every .cc file that uses DEFUN, -// or DEFCMD. - -#define DEFUN_INTERNAL(name, args_name, nargout_name, doc) \ - BEGIN_INSTALL_BUILTIN \ - XDEFUN_INTERNAL (name, args_name, nargout_name, doc) \ - END_INSTALL_BUILTIN - -#define DEFCONSTFUN_INTERNAL(name, args_name, nargout_name, doc) \ - BEGIN_INSTALL_BUILTIN \ - XDEFCONSTFUN_INTERNAL (name, args_name, nargout_name, doc) \ - END_INSTALL_BUILTIN - -#define DEFUNX_INTERNAL(name, fname, args_name, nargout_name, doc) \ - BEGIN_INSTALL_BUILTIN \ - XDEFUNX_INTERNAL (name, fname, args_name, nargout_name, doc) \ - END_INSTALL_BUILTIN - -// Generate code to install name in the symbol table. The script -// mkdefs will create a .def file for every .cc file that uses -// DEFUN_DLD. - -#define DEFUN_DLD_INTERNAL(name, args_name, nargout_name, doc) \ - BEGIN_INSTALL_BUILTIN \ - XDEFUN_DLD_INTERNAL (name, args_name, nargout_name, doc) \ - END_INSTALL_BUILTIN - -#define DEFUNX_DLD_INTERNAL(name, fname, args_name, nargout_name, doc) \ - BEGIN_INSTALL_BUILTIN \ - XDEFUNX_DLD_INTERNAL (name, fname, args_name, nargout_name, doc) \ - END_INSTALL_BUILTIN - -// Generate code for making another name for an existing function. - -#define DEFALIAS_INTERNAL(alias, name) \ - BEGIN_INSTALL_BUILTIN \ - XDEFALIAS_INTERNAL(alias, name) \ - END_INSTALL_BUILTIN - -#else - -// Generate the first line of the function definition. This ensures -// that the internal functions all have the same signature. - -#define DEFUN_INTERNAL(name, args_name, nargout_name, doc) \ - DECLARE_FUN (name, args_name, nargout_name) - -#define DEFCONSTFUN_INTERNAL(name, args_name, nargout_name, doc) \ - DECLARE_FUN (name, args_name, nargout_name) - -#define DEFUNX_INTERNAL(name, fname, args_name, nargout_name, doc) \ - DECLARE_FUNX (fname, args_name, nargout_name) - -// No definition is required for an alias. - -#define DEFALIAS_INTERNAL(alias, name) - #endif - -#endif
--- a/libinterp/corefcn/defun.h Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/defun.h Tue Jun 21 16:07:51 2016 -0400 @@ -44,7 +44,7 @@ // doc is the simple help text for the function. #define DEFUN(name, args_name, nargout_name, doc) \ - DEFUN_INTERNAL (name, args_name, nargout_name, doc) + DECLARE_FUN (name, args_name, nargout_name) // This one can be used when 'name' cannot be used directly (if it is // already defined as a macro). In that case, name is already a @@ -52,17 +52,16 @@ // too (the convention is to use a prefix of "F", so "foo" becomes "Ffoo"). #define DEFUNX(name, fname, args_name, nargout_name, doc) \ - DEFUNX_INTERNAL (name, fname, args_name, nargout_name, doc) + DECLARE_FUNX (fname, args_name, nargout_name) // This is a function with a name that can't be hidden by a variable. #define DEFCONSTFUN(name, args_name, nargout_name, doc) \ - DEFCONSTFUN_INTERNAL (name, args_name, nargout_name, doc) + DECLARE_FUN (name, args_name, nargout_name) // Make alias another name for the existing function name. This macro -// must be used in the same file where name is defined, after the -// definition for name. +// is processed by the mkbuiltins to generate code in builtins.cc to +// create the alias in the symbol table. -#define DEFALIAS(alias, name) \ - DEFALIAS_INTERNAL (alias, name) +#define DEFALIAS(alias, name) #endif
--- a/libinterp/corefcn/det.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/det.cc Tue Jun 21 16:07:51 2016 -0400 @@ -48,21 +48,21 @@ dynamic_cast<const CLASS *> (&arg.get_rep ()) : 0 DEFUN (det, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} det (@var{A})\n\ -@deftypefnx {} {[@var{d}, @var{rcond}] =} det (@var{A})\n\ -Compute the determinant of @var{A}.\n\ -\n\ -Return an estimate of the reciprocal condition number if requested.\n\ -\n\ -Programming Notes: Routines from @sc{lapack} are used for full matrices and\n\ -code from @sc{umfpack} is used for sparse matrices.\n\ -\n\ -The determinant should not be used to check a matrix for singularity.\n\ -For that, use any of the condition number functions: @code{cond},\n\ -@code{condest}, @code{rcond}.\n\ -@seealso{cond, condest, rcond}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} det (@var{A}) +@deftypefnx {} {[@var{d}, @var{rcond}] =} det (@var{A}) +Compute the determinant of @var{A}. + +Return an estimate of the reciprocal condition number if requested. + +Programming Notes: Routines from @sc{lapack} are used for full matrices and +code from @sc{umfpack} is used for sparse matrices. + +The determinant should not be used to check a matrix for singularity. +For that, use any of the condition number functions: @code{cond}, +@code{condest}, @code{rcond}. +@seealso{cond, condest, rcond} +@end deftypefn */) { if (args.length () != 1) print_usage ();
--- a/libinterp/corefcn/dirfns.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/dirfns.cc Tue Jun 21 16:07:51 2016 -0400 @@ -88,34 +88,34 @@ } DEFUN (cd, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} cd @var{dir}\n\ -@deftypefnx {} {} cd\n\ -@deftypefnx {} {@var{old_dir} =} cd (@var{dir})\n\ -@deftypefnx {} {} chdir @dots{}\n\ -Change the current working directory to @var{dir}.\n\ -\n\ -If @var{dir} is omitted, the current directory is changed to the user's home\n\ -directory (@qcode{\"~\"}).\n\ -\n\ -For example,\n\ -\n\ -@example\n\ -cd ~/octave\n\ -@end example\n\ -\n\ -@noindent\n\ -changes the current working directory to @file{~/octave}. If the\n\ -directory does not exist, an error message is printed and the working\n\ -directory is not changed.\n\ -\n\ -@code{chdir} is an alias for @code{cd} and can be used in all of the same\n\ -calling formats.\n\ -\n\ -Compatibility Note: When called with no arguments, @sc{matlab} prints the\n\ -present working directory rather than changing to the user's home directory.\n\ -@seealso{pwd, mkdir, rmdir, dir, ls}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} cd @var{dir} +@deftypefnx {} {} cd +@deftypefnx {} {@var{old_dir} =} cd (@var{dir}) +@deftypefnx {} {} chdir @dots{} +Change the current working directory to @var{dir}. + +If @var{dir} is omitted, the current directory is changed to the user's home +directory (@qcode{"~"}). + +For example, + +@example +cd ~/octave +@end example + +@noindent +changes the current working directory to @file{~/octave}. If the +directory does not exist, an error message is printed and the working +directory is not changed. + +@code{chdir} is an alias for @code{cd} and can be used in all of the same +calling formats. + +Compatibility Note: When called with no arguments, @sc{matlab} prints the +present working directory rather than changing to the user's home directory. +@seealso{pwd, mkdir, rmdir, dir, ls} +@end deftypefn */) { int nargin = args.length (); @@ -148,29 +148,29 @@ DEFALIAS (chdir, cd); DEFUN (pwd, , , - "-*- texinfo -*-\n\ -@deftypefn {} {} pwd ()\n\ -@deftypefnx {} {@var{dir} =} pwd ()\n\ -Return the current working directory.\n\ -@seealso{cd, dir, ls, mkdir, rmdir}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} pwd () +@deftypefnx {} {@var{dir} =} pwd () +Return the current working directory. +@seealso{cd, dir, ls, mkdir, rmdir} +@end deftypefn */) { return ovl (octave::sys::env::get_current_directory ()); } DEFUN (readdir, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{files} =} readdir (@var{dir})\n\ -@deftypefnx {} {[@var{files}, @var{err}, @var{msg}] =} readdir (@var{dir})\n\ -Return the names of files in the directory @var{dir} as a cell array of\n\ -strings.\n\ -\n\ -If an error occurs, return an empty cell array in @var{files}.\n\ -If successful, @var{err} is 0 and @var{msg} is an empty string.\n\ -Otherwise, @var{err} is nonzero and @var{msg} contains a system-dependent\n\ -error message.\n\ -@seealso{ls, dir, glob, what}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{files} =} readdir (@var{dir}) +@deftypefnx {} {[@var{files}, @var{err}, @var{msg}] =} readdir (@var{dir}) +Return the names of files in the directory @var{dir} as a cell array of +strings. + +If an error occurs, return an empty cell array in @var{files}. +If successful, @var{err} is 0 and @var{msg} is an empty string. +Otherwise, @var{err} is nonzero and @var{msg} contains a system-dependent +error message. +@seealso{ls, dir, glob, what} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -199,11 +199,11 @@ // OTOH, that might cause trouble with compatibility later... DEFUN (__mkdir__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __mkdir__ (@var{parent}, @var{dir})\n\ -Internal function called by mkdir.m.\n\ -@seealso{mkdir, rmdir, pwd, cd, umask}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __mkdir__ (@var{parent}, @var{dir}) +Internal function called by mkdir.m. +@seealso{mkdir, rmdir, pwd, cd, umask} +@end deftypefn */) { int nargin = args.length (); @@ -245,22 +245,22 @@ } DEFUNX ("rmdir", Frmdir, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} rmdir @var{dir}\n\ -@deftypefnx {} {} rmdir (@var{dir}, \"s\")\n\ -@deftypefnx {} {[@var{status}, @var{msg}, @var{msgid}] =} rmdir (@dots{})\n\ -Remove the directory named @var{dir}.\n\ -\n\ -If the optional second parameter is supplied with value @qcode{\"s\"},\n\ -recursively remove all subdirectories as well.\n\ -\n\ -If successful, @var{status} is 1, and @var{msg}, @var{msgid} are empty\n\ -character strings (""). Otherwise, @var{status} is 0, @var{msg} contains a\n\ -system-dependent error message, and @var{msgid} contains a unique message\n\ -identifier.\n\ -\n\ -@seealso{mkdir, confirm_recursive_rmdir, pwd}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} rmdir @var{dir} +@deftypefnx {} {} rmdir (@var{dir}, "s") +@deftypefnx {} {[@var{status}, @var{msg}, @var{msgid}] =} rmdir (@dots{}) +Remove the directory named @var{dir}. + +If the optional second parameter is supplied with value @qcode{"s"}, +recursively remove all subdirectories as well. + +If successful, @var{status} is 1, and @var{msg}, @var{msgid} are empty +character strings (""). Otherwise, @var{status} is 0, @var{msg} contains a +system-dependent error message, and @var{msgid} contains a unique message +identifier. + +@seealso{mkdir, confirm_recursive_rmdir, pwd} +@end deftypefn */) { int nargin = args.length (); @@ -300,16 +300,16 @@ } DEFUNX ("link", Flink, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} link @var{old} @var{new}\n\ -@deftypefnx {} {[@var{err}, @var{msg}] =} link (@var{old}, @var{new})\n\ -Create a new link (also known as a hard link) to an existing file.\n\ -\n\ -If successful, @var{err} is 0 and @var{msg} is an empty string.\n\ -Otherwise, @var{err} is nonzero and @var{msg} contains a system-dependent\n\ -error message.\n\ -@seealso{symlink, unlink, readlink, lstat}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} link @var{old} @var{new} +@deftypefnx {} {[@var{err}, @var{msg}] =} link (@var{old}, @var{new}) +Create a new link (also known as a hard link) to an existing file. + +If successful, @var{err} is 0 and @var{msg} is an empty string. +Otherwise, @var{err} is nonzero and @var{msg} contains a system-dependent +error message. +@seealso{symlink, unlink, readlink, lstat} +@end deftypefn */) { if (args.length () != 2) print_usage (); @@ -331,16 +331,16 @@ } DEFUNX ("symlink", Fsymlink, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} symlink @var{old} @var{new}\n\ -@deftypefnx {} {[@var{err}, @var{msg}] =} symlink (@var{old}, @var{new})\n\ -Create a symbolic link @var{new} which contains the string @var{old}.\n\ -\n\ -If successful, @var{err} is 0 and @var{msg} is an empty string.\n\ -Otherwise, @var{err} is nonzero and @var{msg} contains a system-dependent\n\ -error message.\n\ -@seealso{link, unlink, readlink, lstat}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} symlink @var{old} @var{new} +@deftypefnx {} {[@var{err}, @var{msg}] =} symlink (@var{old}, @var{new}) +Create a symbolic link @var{new} which contains the string @var{old}. + +If successful, @var{err} is 0 and @var{msg} is an empty string. +Otherwise, @var{err} is nonzero and @var{msg} contains a system-dependent +error message. +@seealso{link, unlink, readlink, lstat} +@end deftypefn */) { if (args.length () != 2) print_usage (); @@ -362,17 +362,17 @@ } DEFUNX ("readlink", Freadlink, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} readlink @var{symlink}\n\ -@deftypefnx {} {[@var{result}, @var{err}, @var{msg}] =} readlink (@var{symlink})\n\ -Read the value of the symbolic link @var{symlink}.\n\ -\n\ -If successful, @var{result} contains the contents of the symbolic link\n\ -@var{symlink}, @var{err} is 0, and @var{msg} is an empty string.\n\ -Otherwise, @var{err} is nonzero and @var{msg} contains a system-dependent\n\ -error message.\n\ -@seealso{lstat, symlink, link, unlink, delete}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} readlink @var{symlink} +@deftypefnx {} {[@var{result}, @var{err}, @var{msg}] =} readlink (@var{symlink}) +Read the value of the symbolic link @var{symlink}. + +If successful, @var{result} contains the contents of the symbolic link +@var{symlink}, @var{err} is 0, and @var{msg} is an empty string. +Otherwise, @var{err} is nonzero and @var{msg} contains a system-dependent +error message. +@seealso{lstat, symlink, link, unlink, delete} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -392,16 +392,16 @@ } DEFUNX ("rename", Frename, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} rename @var{old} @var{new}\n\ -@deftypefnx {} {[@var{err}, @var{msg}] =} rename (@var{old}, @var{new})\n\ -Change the name of file @var{old} to @var{new}.\n\ -\n\ -If successful, @var{err} is 0 and @var{msg} is an empty string.\n\ -Otherwise, @var{err} is nonzero and @var{msg} contains a system-dependent\n\ -error message.\n\ -@seealso{movefile, copyfile, ls, dir}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} rename @var{old} @var{new} +@deftypefnx {} {[@var{err}, @var{msg}] =} rename (@var{old}, @var{new}) +Change the name of file @var{old} to @var{new}. + +If successful, @var{err} is 0 and @var{msg} is an empty string. +Otherwise, @var{err} is nonzero and @var{msg} contains a system-dependent +error message. +@seealso{movefile, copyfile, ls, dir} +@end deftypefn */) { if (args.length () != 2) print_usage (); @@ -423,55 +423,55 @@ } DEFUN (glob, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} glob (@var{pattern})\n\ -Given an array of pattern strings (as a char array or a cell array) in\n\ -@var{pattern}, return a cell array of filenames that match any of\n\ -them, or an empty cell array if no patterns match.\n\ -\n\ -The pattern strings are interpreted as filename globbing patterns (as they\n\ -are used by Unix shells).\n\ -\n\ -Within a pattern\n\ -\n\ -@table @code\n\ -@item *\n\ -matches any string, including the null string,\n\ -\n\ -@item ?\n\ -matches any single character, and\n\ -\n\ -@item [@dots{}]\n\ -matches any of the enclosed characters.\n\ -@end table\n\ -\n\ -Tilde expansion is performed on each of the patterns before looking for\n\ -matching filenames. For example:\n\ -\n\ -@example\n\ -ls\n\ - @result{}\n\ - file1 file2 file3 myfile1 myfile1b\n\ -glob (\"*file1\")\n\ - @result{}\n\ - @{\n\ - [1,1] = file1\n\ - [2,1] = myfile1\n\ - @}\n\ -glob (\"myfile?\")\n\ - @result{}\n\ - @{\n\ - [1,1] = myfile1\n\ - @}\n\ -glob (\"file[12]\")\n\ - @result{}\n\ - @{\n\ - [1,1] = file1\n\ - [2,1] = file2\n\ - @}\n\ -@end example\n\ -@seealso{ls, dir, readdir, what}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} glob (@var{pattern}) +Given an array of pattern strings (as a char array or a cell array) in +@var{pattern}, return a cell array of filenames that match any of +them, or an empty cell array if no patterns match. + +The pattern strings are interpreted as filename globbing patterns (as they +are used by Unix shells). + +Within a pattern + +@table @code +@item * +matches any string, including the null string, + +@item ? +matches any single character, and + +@item [@dots{}] +matches any of the enclosed characters. +@end table + +Tilde expansion is performed on each of the patterns before looking for +matching filenames. For example: + +@example +ls + @result{} + file1 file2 file3 myfile1 myfile1b +glob ("*file1") + @result{} + @{ + [1,1] = file1 + [2,1] = myfile1 + @} +glob ("myfile?") + @result{} + @{ + [1,1] = myfile1 + @} +glob ("file[12]") + @result{} + @{ + [1,1] = file1 + [2,1] = file2 + @} +@end example +@seealso{ls, dir, readdir, what} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -516,22 +516,22 @@ */ DEFUN (__fnmatch__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} fnmatch (@var{pattern}, @var{string})\n\ -Return true or false for each element of @var{string} that matches any of\n\ -the elements of the string array @var{pattern}, using the rules of\n\ -filename pattern matching.\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -fnmatch (\"a*b\", @{\"ab\"; \"axyzb\"; \"xyzab\"@})\n\ - @result{} [ 1; 1; 0 ]\n\ -@end group\n\ -@end example\n\ -@seealso{glob, regexp}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} fnmatch (@var{pattern}, @var{string}) +Return true or false for each element of @var{string} that matches any of +the elements of the string array @var{pattern}, using the rules of +filename pattern matching. + +For example: + +@example +@group +fnmatch ("a*b", @{"ab"; "axyzb"; "xyzab"@}) + @result{} [ 1; 1; 0 ] +@end group +@end example +@seealso{glob, regexp} +@end deftypefn */) { if (args.length () != 2) print_usage (); @@ -545,17 +545,17 @@ } DEFUN (filesep, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} filesep ()\n\ -@deftypefnx {} {} filesep (\"all\")\n\ -Return the system-dependent character used to separate directory names.\n\ -\n\ -If @qcode{\"all\"} is given, the function returns all valid file separators\n\ -in the form of a string. The list of file separators is system-dependent.\n\ -It is @samp{/} (forward slash) under UNIX or @w{Mac OS X}, @samp{/} and\n\ -@samp{\\} (forward and backward slashes) under Windows.\n\ -@seealso{pathsep}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} filesep () +@deftypefnx {} {} filesep ("all") +Return the system-dependent character used to separate directory names. + +If @qcode{"all"} is given, the function returns all valid file separators +in the form of a string. The list of file separators is system-dependent. +It is @samp{/} (forward slash) under UNIX or @w{Mac OS X}, @samp{/} and +@samp{\} (forward and backward slashes) under Windows. +@seealso{pathsep} +@end deftypefn */) { int nargin = args.length (); @@ -579,12 +579,12 @@ } DEFUN (pathsep, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} pathsep ()\n\ -@deftypefnx {} {@var{old_val} =} pathsep (@var{new_val})\n\ -Query or set the character used to separate directories in a path.\n\ -@seealso{filesep}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} pathsep () +@deftypefnx {} {@var{old_val} =} pathsep (@var{new_val}) +Query or set the character used to separate directories in a path. +@seealso{filesep} +@end deftypefn */) { int nargin = args.length (); @@ -620,18 +620,18 @@ } DEFUN (confirm_recursive_rmdir, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} confirm_recursive_rmdir ()\n\ -@deftypefnx {} {@var{old_val} =} confirm_recursive_rmdir (@var{new_val})\n\ -@deftypefnx {} {} confirm_recursive_rmdir (@var{new_val}, \"local\")\n\ -Query or set the internal variable that controls whether Octave\n\ -will ask for confirmation before recursively removing a directory tree.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{rmdir}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} confirm_recursive_rmdir () +@deftypefnx {} {@var{old_val} =} confirm_recursive_rmdir (@var{new_val}) +@deftypefnx {} {} confirm_recursive_rmdir (@var{new_val}, "local") +Query or set the internal variable that controls whether Octave +will ask for confirmation before recursively removing a directory tree. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{rmdir} +@end deftypefn */) { return SET_INTERNAL_VARIABLE (confirm_recursive_rmdir); }
--- a/libinterp/corefcn/dlmread.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/dlmread.cc Tue Jun 21 16:07:51 2016 -0400 @@ -157,38 +157,38 @@ } DEFUN (dlmread, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{data} =} dlmread (@var{file})\n\ -@deftypefnx {} {@var{data} =} dlmread (@var{file}, @var{sep})\n\ -@deftypefnx {} {@var{data} =} dlmread (@var{file}, @var{sep}, @var{r0}, @var{c0})\n\ -@deftypefnx {} {@var{data} =} dlmread (@var{file}, @var{sep}, @var{range})\n\ -@deftypefnx {} {@var{data} =} dlmread (@dots{}, \"emptyvalue\", @var{EMPTYVAL})\n\ -Read numeric data from the text file @var{file} which uses the delimiter\n\ -@var{sep} between data values.\n\ -\n\ -If @var{sep} is not defined the separator between fields is determined from\n\ -the file itself.\n\ -\n\ -The optional scalar arguments @var{r0} and @var{c0} define the starting row\n\ -and column of the data to be read. These values are indexed from zero,\n\ -i.e., the first data row corresponds to an index of zero.\n\ -\n\ -The @var{range} parameter specifies exactly which data elements are read.\n\ -The first form of the parameter is a 4-element vector containing the upper\n\ -left and lower right corners @code{[@var{R0},@var{C0},@var{R1},@var{C1}]}\n\ -where the indices are zero-based. Alternatively, a spreadsheet style\n\ -form such as @qcode{\"A2..Q15\"} or @qcode{\"T1:AA5\"} can be used. The\n\ -lowest alphabetical index @qcode{'A'} refers to the first column. The\n\ -lowest row index is 1.\n\ -\n\ -@var{file} should be a filename or a file id given by @code{fopen}. In the\n\ -latter case, the file is read until end of file is reached.\n\ -\n\ -The @qcode{\"emptyvalue\"} option may be used to specify the value used to\n\ -fill empty fields. The default is zero. Note that any non-numeric values,\n\ -such as text, are also replaced by the @qcode{\"emptyvalue\"}.\n\ -@seealso{csvread, textscan, textread, dlmwrite}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{data} =} dlmread (@var{file}) +@deftypefnx {} {@var{data} =} dlmread (@var{file}, @var{sep}) +@deftypefnx {} {@var{data} =} dlmread (@var{file}, @var{sep}, @var{r0}, @var{c0}) +@deftypefnx {} {@var{data} =} dlmread (@var{file}, @var{sep}, @var{range}) +@deftypefnx {} {@var{data} =} dlmread (@dots{}, "emptyvalue", @var{EMPTYVAL}) +Read numeric data from the text file @var{file} which uses the delimiter +@var{sep} between data values. + +If @var{sep} is not defined the separator between fields is determined from +the file itself. + +The optional scalar arguments @var{r0} and @var{c0} define the starting row +and column of the data to be read. These values are indexed from zero, +i.e., the first data row corresponds to an index of zero. + +The @var{range} parameter specifies exactly which data elements are read. +The first form of the parameter is a 4-element vector containing the upper +left and lower right corners @code{[@var{R0},@var{C0},@var{R1},@var{C1}]} +where the indices are zero-based. Alternatively, a spreadsheet style +form such as @qcode{"A2..Q15"} or @qcode{"T1:AA5"} can be used. The +lowest alphabetical index @qcode{'A'} refers to the first column. The +lowest row index is 1. + +@var{file} should be a filename or a file id given by @code{fopen}. In the +latter case, the file is read until end of file is reached. + +The @qcode{"emptyvalue"} option may be used to specify the value used to +fill empty fields. The default is zero. Note that any non-numeric values, +such as text, are also replaced by the @qcode{"emptyvalue"}. +@seealso{csvread, textscan, textread, dlmwrite} +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/dot.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/dot.cc Tue Jun 21 16:07:51 2016 -0400 @@ -104,23 +104,23 @@ } DEFUN (dot, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} dot (@var{x}, @var{y}, @var{dim})\n\ -Compute the dot product of two vectors.\n\ -\n\ -If @var{x} and @var{y} are matrices, calculate the dot products along the\n\ -first non-singleton dimension.\n\ -\n\ -If the optional argument @var{dim} is given, calculate the dot products\n\ -along this dimension.\n\ -\n\ -This is equivalent to\n\ -@code{sum (conj (@var{X}) .* @var{Y}, @var{dim})},\n\ -but avoids forming a temporary array and is faster. When @var{X} and\n\ -@var{Y} are column vectors, the result is equivalent to\n\ -@code{@var{X}' * @var{Y}}.\n\ -@seealso{cross, divergence}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} dot (@var{x}, @var{y}, @var{dim}) +Compute the dot product of two vectors. + +If @var{x} and @var{y} are matrices, calculate the dot products along the +first non-singleton dimension. + +If the optional argument @var{dim} is given, calculate the dot products +along this dimension. + +This is equivalent to +@code{sum (conj (@var{X}) .* @var{Y}, @var{dim})}, +but avoids forming a temporary array and is faster. When @var{X} and +@var{Y} are column vectors, the result is equivalent to +@code{@var{X}' * @var{Y}}. +@seealso{cross, divergence} +@end deftypefn */) { int nargin = args.length (); @@ -267,23 +267,23 @@ */ DEFUN (blkmm, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} blkmm (@var{A}, @var{B})\n\ -Compute products of matrix blocks.\n\ -\n\ -The blocks are given as 2-dimensional subarrays of the arrays @var{A},\n\ -@var{B}. The size of @var{A} must have the form @code{[m,k,@dots{}]} and\n\ -size of @var{B} must be @code{[k,n,@dots{}]}. The result is then of size\n\ -@code{[m,n,@dots{}]} and is computed as follows:\n\ -\n\ -@example\n\ -@group\n\ -for i = 1:prod (size (@var{A})(3:end))\n\ - @var{C}(:,:,i) = @var{A}(:,:,i) * @var{B}(:,:,i)\n\ -endfor\n\ -@end group\n\ -@end example\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} blkmm (@var{A}, @var{B}) +Compute products of matrix blocks. + +The blocks are given as 2-dimensional subarrays of the arrays @var{A}, +@var{B}. The size of @var{A} must have the form @code{[m,k,@dots{}]} and +size of @var{B} must be @code{[k,n,@dots{}]}. The result is then of size +@code{[m,n,@dots{}]} and is computed as follows: + +@example +@group +for i = 1:prod (size (@var{A})(3:end)) + @var{C}(:,:,i) = @var{A}(:,:,i) * @var{B}(:,:,i) +endfor +@end group +@end example +@end deftypefn */) { if (args.length () != 2) print_usage ();
--- a/libinterp/corefcn/eig.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/eig.cc Tue Jun 21 16:07:51 2016 -0400 @@ -34,21 +34,21 @@ #include "utils.h" DEFUN (eig, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{lambda} =} eig (@var{A})\n\ -@deftypefnx {} {@var{lambda} =} eig (@var{A}, @var{B})\n\ -@deftypefnx {} {[@var{V}, @var{lambda}] =} eig (@var{A})\n\ -@deftypefnx {} {[@var{V}, @var{lambda}] =} eig (@var{A}, @var{B})\n\ -Compute the eigenvalues (and optionally the eigenvectors) of a matrix\n\ -or a pair of matrices\n\ -\n\ -The algorithm used depends on whether there are one or two input\n\ -matrices, if they are real or complex, and if they are symmetric\n\ -(Hermitian if complex) or non-symmetric.\n\ -\n\ -The eigenvalues returned by @code{eig} are not ordered.\n\ -@seealso{eigs, svd}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{lambda} =} eig (@var{A}) +@deftypefnx {} {@var{lambda} =} eig (@var{A}, @var{B}) +@deftypefnx {} {[@var{V}, @var{lambda}] =} eig (@var{A}) +@deftypefnx {} {[@var{V}, @var{lambda}] =} eig (@var{A}, @var{B}) +Compute the eigenvalues (and optionally the eigenvectors) of a matrix +or a pair of matrices + +The algorithm used depends on whether there are one or two input +matrices, if they are real or complex, and if they are symmetric +(Hermitian if complex) or non-symmetric. + +The eigenvalues returned by @code{eig} are not ordered. +@seealso{eigs, svd} +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/ellipj.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/ellipj.cc Tue Jun 21 16:07:51 2016 -0400 @@ -29,44 +29,44 @@ #include "lo-specfun.h" DEFUN (ellipj, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{sn}, @var{cn}, @var{dn}, @var{err}] =} ellipj (@var{u}, @var{m})\n\ -@deftypefnx {} {[@var{sn}, @var{cn}, @var{dn}, @var{err}] =} ellipj (@var{u}, @var{m}, @var{tol})\n\ -Compute the Jacobi elliptic functions @var{sn}, @var{cn}, and @var{dn}\n\ -of complex argument @var{u} and real parameter @var{m}.\n\ -\n\ -If @var{m} is a scalar, the results are the same size as @var{u}.\n\ -If @var{u} is a scalar, the results are the same size as @var{m}.\n\ -If @var{u} is a column vector and @var{m} is a row vector, the\n\ -results are matrices with @code{length (@var{u})} rows and\n\ -@code{length (@var{m})} columns. Otherwise, @var{u} and\n\ -@var{m} must conform in size and the results will be the same size as the\n\ -inputs.\n\ -\n\ -The value of @var{u} may be complex.\n\ -The value of @var{m} must be 0 @leq{} @var{m} @leq{} 1.\n\ -\n\ -The optional input @var{tol} is currently ignored (@sc{matlab} uses this to\n\ -allow faster, less accurate approximation).\n\ -\n\ -If requested, @var{err} contains the following status information\n\ -and is the same size as the result.\n\ -\n\ -@enumerate 0\n\ -@item\n\ -Normal return.\n\ -\n\ -@item\n\ -Error---no computation, algorithm termination condition not met,\n\ -return @code{NaN}.\n\ -@end enumerate\n\ -\n\ -Reference: Milton @nospell{Abramowitz} and Irene A @nospell{Stegun},\n\ -@cite{Handbook of Mathematical Functions}, Chapter 16 (Sections 16.4, 16.13,\n\ -and 16.15), Dover, 1965.\n\ -\n\ -@seealso{ellipke}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{sn}, @var{cn}, @var{dn}, @var{err}] =} ellipj (@var{u}, @var{m}) +@deftypefnx {} {[@var{sn}, @var{cn}, @var{dn}, @var{err}] =} ellipj (@var{u}, @var{m}, @var{tol}) +Compute the Jacobi elliptic functions @var{sn}, @var{cn}, and @var{dn} +of complex argument @var{u} and real parameter @var{m}. + +If @var{m} is a scalar, the results are the same size as @var{u}. +If @var{u} is a scalar, the results are the same size as @var{m}. +If @var{u} is a column vector and @var{m} is a row vector, the +results are matrices with @code{length (@var{u})} rows and +@code{length (@var{m})} columns. Otherwise, @var{u} and +@var{m} must conform in size and the results will be the same size as the +inputs. + +The value of @var{u} may be complex. +The value of @var{m} must be 0 @leq{} @var{m} @leq{} 1. + +The optional input @var{tol} is currently ignored (@sc{matlab} uses this to +allow faster, less accurate approximation). + +If requested, @var{err} contains the following status information +and is the same size as the result. + +@enumerate 0 +@item +Normal return. + +@item +Error---no computation, algorithm termination condition not met, +return @code{NaN}. +@end enumerate + +Reference: Milton @nospell{Abramowitz} and Irene A @nospell{Stegun}, +@cite{Handbook of Mathematical Functions}, Chapter 16 (Sections 16.4, 16.13, +and 16.15), Dover, 1965. + +@seealso{ellipke} +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/error.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/error.cc Tue Jun 21 16:07:51 2016 -0400 @@ -897,16 +897,16 @@ } DEFUN (rethrow, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} rethrow (@var{err})\n\ -Reissue a previous error as defined by @var{err}.\n\ -\n\ -@var{err} is a structure that must contain at least the @qcode{\"message\"}\n\ -and @qcode{\"identifier\"} fields. @var{err} can also contain a field\n\ -@qcode{\"stack\"} that gives information on the assumed location of the\n\ -error. Typically @var{err} is returned from @code{lasterror}.\n\ -@seealso{lasterror, lasterr, error}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} rethrow (@var{err}) +Reissue a previous error as defined by @var{err}. + +@var{err} is a structure that must contain at least the @qcode{"message"} +and @qcode{"identifier"} fields. @var{err} can also contain a field +@qcode{"stack"} that gives information on the assumed location of the +error. Typically @var{err} is returned from @code{lasterror}. +@seealso{lasterror, lasterr, error} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1081,93 +1081,93 @@ } DEFUN (error, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} error (@var{template}, @dots{})\n\ -@deftypefnx {} {} error (@var{id}, @var{template}, @dots{})\n\ -Display an error message and stop m-file execution.\n\ -\n\ -Format the optional arguments under the control of the template string\n\ -@var{template} using the same rules as the @code{printf} family of\n\ -functions (@pxref{Formatted Output}) and print the resulting message\n\ -on the @code{stderr} stream. The message is prefixed by the character\n\ -string @samp{error: }.\n\ -\n\ -Calling @code{error} also sets Octave's internal error state such that\n\ -control will return to the top level without evaluating any further\n\ -commands. This is useful for aborting from functions or scripts.\n\ -\n\ -If the error message does not end with a newline character, Octave will\n\ -print a traceback of all the function calls leading to the error. For\n\ -example, given the following function definitions:\n\ -\n\ -@example\n\ -@group\n\ -function f () g (); end\n\ -function g () h (); end\n\ -function h () nargin == 1 || error (\"nargin != 1\"); end\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -calling the function @code{f} will result in a list of messages that\n\ -can help you to quickly locate the exact location of the error:\n\ -\n\ -@example\n\ -@group\n\ -f ()\n\ -error: nargin != 1\n\ -error: called from:\n\ -error: error at line -1, column -1\n\ -error: h at line 1, column 27\n\ -error: g at line 1, column 15\n\ -error: f at line 1, column 15\n\ -@end group\n\ -@end example\n\ -\n\ -If the error message ends in a newline character, Octave will print the\n\ -message but will not display any traceback messages as it returns\n\ -control to the top level. For example, modifying the error message\n\ -in the previous example to end in a newline causes Octave to only print\n\ -a single message:\n\ -\n\ -@example\n\ -@group\n\ -function h () nargin == 1 || error (\"nargin != 1\\n\"); end\n\ -f ()\n\ -error: nargin != 1\n\ -@end group\n\ -@end example\n\ -\n\ -A null string (\"\") input to @code{error} will be ignored and the code\n\ -will continue running as if the statement were a NOP@. This is for\n\ -compatibility with @sc{matlab}. It also makes it possible to write code\n\ -such as\n\ -\n\ -@example\n\ -@group\n\ -err_msg = \"\";\n\ -if (CONDITION 1)\n\ - err_msg = \"CONDITION 1 found\";\n\ -elseif (CONDITION2)\n\ - err_msg = \"CONDITION 2 found\";\n\ -@dots{}\n\ -endif\n\ -error (err_msg);\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -which will only stop execution if an error has been found.\n\ -\n\ -Implementation Note: For compatibility with @sc{matlab}, escape\n\ -sequences in @var{template} (e.g., @qcode{\"@xbackslashchar{}n\"} =>\n\ -newline) are processed regardless of whether @var{template} has been defined\n\ -with single quotes, as long as there are two or more input arguments. To\n\ -disable escape sequence expansion use a second backslash before the sequence\n\ -(e.g., @qcode{\"@xbackslashchar{}@xbackslashchar{}n\"}) or use the\n\ -@code{regexptranslate} function.\n\ -@seealso{warning, lasterror}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} error (@var{template}, @dots{}) +@deftypefnx {} {} error (@var{id}, @var{template}, @dots{}) +Display an error message and stop m-file execution. + +Format the optional arguments under the control of the template string +@var{template} using the same rules as the @code{printf} family of +functions (@pxref{Formatted Output}) and print the resulting message +on the @code{stderr} stream. The message is prefixed by the character +string @samp{error: }. + +Calling @code{error} also sets Octave's internal error state such that +control will return to the top level without evaluating any further +commands. This is useful for aborting from functions or scripts. + +If the error message does not end with a newline character, Octave will +print a traceback of all the function calls leading to the error. For +example, given the following function definitions: + +@example +@group +function f () g (); end +function g () h (); end +function h () nargin == 1 || error ("nargin != 1"); end +@end group +@end example + +@noindent +calling the function @code{f} will result in a list of messages that +can help you to quickly locate the exact location of the error: + +@example +@group +f () +error: nargin != 1 +error: called from: +error: error at line -1, column -1 +error: h at line 1, column 27 +error: g at line 1, column 15 +error: f at line 1, column 15 +@end group +@end example + +If the error message ends in a newline character, Octave will print the +message but will not display any traceback messages as it returns +control to the top level. For example, modifying the error message +in the previous example to end in a newline causes Octave to only print +a single message: + +@example +@group +function h () nargin == 1 || error ("nargin != 1\n"); end +f () +error: nargin != 1 +@end group +@end example + +A null string ("") input to @code{error} will be ignored and the code +will continue running as if the statement were a NOP@. This is for +compatibility with @sc{matlab}. It also makes it possible to write code +such as + +@example +@group +err_msg = ""; +if (CONDITION 1) + err_msg = "CONDITION 1 found"; +elseif (CONDITION2) + err_msg = "CONDITION 2 found"; +@dots{} +endif +error (err_msg); +@end group +@end example + +@noindent +which will only stop execution if an error has been found. + +Implementation Note: For compatibility with @sc{matlab}, escape +sequences in @var{template} (e.g., @qcode{"@xbackslashchar{}n"} => +newline) are processed regardless of whether @var{template} has been defined +with single quotes, as long as there are two or more input arguments. To +disable escape sequence expansion use a second backslash before the sequence +(e.g., @qcode{"@xbackslashchar{}@xbackslashchar{}n"}) or use the +@code{regexptranslate} function. +@seealso{warning, lasterror} +@end deftypefn */) { int nargin = args.length (); @@ -1396,70 +1396,70 @@ } DEFUN (warning, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} warning (@var{template}, @dots{})\n\ -@deftypefnx {} {} warning (@var{id}, @var{template}, @dots{})\n\ -@deftypefnx {} {} warning (\"on\", @var{id})\n\ -@deftypefnx {} {} warning (\"off\", @var{id})\n\ -@deftypefnx {} {} warning (\"query\", @var{id})\n\ -@deftypefnx {} {} warning (\"error\", @var{id})\n\ -@deftypefnx {} {} warning (@var{state}, \"backtrace\")\n\ -@deftypefnx {} {} warning (@var{state}, @var{id}, \"local\")\n\ -Display a warning message or control the behavior of Octave's warning\n\ -system.\n\ -\n\ -Format the optional arguments under the control of the template string\n\ -@var{template} using the same rules as the @code{printf} family of\n\ -functions (@pxref{Formatted Output}) and print the resulting message\n\ -on the @code{stderr} stream. The message is prefixed by the character\n\ -string @samp{warning: }.\n\ -You should use this function when you want to notify the user\n\ -of an unusual condition, but only when it makes sense for your program\n\ -to go on.\n\ -\n\ -The optional message identifier allows users to enable or disable\n\ -warnings tagged by @var{id}. A message identifier is of the form\n\ -\"NAMESPACE:WARNING-NAME\". Octave's own warnings use the\n\ -@qcode{\"Octave\"} namespace (@pxref{XREFwarning_ids}). The special\n\ -identifier @qcode{\"all\"} may be used to set the state of all warnings.\n\ -\n\ -If the first argument is @qcode{\"on\"} or @qcode{\"off\"},\n\ -set the state of a particular warning using the identifier @var{id}. If the\n\ -first argument is @qcode{\"query\"}, query the state of this warning\n\ -instead. If the identifier is omitted, a value of @qcode{\"all\"} is\n\ -assumed. If you set the state of a warning to @qcode{\"error\"}, the\n\ -warning named by @var{id} is handled as if it were an error instead. So,\n\ -for example, the following handles all warnings as errors:\n\ -\n\ -@example\n\ -@group\n\ -warning (\"error\");\n\ -@end group\n\ -@end example\n\ -\n\ -If the state is @qcode{\"on\"} or @qcode{\"off\"} and the third argument\n\ -is @qcode{\"backtrace\"}, then a stack trace is printed along with the\n\ -warning message when warnings occur inside function calls. This option\n\ -is enabled by default.\n\ -\n\ -If the state is @qcode{\"on\"}, @qcode{\"off\"}, or @qcode{\"error\"}\n\ -and the third argument is @qcode{\"local\"}, then the warning state\n\ -will be set temporarily, until the end of the current function.\n\ -Changes to warning states that are set locally affect the current\n\ -function and all functions called from the current scope. The\n\ -previous warning state is restored on return from the current\n\ -function. The @qcode{\"local\"} option is ignored if used in the top-level\n\ -workspace.\n\ -\n\ -Implementation Note: For compatibility with @sc{matlab}, escape\n\ -sequences in @var{template} (e.g., @qcode{\"@xbackslashchar{}n\"} =>\n\ -newline) are processed regardless of whether @var{template} has been defined\n\ -with single quotes, as long as there are two or more input arguments. To\n\ -disable escape sequence expansion use a second backslash before the sequence\n\ -(e.g., @qcode{\"@xbackslashchar{}@xbackslashchar{}n\"}) or use the\n\ -@code{regexptranslate} function.\n\ -@seealso{warning_ids, lastwarn, error}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} warning (@var{template}, @dots{}) +@deftypefnx {} {} warning (@var{id}, @var{template}, @dots{}) +@deftypefnx {} {} warning ("on", @var{id}) +@deftypefnx {} {} warning ("off", @var{id}) +@deftypefnx {} {} warning ("query", @var{id}) +@deftypefnx {} {} warning ("error", @var{id}) +@deftypefnx {} {} warning (@var{state}, "backtrace") +@deftypefnx {} {} warning (@var{state}, @var{id}, "local") +Display a warning message or control the behavior of Octave's warning +system. + +Format the optional arguments under the control of the template string +@var{template} using the same rules as the @code{printf} family of +functions (@pxref{Formatted Output}) and print the resulting message +on the @code{stderr} stream. The message is prefixed by the character +string @samp{warning: }. +You should use this function when you want to notify the user +of an unusual condition, but only when it makes sense for your program +to go on. + +The optional message identifier allows users to enable or disable +warnings tagged by @var{id}. A message identifier is of the form +"NAMESPACE:WARNING-NAME". Octave's own warnings use the +@qcode{"Octave"} namespace (@pxref{XREFwarning_ids}). The special +identifier @qcode{"all"} may be used to set the state of all warnings. + +If the first argument is @qcode{"on"} or @qcode{"off"}, +set the state of a particular warning using the identifier @var{id}. If the +first argument is @qcode{"query"}, query the state of this warning +instead. If the identifier is omitted, a value of @qcode{"all"} is +assumed. If you set the state of a warning to @qcode{"error"}, the +warning named by @var{id} is handled as if it were an error instead. So, +for example, the following handles all warnings as errors: + +@example +@group +warning ("error"); +@end group +@end example + +If the state is @qcode{"on"} or @qcode{"off"} and the third argument +is @qcode{"backtrace"}, then a stack trace is printed along with the +warning message when warnings occur inside function calls. This option +is enabled by default. + +If the state is @qcode{"on"}, @qcode{"off"}, or @qcode{"error"} +and the third argument is @qcode{"local"}, then the warning state +will be set temporarily, until the end of the current function. +Changes to warning states that are set locally affect the current +function and all functions called from the current scope. The +previous warning state is restored on return from the current +function. The @qcode{"local"} option is ignored if used in the top-level +workspace. + +Implementation Note: For compatibility with @sc{matlab}, escape +sequences in @var{template} (e.g., @qcode{"@xbackslashchar{}n"} => +newline) are processed regardless of whether @var{template} has been defined +with single quotes, as long as there are two or more input arguments. To +disable escape sequence expansion use a second backslash before the sequence +(e.g., @qcode{"@xbackslashchar{}@xbackslashchar{}n"}) or use the +@code{regexptranslate} function. +@seealso{warning_ids, lastwarn, error} +@end deftypefn */) { octave_value retval; @@ -1795,51 +1795,51 @@ } DEFUN (lasterror, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{lasterr} =} lasterror ()\n\ -@deftypefnx {} {} lasterror (@var{err})\n\ -@deftypefnx {} {} lasterror (\"reset\")\n\ -Query or set the last error message structure.\n\ -\n\ -When called without arguments, return a structure containing the last error\n\ -message and other information related to this error. The elements of the\n\ -structure are:\n\ -\n\ -@table @code\n\ -@item message\n\ -The text of the last error message\n\ -\n\ -@item identifier\n\ -The message identifier of this error message\n\ -\n\ -@item stack\n\ -A structure containing information on where the message occurred. This may\n\ -be an empty structure if the information cannot be obtained. The fields of\n\ -the structure are:\n\ -\n\ -@table @code\n\ -@item file\n\ -The name of the file where the error occurred\n\ -\n\ -@item name\n\ -The name of function in which the error occurred\n\ -\n\ -@item line\n\ -The line number at which the error occurred\n\ -\n\ -@item column\n\ -An optional field with the column number at which the error occurred\n\ -@end table\n\ -@end table\n\ -\n\ -The last error structure may be set by passing a scalar structure,\n\ -@var{err}, as input. Any fields of @var{err} that match those above are\n\ -set while any unspecified fields are initialized with default values.\n\ -\n\ -If @code{lasterror} is called with the argument @qcode{\"reset\"}, all\n\ -fields are set to their default values.\n\ -@seealso{lasterr, error, lastwarn}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{lasterr} =} lasterror () +@deftypefnx {} {} lasterror (@var{err}) +@deftypefnx {} {} lasterror ("reset") +Query or set the last error message structure. + +When called without arguments, return a structure containing the last error +message and other information related to this error. The elements of the +structure are: + +@table @code +@item message +The text of the last error message + +@item identifier +The message identifier of this error message + +@item stack +A structure containing information on where the message occurred. This may +be an empty structure if the information cannot be obtained. The fields of +the structure are: + +@table @code +@item file +The name of the file where the error occurred + +@item name +The name of function in which the error occurred + +@item line +The line number at which the error occurred + +@item column +An optional field with the column number at which the error occurred +@end table +@end table + +The last error structure may be set by passing a scalar structure, +@var{err}, as input. Any fields of @var{err} that match those above are +set while any unspecified fields are initialized with default values. + +If @code{lasterror} is called with the argument @qcode{"reset"}, all +fields are set to their default values. +@seealso{lasterr, error, lastwarn} +@end deftypefn */) { int nargin = args.length (); @@ -1973,20 +1973,20 @@ */ DEFUN (lasterr, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{msg}, @var{msgid}] =} lasterr ()\n\ -@deftypefnx {} {} lasterr (@var{msg})\n\ -@deftypefnx {} {} lasterr (@var{msg}, @var{msgid})\n\ -Query or set the last error message.\n\ -\n\ -When called without input arguments, return the last error message and\n\ -message identifier.\n\ -\n\ -With one argument, set the last error message to @var{msg}.\n\ -\n\ -With two arguments, also set the last message identifier.\n\ -@seealso{lasterror, error, lastwarn}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{msg}, @var{msgid}] =} lasterr () +@deftypefnx {} {} lasterr (@var{msg}) +@deftypefnx {} {} lasterr (@var{msg}, @var{msgid}) +Query or set the last error message. + +When called without input arguments, return the last error message and +message identifier. + +With one argument, set the last error message to @var{msg}. + +With two arguments, also set the last message identifier. +@seealso{lasterror, error, lastwarn} +@end deftypefn */) { int nargin = args.length (); @@ -2016,20 +2016,20 @@ } DEFUN (lastwarn, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{msg}, @var{msgid}] =} lastwarn ()\n\ -@deftypefnx {} {} lastwarn (@var{msg})\n\ -@deftypefnx {} {} lastwarn (@var{msg}, @var{msgid})\n\ -Query or set the last warning message.\n\ -\n\ -When called without input arguments, return the last warning message and\n\ -message identifier.\n\ -\n\ -With one argument, set the last warning message to @var{msg}.\n\ -\n\ -With two arguments, also set the last message identifier.\n\ -@seealso{warning, lasterror, lasterr}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{msg}, @var{msgid}] =} lastwarn () +@deftypefnx {} {} lastwarn (@var{msg}) +@deftypefnx {} {} lastwarn (@var{msg}, @var{msgid}) +Query or set the last warning message. + +When called without input arguments, return the last warning message and +message identifier. + +With one argument, set the last warning message to @var{msg}. + +With two arguments, also set the last message identifier. +@seealso{warning, lasterror, lasterr} +@end deftypefn */) { int nargin = args.length (); @@ -2061,87 +2061,87 @@ // FIXME: Deprecated in 4.0 and scheduled for removal in 4.4. DEFUN (__usage__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} usage (@var{msg})\n\ -Print the message @var{msg}, prefixed by the string @samp{usage: }, and\n\ -set Octave's internal error state such that control will return to the\n\ -top level without evaluating any more commands. This is useful for\n\ -aborting from functions.\n\ -\n\ -After @code{usage} is evaluated, Octave will print a traceback of all\n\ -the function calls leading to the usage message.\n\ -\n\ -You should use this function for reporting problems errors that result\n\ -from an improper call to a function, such as calling a function with an\n\ -incorrect number of arguments, or with arguments of the wrong type. For\n\ -example, most functions distributed with Octave begin with code like\n\ -this\n\ -\n\ -@example\n\ -@group\n\ -if (nargin != 2)\n\ - usage (\"foo (a, b)\");\n\ -endif\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -to check for the proper number of arguments.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} usage (@var{msg}) +Print the message @var{msg}, prefixed by the string @samp{usage: }, and +set Octave's internal error state such that control will return to the +top level without evaluating any more commands. This is useful for +aborting from functions. + +After @code{usage} is evaluated, Octave will print a traceback of all +the function calls leading to the usage message. + +You should use this function for reporting problems errors that result +from an improper call to a function, such as calling a function with an +incorrect number of arguments, or with arguments of the wrong type. For +example, most functions distributed with Octave begin with code like +this + +@example +@group +if (nargin != 2) + usage ("foo (a, b)"); +endif +@end group +@end example + +@noindent +to check for the proper number of arguments. +@end deftypefn */) { handle_message (usage_with_id, "", "unknown", args, true); return ovl (); } DEFUN (beep_on_error, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} beep_on_error ()\n\ -@deftypefnx {} {@var{old_val} =} beep_on_error (@var{new_val})\n\ -@deftypefnx {} {} beep_on_error (@var{new_val}, \"local\")\n\ -Query or set the internal variable that controls whether Octave will try\n\ -to ring the terminal bell before printing an error message.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} beep_on_error () +@deftypefnx {} {@var{old_val} =} beep_on_error (@var{new_val}) +@deftypefnx {} {} beep_on_error (@var{new_val}, "local") +Query or set the internal variable that controls whether Octave will try +to ring the terminal bell before printing an error message. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@end deftypefn */) { return SET_INTERNAL_VARIABLE (beep_on_error); } DEFUN (debug_on_error, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} debug_on_error ()\n\ -@deftypefnx {} {@var{old_val} =} debug_on_error (@var{new_val})\n\ -@deftypefnx {} {} debug_on_error (@var{new_val}, \"local\")\n\ -Query or set the internal variable that controls whether Octave will try\n\ -to enter the debugger when an error is encountered.\n\ -\n\ -This will also inhibit printing of the normal traceback message (you will\n\ -only see the top-level error message).\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{debug_on_warning, debug_on_interrupt}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} debug_on_error () +@deftypefnx {} {@var{old_val} =} debug_on_error (@var{new_val}) +@deftypefnx {} {} debug_on_error (@var{new_val}, "local") +Query or set the internal variable that controls whether Octave will try +to enter the debugger when an error is encountered. + +This will also inhibit printing of the normal traceback message (you will +only see the top-level error message). + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{debug_on_warning, debug_on_interrupt} +@end deftypefn */) { return SET_INTERNAL_VARIABLE (debug_on_error); } DEFUN (debug_on_warning, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} debug_on_warning ()\n\ -@deftypefnx {} {@var{old_val} =} debug_on_warning (@var{new_val})\n\ -@deftypefnx {} {} debug_on_warning (@var{new_val}, \"local\")\n\ -Query or set the internal variable that controls whether Octave will try\n\ -to enter the debugger when a warning is encountered.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{debug_on_error, debug_on_interrupt}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} debug_on_warning () +@deftypefnx {} {@var{old_val} =} debug_on_warning (@var{new_val}) +@deftypefnx {} {} debug_on_warning (@var{new_val}, "local") +Query or set the internal variable that controls whether Octave will try +to enter the debugger when a warning is encountered. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{debug_on_error, debug_on_interrupt} +@end deftypefn */) { return SET_INTERNAL_VARIABLE (debug_on_warning); }
--- a/libinterp/corefcn/fft.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/fft.cc Tue Jun 21 16:07:51 2016 -0400 @@ -173,58 +173,58 @@ DEFUN (fft, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} fft (@var{x})\n\ -@deftypefnx {} {} fft (@var{x}, @var{n})\n\ -@deftypefnx {} {} fft (@var{x}, @var{n}, @var{dim})\n\ -Compute the discrete Fourier transform of @var{A} using\n\ -a Fast Fourier Transform (FFT) algorithm.\n\ -\n\ -The FFT is calculated along the first non-singleton dimension of the\n\ -array. Thus if @var{x} is a matrix, @code{fft (@var{x})} computes the\n\ -FFT for each column of @var{x}.\n\ -\n\ -If called with two arguments, @var{n} is expected to be an integer\n\ -specifying the number of elements of @var{x} to use, or an empty\n\ -matrix to specify that its value should be ignored. If @var{n} is\n\ -larger than the dimension along which the FFT is calculated, then\n\ -@var{x} is resized and padded with zeros. Otherwise, if @var{n} is\n\ -smaller than the dimension along which the FFT is calculated, then\n\ -@var{x} is truncated.\n\ -\n\ -If called with three arguments, @var{dim} is an integer specifying the\n\ -dimension of the matrix along which the FFT is performed\n\ -@seealso{ifft, fft2, fftn, fftw}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} fft (@var{x}) +@deftypefnx {} {} fft (@var{x}, @var{n}) +@deftypefnx {} {} fft (@var{x}, @var{n}, @var{dim}) +Compute the discrete Fourier transform of @var{A} using +a Fast Fourier Transform (FFT) algorithm. + +The FFT is calculated along the first non-singleton dimension of the +array. Thus if @var{x} is a matrix, @code{fft (@var{x})} computes the +FFT for each column of @var{x}. + +If called with two arguments, @var{n} is expected to be an integer +specifying the number of elements of @var{x} to use, or an empty +matrix to specify that its value should be ignored. If @var{n} is +larger than the dimension along which the FFT is calculated, then +@var{x} is resized and padded with zeros. Otherwise, if @var{n} is +smaller than the dimension along which the FFT is calculated, then +@var{x} is truncated. + +If called with three arguments, @var{dim} is an integer specifying the +dimension of the matrix along which the FFT is performed +@seealso{ifft, fft2, fftn, fftw} +@end deftypefn */) { return do_fft (args, "fft", 0); } DEFUN (ifft, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} ifft (@var{x})\n\ -@deftypefnx {} {} ifft (@var{x}, @var{n})\n\ -@deftypefnx {} {} ifft (@var{x}, @var{n}, @var{dim})\n\ -Compute the inverse discrete Fourier transform of @var{A}\n\ -using a Fast Fourier Transform (FFT) algorithm.\n\ -\n\ -The inverse FFT is calculated along the first non-singleton dimension\n\ -of the array. Thus if @var{x} is a matrix, @code{fft (@var{x})} computes\n\ -the inverse FFT for each column of @var{x}.\n\ -\n\ -If called with two arguments, @var{n} is expected to be an integer\n\ -specifying the number of elements of @var{x} to use, or an empty\n\ -matrix to specify that its value should be ignored. If @var{n} is\n\ -larger than the dimension along which the inverse FFT is calculated, then\n\ -@var{x} is resized and padded with zeros. Otherwise, if @var{n} is\n\ -smaller than the dimension along which the inverse FFT is calculated,\n\ -then @var{x} is truncated.\n\ -\n\ -If called with three arguments, @var{dim} is an integer specifying the\n\ -dimension of the matrix along which the inverse FFT is performed\n\ -@seealso{fft, ifft2, ifftn, fftw}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} ifft (@var{x}) +@deftypefnx {} {} ifft (@var{x}, @var{n}) +@deftypefnx {} {} ifft (@var{x}, @var{n}, @var{dim}) +Compute the inverse discrete Fourier transform of @var{A} +using a Fast Fourier Transform (FFT) algorithm. + +The inverse FFT is calculated along the first non-singleton dimension +of the array. Thus if @var{x} is a matrix, @code{fft (@var{x})} computes +the inverse FFT for each column of @var{x}. + +If called with two arguments, @var{n} is expected to be an integer +specifying the number of elements of @var{x} to use, or an empty +matrix to specify that its value should be ignored. If @var{n} is +larger than the dimension along which the inverse FFT is calculated, then +@var{x} is resized and padded with zeros. Otherwise, if @var{n} is +smaller than the dimension along which the inverse FFT is calculated, +then @var{x} is truncated. + +If called with three arguments, @var{dim} is an integer specifying the +dimension of the matrix along which the inverse FFT is performed +@seealso{fft, ifft2, ifftn, fftw} +@end deftypefn */) { return do_fft (args, "ifft", 1); }
--- a/libinterp/corefcn/fft2.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/fft2.cc Tue Jun 21 16:07:51 2016 -0400 @@ -140,40 +140,40 @@ } DEFUN (fft2, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} fft2 (@var{A})\n\ -@deftypefnx {} {} fft2 (@var{A}, @var{m}, @var{n})\n\ -Compute the two-dimensional discrete Fourier transform of @var{A} using\n\ -a Fast Fourier Transform (FFT) algorithm.\n\ -\n\ -The optional arguments @var{m} and @var{n} may be used specify the number of\n\ -rows and columns of @var{A} to use. If either of these is larger than the\n\ -size of @var{A}, @var{A} is resized and padded with zeros.\n\ -\n\ -If @var{A} is a multi-dimensional matrix, each two-dimensional sub-matrix\n\ -of @var{A} is treated separately.\n\ -@seealso{ifft2, fft, fftn, fftw}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} fft2 (@var{A}) +@deftypefnx {} {} fft2 (@var{A}, @var{m}, @var{n}) +Compute the two-dimensional discrete Fourier transform of @var{A} using +a Fast Fourier Transform (FFT) algorithm. + +The optional arguments @var{m} and @var{n} may be used specify the number of +rows and columns of @var{A} to use. If either of these is larger than the +size of @var{A}, @var{A} is resized and padded with zeros. + +If @var{A} is a multi-dimensional matrix, each two-dimensional sub-matrix +of @var{A} is treated separately. +@seealso{ifft2, fft, fftn, fftw} +@end deftypefn */) { return do_fft2 (args, "fft2", 0); } DEFUN (ifft2, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} ifft2 (@var{A})\n\ -@deftypefnx {} {} ifft2 (@var{A}, @var{m}, @var{n})\n\ -Compute the inverse two-dimensional discrete Fourier transform of @var{A}\n\ -using a Fast Fourier Transform (FFT) algorithm.\n\ -\n\ -The optional arguments @var{m} and @var{n} may be used specify the number of\n\ -rows and columns of @var{A} to use. If either of these is larger than the\n\ -size of @var{A}, @var{A} is resized and padded with zeros.\n\ -\n\ -If @var{A} is a multi-dimensional matrix, each two-dimensional sub-matrix\n\ -of @var{A} is treated separately\n\ -@seealso{fft2, ifft, ifftn, fftw}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} ifft2 (@var{A}) +@deftypefnx {} {} ifft2 (@var{A}, @var{m}, @var{n}) +Compute the inverse two-dimensional discrete Fourier transform of @var{A} +using a Fast Fourier Transform (FFT) algorithm. + +The optional arguments @var{m} and @var{n} may be used specify the number of +rows and columns of @var{A} to use. If either of these is larger than the +size of @var{A}, @var{A} is resized and padded with zeros. + +If @var{A} is a multi-dimensional matrix, each two-dimensional sub-matrix +of @var{A} is treated separately +@seealso{fft2, ifft, ifftn, fftw} +@end deftypefn */) { return do_fft2 (args, "ifft2", 1); }
--- a/libinterp/corefcn/fftn.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/fftn.cc Tue Jun 21 16:07:51 2016 -0400 @@ -126,39 +126,39 @@ } DEFUN (fftn, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} fftn (@var{A})\n\ -@deftypefnx {} {} fftn (@var{A}, @var{size})\n\ -Compute the N-dimensional discrete Fourier transform of @var{A} using\n\ -a Fast Fourier Transform (FFT) algorithm.\n\ -\n\ -The optional vector argument @var{size} may be used specify the dimensions\n\ -of the array to be used. If an element of @var{size} is smaller than the\n\ -corresponding dimension of @var{A}, then the dimension of @var{A} is\n\ -truncated prior to performing the FFT@. Otherwise, if an element of\n\ -@var{size} is larger than the corresponding dimension then @var{A} is\n\ -resized and padded with zeros.\n\ -@seealso{ifftn, fft, fft2, fftw}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} fftn (@var{A}) +@deftypefnx {} {} fftn (@var{A}, @var{size}) +Compute the N-dimensional discrete Fourier transform of @var{A} using +a Fast Fourier Transform (FFT) algorithm. + +The optional vector argument @var{size} may be used specify the dimensions +of the array to be used. If an element of @var{size} is smaller than the +corresponding dimension of @var{A}, then the dimension of @var{A} is +truncated prior to performing the FFT@. Otherwise, if an element of +@var{size} is larger than the corresponding dimension then @var{A} is +resized and padded with zeros. +@seealso{ifftn, fft, fft2, fftw} +@end deftypefn */) { return do_fftn (args, "fftn", 0); } DEFUN (ifftn, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} ifftn (@var{A})\n\ -@deftypefnx {} {} ifftn (@var{A}, @var{size})\n\ -Compute the inverse N-dimensional discrete Fourier transform of @var{A}\n\ -using a Fast Fourier Transform (FFT) algorithm.\n\ -\n\ -The optional vector argument @var{size} may be used specify the dimensions\n\ -of the array to be used. If an element of @var{size} is smaller than the\n\ -corresponding dimension of @var{A}, then the dimension of @var{A} is\n\ -truncated prior to performing the inverse FFT@. Otherwise, if an element of\n\ -@var{size} is larger than the corresponding dimension then @var{A} is\n\ -resized and padded with zeros.\n\ -@seealso{fftn, ifft, ifft2, fftw}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} ifftn (@var{A}) +@deftypefnx {} {} ifftn (@var{A}, @var{size}) +Compute the inverse N-dimensional discrete Fourier transform of @var{A} +using a Fast Fourier Transform (FFT) algorithm. + +The optional vector argument @var{size} may be used specify the dimensions +of the array to be used. If an element of @var{size} is smaller than the +corresponding dimension of @var{A}, then the dimension of @var{A} is +truncated prior to performing the inverse FFT@. Otherwise, if an element of +@var{size} is larger than the corresponding dimension then @var{A} is +resized and padded with zeros. +@seealso{fftn, ifft, ifft2, fftw} +@end deftypefn */) { return do_fftn (args, "ifftn", 1); }
--- a/libinterp/corefcn/file-io.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/file-io.cc Tue Jun 21 16:07:51 2016 -0400 @@ -232,18 +232,18 @@ } DEFUN (fclose, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} fclose (@var{fid})\n\ -@deftypefnx {} {} fclose (\"all\")\n\ -@deftypefnx {} {@var{status} =} fclose (\"all\")\n\ -Close the file specified by the file descriptor @var{fid}.\n\ -\n\ -If successful, @code{fclose} returns 0, otherwise, it returns -1. The\n\ -second form of the @code{fclose} call closes all open files except\n\ -@code{stdin}, @code{stdout}, @code{stderr}, and any FIDs associated\n\ -with gnuplot.\n\ -@seealso{fopen, fflush, freport}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} fclose (@var{fid}) +@deftypefnx {} {} fclose ("all") +@deftypefnx {} {@var{status} =} fclose ("all") +Close the file specified by the file descriptor @var{fid}. + +If successful, @code{fclose} returns 0, otherwise, it returns -1. The +second form of the @code{fclose} call closes all open files except +@code{stdin}, @code{stdout}, @code{stderr}, and any FIDs associated +with gnuplot. +@seealso{fopen, fflush, freport} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -252,12 +252,12 @@ } DEFUN (fclear, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} fclear (@var{fid})\n\ -Clear the stream state for the file specified by the file descriptor\n\ -@var{fid}.\n\ -@seealso{ferror, fopen}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} fclear (@var{fid}) +Clear the stream state for the file specified by the file descriptor +@var{fid}. +@seealso{ferror, fopen} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -272,19 +272,19 @@ } DEFUN (fflush, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} fflush (@var{fid})\n\ -Flush output to file descriptor @var{fid}.\n\ -\n\ -@code{fflush} returns 0 on success and an OS dependent error value\n\ -(@minus{}1 on Unix) on error.\n\ -\n\ -Programming Note: Flushing is useful for ensuring that all pending output\n\ -makes it to the screen before some other event occurs. For example, it is\n\ -always a good idea to flush the standard output stream before calling\n\ -@code{input}.\n\ -@seealso{fopen, fclose}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} fflush (@var{fid}) +Flush output to file descriptor @var{fid}. + +@code{fflush} returns 0 on success and an OS dependent error value +(@minus{}1 on Unix) on error. + +Programming Note: Flushing is useful for ensuring that all pending output +makes it to the screen before some other event occurs. For example, it is +always a good idea to flush the standard output stream before calling +@code{input}. +@seealso{fopen, fclose} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -311,23 +311,23 @@ } DEFUN (fgetl, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{str} =} fgetl (@var{fid})\n\ -@deftypefnx {} {@var{str} =} fgetl (@var{fid}, @var{len})\n\ -Read characters from a file, stopping after a newline, or EOF,\n\ -or @var{len} characters have been read.\n\ -\n\ -The characters read, excluding the possible trailing newline, are returned\n\ -as a string.\n\ -\n\ -If @var{len} is omitted, @code{fgetl} reads until the next newline\n\ -character.\n\ -\n\ -If there are no more characters to read, @code{fgetl} returns @minus{}1.\n\ -\n\ -To read a line and return the terminating newline see @code{fgets}.\n\ -@seealso{fgets, fscanf, fread, fopen}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{str} =} fgetl (@var{fid}) +@deftypefnx {} {@var{str} =} fgetl (@var{fid}, @var{len}) +Read characters from a file, stopping after a newline, or EOF, +or @var{len} characters have been read. + +The characters read, excluding the possible trailing newline, are returned +as a string. + +If @var{len} is omitted, @code{fgetl} reads until the next newline +character. + +If there are no more characters to read, @code{fgetl} returns @minus{}1. + +To read a line and return the terminating newline see @code{fgets}. +@seealso{fgets, fscanf, fread, fopen} +@end deftypefn */) { static std::string who = "fgetl"; @@ -351,23 +351,23 @@ } DEFUN (fgets, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{str} =} fgets (@var{fid})\n\ -@deftypefnx {} {@var{str} =} fgets (@var{fid}, @var{len})\n\ -Read characters from a file, stopping after a newline, or EOF,\n\ -or @var{len} characters have been read.\n\ -\n\ -The characters read, including the possible trailing newline, are returned\n\ -as a string.\n\ -\n\ -If @var{len} is omitted, @code{fgets} reads until the next newline\n\ -character.\n\ -\n\ -If there are no more characters to read, @code{fgets} returns @minus{}1.\n\ -\n\ -To read a line and discard the terminating newline see @code{fgetl}.\n\ -@seealso{fputs, fgetl, fscanf, fread, fopen}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{str} =} fgets (@var{fid}) +@deftypefnx {} {@var{str} =} fgets (@var{fid}, @var{len}) +Read characters from a file, stopping after a newline, or EOF, +or @var{len} characters have been read. + +The characters read, including the possible trailing newline, are returned +as a string. + +If @var{len} is omitted, @code{fgets} reads until the next newline +character. + +If there are no more characters to read, @code{fgets} returns @minus{}1. + +To read a line and discard the terminating newline see @code{fgetl}. +@seealso{fputs, fgetl, fscanf, fread, fopen} +@end deftypefn */) { static std::string who = "fgets"; @@ -391,23 +391,23 @@ } DEFUN (fskipl, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{nlines} =} fskipl (@var{fid})\n\ -@deftypefnx {} {@var{nlines} =} fskipl (@var{fid}, @var{count})\n\ -@deftypefnx {} {@var{nlines} =} fskipl (@var{fid}, Inf)\n\ -Read and skip @var{count} lines from the file specified by the file\n\ -descriptor @var{fid}.\n\ -\n\ -@code{fskipl} discards characters until an end-of-line is encountered\n\ -exactly @var{count}-times, or until the end-of-file marker is found.\n\ -\n\ -If @var{count} is omitted, it defaults to 1. @var{count} may also be\n\ -@code{Inf}, in which case lines are skipped until the end of the file.\n\ -This form is suitable for counting the number of lines in a file.\n\ -\n\ -Returns the number of lines skipped (end-of-line sequences encountered).\n\ -@seealso{fgetl, fgets, fscanf, fopen}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{nlines} =} fskipl (@var{fid}) +@deftypefnx {} {@var{nlines} =} fskipl (@var{fid}, @var{count}) +@deftypefnx {} {@var{nlines} =} fskipl (@var{fid}, Inf) +Read and skip @var{count} lines from the file specified by the file +descriptor @var{fid}. + +@code{fskipl} discards characters until an end-of-line is encountered +exactly @var{count}-times, or until the end-of-file marker is found. + +If @var{count} is omitted, it defaults to 1. @var{count} may also be +@code{Inf}, in which case lines are skipped until the end of the file. +This form is suitable for counting the number of lines in a file. + +Returns the number of lines skipped (end-of-line sequences encountered). +@seealso{fgetl, fgets, fscanf, fopen} +@end deftypefn */) { static std::string who = "fskipl"; @@ -507,105 +507,105 @@ } DEFUN (fopen, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{fid} =} fopen (@var{name})\n\ -@deftypefnx {} {@var{fid} =} fopen (@var{name}, @var{mode})\n\ -@deftypefnx {} {@var{fid} =} fopen (@var{name}, @var{mode}, @var{arch})\n\ -@deftypefnx {} {[@var{fid}, @var{msg}] =} fopen (@dots{})\n\ -@deftypefnx {} {@var{fid_list} =} fopen (\"all\")\n\ -@deftypefnx {} {[@var{file}, @var{mode}, @var{arch}] =} fopen (@var{fid})\n\ -Open a file for low-level I/O or query open files and file descriptors.\n\ -\n\ -The first form of the @code{fopen} function opens the named file with\n\ -the specified mode (read-write, read-only, etc.) and architecture\n\ -interpretation (IEEE big endian, IEEE little endian, etc.), and returns\n\ -an integer value that may be used to refer to the file later. If an\n\ -error occurs, @var{fid} is set to @minus{}1 and @var{msg} contains the\n\ -corresponding system error message. The @var{mode} is a one or two\n\ -character string that specifies whether the file is to be opened for\n\ -reading, writing, or both.\n\ -\n\ -The second form of the @code{fopen} function returns a vector of file ids\n\ -corresponding to all the currently open files, excluding the\n\ -@code{stdin}, @code{stdout}, and @code{stderr} streams.\n\ -\n\ -The third form of the @code{fopen} function returns information about the\n\ -open file given its file id.\n\ -\n\ -For example,\n\ -\n\ -@example\n\ -myfile = fopen (\"splat.dat\", \"r\", \"ieee-le\");\n\ -@end example\n\ -\n\ -@noindent\n\ -opens the file @file{splat.dat} for reading. If necessary, binary\n\ -numeric values will be read assuming they are stored in IEEE format with\n\ -the least significant bit first, and then converted to the native\n\ -representation.\n\ -\n\ -Opening a file that is already open simply opens it again and returns a\n\ -separate file id. It is not an error to open a file several times,\n\ -though writing to the same file through several different file ids may\n\ -produce unexpected results.\n\ -\n\ -The possible values @samp{mode} may have are\n\ -\n\ -@table @asis\n\ -@item @samp{r} (default)\n\ -Open a file for reading.\n\ -\n\ -@item @samp{w}\n\ -Open a file for writing. The previous contents are discarded.\n\ -\n\ -@item @samp{a}\n\ -Open or create a file for writing at the end of the file.\n\ -\n\ -@item @samp{r+}\n\ -Open an existing file for reading and writing.\n\ -\n\ -@item @samp{w+}\n\ -Open a file for reading or writing. The previous contents are\n\ -discarded.\n\ -\n\ -@item @samp{a+}\n\ -Open or create a file for reading or writing at the end of the\n\ -file.\n\ -@end table\n\ -\n\ -Append a @qcode{\"t\"} to the mode string to open the file in text mode or a\n\ -@qcode{\"b\"} to open in binary mode. On Windows and Macintosh systems,\n\ -text mode reading and writing automatically converts linefeeds to the\n\ -appropriate line end character for the system (carriage-return linefeed on\n\ -Windows, carriage-return on Macintosh). The default when no mode is\n\ -specified is binary mode.\n\ -\n\ -Additionally, you may append a @qcode{\"z\"} to the mode string to open a\n\ -gzipped file for reading or writing. For this to be successful, you\n\ -must also open the file in binary mode.\n\ -\n\ -The parameter @var{arch} is a string specifying the default data format\n\ -for the file. Valid values for @var{arch} are:\n\ -\n\ -@table @asis\n\ -@item @qcode{\"native\"} or @qcode{\"n\"} (default)\n\ -The format of the current machine.\n\ -\n\ -@item @qcode{\"ieee-be\"} or @qcode{\"b\"}\n\ -IEEE big endian format.\n\ -\n\ -@item @qcode{\"ieee-le\"} or @qcode{\"l\"}\n\ -IEEE little endian format.\n\ -@end table\n\ -\n\ -@noindent\n\ -However, conversions are currently only supported for @samp{native},\n\ -@samp{ieee-be}, and @samp{ieee-le} formats.\n\ -\n\ -When opening a new file that does not yet exist, permissions will be set to\n\ -@code{0666 - @var{umask}}.\n\ -@seealso{fclose, fgets, fgetl, fscanf, fread, fputs, fdisp, fprintf, fwrite, fskipl, fseek, frewind, ftell, feof, ferror, fclear, fflush, freport, umask}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{fid} =} fopen (@var{name}) +@deftypefnx {} {@var{fid} =} fopen (@var{name}, @var{mode}) +@deftypefnx {} {@var{fid} =} fopen (@var{name}, @var{mode}, @var{arch}) +@deftypefnx {} {[@var{fid}, @var{msg}] =} fopen (@dots{}) +@deftypefnx {} {@var{fid_list} =} fopen ("all") +@deftypefnx {} {[@var{file}, @var{mode}, @var{arch}] =} fopen (@var{fid}) +Open a file for low-level I/O or query open files and file descriptors. + +The first form of the @code{fopen} function opens the named file with +the specified mode (read-write, read-only, etc.) and architecture +interpretation (IEEE big endian, IEEE little endian, etc.), and returns +an integer value that may be used to refer to the file later. If an +error occurs, @var{fid} is set to @minus{}1 and @var{msg} contains the +corresponding system error message. The @var{mode} is a one or two +character string that specifies whether the file is to be opened for +reading, writing, or both. + +The second form of the @code{fopen} function returns a vector of file ids +corresponding to all the currently open files, excluding the +@code{stdin}, @code{stdout}, and @code{stderr} streams. + +The third form of the @code{fopen} function returns information about the +open file given its file id. + +For example, + +@example +myfile = fopen ("splat.dat", "r", "ieee-le"); +@end example + +@noindent +opens the file @file{splat.dat} for reading. If necessary, binary +numeric values will be read assuming they are stored in IEEE format with +the least significant bit first, and then converted to the native +representation. + +Opening a file that is already open simply opens it again and returns a +separate file id. It is not an error to open a file several times, +though writing to the same file through several different file ids may +produce unexpected results. + +The possible values @samp{mode} may have are + +@table @asis +@item @samp{r} (default) +Open a file for reading. + +@item @samp{w} +Open a file for writing. The previous contents are discarded. + +@item @samp{a} +Open or create a file for writing at the end of the file. + +@item @samp{r+} +Open an existing file for reading and writing. + +@item @samp{w+} +Open a file for reading or writing. The previous contents are +discarded. + +@item @samp{a+} +Open or create a file for reading or writing at the end of the +file. +@end table + +Append a @qcode{"t"} to the mode string to open the file in text mode or a +@qcode{"b"} to open in binary mode. On Windows and Macintosh systems, +text mode reading and writing automatically converts linefeeds to the +appropriate line end character for the system (carriage-return linefeed on +Windows, carriage-return on Macintosh). The default when no mode is +specified is binary mode. + +Additionally, you may append a @qcode{"z"} to the mode string to open a +gzipped file for reading or writing. For this to be successful, you +must also open the file in binary mode. + +The parameter @var{arch} is a string specifying the default data format +for the file. Valid values for @var{arch} are: + +@table @asis +@item @qcode{"native"} or @qcode{"n"} (default) +The format of the current machine. + +@item @qcode{"ieee-be"} or @qcode{"b"} +IEEE big endian format. + +@item @qcode{"ieee-le"} or @qcode{"l"} +IEEE little endian format. +@end table + +@noindent +However, conversions are currently only supported for @samp{native}, +@samp{ieee-be}, and @samp{ieee-le} formats. + +When opening a new file that does not yet exist, permissions will be set to +@code{0666 - @var{umask}}. +@seealso{fclose, fgets, fgetl, fscanf, fread, fputs, fdisp, fprintf, fwrite, fskipl, fseek, frewind, ftell, feof, ferror, fclear, fflush, freport, umask} +@end deftypefn */) { int nargin = args.length (); @@ -658,27 +658,27 @@ } DEFUN (freport, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} freport ()\n\ -Print a list of which files have been opened, and whether they are open\n\ -for reading, writing, or both.\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -freport ()\n\ -\n\ - @print{} number mode arch name\n\ - @print{} ------ ---- ---- ----\n\ - @print{} 0 r ieee-le stdin\n\ - @print{} 1 w ieee-le stdout\n\ - @print{} 2 w ieee-le stderr\n\ - @print{} 3 r ieee-le myfile\n\ -@end group\n\ -@end example\n\ -@seealso{fopen, fclose, is_valid_file_id}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} freport () +Print a list of which files have been opened, and whether they are open +for reading, writing, or both. + +For example: + +@example +@group +freport () + + @print{} number mode arch name + @print{} ------ ---- ---- ---- + @print{} 0 r ieee-le stdin + @print{} 1 w ieee-le stdout + @print{} 2 w ieee-le stderr + @print{} 3 r ieee-le myfile +@end group +@end example +@seealso{fopen, fclose, is_valid_file_id} +@end deftypefn */) { if (args.length () > 0) warning ("freport: ignoring extra arguments"); @@ -689,16 +689,16 @@ } DEFUN (frewind, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} frewind (@var{fid})\n\ -@deftypefnx {} {@var{status} =} frewind (@var{fid})\n\ -Move the file pointer to the beginning of the file specified by file\n\ -descriptor @var{fid}.\n\ -\n\ -@code{frewind} returns 0 for success, and -1 if an error is encountered. It\n\ -is equivalent to @code{fseek (@var{fid}, 0, SEEK_SET)}.\n\ -@seealso{fseek, ftell, fopen}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} frewind (@var{fid}) +@deftypefnx {} {@var{status} =} frewind (@var{fid}) +Move the file pointer to the beginning of the file specified by file +descriptor @var{fid}. + +@code{frewind} returns 0 for success, and -1 if an error is encountered. It +is equivalent to @code{fseek (@var{fid}, 0, SEEK_SET)}. +@seealso{fseek, ftell, fopen} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -716,23 +716,23 @@ } DEFUN (fseek, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} fseek (@var{fid}, @var{offset})\n\ -@deftypefnx {} {} fseek (@var{fid}, @var{offset}, @var{origin})\n\ -@deftypefnx {} {@var{status} =} fseek (@dots{})\n\ -Set the file pointer to the location @var{offset} within the file @var{fid}.\n\ -\n\ -The pointer is positioned @var{offset} characters from the @var{origin},\n\ -which may be one of the predefined variables @w{@code{SEEK_CUR}} (current\n\ -position), @w{@code{SEEK_SET}} (beginning), or @w{@code{SEEK_END}} (end of\n\ -file) or strings @qcode{\"cof\"}, @qcode{\"bof\"} or @qcode{\"eof\"}. If\n\ -@var{origin} is omitted, @w{@code{SEEK_SET}} is assumed. @var{offset} may\n\ -be positive, negative, or zero but not all combinations of @var{origin} and\n\ -@var{offset} can be realized.\n\ -\n\ -@code{fseek} returns 0 on success and -1 on error.\n\ -@seealso{fskipl, frewind, ftell, fopen}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} fseek (@var{fid}, @var{offset}) +@deftypefnx {} {} fseek (@var{fid}, @var{offset}, @var{origin}) +@deftypefnx {} {@var{status} =} fseek (@dots{}) +Set the file pointer to the location @var{offset} within the file @var{fid}. + +The pointer is positioned @var{offset} characters from the @var{origin}, +which may be one of the predefined variables @w{@code{SEEK_CUR}} (current +position), @w{@code{SEEK_SET}} (beginning), or @w{@code{SEEK_END}} (end of +file) or strings @qcode{"cof"}, @qcode{"bof"} or @qcode{"eof"}. If +@var{origin} is omitted, @w{@code{SEEK_SET}} is assumed. @var{offset} may +be positive, negative, or zero but not all combinations of @var{origin} and +@var{offset} can be realized. + +@code{fseek} returns 0 on success and -1 on error. +@seealso{fskipl, frewind, ftell, fopen} +@end deftypefn */) { int nargin = args.length (); @@ -747,12 +747,12 @@ } DEFUN (ftell, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{pos} =} ftell (@var{fid})\n\ -Return the position of the file pointer as the number of characters from the\n\ -beginning of the file specified by file descriptor @var{fid}.\n\ -@seealso{fseek, frewind, feof, fopen}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{pos} =} ftell (@var{fid}) +Return the position of the file pointer as the number of characters from the +beginning of the file specified by file descriptor @var{fid}. +@seealso{fseek, frewind, feof, fopen} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -763,23 +763,23 @@ } DEFUN (fprintf, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} fprintf (@var{fid}, @var{template}, @dots{})\n\ -@deftypefnx {} {} fprintf (@var{template}, @dots{})\n\ -@deftypefnx {} {@var{numbytes} =} fprintf (@dots{})\n\ -This function is equivalent to @code{printf}, except that the output is\n\ -written to the file descriptor @var{fid} instead of @code{stdout}.\n\ -\n\ -If @var{fid} is omitted, the output is written to @code{stdout} making the\n\ -function exactly equivalent to @code{printf}.\n\ -\n\ -The optional output returns the number of bytes written to the file.\n\ -\n\ -Implementation Note: For compatibility with @sc{matlab}, escape sequences in\n\ -the template string (e.g., @qcode{\"@xbackslashchar{}n\"} => newline) are\n\ -expanded even when the template string is defined with single quotes.\n\ -@seealso{fputs, fdisp, fwrite, fscanf, printf, sprintf, fopen}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} fprintf (@var{fid}, @var{template}, @dots{}) +@deftypefnx {} {} fprintf (@var{template}, @dots{}) +@deftypefnx {} {@var{numbytes} =} fprintf (@dots{}) +This function is equivalent to @code{printf}, except that the output is +written to the file descriptor @var{fid} instead of @code{stdout}. + +If @var{fid} is omitted, the output is written to @code{stdout} making the +function exactly equivalent to @code{printf}. + +The optional output returns the number of bytes written to the file. + +Implementation Note: For compatibility with @sc{matlab}, escape sequences in +the template string (e.g., @qcode{"@xbackslashchar{}n"} => newline) are +expanded even when the template string is defined with single quotes. +@seealso{fputs, fdisp, fwrite, fscanf, printf, sprintf, fopen} +@end deftypefn */) { static std::string who = "fprintf"; @@ -823,22 +823,22 @@ } DEFUN (printf, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} printf (@var{template}, @dots{})\n\ -Print optional arguments under the control of the template string\n\ -@var{template} to the stream @code{stdout} and return the number of\n\ -characters printed.\n\ -@ifclear OCTAVE_MANUAL\n\ -\n\ -See the Formatted Output section of the GNU Octave manual for a\n\ -complete description of the syntax of the template string.\n\ -@end ifclear\n\ -\n\ -Implementation Note: For compatibility with @sc{matlab}, escape sequences in\n\ -the template string (e.g., @qcode{\"@xbackslashchar{}n\"} => newline) are\n\ -expanded even when the template string is defined with single quotes.\n\ -@seealso{fprintf, sprintf, scanf}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} printf (@var{template}, @dots{}) +Print optional arguments under the control of the template string +@var{template} to the stream @code{stdout} and return the number of +characters printed. +@ifclear OCTAVE_MANUAL + +See the Formatted Output section of the GNU Octave manual for a +complete description of the syntax of the template string. +@end ifclear + +Implementation Note: For compatibility with @sc{matlab}, escape sequences in +the template string (e.g., @qcode{"@xbackslashchar{}n"} => newline) are +expanded even when the template string is defined with single quotes. +@seealso{fprintf, sprintf, scanf} +@end deftypefn */) { static std::string who = "printf"; @@ -871,18 +871,18 @@ } DEFUN (fputs, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} fputs (@var{fid}, @var{string})\n\ -@deftypefnx {} {@var{status} =} fputs (@var{fid}, @var{string})\n\ -Write the string @var{string} to the file with file descriptor @var{fid}.\n\ -\n\ -The string is written to the file with no additional formatting. Use\n\ -@code{fdisp} instead to automatically append a newline character appropriate\n\ -for the local machine.\n\ -\n\ -Return a non-negative number on success or EOF on error.\n\ -@seealso{fdisp, fprintf, fwrite, fopen}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} fputs (@var{fid}, @var{string}) +@deftypefnx {} {@var{status} =} fputs (@var{fid}, @var{string}) +Write the string @var{string} to the file with file descriptor @var{fid}. + +The string is written to the file with no additional formatting. Use +@code{fdisp} instead to automatically append a newline character appropriate +for the local machine. + +Return a non-negative number on success or EOF on error. +@seealso{fdisp, fprintf, fwrite, fopen} +@end deftypefn */) { static std::string who = "fputs"; @@ -895,17 +895,17 @@ } DEFUN (puts, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} puts (@var{string})\n\ -@deftypefnx {} {@var{status} =} puts (@var{string})\n\ -Write a string to the standard output with no formatting.\n\ -\n\ -The string is written verbatim to the standard output. Use @code{disp} to\n\ -automatically append a newline character appropriate for the local machine.\n\ -\n\ -Return a non-negative number on success and EOF on error.\n\ -@seealso{fputs, disp}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} puts (@var{string}) +@deftypefnx {} {@var{status} =} puts (@var{string}) +Write a string to the standard output with no formatting. + +The string is written verbatim to the standard output. Use @code{disp} to +automatically append a newline character appropriate for the local machine. + +Return a non-negative number on success and EOF on error. +@seealso{fputs, disp} +@end deftypefn */) { static std::string who = "puts"; @@ -916,20 +916,20 @@ } DEFUN (sprintf, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} sprintf (@var{template}, @dots{})\n\ -This is like @code{printf}, except that the output is returned as a\n\ -string.\n\ -\n\ -Unlike the C library function, which requires you to provide a suitably\n\ -sized string as an argument, Octave's @code{sprintf} function returns the\n\ -string, automatically sized to hold all of the items converted.\n\ -\n\ -Implementation Note: For compatibility with @sc{matlab}, escape sequences in\n\ -the template string (e.g., @qcode{\"@xbackslashchar{}n\"} => newline) are\n\ -expanded even when the template string is defined with single quotes.\n\ -@seealso{printf, fprintf, sscanf}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} sprintf (@var{template}, @dots{}) +This is like @code{printf}, except that the output is returned as a +string. + +Unlike the C library function, which requires you to provide a suitably +sized string as an argument, Octave's @code{sprintf} function returns the +string, automatically sized to hold all of the items converted. + +Implementation Note: For compatibility with @sc{matlab}, escape sequences in +the template string (e.g., @qcode{"@xbackslashchar{}n"} => newline) are +expanded even when the template string is defined with single quotes. +@seealso{printf, fprintf, sscanf} +@end deftypefn */) { static std::string who = "sprintf"; @@ -979,54 +979,54 @@ } DEFUN (fscanf, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{val}, @var{count}, @var{errmsg}] =} fscanf (@var{fid}, @var{template}, @var{size})\n\ -@deftypefnx {} {[@var{v1}, @var{v2}, @dots{}, @var{count}, @var{errmsg}] =} fscanf (@var{fid}, @var{template}, \"C\")\n\ -In the first form, read from @var{fid} according to @var{template},\n\ -returning the result in the matrix @var{val}.\n\ -\n\ -The optional argument @var{size} specifies the amount of data to read\n\ -and may be one of\n\ -\n\ -@table @code\n\ -@item Inf\n\ -Read as much as possible, returning a column vector.\n\ -\n\ -@item @var{nr}\n\ -Read up to @var{nr} elements, returning a column vector.\n\ -\n\ -@item [@var{nr}, Inf]\n\ -Read as much as possible, returning a matrix with @var{nr} rows. If the\n\ -number of elements read is not an exact multiple of @var{nr}, the last\n\ -column is padded with zeros.\n\ -\n\ -@item [@var{nr}, @var{nc}]\n\ -Read up to @code{@var{nr} * @var{nc}} elements, returning a matrix with\n\ -@var{nr} rows. If the number of elements read is not an exact multiple\n\ -of @var{nr}, the last column is padded with zeros.\n\ -@end table\n\ -\n\ -@noindent\n\ -If @var{size} is omitted, a value of @code{Inf} is assumed.\n\ -\n\ -A string is returned if @var{template} specifies only character conversions.\n\ -\n\ -The number of items successfully read is returned in @var{count}.\n\ -\n\ -If an error occurs, @var{errmsg} contains a system-dependent error message.\n\ -\n\ -In the second form, read from @var{fid} according to @var{template},\n\ -with each conversion specifier in @var{template} corresponding to a\n\ -single scalar return value. This form is more ``C-like'', and also\n\ -compatible with previous versions of Octave. The number of successful\n\ -conversions is returned in @var{count}\n\ -@ifclear OCTAVE_MANUAL\n\ -\n\ -See the Formatted Input section of the GNU Octave manual for a\n\ -complete description of the syntax of the template string.\n\ -@end ifclear\n\ -@seealso{fgets, fgetl, fread, scanf, sscanf, fopen}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{val}, @var{count}, @var{errmsg}] =} fscanf (@var{fid}, @var{template}, @var{size}) +@deftypefnx {} {[@var{v1}, @var{v2}, @dots{}, @var{count}, @var{errmsg}] =} fscanf (@var{fid}, @var{template}, "C") +In the first form, read from @var{fid} according to @var{template}, +returning the result in the matrix @var{val}. + +The optional argument @var{size} specifies the amount of data to read +and may be one of + +@table @code +@item Inf +Read as much as possible, returning a column vector. + +@item @var{nr} +Read up to @var{nr} elements, returning a column vector. + +@item [@var{nr}, Inf] +Read as much as possible, returning a matrix with @var{nr} rows. If the +number of elements read is not an exact multiple of @var{nr}, the last +column is padded with zeros. + +@item [@var{nr}, @var{nc}] +Read up to @code{@var{nr} * @var{nc}} elements, returning a matrix with +@var{nr} rows. If the number of elements read is not an exact multiple +of @var{nr}, the last column is padded with zeros. +@end table + +@noindent +If @var{size} is omitted, a value of @code{Inf} is assumed. + +A string is returned if @var{template} specifies only character conversions. + +The number of items successfully read is returned in @var{count}. + +If an error occurs, @var{errmsg} contains a system-dependent error message. + +In the second form, read from @var{fid} according to @var{template}, +with each conversion specifier in @var{template} corresponding to a +single scalar return value. This form is more ``C-like'', and also +compatible with previous versions of Octave. The number of successful +conversions is returned in @var{count} +@ifclear OCTAVE_MANUAL + +See the Formatted Input section of the GNU Octave manual for a +complete description of the syntax of the template string. +@end ifclear +@seealso{fgets, fgetl, fread, scanf, sscanf, fopen} +@end deftypefn */) { static std::string who = "fscanf"; @@ -1079,17 +1079,17 @@ } DEFUN (sscanf, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{val}, @var{count}, @var{errmsg}, @var{pos}] =} sscanf (@var{string}, @var{template}, @var{size})\n\ -@deftypefnx {} {[@var{v1}, @var{v2}, @dots{}, @var{count}, @var{errmsg}] =} sscanf (@var{string}, @var{template}, \"C\")\n\ -This is like @code{fscanf}, except that the characters are taken from the\n\ -string @var{string} instead of from a stream.\n\ -\n\ -Reaching the end of the string is treated as an end-of-file condition. In\n\ -addition to the values returned by @code{fscanf}, the index of the next\n\ -character to be read is returned in @var{pos}.\n\ -@seealso{fscanf, scanf, sprintf}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{val}, @var{count}, @var{errmsg}, @var{pos}] =} sscanf (@var{string}, @var{template}, @var{size}) +@deftypefnx {} {[@var{v1}, @var{v2}, @dots{}, @var{count}, @var{errmsg}] =} sscanf (@var{string}, @var{template}, "C") +This is like @code{fscanf}, except that the characters are taken from the +string @var{string} instead of from a stream. + +Reaching the end of the string is treated as an end-of-file condition. In +addition to the values returned by @code{fscanf}, the index of the next +character to be read is returned in @var{pos}. +@seealso{fscanf, scanf, sprintf} +@end deftypefn */) { static std::string who = "sscanf"; @@ -1137,14 +1137,14 @@ } DEFUN (scanf, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{val}, @var{count}, @var{errmsg}] =} scanf (@var{template}, @var{size})\n\ -@deftypefnx {} {[@var{v1}, @var{v2}, @dots{}, @var{count}, @var{errmsg}]] =} scanf (@var{template}, \"C\")\n\ -This is equivalent to calling @code{fscanf} with @var{fid} = @code{stdin}.\n\ -\n\ -It is currently not useful to call @code{scanf} in interactive programs.\n\ -@seealso{fscanf, sscanf, printf}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{val}, @var{count}, @var{errmsg}] =} scanf (@var{template}, @var{size}) +@deftypefnx {} {[@var{v1}, @var{v2}, @dots{}, @var{count}, @var{errmsg}]] =} scanf (@var{template}, "C") +This is equivalent to calling @code{fscanf} with @var{fid} = @code{stdin}. + +It is currently not useful to call @code{scanf} in interactive programs. +@seealso{fscanf, sscanf, printf} +@end deftypefn */) { int nargin = args.length (); @@ -1226,270 +1226,270 @@ } DEFUN (textscan, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{C} =} textscan (@var{fid}, @var{format})\n\ -@deftypefnx {} {@var{C} =} textscan (@var{fid}, @var{format}, @var{repeat})\n\ -@deftypefnx {} {@var{C} =} textscan (@var{fid}, @var{format}, @var{param}, @var{value}, @dots{})\n\ -@deftypefnx {} {@var{C} =} textscan (@var{fid}, @var{format}, @var{repeat}, @var{param}, @var{value}, @dots{})\n\ -@deftypefnx {} {@var{C} =} textscan (@var{str}, @dots{})\n\ -@deftypefnx {} {[@var{C}, @var{position}, @var{errmsg}] =} textscan (@dots{})\n\ -Read data from a text file or string.\n\ -\n\ -The string @var{str} or file associated with @var{fid} is read from and\n\ -parsed according to @var{format}. The function is an extension of\n\ -@code{strread} and @code{textread}. Differences include: the ability to\n\ -read from either a file or a string, additional options, and additional\n\ -format specifiers.\n\ -\n\ -The input is interpreted as a sequence of words, delimiters (such as\n\ -whitespace), and literals. The characters that form delimiters and\n\ -whitespace are determined by the options. The format consists of format\n\ -specifiers interspersed between literals. In the format, whitespace forms\n\ -a delimiter between consecutive literals, but is otherwise ignored.\n\ -\n\ -The output @var{C} is a cell array where the number of columns is determined\n\ -by the number of format specifiers.\n\ -\n\ -The first word of the input is matched to the first specifier of the format\n\ -and placed in the first column of the output; the second is matched to the\n\ -second specifier and placed in the second column and so forth. If there\n\ -are more words than specifiers then the process is repeated until all words\n\ -have been processed or the limit imposed by @var{repeat} has been met (see\n\ -below).\n\ -\n\ -The string @var{format} describes how the words in @var{str} should be\n\ -parsed. As in @var{fscanf}, any (non-whitespace) text in the format that is\n\ -not one of these specifiers is considered a literal. If there is a literal\n\ -between two format specifiers then that same literal must appear in the\n\ -input stream between the matching words.\n\ -\n\ -The following specifiers are valid:\n\ -\n\ -@table @code\n\ -@item %f\n\ -@itemx %f64\n\ -@itemx %n\n\ -The word is parsed as a number and converted to double.\n\ -\n\ -@item %f32\n\ -The word is parsed as a number and converted to single (float).\n\ -\n\ -@item %d\n\ -@itemx %d8\n\ -@itemx %d16\n\ -@itemx %d32\n\ -@itemx %d64\n\ -The word is parsed as a number and converted to int8, int16, int32, or\n\ -int64. If no size is specified then int32 is used.\n\ -\n\ -@item %u\n\ -@itemx %u8\n\ -@itemx %u16\n\ -@itemx %u32\n\ -@itemx %u64\n\ -The word is parsed as a number and converted to uint8, uint16, uint32, or\n\ -uint64. If no size is specified then uint32 is used.\n\ -\n\ -@item %s\n\ -The word is parsed as a string ending at the last character before\n\ -whitespace, an end-of-line, or a delimiter specified in the options.\n\ -\n\ -@item %q\n\ -The word is parsed as a \"quoted string\".\n\ -If the first character of the string is a double quote (\") then the string\n\ -includes everything until a matching double quote---including whitespace,\n\ -delimiters, and end-of-line characters. If a pair of consecutive double\n\ -quotes appears in the input, it is replaced in the output by a single\n\ -double quote. For examples, the input \"He said \"\"Hello\"\"\" would\n\ -return the value 'He said \"Hello\"'.\n\ -\n\ -@item %c\n\ -The next character of the input is read.\n\ -This includes delimiters, whitespace, and end-of-line characters.\n\ -\n\ -@item %[@dots{}]\n\ -@itemx %[^@dots{}]\n\ -In the first form, the word consists of the longest run consisting of only\n\ -characters between the brackets. Ranges of characters can be specified by\n\ -a hyphen; for example, %[0-9a-zA-Z] matches all alphanumeric characters (if\n\ -the underlying character set is ASCII). Since @sc{matlab} treats hyphens\n\ -literally, this expansion only applies to alphanumeric characters. To\n\ -include '-' in the set, it should appear first or last in the brackets; to\n\ -include ']', it should be the first character. If the first character is\n\ -'^' then the word consists of characters @strong{not} listed.\n\ -\n\ -@item %N@dots{}\n\ -For %s, %c %d, %f, %n, %u, an optional width can be specified as %Ns, etc.\n\ -where N is an integer > 1. For %c, this causes exactly N characters to be\n\ -read instead of a single character. For the other specifiers, it is an\n\ -upper bound on the number of characters read; normal delimiters can cause\n\ -fewer characters to be read. For complex numbers, this limit applies to\n\ -the real and imaginary components individually. For %f and %n, format\n\ -specifiers like %N.Mf are allowed, where M is an upper bound on number of\n\ -characters after the decimal point to be considered; subsequent digits are\n\ -skipped. For example, the specifier %8.2f would read 12.345e6 as 1.234e7.\n\ -\n\ -@item %*@dots{}\n\ -The word specified by the remainder of the conversion specifier is skipped.\n\ -\n\ -@item literals\n\ -In addition the format may contain literal character strings; these will be\n\ -skipped during reading. If the input string does not match this literal,\n\ -the processing terminates.\n\ -@end table\n\ -\n\ -Parsed words corresponding to the first specifier are returned in the first\n\ -output argument and likewise for the rest of the specifiers.\n\ -\n\ -By default, if there is only one input argument, @var{format} is @t{\"%f\"}.\n\ -This means that numbers are read from the input into a single column vector.\n\ -If @var{format} is explicitly empty (@qcode{\"\"}) then textscan will\n\ -return data in a number of columns matching the number of fields on the\n\ -first data line of the input. Either of these is suitable only when the\n\ -input is exclusively numeric.\n\ -\n\ -For example, the string\n\ -\n\ -@smallexample\n\ -@group\n\ -@var{str} = \"\\\n\ -Bunny Bugs 5.5\\n\\\n\ -Duck Daffy -7.5e-5\\n\\\n\ -Penguin Tux 6\"\n\ -@end group\n\ -@end smallexample\n\ -\n\ -@noindent\n\ -can be read using\n\ -\n\ -@example\n\ -@var{a} = textscan (@var{str}, \"%s %s %f\");\n\ -@end example\n\ -\n\ -The optional numeric argument @var{repeat} can be used for limiting the\n\ -number of items read:\n\ -\n\ -@table @asis\n\ -@item -1\n\ -Read all of the string or file until the end (default).\n\ -\n\ -@item N\n\ -Read until the first of two conditions occurs: 1) the format has been\n\ -processed N times, or 2) N lines of the input have been processed. Zero\n\ -(0) is an acceptable value for @var{repeat}. Currently, end-of-line\n\ -characters inside %q, %c, and %[@dots{}]$ conversions do not contribute to\n\ -the line count. This is incompatible with @sc{matlab} and may change in\n\ -future.\n\ -@end table\n\ -\n\ -The behavior of @code{textscan} can be changed via property/value pairs.\n\ -The following properties are recognized:\n\ -\n\ -@table @asis\n\ -@item @qcode{\"BufSize\"}\n\ -This specifies the number of bytes to use for the internal buffer.\n\ -A modest speed improvement may be obtained by setting this to a large value\n\ -when reading a large file, especially if the input contains long strings.\n\ -The default is 4096, or a value dependent on @var{n} if that is specified.\n\ -\n\ -@item @qcode{\"CollectOutput\"}\n\ -A value of 1 or true instructs @code{textscan} to concatenate consecutive\n\ -columns of the same class in the output cell array. A value of 0 or false\n\ -(default) leaves output in distinct columns.\n\ -\n\ -@item @qcode{\"CommentStyle\"}\n\ -Specify parts of the input which are considered comments and will be\n\ -skipped. @var{value} is the comment style and can be either (1) A string\n\ -or 1x1 cell string, to skip everything to the right of it; (2) A cell array\n\ -of two strings, to skip everything between the first and second strings. \n\ -Comments are only parsed where whitespace is accepted and do not act as\n\ -delimiters.\n\ -\n\ -@item @qcode{\"Delimiter\"}\n\ -If @var{value} is a string, any character in @var{value} will be used to\n\ -split the input into words. If @var{value} is a cell array of strings,\n\ -any string in the array will be used to split the input into words.\n\ -(default value = any whitespace.)\n\ -\n\ -@item @qcode{\"EmptyValue\"}\n\ -Value to return for empty numeric values in non-whitespace delimited data.\n\ -The default is NaN@. When the data type does not support NaN (int32 for\n\ -example), then the default is zero.\n\ -\n\ -@item @qcode{\"EndOfLine\"}\n\ -@var{value} can be either an emtpy or one character specifying the\n\ -end-of-line character, or the pair\n\ -@qcode{\"@xbackslashchar{}r@xbackslashchar{}n\"} (CRLF).\n\ -In the latter case, any of\n\ -@qcode{\"@xbackslashchar{}r\"}, @qcode{\"@xbackslashchar{}n\"} or\n\ -@qcode{\"@xbackslashchar{}r@xbackslashchar{}n\"} is counted as a (single)\n\ -newline. If no value is given,\n\ -@qcode{\"@xbackslashchar{}r@xbackslashchar{}n\"} is used.\n\ -@c If set to \"\" (empty string) EOLs are ignored as delimiters and added\n\ -@c to whitespace.\n\ -\n\ -@c When reading from a character string, optional input argument @var{n}\n\ -@c specifies the number of times @var{format} should be used (i.e., to limit\n\ -@c the amount of data read).\n\ -@c When reading from file, @var{n} specifies the number of data lines to read;\n\ -@c in this sense it differs slightly from the format repeat count in strread.\n\ -\n\ -@item @qcode{\"HeaderLines\"}\n\ -The first @var{value} number of lines of @var{fid} are skipped. Note that\n\ -this does not refer to the first non-comment lines, but the first lines of\n\ -any type.\n\ -\n\ -@item @qcode{\"MultipleDelimsAsOne\"}\n\ -If @var{value} is nonzero, treat a series of consecutive delimiters,\n\ -without whitespace in between, as a single delimiter. Consecutive\n\ -delimiter series need not be vertically aligned. Without this option, a\n\ -single delimiter before the end of the line does not cause the line to be\n\ -considered to end with an empty value, but a single delimiter at the start\n\ -of a line causes the line to be considered to start with an empty value.\n\ -\n\ -@item @qcode{\"TreatAsEmpty\"}\n\ -Treat single occurrences (surrounded by delimiters or whitespace) of the\n\ -string(s) in @var{value} as missing values.\n\ -\n\ -@item @qcode{\"ReturnOnError\"}\n\ -If set to numerical 1 or true, return normally as soon as an error is\n\ -encountered, such as trying to read a string using @qcode{%f}.\n\ -If set to 0 or false, return an error and no data.\n\ -\n\ -@item @qcode{\"Whitespace\"}\n\ -Any character in @var{value} will be interpreted as whitespace and trimmed;\n\ -The default value for whitespace is\n\ -@c Note: the next line specifically has a newline which generates a space\n\ -@c in the output of qcode, but keeps the next line < 80 characters.\n\ -@qcode{\"\n\ -@xbackslashchar{}b@xbackslashchar{}r@xbackslashchar{}n@xbackslashchar{}t\"}\n\ -(note the space). Unless whitespace is set to @qcode{\"\"} (empty) AND at\n\ -least one @qcode{\"%s\"} format conversion specifier is supplied, a space is\n\ -always part of whitespace.\n\ -\n\ -@end table\n\ -\n\ -When the number of words in @var{str} or @var{fid} doesn't match an exact\n\ -multiple of the number of format conversion specifiers, @code{textscan}'s\n\ -behavior depends on whether the last character of the string or file is an\n\ -end-of-line as specified by the @code{EndOfLine} option:\n\ -\n\ -@table @asis\n\ -@item last character = end-of-line\n\ -Data columns are padded with empty fields, NaN or 0 (for integer fields) so\n\ -that all columns have equal length\n\ -\n\ -@item last character is not end-of-line\n\ -Data columns are not padded; @code{textscan} returns columns of unequal\n\ -length\n\ -@end table\n\ -\n\ -\n\ -The second output @var{position} provides the location, in characters\n\ -from the beginning of the file or string, where processing stopped.\n\ -\n\ -@seealso{dlmread, fscanf, load, strread, textread}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{C} =} textscan (@var{fid}, @var{format}) +@deftypefnx {} {@var{C} =} textscan (@var{fid}, @var{format}, @var{repeat}) +@deftypefnx {} {@var{C} =} textscan (@var{fid}, @var{format}, @var{param}, @var{value}, @dots{}) +@deftypefnx {} {@var{C} =} textscan (@var{fid}, @var{format}, @var{repeat}, @var{param}, @var{value}, @dots{}) +@deftypefnx {} {@var{C} =} textscan (@var{str}, @dots{}) +@deftypefnx {} {[@var{C}, @var{position}, @var{errmsg}] =} textscan (@dots{}) +Read data from a text file or string. + +The string @var{str} or file associated with @var{fid} is read from and +parsed according to @var{format}. The function is an extension of +@code{strread} and @code{textread}. Differences include: the ability to +read from either a file or a string, additional options, and additional +format specifiers. + +The input is interpreted as a sequence of words, delimiters (such as +whitespace), and literals. The characters that form delimiters and +whitespace are determined by the options. The format consists of format +specifiers interspersed between literals. In the format, whitespace forms +a delimiter between consecutive literals, but is otherwise ignored. + +The output @var{C} is a cell array where the number of columns is determined +by the number of format specifiers. + +The first word of the input is matched to the first specifier of the format +and placed in the first column of the output; the second is matched to the +second specifier and placed in the second column and so forth. If there +are more words than specifiers then the process is repeated until all words +have been processed or the limit imposed by @var{repeat} has been met (see +below). + +The string @var{format} describes how the words in @var{str} should be +parsed. As in @var{fscanf}, any (non-whitespace) text in the format that is +not one of these specifiers is considered a literal. If there is a literal +between two format specifiers then that same literal must appear in the +input stream between the matching words. + +The following specifiers are valid: + +@table @code +@item %f +@itemx %f64 +@itemx %n +The word is parsed as a number and converted to double. + +@item %f32 +The word is parsed as a number and converted to single (float). + +@item %d +@itemx %d8 +@itemx %d16 +@itemx %d32 +@itemx %d64 +The word is parsed as a number and converted to int8, int16, int32, or +int64. If no size is specified then int32 is used. + +@item %u +@itemx %u8 +@itemx %u16 +@itemx %u32 +@itemx %u64 +The word is parsed as a number and converted to uint8, uint16, uint32, or +uint64. If no size is specified then uint32 is used. + +@item %s +The word is parsed as a string ending at the last character before +whitespace, an end-of-line, or a delimiter specified in the options. + +@item %q +The word is parsed as a "quoted string". +If the first character of the string is a double quote (") then the string +includes everything until a matching double quote---including whitespace, +delimiters, and end-of-line characters. If a pair of consecutive double +quotes appears in the input, it is replaced in the output by a single +double quote. For examples, the input "He said ""Hello""" would +return the value 'He said "Hello"'. + +@item %c +The next character of the input is read. +This includes delimiters, whitespace, and end-of-line characters. + +@item %[@dots{}] +@itemx %[^@dots{}] +In the first form, the word consists of the longest run consisting of only +characters between the brackets. Ranges of characters can be specified by +a hyphen; for example, %[0-9a-zA-Z] matches all alphanumeric characters (if +the underlying character set is ASCII). Since @sc{matlab} treats hyphens +literally, this expansion only applies to alphanumeric characters. To +include '-' in the set, it should appear first or last in the brackets; to +include ']', it should be the first character. If the first character is +'^' then the word consists of characters @strong{not} listed. + +@item %N@dots{} +For %s, %c %d, %f, %n, %u, an optional width can be specified as %Ns, etc. +where N is an integer > 1. For %c, this causes exactly N characters to be +read instead of a single character. For the other specifiers, it is an +upper bound on the number of characters read; normal delimiters can cause +fewer characters to be read. For complex numbers, this limit applies to +the real and imaginary components individually. For %f and %n, format +specifiers like %N.Mf are allowed, where M is an upper bound on number of +characters after the decimal point to be considered; subsequent digits are +skipped. For example, the specifier %8.2f would read 12.345e6 as 1.234e7. + +@item %*@dots{} +The word specified by the remainder of the conversion specifier is skipped. + +@item literals +In addition the format may contain literal character strings; these will be +skipped during reading. If the input string does not match this literal, +the processing terminates. +@end table + +Parsed words corresponding to the first specifier are returned in the first +output argument and likewise for the rest of the specifiers. + +By default, if there is only one input argument, @var{format} is @t{"%f"}. +This means that numbers are read from the input into a single column vector. +If @var{format} is explicitly empty (@qcode{""}) then textscan will +return data in a number of columns matching the number of fields on the +first data line of the input. Either of these is suitable only when the +input is exclusively numeric. + +For example, the string + +@smallexample +@group +@var{str} = "\ +Bunny Bugs 5.5\n\ +Duck Daffy -7.5e-5\n\ +Penguin Tux 6" +@end group +@end smallexample + +@noindent +can be read using + +@example +@var{a} = textscan (@var{str}, "%s %s %f"); +@end example + +The optional numeric argument @var{repeat} can be used for limiting the +number of items read: + +@table @asis +@item -1 +Read all of the string or file until the end (default). + +@item N +Read until the first of two conditions occurs: 1) the format has been +processed N times, or 2) N lines of the input have been processed. Zero +(0) is an acceptable value for @var{repeat}. Currently, end-of-line +characters inside %q, %c, and %[@dots{}]$ conversions do not contribute to +the line count. This is incompatible with @sc{matlab} and may change in +future. +@end table + +The behavior of @code{textscan} can be changed via property/value pairs. +The following properties are recognized: + +@table @asis +@item @qcode{"BufSize"} +This specifies the number of bytes to use for the internal buffer. +A modest speed improvement may be obtained by setting this to a large value +when reading a large file, especially if the input contains long strings. +The default is 4096, or a value dependent on @var{n} if that is specified. + +@item @qcode{"CollectOutput"} +A value of 1 or true instructs @code{textscan} to concatenate consecutive +columns of the same class in the output cell array. A value of 0 or false +(default) leaves output in distinct columns. + +@item @qcode{"CommentStyle"} +Specify parts of the input which are considered comments and will be +skipped. @var{value} is the comment style and can be either (1) A string +or 1x1 cell string, to skip everything to the right of it; (2) A cell array +of two strings, to skip everything between the first and second strings. +Comments are only parsed where whitespace is accepted and do not act as +delimiters. + +@item @qcode{"Delimiter"} +If @var{value} is a string, any character in @var{value} will be used to +split the input into words. If @var{value} is a cell array of strings, +any string in the array will be used to split the input into words. +(default value = any whitespace.) + +@item @qcode{"EmptyValue"} +Value to return for empty numeric values in non-whitespace delimited data. +The default is NaN@. When the data type does not support NaN (int32 for +example), then the default is zero. + +@item @qcode{"EndOfLine"} +@var{value} can be either an emtpy or one character specifying the +end-of-line character, or the pair +@qcode{"@xbackslashchar{}r@xbackslashchar{}n"} (CRLF). +In the latter case, any of +@qcode{"@xbackslashchar{}r"}, @qcode{"@xbackslashchar{}n"} or +@qcode{"@xbackslashchar{}r@xbackslashchar{}n"} is counted as a (single) +newline. If no value is given, +@qcode{"@xbackslashchar{}r@xbackslashchar{}n"} is used. +@c If set to "" (empty string) EOLs are ignored as delimiters and added +@c to whitespace. + +@c When reading from a character string, optional input argument @var{n} +@c specifies the number of times @var{format} should be used (i.e., to limit +@c the amount of data read). +@c When reading from file, @var{n} specifies the number of data lines to read; +@c in this sense it differs slightly from the format repeat count in strread. + +@item @qcode{"HeaderLines"} +The first @var{value} number of lines of @var{fid} are skipped. Note that +this does not refer to the first non-comment lines, but the first lines of +any type. + +@item @qcode{"MultipleDelimsAsOne"} +If @var{value} is nonzero, treat a series of consecutive delimiters, +without whitespace in between, as a single delimiter. Consecutive +delimiter series need not be vertically aligned. Without this option, a +single delimiter before the end of the line does not cause the line to be +considered to end with an empty value, but a single delimiter at the start +of a line causes the line to be considered to start with an empty value. + +@item @qcode{"TreatAsEmpty"} +Treat single occurrences (surrounded by delimiters or whitespace) of the +string(s) in @var{value} as missing values. + +@item @qcode{"ReturnOnError"} +If set to numerical 1 or true, return normally as soon as an error is +encountered, such as trying to read a string using @qcode{%f}. +If set to 0 or false, return an error and no data. + +@item @qcode{"Whitespace"} +Any character in @var{value} will be interpreted as whitespace and trimmed; +The default value for whitespace is +@c Note: the next line specifically has a newline which generates a space +@c in the output of qcode, but keeps the next line < 80 characters. +@qcode{" +@xbackslashchar{}b@xbackslashchar{}r@xbackslashchar{}n@xbackslashchar{}t"} +(note the space). Unless whitespace is set to @qcode{""} (empty) AND at +least one @qcode{"%s"} format conversion specifier is supplied, a space is +always part of whitespace. + +@end table + +When the number of words in @var{str} or @var{fid} doesn't match an exact +multiple of the number of format conversion specifiers, @code{textscan}'s +behavior depends on whether the last character of the string or file is an +end-of-line as specified by the @code{EndOfLine} option: + +@table @asis +@item last character = end-of-line +Data columns are padded with empty fields, NaN or 0 (for integer fields) so +that all columns have equal length + +@item last character is not end-of-line +Data columns are not padded; @code{textscan} returns columns of unequal +length +@end table + + +The second output @var{position} provides the location, in characters +from the beginning of the file or string, where processing stopped. + +@seealso{dlmread, fscanf, load, strread, textread} +@end deftypefn */) { static std::string who = "textscan"; @@ -1497,11 +1497,11 @@ } DEFUN (__textscan__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{C} =} __textscan__ (@var{who}, @dots{})\n\ -Like @code{textscan} but accept additional argument @var{who} to use\n\ -as the name of the function when reporting errors.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{C} =} __textscan__ (@var{who}, @dots{}) +Like @code{textscan} but accept additional argument @var{who} to use +as the name of the function when reporting errors. +@end deftypefn */) { if (args.length () == 0) print_usage (); @@ -2285,175 +2285,175 @@ } DEFUN (fread, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} fread (@var{fid})\n\ -@deftypefnx {} {@var{val} =} fread (@var{fid}, @var{size})\n\ -@deftypefnx {} {@var{val} =} fread (@var{fid}, @var{size}, @var{precision})\n\ -@deftypefnx {} {@var{val} =} fread (@var{fid}, @var{size}, @var{precision}, @var{skip})\n\ -@deftypefnx {} {@var{val} =} fread (@var{fid}, @var{size}, @var{precision}, @var{skip}, @var{arch})\n\ -@deftypefnx {} {[@var{val}, @var{count}] =} fread (@dots{})\n\ -Read binary data from the file specified by the file descriptor @var{fid}.\n\ -\n\ -The optional argument @var{size} specifies the amount of data to read\n\ -and may be one of\n\ -\n\ -@table @code\n\ -@item Inf\n\ -Read as much as possible, returning a column vector.\n\ -\n\ -@item @var{nr}\n\ -Read up to @var{nr} elements, returning a column vector.\n\ -\n\ -@item [@var{nr}, Inf]\n\ -Read as much as possible, returning a matrix with @var{nr} rows. If the\n\ -number of elements read is not an exact multiple of @var{nr}, the last\n\ -column is padded with zeros.\n\ -\n\ -@item [@var{nr}, @var{nc}]\n\ -Read up to @code{@var{nr} * @var{nc}} elements, returning a matrix with\n\ -@var{nr} rows. If the number of elements read is not an exact multiple\n\ -of @var{nr}, the last column is padded with zeros.\n\ -@end table\n\ -\n\ -@noindent\n\ -If @var{size} is omitted, a value of @code{Inf} is assumed.\n\ -\n\ -The optional argument @var{precision} is a string specifying the type of\n\ -data to read and may be one of\n\ -\n\ -@table @asis\n\ -@item @qcode{\"schar\"}\n\ -@itemx @qcode{\"signed char\"}\n\ -Signed character.\n\ -\n\ -@item @qcode{\"uchar\"}\n\ -@itemx @qcode{\"unsigned char\"}\n\ -Unsigned character.\n\ -\n\ -@item @qcode{\"int8\"}\n\ -@itemx @qcode{\"integer*1\"}\n\ -\n\ -8-bit signed integer.\n\ -\n\ -@item @qcode{\"int16\"}\n\ -@itemx @qcode{\"integer*2\"}\n\ -16-bit signed integer.\n\ -\n\ -@item @qcode{\"int32\"}\n\ -@itemx @qcode{\"integer*4\"}\n\ -32-bit signed integer.\n\ -\n\ -@item @qcode{\"int64\"}\n\ -@itemx @qcode{\"integer*8\"}\n\ -64-bit signed integer.\n\ -\n\ -@item @qcode{\"uint8\"}\n\ -8-bit unsigned integer.\n\ -\n\ -@item @qcode{\"uint16\"}\n\ -16-bit unsigned integer.\n\ -\n\ -@item @qcode{\"uint32\"}\n\ -32-bit unsigned integer.\n\ -\n\ -@item @qcode{\"uint64\"}\n\ -64-bit unsigned integer.\n\ -\n\ -@item @qcode{\"single\"}\n\ -@itemx @qcode{\"float32\"}\n\ -@itemx @qcode{\"real*4\"}\n\ -32-bit floating point number.\n\ -\n\ -@item @qcode{\"double\"}\n\ -@itemx @qcode{\"float64\"}\n\ -@itemx @qcode{\"real*8\"}\n\ -64-bit floating point number.\n\ -\n\ -@item @qcode{\"char\"}\n\ -@itemx @qcode{\"char*1\"}\n\ -Single character.\n\ -\n\ -@item @qcode{\"short\"}\n\ -Short integer (size is platform dependent).\n\ -\n\ -@item @qcode{\"int\"}\n\ -Integer (size is platform dependent).\n\ -\n\ -@item @qcode{\"long\"}\n\ -Long integer (size is platform dependent).\n\ -\n\ -@item @qcode{\"ushort\"}\n\ -@itemx @qcode{\"unsigned short\"}\n\ -Unsigned short integer (size is platform dependent).\n\ -\n\ -@item @qcode{\"uint\"}\n\ -@itemx @qcode{\"unsigned int\"}\n\ -Unsigned integer (size is platform dependent).\n\ -\n\ -@item @qcode{\"ulong\"}\n\ -@itemx @qcode{\"unsigned long\"}\n\ -Unsigned long integer (size is platform dependent).\n\ -\n\ -@item @qcode{\"float\"}\n\ -Single precision floating point number (size is platform dependent).\n\ -@end table\n\ -\n\ -@noindent\n\ -The default precision is @qcode{\"uchar\"}.\n\ -\n\ -The @var{precision} argument may also specify an optional repeat\n\ -count. For example, @samp{32*single} causes @code{fread} to read\n\ -a block of 32 single precision floating point numbers. Reading in\n\ -blocks is useful in combination with the @var{skip} argument.\n\ -\n\ -The @var{precision} argument may also specify a type conversion.\n\ -For example, @samp{int16=>int32} causes @code{fread} to read 16-bit\n\ -integer values and return an array of 32-bit integer values. By\n\ -default, @code{fread} returns a double precision array. The special\n\ -form @samp{*TYPE} is shorthand for @samp{TYPE=>TYPE}.\n\ -\n\ -The conversion and repeat counts may be combined. For example, the\n\ -specification @samp{32*single=>single} causes @code{fread} to read\n\ -blocks of single precision floating point values and return an array\n\ -of single precision values instead of the default array of double\n\ -precision values.\n\ -\n\ -The optional argument @var{skip} specifies the number of bytes to skip\n\ -after each element (or block of elements) is read. If it is not\n\ -specified, a value of 0 is assumed. If the final block read is not\n\ -complete, the final skip is omitted. For example,\n\ -\n\ -@example\n\ -fread (f, 10, \"3*single=>single\", 8)\n\ -@end example\n\ -\n\ -@noindent\n\ -will omit the final 8-byte skip because the last read will not be\n\ -a complete block of 3 values.\n\ -\n\ -The optional argument @var{arch} is a string specifying the data format\n\ -for the file. Valid values are\n\ -\n\ -@table @asis\n\ -@item @qcode{\"native\"} or @qcode{\"n\"}\n\ -The format of the current machine.\n\ -\n\ -@item @qcode{\"ieee-be\"} or @qcode{\"b\"}\n\ -IEEE big endian.\n\ -\n\ -@item @qcode{\"ieee-le\"} or @qcode{\"l\"}\n\ -IEEE little endian.\n\ -@end table\n\ -\n\ -If no @var{arch} is given the value used in the call to @code{fopen} which\n\ -created the file descriptor is used. Otherwise, the value specified with\n\ -@code{fread} overrides that of @code{fopen} and determines the data format.\n\ -\n\ -The output argument @var{val} contains the data read from the file.\n\ -\n\ -The optional return value @var{count} contains the number of elements read.\n\ -@seealso{fwrite, fgets, fgetl, fscanf, fopen}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} fread (@var{fid}) +@deftypefnx {} {@var{val} =} fread (@var{fid}, @var{size}) +@deftypefnx {} {@var{val} =} fread (@var{fid}, @var{size}, @var{precision}) +@deftypefnx {} {@var{val} =} fread (@var{fid}, @var{size}, @var{precision}, @var{skip}) +@deftypefnx {} {@var{val} =} fread (@var{fid}, @var{size}, @var{precision}, @var{skip}, @var{arch}) +@deftypefnx {} {[@var{val}, @var{count}] =} fread (@dots{}) +Read binary data from the file specified by the file descriptor @var{fid}. + +The optional argument @var{size} specifies the amount of data to read +and may be one of + +@table @code +@item Inf +Read as much as possible, returning a column vector. + +@item @var{nr} +Read up to @var{nr} elements, returning a column vector. + +@item [@var{nr}, Inf] +Read as much as possible, returning a matrix with @var{nr} rows. If the +number of elements read is not an exact multiple of @var{nr}, the last +column is padded with zeros. + +@item [@var{nr}, @var{nc}] +Read up to @code{@var{nr} * @var{nc}} elements, returning a matrix with +@var{nr} rows. If the number of elements read is not an exact multiple +of @var{nr}, the last column is padded with zeros. +@end table + +@noindent +If @var{size} is omitted, a value of @code{Inf} is assumed. + +The optional argument @var{precision} is a string specifying the type of +data to read and may be one of + +@table @asis +@item @qcode{"schar"} +@itemx @qcode{"signed char"} +Signed character. + +@item @qcode{"uchar"} +@itemx @qcode{"unsigned char"} +Unsigned character. + +@item @qcode{"int8"} +@itemx @qcode{"integer*1"} + +8-bit signed integer. + +@item @qcode{"int16"} +@itemx @qcode{"integer*2"} +16-bit signed integer. + +@item @qcode{"int32"} +@itemx @qcode{"integer*4"} +32-bit signed integer. + +@item @qcode{"int64"} +@itemx @qcode{"integer*8"} +64-bit signed integer. + +@item @qcode{"uint8"} +8-bit unsigned integer. + +@item @qcode{"uint16"} +16-bit unsigned integer. + +@item @qcode{"uint32"} +32-bit unsigned integer. + +@item @qcode{"uint64"} +64-bit unsigned integer. + +@item @qcode{"single"} +@itemx @qcode{"float32"} +@itemx @qcode{"real*4"} +32-bit floating point number. + +@item @qcode{"double"} +@itemx @qcode{"float64"} +@itemx @qcode{"real*8"} +64-bit floating point number. + +@item @qcode{"char"} +@itemx @qcode{"char*1"} +Single character. + +@item @qcode{"short"} +Short integer (size is platform dependent). + +@item @qcode{"int"} +Integer (size is platform dependent). + +@item @qcode{"long"} +Long integer (size is platform dependent). + +@item @qcode{"ushort"} +@itemx @qcode{"unsigned short"} +Unsigned short integer (size is platform dependent). + +@item @qcode{"uint"} +@itemx @qcode{"unsigned int"} +Unsigned integer (size is platform dependent). + +@item @qcode{"ulong"} +@itemx @qcode{"unsigned long"} +Unsigned long integer (size is platform dependent). + +@item @qcode{"float"} +Single precision floating point number (size is platform dependent). +@end table + +@noindent +The default precision is @qcode{"uchar"}. + +The @var{precision} argument may also specify an optional repeat +count. For example, @samp{32*single} causes @code{fread} to read +a block of 32 single precision floating point numbers. Reading in +blocks is useful in combination with the @var{skip} argument. + +The @var{precision} argument may also specify a type conversion. +For example, @samp{int16=>int32} causes @code{fread} to read 16-bit +integer values and return an array of 32-bit integer values. By +default, @code{fread} returns a double precision array. The special +form @samp{*TYPE} is shorthand for @samp{TYPE=>TYPE}. + +The conversion and repeat counts may be combined. For example, the +specification @samp{32*single=>single} causes @code{fread} to read +blocks of single precision floating point values and return an array +of single precision values instead of the default array of double +precision values. + +The optional argument @var{skip} specifies the number of bytes to skip +after each element (or block of elements) is read. If it is not +specified, a value of 0 is assumed. If the final block read is not +complete, the final skip is omitted. For example, + +@example +fread (f, 10, "3*single=>single", 8) +@end example + +@noindent +will omit the final 8-byte skip because the last read will not be +a complete block of 3 values. + +The optional argument @var{arch} is a string specifying the data format +for the file. Valid values are + +@table @asis +@item @qcode{"native"} or @qcode{"n"} +The format of the current machine. + +@item @qcode{"ieee-be"} or @qcode{"b"} +IEEE big endian. + +@item @qcode{"ieee-le"} or @qcode{"l"} +IEEE little endian. +@end table + +If no @var{arch} is given the value used in the call to @code{fopen} which +created the file descriptor is used. Otherwise, the value specified with +@code{fread} overrides that of @code{fopen} and determines the data format. + +The output argument @var{val} contains the data read from the file. + +The optional return value @var{count} contains the number of elements read. +@seealso{fwrite, fgets, fgetl, fscanf, fopen} +@end deftypefn */) { int nargin = args.length (); @@ -2532,26 +2532,26 @@ } DEFUN (fwrite, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} fwrite (@var{fid}, @var{data})\n\ -@deftypefnx {} {} fwrite (@var{fid}, @var{data}, @var{precision})\n\ -@deftypefnx {} {} fwrite (@var{fid}, @var{data}, @var{precision}, @var{skip})\n\ -@deftypefnx {} {} fwrite (@var{fid}, @var{data}, @var{precision}, @var{skip}, @var{arch})\n\ -@deftypefnx {} {@var{count} =} fwrite (@dots{})\n\ -Write data in binary form to the file specified by the file descriptor\n\ -@var{fid}, returning the number of values @var{count} successfully written\n\ -to the file.\n\ -\n\ -The argument @var{data} is a matrix of values that are to be written to\n\ -the file. The values are extracted in column-major order.\n\ -\n\ -The remaining arguments @var{precision}, @var{skip}, and @var{arch} are\n\ -optional, and are interpreted as described for @code{fread}.\n\ -\n\ -The behavior of @code{fwrite} is undefined if the values in @var{data}\n\ -are too large to fit in the specified precision.\n\ -@seealso{fread, fputs, fprintf, fopen}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} fwrite (@var{fid}, @var{data}) +@deftypefnx {} {} fwrite (@var{fid}, @var{data}, @var{precision}) +@deftypefnx {} {} fwrite (@var{fid}, @var{data}, @var{precision}, @var{skip}) +@deftypefnx {} {} fwrite (@var{fid}, @var{data}, @var{precision}, @var{skip}, @var{arch}) +@deftypefnx {} {@var{count} =} fwrite (@dots{}) +Write data in binary form to the file specified by the file descriptor +@var{fid}, returning the number of values @var{count} successfully written +to the file. + +The argument @var{data} is a matrix of values that are to be written to +the file. The values are extracted in column-major order. + +The remaining arguments @var{precision}, @var{skip}, and @var{arch} are +optional, and are interpreted as described for @code{fread}. + +The behavior of @code{fwrite} is undefined if the values in @var{data} +are too large to fit in the specified precision. +@seealso{fread, fputs, fprintf, fopen} +@end deftypefn */) { int nargin = args.length (); @@ -2586,16 +2586,16 @@ } DEFUNX ("feof", Ffeof, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{status} =} feof (@var{fid})\n\ -Return 1 if an end-of-file condition has been encountered for the file\n\ -specified by file descriptor @var{fid} and 0 otherwise.\n\ -\n\ -Note that @code{feof} will only return 1 if the end of the file has already\n\ -been encountered, not if the next read operation will result in an\n\ -end-of-file condition.\n\ -@seealso{fread, frewind, fseek, fclear, fopen}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{status} =} feof (@var{fid}) +Return 1 if an end-of-file condition has been encountered for the file +specified by file descriptor @var{fid} and 0 otherwise. + +Note that @code{feof} will only return 1 if the end of the file has already +been encountered, not if the next read operation will result in an +end-of-file condition. +@seealso{fread, frewind, fseek, fclear, fopen} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -2606,25 +2606,25 @@ } DEFUNX ("ferror", Fferror, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{msg} =} ferror (@var{fid})\n\ -@deftypefnx {} {[@var{msg}, @var{err}] =} ferror (@var{fid})\n\ -@deftypefnx {} {[@var{dots}] =} ferror (@var{fid}, \"clear\")\n\ -Query the error status of the stream specified by file descriptor @var{fid}\n\ -\n\ -If an error condition exists then return a string @var{msg} describing the\n\ -error. Otherwise, return an empty string @qcode{\"\"}.\n\ -\n\ -The second input @qcode{\"clear\"} is optional. If supplied, the error\n\ -state on the stream will be cleared.\n\ -\n\ -The optional second output is a numeric indication of the error status.\n\ -@var{err} is 1 if an error condition has been encountered and 0 otherwise.\n\ -\n\ -Note that @code{ferror} indicates if an error has already occurred, not\n\ -whether the next operation will result in an error condition.\n\ -@seealso{fclear, fopen}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{msg} =} ferror (@var{fid}) +@deftypefnx {} {[@var{msg}, @var{err}] =} ferror (@var{fid}) +@deftypefnx {} {[@var{dots}] =} ferror (@var{fid}, "clear") +Query the error status of the stream specified by file descriptor @var{fid} + +If an error condition exists then return a string @var{msg} describing the +error. Otherwise, return an empty string @qcode{""}. + +The second input @qcode{"clear"} is optional. If supplied, the error +state on the stream will be cleared. + +The optional second output is a numeric indication of the error status. +@var{err} is 1 if an error condition has been encountered and 0 otherwise. + +Note that @code{ferror} indicates if an error has already occurred, not +whether the next operation will result in an error condition. +@seealso{fclear, fopen} +@end deftypefn */) { int nargin = args.length (); @@ -2650,42 +2650,42 @@ } DEFUNX ("popen", Fpopen, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{fid} =} popen (@var{command}, @var{mode})\n\ -Start a process and create a pipe.\n\ -\n\ -The name of the command to run is given by @var{command}. The argument\n\ -@var{mode} may be\n\ -\n\ -@table @code\n\ -@item @qcode{\"r\"}\n\ -The pipe will be connected to the standard output of the process, and\n\ -open for reading.\n\ -\n\ -@item @qcode{\"w\"}\n\ -The pipe will be connected to the standard input of the process, and\n\ -open for writing.\n\ -@end table\n\ -\n\ -The file identifier corresponding to the input or output stream of the\n\ -process is returned in @var{fid}.\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -fid = popen (\"ls -ltr / | tail -3\", \"r\");\n\ -while (ischar (s = fgets (fid)))\n\ - fputs (stdout, s);\n\ -endwhile\n\ -\n\ - @print{} drwxr-xr-x 33 root root 3072 Feb 15 13:28 etc\n\ - @print{} drwxr-xr-x 3 root root 1024 Feb 15 13:28 lib\n\ - @print{} drwxrwxrwt 15 root root 2048 Feb 17 14:53 tmp\n\ -@end group\n\ -@end example\n\ -@seealso{popen2}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{fid} =} popen (@var{command}, @var{mode}) +Start a process and create a pipe. + +The name of the command to run is given by @var{command}. The argument +@var{mode} may be + +@table @code +@item @qcode{"r"} +The pipe will be connected to the standard output of the process, and +open for reading. + +@item @qcode{"w"} +The pipe will be connected to the standard input of the process, and +open for writing. +@end table + +The file identifier corresponding to the input or output stream of the +process is returned in @var{fid}. + +For example: + +@example +@group +fid = popen ("ls -ltr / | tail -3", "r"); +while (ischar (s = fgets (fid))) + fputs (stdout, s); +endwhile + + @print{} drwxr-xr-x 33 root root 3072 Feb 15 13:28 etc + @print{} drwxr-xr-x 3 root root 1024 Feb 15 13:28 lib + @print{} drwxrwxrwt 15 root root 2048 Feb 17 14:53 tmp +@end group +@end example +@seealso{popen2} +@end deftypefn */) { if (args.length () != 2) print_usage (); @@ -2714,13 +2714,13 @@ } DEFUNX ("pclose", Fpclose, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} pclose (@var{fid})\n\ -Close a file identifier that was opened by @code{popen}.\n\ -\n\ -The function @code{fclose} may also be used for the same purpose.\n\ -@seealso{fclose, popen}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} pclose (@var{fid}) +Close a file identifier that was opened by @code{popen}. + +The function @code{fclose} may also be used for the same purpose. +@seealso{fclose, popen} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -2729,24 +2729,24 @@ } DEFUN (tempname, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{fname} =} tempname ()\n\ -@deftypefnx {} {@var{fname} =} tempname (@var{dir})\n\ -@deftypefnx {} {@var{fname} =} tempname (@var{dir}, @var{prefix})\n\ -Return a unique temporary filename as a string.\n\ -\n\ -If @var{prefix} is omitted, a value of @qcode{\"oct-\"} is used.\n\ -\n\ -If @var{dir} is also omitted, the default directory for temporary files\n\ -(@code{P_tmpdir}) is used. If @var{dir} is provided, it must exist,\n\ -otherwise the default directory for temporary files is used.\n\ -\n\ -Programming Note: Because the named file is not opened by @code{tempname},\n\ -it is possible, though relatively unlikely, that it will not be available\n\ -by the time your program attempts to open it. If this is a concern,\n\ -see @code{tmpfile}.\n\ -@seealso{mkstemp, tempdir, P_tmpdir, tmpfile}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{fname} =} tempname () +@deftypefnx {} {@var{fname} =} tempname (@var{dir}) +@deftypefnx {} {@var{fname} =} tempname (@var{dir}, @var{prefix}) +Return a unique temporary filename as a string. + +If @var{prefix} is omitted, a value of @qcode{"oct-"} is used. + +If @var{dir} is also omitted, the default directory for temporary files +(@code{P_tmpdir}) is used. If @var{dir} is provided, it must exist, +otherwise the default directory for temporary files is used. + +Programming Note: Because the named file is not opened by @code{tempname}, +it is possible, though relatively unlikely, that it will not be available +by the time your program attempts to open it. If this is a concern, +see @code{tmpfile}. +@seealso{mkstemp, tempdir, P_tmpdir, tmpfile} +@end deftypefn */) { int nargin = args.length (); @@ -2820,19 +2820,19 @@ */ DEFUN (tmpfile, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{fid}, @var{msg}] =} tmpfile ()\n\ -Return the file ID corresponding to a new temporary file with a unique\n\ -name.\n\ -\n\ -The file is opened in binary read/write (@qcode{\"w+b\"}) mode and will be\n\ -deleted automatically when it is closed or when Octave exits.\n\ -\n\ -If successful, @var{fid} is a valid file ID and @var{msg} is an empty\n\ -string. Otherwise, @var{fid} is -1 and @var{msg} contains a\n\ -system-dependent error message.\n\ -@seealso{tempname, mkstemp, tempdir, P_tmpdir}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{fid}, @var{msg}] =} tmpfile () +Return the file ID corresponding to a new temporary file with a unique +name. + +The file is opened in binary read/write (@qcode{"w+b"}) mode and will be +deleted automatically when it is closed or when Octave exits. + +If successful, @var{fid} is a valid file ID and @var{msg} is an empty +string. Otherwise, @var{fid} is -1 and @var{msg} contains a +system-dependent error message. +@seealso{tempname, mkstemp, tempdir, P_tmpdir} +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -2863,28 +2863,28 @@ } DEFUN (mkstemp, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{fid}, @var{name}, @var{msg}] =} mkstemp (\"@var{template}\")\n\ -@deftypefnx {} {[@var{fid}, @var{name}, @var{msg}] =} mkstemp (\"@var{template}\", @var{delete})\n\ -Return the file descriptor @var{fid} corresponding to a new temporary file\n\ -with a unique name created from @var{template}.\n\ -\n\ -The last six characters of @var{template} must be @qcode{\"XXXXXX\"} and\n\ -these are replaced with a string that makes the filename unique. The file\n\ -is then created with mode read/write and permissions that are system\n\ -dependent (on GNU/Linux systems, the permissions will be 0600 for versions\n\ -of glibc 2.0.7 and later). The file is opened in binary mode and with the\n\ -@w{@code{O_EXCL}} flag.\n\ -\n\ -If the optional argument @var{delete} is supplied and is true, the file will\n\ -be deleted automatically when Octave exits.\n\ -\n\ -If successful, @var{fid} is a valid file ID, @var{name} is the name of the\n\ -file, and @var{msg} is an empty string. Otherwise, @var{fid} is -1,\n\ -@var{name} is empty, and @var{msg} contains a system-dependent error\n\ -message.\n\ -@seealso{tempname, tempdir, P_tmpdir, tmpfile, fopen}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{fid}, @var{name}, @var{msg}] =} mkstemp ("@var{template}") +@deftypefnx {} {[@var{fid}, @var{name}, @var{msg}] =} mkstemp ("@var{template}", @var{delete}) +Return the file descriptor @var{fid} corresponding to a new temporary file +with a unique name created from @var{template}. + +The last six characters of @var{template} must be @qcode{"XXXXXX"} and +these are replaced with a string that makes the filename unique. The file +is then created with mode read/write and permissions that are system +dependent (on GNU/Linux systems, the permissions will be 0600 for versions +of glibc 2.0.7 and later). The file is opened in binary mode and with the +@w{@code{O_EXCL}} flag. + +If the optional argument @var{delete} is supplied and is true, the file will +be deleted automatically when Octave exits. + +If successful, @var{fid} is a valid file ID, @var{name} is the name of the +file, and @var{msg} is an empty string. Otherwise, @var{fid} is -1, +@var{name} is empty, and @var{msg} contains a system-dependent error +message. +@seealso{tempname, tempdir, P_tmpdir, tmpfile, fopen} +@end deftypefn */) { int nargin = args.length (); @@ -2967,22 +2967,22 @@ } DEFUNX ("umask", Fumask, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} umask (@var{mask})\n\ -Set the permission mask for file creation.\n\ -\n\ -The parameter @var{mask} is an integer, interpreted as an octal number.\n\ -\n\ -If successful, returns the previous value of the mask (as an integer to be\n\ -interpreted as an octal number); otherwise an error message is printed.\n\ -\n\ -The permission mask is a UNIX concept used when creating new objects on a\n\ -file system such as files, directories, or named FIFOs. The object to be\n\ -created has base permissions in an octal number @var{mode} which are\n\ -modified according to the octal value of @var{mask}. The final permissions\n\ -for the new object are @code{@var{mode} - @var{mask}}.\n\ -@seealso{fopen, mkdir, mkfifo}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} umask (@var{mask}) +Set the permission mask for file creation. + +The parameter @var{mask} is an integer, interpreted as an octal number. + +If successful, returns the previous value of the mask (as an integer to be +interpreted as an octal number); otherwise an error message is printed. + +The permission mask is a UNIX concept used when creating new objects on a +file system such as files, directories, or named FIFOs. The object to be +created has base permissions in an octal number @var{mode} which are +modified according to the octal value of @var{mask}. The final permissions +for the new object are @code{@var{mode} - @var{mask}}. +@seealso{fopen, mkdir, mkfifo} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -3012,17 +3012,17 @@ } DEFUNX ("P_tmpdir", FP_tmpdir, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} P_tmpdir ()\n\ -Return the name of the host system's @strong{default} directory for\n\ -temporary files.\n\ -\n\ -Programming Note: The value returned by @code{P_tmpdir} is always the\n\ -default location. This value may not agree with that returned from\n\ -@code{tempdir} if the user has overridden the default with the @env{TMPDIR}\n\ -environment variable.\n\ -@seealso{tempdir, tempname, mkstemp, tmpfile}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} P_tmpdir () +Return the name of the host system's @strong{default} directory for +temporary files. + +Programming Note: The value returned by @code{P_tmpdir} is always the +default location. This value may not agree with that returned from +@code{tempdir} if the user has overridden the default with the @env{TMPDIR} +environment variable. +@seealso{tempdir, tempname, mkstemp, tmpfile} +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -3034,47 +3034,47 @@ // this way for Matlab compatibility. DEFUNX ("SEEK_SET", FSEEK_SET, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} SEEK_SET ()\n\ -@deftypefnx {} {} SEEK_CUR ()\n\ -@deftypefnx {} {} SEEK_END ()\n\ -Return the numerical value to pass to @code{fseek} to perform one of the\n\ -following actions:\n\ -\n\ -@table @code\n\ -@item SEEK_SET\n\ -Position file relative to the beginning.\n\ -\n\ -@item SEEK_CUR\n\ -Position file relative to the current position.\n\ -\n\ -@item SEEK_END\n\ -Position file relative to the end.\n\ -@end table\n\ -@seealso{fseek}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} SEEK_SET () +@deftypefnx {} {} SEEK_CUR () +@deftypefnx {} {} SEEK_END () +Return the numerical value to pass to @code{fseek} to perform one of the +following actions: + +@table @code +@item SEEK_SET +Position file relative to the beginning. + +@item SEEK_CUR +Position file relative to the current position. + +@item SEEK_END +Position file relative to the end. +@end table +@seealso{fseek} +@end deftypefn */) { return const_value ("SEEK_SET", args, -1); } DEFUNX ("SEEK_CUR", FSEEK_CUR, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} SEEK_CUR ()\n\ -Return the numerical value to pass to @code{fseek} to\n\ -position the file pointer relative to the current position.\n\ -@seealso{SEEK_SET, SEEK_END}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} SEEK_CUR () +Return the numerical value to pass to @code{fseek} to +position the file pointer relative to the current position. +@seealso{SEEK_SET, SEEK_END} +@end deftypefn */) { return const_value ("SEEK_CUR", args, 0); } DEFUNX ("SEEK_END", FSEEK_END, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} SEEK_END ()\n\ -Return the numerical value to pass to @code{fseek} to\n\ -position the file pointer relative to the end of the file.\n\ -@seealso{SEEK_SET, SEEK_CUR}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} SEEK_END () +Return the numerical value to pass to @code{fseek} to +position the file pointer relative to the end of the file. +@seealso{SEEK_SET, SEEK_CUR} +@end deftypefn */) { return const_value ("SEEK_END", args, 1); } @@ -3090,39 +3090,39 @@ } DEFUNX ("stdin", Fstdin, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} stdin ()\n\ -Return the numeric value corresponding to the standard input stream.\n\ -\n\ -When Octave is used interactively, stdin is filtered through the command\n\ -line editing functions.\n\ -@seealso{stdout, stderr}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} stdin () +Return the numeric value corresponding to the standard input stream. + +When Octave is used interactively, stdin is filtered through the command +line editing functions. +@seealso{stdout, stderr} +@end deftypefn */) { return const_value ("stdin", args, stdin_file); } DEFUNX ("stdout", Fstdout, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} stdout ()\n\ -Return the numeric value corresponding to the standard output stream.\n\ -\n\ -Data written to the standard output is normally filtered through the pager.\n\ -@seealso{stdin, stderr}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} stdout () +Return the numeric value corresponding to the standard output stream. + +Data written to the standard output is normally filtered through the pager. +@seealso{stdin, stderr} +@end deftypefn */) { return const_value ("stdout", args, stdout_file); } DEFUNX ("stderr", Fstderr, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} stderr ()\n\ -Return the numeric value corresponding to the standard error stream.\n\ -\n\ -Even if paging is turned on, the standard error is not sent to the pager.\n\ -It is useful for error messages and prompts.\n\ -@seealso{stdin, stdout}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} stderr () +Return the numeric value corresponding to the standard error stream. + +Even if paging is turned on, the standard error is not sent to the pager. +It is useful for error messages and prompts. +@seealso{stdin, stdout} +@end deftypefn */) { return const_value ("stderr", args, stderr_file); }
--- a/libinterp/corefcn/filter.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/filter.cc Tue Jun 21 16:07:51 2016 -0400 @@ -228,107 +228,107 @@ } DEFUN (filter, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{y} =} filter (@var{b}, @var{a}, @var{x})\n\ -@deftypefnx {} {[@var{y}, @var{sf}] =} filter (@var{b}, @var{a}, @var{x}, @var{si})\n\ -@deftypefnx {} {[@var{y}, @var{sf}] =} filter (@var{b}, @var{a}, @var{x}, [], @var{dim})\n\ -@deftypefnx {} {[@var{y}, @var{sf}] =} filter (@var{b}, @var{a}, @var{x}, @var{si}, @var{dim})\n\ -Apply a 1-D digital filter to the data @var{x}.\n\ -\n\ -@code{filter} returns the solution to the following linear, time-invariant\n\ -difference equation:\n\ -@tex\n\ -$$\n\ -\\sum_{k=0}^N a_{k+1} y_{n-k} = \\sum_{k=0}^M b_{k+1} x_{n-k}, \\qquad\n\ - 1 \\le n \\le P\n\ -$$\n\ -@end tex\n\ -@ifnottex\n\ -@c Set example in small font to prevent overfull line\n\ -\n\ -@smallexample\n\ -@group\n\ - N M\n\ -SUM a(k+1) y(n-k) = SUM b(k+1) x(n-k) for 1<=n<=length(x)\n\ -k=0 k=0\n\ -@end group\n\ -@end smallexample\n\ -\n\ -@end ifnottex\n\ -\n\ -@noindent\n\ -where\n\ -@ifnottex\n\ -N=length(a)-1 and M=length(b)-1.\n\ -@end ifnottex\n\ -@tex\n\ -$a \\in \\Re^{N-1}$, $b \\in \\Re^{M-1}$, and $x \\in \\Re^P$.\n\ -@end tex\n\ -The result is calculated over the first non-singleton dimension of @var{x}\n\ -or over @var{dim} if supplied.\n\ -\n\ -An equivalent form of the equation is:\n\ -@tex\n\ -$$\n\ -y_n = -\\sum_{k=1}^N c_{k+1} y_{n-k} + \\sum_{k=0}^M d_{k+1} x_{n-k}, \\qquad\n\ - 1 \\le n \\le P\n\ -$$\n\ -@end tex\n\ -@ifnottex\n\ -@c Set example in small font to prevent overfull line\n\ -\n\ -@smallexample\n\ -@group\n\ - N M\n\ -y(n) = - SUM c(k+1) y(n-k) + SUM d(k+1) x(n-k) for 1<=n<=length(x)\n\ - k=1 k=0\n\ -@end group\n\ -@end smallexample\n\ -\n\ -@end ifnottex\n\ -\n\ -@noindent\n\ -where\n\ -@ifnottex\n\ - c = a/a(1) and d = b/a(1).\n\ -@end ifnottex\n\ -@tex\n\ -$c = a/a_1$ and $d = b/a_1$.\n\ -@end tex\n\ -\n\ -If the fourth argument @var{si} is provided, it is taken as the\n\ -initial state of the system and the final state is returned as\n\ -@var{sf}. The state vector is a column vector whose length is\n\ -equal to the length of the longest coefficient vector minus one.\n\ -If @var{si} is not supplied, the initial state vector is set to all\n\ -zeros.\n\ -\n\ -In terms of the Z Transform, @var{y} is the result of passing the\n\ -discrete-time signal @var{x} through a system characterized by the following\n\ -rational system function:\n\ -@tex\n\ -$$\n\ -H(z) = {\\displaystyle\\sum_{k=0}^M d_{k+1} z^{-k}\n\ - \\over 1 + \\displaystyle\\sum_{k+1}^N c_{k+1} z^{-k}}\n\ -$$\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ -@group\n\ - M\n\ - SUM d(k+1) z^(-k)\n\ - k=0\n\ -H(z) = ---------------------\n\ - N\n\ - 1 + SUM c(k+1) z^(-k)\n\ - k=1\n\ -@end group\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -@seealso{filter2, fftfilt, freqz}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{y} =} filter (@var{b}, @var{a}, @var{x}) +@deftypefnx {} {[@var{y}, @var{sf}] =} filter (@var{b}, @var{a}, @var{x}, @var{si}) +@deftypefnx {} {[@var{y}, @var{sf}] =} filter (@var{b}, @var{a}, @var{x}, [], @var{dim}) +@deftypefnx {} {[@var{y}, @var{sf}] =} filter (@var{b}, @var{a}, @var{x}, @var{si}, @var{dim}) +Apply a 1-D digital filter to the data @var{x}. + +@code{filter} returns the solution to the following linear, time-invariant +difference equation: +@tex +$$ +\sum_{k=0}^N a_{k+1} y_{n-k} = \sum_{k=0}^M b_{k+1} x_{n-k}, \qquad + 1 \le n \le P +$$ +@end tex +@ifnottex +@c Set example in small font to prevent overfull line + +@smallexample +@group + N M +SUM a(k+1) y(n-k) = SUM b(k+1) x(n-k) for 1<=n<=length(x) +k=0 k=0 +@end group +@end smallexample + +@end ifnottex + +@noindent +where +@ifnottex +N=length(a)-1 and M=length(b)-1. +@end ifnottex +@tex +$a \in \Re^{N-1}$, $b \in \Re^{M-1}$, and $x \in \Re^P$. +@end tex +The result is calculated over the first non-singleton dimension of @var{x} +or over @var{dim} if supplied. + +An equivalent form of the equation is: +@tex +$$ +y_n = -\sum_{k=1}^N c_{k+1} y_{n-k} + \sum_{k=0}^M d_{k+1} x_{n-k}, \qquad + 1 \le n \le P +$$ +@end tex +@ifnottex +@c Set example in small font to prevent overfull line + +@smallexample +@group + N M +y(n) = - SUM c(k+1) y(n-k) + SUM d(k+1) x(n-k) for 1<=n<=length(x) + k=1 k=0 +@end group +@end smallexample + +@end ifnottex + +@noindent +where +@ifnottex + c = a/a(1) and d = b/a(1). +@end ifnottex +@tex +$c = a/a_1$ and $d = b/a_1$. +@end tex + +If the fourth argument @var{si} is provided, it is taken as the +initial state of the system and the final state is returned as +@var{sf}. The state vector is a column vector whose length is +equal to the length of the longest coefficient vector minus one. +If @var{si} is not supplied, the initial state vector is set to all +zeros. + +In terms of the Z Transform, @var{y} is the result of passing the +discrete-time signal @var{x} through a system characterized by the following +rational system function: +@tex +$$ +H(z) = {\displaystyle\sum_{k=0}^M d_{k+1} z^{-k} + \over 1 + \displaystyle\sum_{k+1}^N c_{k+1} z^{-k}} +$$ +@end tex +@ifnottex + +@example +@group + M + SUM d(k+1) z^(-k) + k=0 +H(z) = --------------------- + N + 1 + SUM c(k+1) z^(-k) + k=1 +@end group +@end example + +@end ifnottex +@seealso{filter2, fftfilt, freqz} +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/find.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/find.cc Tue Jun 21 16:07:51 2016 -0400 @@ -318,70 +318,70 @@ } DEFUN (find, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{idx} =} find (@var{x})\n\ -@deftypefnx {} {@var{idx} =} find (@var{x}, @var{n})\n\ -@deftypefnx {} {@var{idx} =} find (@var{x}, @var{n}, @var{direction})\n\ -@deftypefnx {} {[i, j] =} find (@dots{})\n\ -@deftypefnx {} {[i, j, v] =} find (@dots{})\n\ -Return a vector of indices of nonzero elements of a matrix, as a row if\n\ -@var{x} is a row vector or as a column otherwise.\n\ -\n\ -To obtain a single index for each matrix element, Octave pretends that the\n\ -columns of a matrix form one long vector (like Fortran arrays are stored).\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -find (eye (2))\n\ - @result{} [ 1; 4 ]\n\ -@end group\n\ -@end example\n\ -\n\ -If two inputs are given, @var{n} indicates the maximum number of elements to\n\ -find from the beginning of the matrix or vector.\n\ -\n\ -If three inputs are given, @var{direction} should be one of\n\ -@qcode{\"first\"} or @qcode{\"last\"}, requesting only the first or last\n\ -@var{n} indices, respectively. However, the indices are always returned in\n\ -ascending order.\n\ -\n\ -If two outputs are requested, @code{find} returns the row and column\n\ -indices of nonzero elements of a matrix. For example:\n\ -\n\ -@example\n\ -@group\n\ -[i, j] = find (2 * eye (2))\n\ - @result{} i = [ 1; 2 ]\n\ - @result{} j = [ 1; 2 ]\n\ -@end group\n\ -@end example\n\ -\n\ -If three outputs are requested, @code{find} also returns a vector\n\ -containing the nonzero values. For example:\n\ -\n\ -@example\n\ -@group\n\ -[i, j, v] = find (3 * eye (2))\n\ - @result{} i = [ 1; 2 ]\n\ - @result{} j = [ 1; 2 ]\n\ - @result{} v = [ 3; 3 ]\n\ -@end group\n\ -@end example\n\ -\n\ -Note that this function is particularly useful for sparse matrices, as\n\ -it extracts the nonzero elements as vectors, which can then be used to\n\ -create the original matrix. For example:\n\ -\n\ -@example\n\ -@group\n\ -sz = size (a);\n\ -[i, j, v] = find (a);\n\ -b = sparse (i, j, v, sz(1), sz(2));\n\ -@end group\n\ -@end example\n\ -@seealso{nonzeros}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{idx} =} find (@var{x}) +@deftypefnx {} {@var{idx} =} find (@var{x}, @var{n}) +@deftypefnx {} {@var{idx} =} find (@var{x}, @var{n}, @var{direction}) +@deftypefnx {} {[i, j] =} find (@dots{}) +@deftypefnx {} {[i, j, v] =} find (@dots{}) +Return a vector of indices of nonzero elements of a matrix, as a row if +@var{x} is a row vector or as a column otherwise. + +To obtain a single index for each matrix element, Octave pretends that the +columns of a matrix form one long vector (like Fortran arrays are stored). +For example: + +@example +@group +find (eye (2)) + @result{} [ 1; 4 ] +@end group +@end example + +If two inputs are given, @var{n} indicates the maximum number of elements to +find from the beginning of the matrix or vector. + +If three inputs are given, @var{direction} should be one of +@qcode{"first"} or @qcode{"last"}, requesting only the first or last +@var{n} indices, respectively. However, the indices are always returned in +ascending order. + +If two outputs are requested, @code{find} returns the row and column +indices of nonzero elements of a matrix. For example: + +@example +@group +[i, j] = find (2 * eye (2)) + @result{} i = [ 1; 2 ] + @result{} j = [ 1; 2 ] +@end group +@end example + +If three outputs are requested, @code{find} also returns a vector +containing the nonzero values. For example: + +@example +@group +[i, j, v] = find (3 * eye (2)) + @result{} i = [ 1; 2 ] + @result{} j = [ 1; 2 ] + @result{} v = [ 3; 3 ] +@end group +@end example + +Note that this function is particularly useful for sparse matrices, as +it extracts the nonzero elements as vectors, which can then be used to +create the original matrix. For example: + +@example +@group +sz = size (a); +[i, j, v] = find (a); +b = sparse (i, j, v, sz(1), sz(2)); +@end group +@end example +@seealso{nonzeros} +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/gammainc.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/gammainc.cc Tue Jun 21 16:07:51 2016 -0400 @@ -33,50 +33,50 @@ #include "utils.h" DEFUN (gammainc, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} gammainc (@var{x}, @var{a})\n\ -@deftypefnx {} {} gammainc (@var{x}, @var{a}, \"lower\")\n\ -@deftypefnx {} {} gammainc (@var{x}, @var{a}, \"upper\")\n\ -Compute the normalized incomplete gamma function.\n\ -\n\ -This is defined as\n\ -@tex\n\ -$$\n\ - \\gamma (x, a) = {1 \\over {\\Gamma (a)}}\\displaystyle{\\int_0^x t^{a-1} e^{-t} dt}\n\ -$$\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ -@group\n\ - x\n\ - 1 /\n\ -gammainc (x, a) = --------- | exp (-t) t^(a-1) dt\n\ - gamma (a) /\n\ - t=0\n\ -@end group\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -with the limiting value of 1 as @var{x} approaches infinity.\n\ -The standard notation is @math{P(a,x)}, e.g., @nospell{Abramowitz} and\n\ -@nospell{Stegun} (6.5.1).\n\ -\n\ -If @var{a} is scalar, then @code{gammainc (@var{x}, @var{a})} is returned\n\ -for each element of @var{x} and vice versa.\n\ -\n\ -If neither @var{x} nor @var{a} is scalar, the sizes of @var{x} and\n\ -@var{a} must agree, and @code{gammainc} is applied element-by-element.\n\ -\n\ -By default the incomplete gamma function integrated from 0 to @var{x} is\n\ -computed. If @qcode{\"upper\"} is given then the complementary function\n\ -integrated from @var{x} to infinity is calculated. It should be noted that\n\ -\n\ -@example\n\ -gammainc (@var{x}, @var{a}) @equiv{} 1 - gammainc (@var{x}, @var{a}, \"upper\")\n\ -@end example\n\ -@seealso{gamma, gammaln}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} gammainc (@var{x}, @var{a}) +@deftypefnx {} {} gammainc (@var{x}, @var{a}, "lower") +@deftypefnx {} {} gammainc (@var{x}, @var{a}, "upper") +Compute the normalized incomplete gamma function. + +This is defined as +@tex +$$ + \gamma (x, a) = {1 \over {\Gamma (a)}}\displaystyle{\int_0^x t^{a-1} e^{-t} dt} +$$ +@end tex +@ifnottex + +@example +@group + x + 1 / +gammainc (x, a) = --------- | exp (-t) t^(a-1) dt + gamma (a) / + t=0 +@end group +@end example + +@end ifnottex +with the limiting value of 1 as @var{x} approaches infinity. +The standard notation is @math{P(a,x)}, e.g., @nospell{Abramowitz} and +@nospell{Stegun} (6.5.1). + +If @var{a} is scalar, then @code{gammainc (@var{x}, @var{a})} is returned +for each element of @var{x} and vice versa. + +If neither @var{x} nor @var{a} is scalar, the sizes of @var{x} and +@var{a} must agree, and @code{gammainc} is applied element-by-element. + +By default the incomplete gamma function integrated from 0 to @var{x} is +computed. If @qcode{"upper"} is given then the complementary function +integrated from @var{x} to infinity is calculated. It should be noted that + +@example +gammainc (@var{x}, @var{a}) @equiv{} 1 - gammainc (@var{x}, @var{a}, "upper") +@end example +@seealso{gamma, gammaln} +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/gcd.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/gcd.cc Tue Jun 21 16:07:51 2016 -0400 @@ -434,43 +434,43 @@ } DEFUN (gcd, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{g} =} gcd (@var{a1}, @var{a2}, @dots{})\n\ -@deftypefnx {} {[@var{g}, @var{v1}, @dots{}] =} gcd (@var{a1}, @var{a2}, @dots{})\n\ -Compute the greatest common divisor of @var{a1}, @var{a2}, @dots{}.\n\ -\n\ -If more than one argument is given then all arguments must be the same size\n\ -or scalar. In this case the greatest common divisor is calculated for each\n\ -element individually. All elements must be ordinary or Gaussian (complex)\n\ -integers. Note that for Gaussian integers, the gcd is only unique up to a\n\ -phase factor (multiplication by 1, -1, i, or -i), so an arbitrary greatest\n\ -common divisor among the four possible is returned.\n\ -\n\ -Optional return arguments @var{v1}, @dots{}, contain integer vectors such\n\ -that,\n\ -\n\ -@tex\n\ -$g = v_1 a_1 + v_2 a_2 + \\cdots$\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ -@var{g} = @var{v1} .* @var{a1} + @var{v2} .* @var{a2} + @dots{}\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -\n\ -Example code:\n\ -\n\ -@example\n\ -@group\n\ -gcd ([15, 9], [20, 18])\n\ - @result{} 5 9\n\ -@end group\n\ -@end example\n\ -\n\ -@seealso{lcm, factor, isprime}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{g} =} gcd (@var{a1}, @var{a2}, @dots{}) +@deftypefnx {} {[@var{g}, @var{v1}, @dots{}] =} gcd (@var{a1}, @var{a2}, @dots{}) +Compute the greatest common divisor of @var{a1}, @var{a2}, @dots{}. + +If more than one argument is given then all arguments must be the same size +or scalar. In this case the greatest common divisor is calculated for each +element individually. All elements must be ordinary or Gaussian (complex) +integers. Note that for Gaussian integers, the gcd is only unique up to a +phase factor (multiplication by 1, -1, i, or -i), so an arbitrary greatest +common divisor among the four possible is returned. + +Optional return arguments @var{v1}, @dots{}, contain integer vectors such +that, + +@tex +$g = v_1 a_1 + v_2 a_2 + \cdots$ +@end tex +@ifnottex + +@example +@var{g} = @var{v1} .* @var{a1} + @var{v2} .* @var{a2} + @dots{} +@end example + +@end ifnottex + +Example code: + +@example +@group +gcd ([15, 9], [20, 18]) + @result{} 5 9 +@end group +@end example + +@seealso{lcm, factor, isprime} +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/getgrent.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/getgrent.cc Tue Jun 21 16:07:51 2016 -0400 @@ -63,13 +63,13 @@ } DEFUN (getgrent, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{grp_struct} =} getgrent ()\n\ -Return an entry from the group database, opening it if necessary.\n\ -\n\ -Once the end of data has been reached, @code{getgrent} returns 0.\n\ -@seealso{setgrent, endgrent}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{grp_struct} =} getgrent () +Return an entry from the group database, opening it if necessary. + +Once the end of data has been reached, @code{getgrent} returns 0. +@seealso{setgrent, endgrent} +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -83,14 +83,14 @@ } DEFUN (getgrgid, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{grp_struct} =} getgrgid (@var{gid}).\n\ -Return the first entry from the group database with the group ID\n\ -@var{gid}.\n\ -\n\ -If the group ID does not exist in the database, @code{getgrgid} returns 0.\n\ -@seealso{getgrnam}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{grp_struct} =} getgrgid (@var{gid}). +Return the first entry from the group database with the group ID +@var{gid}. + +If the group ID does not exist in the database, @code{getgrgid} returns 0. +@seealso{getgrnam} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -111,14 +111,14 @@ } DEFUN (getgrnam, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{grp_struct} =} getgrnam (@var{name})\n\ -Return the first entry from the group database with the group name\n\ -@var{name}.\n\ -\n\ -If the group name does not exist in the database, @code{getgrnam} returns 0.\n\ -@seealso{getgrgid}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{grp_struct} =} getgrnam (@var{name}) +Return the first entry from the group database with the group name +@var{name}. + +If the group name does not exist in the database, @code{getgrnam} returns 0. +@seealso{getgrgid} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -134,11 +134,11 @@ } DEFUN (setgrent, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} setgrent ()\n\ -Return the internal pointer to the beginning of the group database.\n\ -@seealso{getgrent, endgrent}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} setgrent () +Return the internal pointer to the beginning of the group database. +@seealso{getgrent, endgrent} +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -152,11 +152,11 @@ } DEFUN (endgrent, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} endgrent ()\n\ -Close the group database.\n\ -@seealso{getgrent, setgrent}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} endgrent () +Close the group database. +@seealso{getgrent, setgrent} +@end deftypefn */) { if (args.length () != 0) print_usage ();
--- a/libinterp/corefcn/getpwent.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/getpwent.cc Tue Jun 21 16:07:51 2016 -0400 @@ -66,14 +66,14 @@ } DEFUN (getpwent, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{pw_struct} =} getpwent ()\n\ -Return a structure containing an entry from the password database,\n\ -opening it if necessary.\n\ -\n\ -Once the end of the data has been reached, @code{getpwent} returns 0.\n\ -@seealso{setpwent, endpwent}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{pw_struct} =} getpwent () +Return a structure containing an entry from the password database, +opening it if necessary. + +Once the end of the data has been reached, @code{getpwent} returns 0. +@seealso{setpwent, endpwent} +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -87,14 +87,14 @@ } DEFUN (getpwuid, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{pw_struct} =} getpwuid (@var{uid}).\n\ -Return a structure containing the first entry from the password database\n\ -with the user ID @var{uid}.\n\ -\n\ -If the user ID does not exist in the database, @code{getpwuid} returns 0.\n\ -@seealso{getpwnam}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{pw_struct} =} getpwuid (@var{uid}). +Return a structure containing the first entry from the password database +with the user ID @var{uid}. + +If the user ID does not exist in the database, @code{getpwuid} returns 0. +@seealso{getpwnam} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -115,14 +115,14 @@ } DEFUN (getpwnam, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{pw_struct} =} getpwnam (@var{name})\n\ -Return a structure containing the first entry from the password database\n\ -with the user name @var{name}.\n\ -\n\ -If the user name does not exist in the database, @code{getpwname} returns 0.\n\ -@seealso{getpwuid}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{pw_struct} =} getpwnam (@var{name}) +Return a structure containing the first entry from the password database +with the user name @var{name}. + +If the user name does not exist in the database, @code{getpwname} returns 0. +@seealso{getpwuid} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -138,11 +138,11 @@ } DEFUN (setpwent, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} setpwent ()\n\ -Return the internal pointer to the beginning of the password database.\n\ -@seealso{getpwent, endpwent}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} setpwent () +Return the internal pointer to the beginning of the password database. +@seealso{getpwent, endpwent} +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -156,11 +156,11 @@ } DEFUN (endpwent, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} endpwent ()\n\ -Close the password database.\n\ -@seealso{getpwent, setpwent}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} endpwent () +Close the password database. +@seealso{getpwent, setpwent} +@end deftypefn */) { if (args.length () != 0) print_usage ();
--- a/libinterp/corefcn/getrusage.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/getrusage.cc Tue Jun 21 16:07:51 2016 -0400 @@ -32,67 +32,67 @@ #include "ovl.h" DEFUN (getrusage, , , - "-*- texinfo -*-\n\ -@deftypefn {} {} getrusage ()\n\ -Return a structure containing a number of statistics about the current\n\ -Octave process.\n\ -\n\ -Not all fields are available on all systems. If it is not possible to get\n\ -CPU time statistics, the CPU time slots are set to zero. Other missing data\n\ -are replaced by NaN@. The list of possible fields is:\n\ -\n\ -@table @code\n\ -@item idrss\n\ -Unshared data size.\n\ -\n\ -@item inblock\n\ -Number of block input operations.\n\ -\n\ -@item isrss\n\ -Unshared stack size.\n\ -\n\ -@item ixrss\n\ -Shared memory size.\n\ -\n\ -@item majflt\n\ -Number of major page faults.\n\ -\n\ -@item maxrss\n\ -Maximum data size.\n\ -\n\ -@item minflt\n\ -Number of minor page faults.\n\ -\n\ -@item msgrcv\n\ -Number of messages received.\n\ -\n\ -@item msgsnd\n\ -Number of messages sent.\n\ -\n\ -@item nivcsw\n\ -Number of involuntary context switches.\n\ -\n\ -@item nsignals\n\ -Number of signals received.\n\ -\n\ -@item nswap\n\ -Number of swaps.\n\ -\n\ -@item nvcsw\n\ -Number of voluntary context switches.\n\ -\n\ -@item oublock\n\ -Number of block output operations.\n\ -\n\ -@item stime\n\ -A structure containing the system CPU time used. The structure has the\n\ -elements @code{sec} (seconds) @code{usec} (microseconds).\n\ -\n\ -@item utime\n\ -A structure containing the user CPU time used. The structure has the\n\ -elements @code{sec} (seconds) @code{usec} (microseconds).\n\ -@end table\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} getrusage () +Return a structure containing a number of statistics about the current +Octave process. + +Not all fields are available on all systems. If it is not possible to get +CPU time statistics, the CPU time slots are set to zero. Other missing data +are replaced by NaN@. The list of possible fields is: + +@table @code +@item idrss +Unshared data size. + +@item inblock +Number of block input operations. + +@item isrss +Unshared stack size. + +@item ixrss +Shared memory size. + +@item majflt +Number of major page faults. + +@item maxrss +Maximum data size. + +@item minflt +Number of minor page faults. + +@item msgrcv +Number of messages received. + +@item msgsnd +Number of messages sent. + +@item nivcsw +Number of involuntary context switches. + +@item nsignals +Number of signals received. + +@item nswap +Number of swaps. + +@item nvcsw +Number of voluntary context switches. + +@item oublock +Number of block output operations. + +@item stime +A structure containing the system CPU time used. The structure has the +elements @code{sec} (seconds) @code{usec} (microseconds). + +@item utime +A structure containing the user CPU time used. The structure has the +elements @code{sec} (seconds) @code{usec} (microseconds). +@end table +@end deftypefn */) { octave_scalar_map ru_map; octave_scalar_map tv_map;
--- a/libinterp/corefcn/givens.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/givens.cc Tue Jun 21 16:07:51 2016 -0400 @@ -31,48 +31,48 @@ #include "ovl.h" DEFUN (givens, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{G} =} givens (@var{x}, @var{y})\n\ -@deftypefnx {} {[@var{c}, @var{s}] =} givens (@var{x}, @var{y})\n\ -Compute the Givens rotation matrix @var{G}.\n\ -\n\ -@tex\n\ -The Givens matrix is a $2\\times 2$ orthogonal matrix\n\ -$$\n\ - G = \\left[\\matrix{c & s\\cr -s'& c\\cr}\\right]\n\ -$$\n\ -such that\n\ -$$\n\ - G \\left[\\matrix{x\\cr y}\\right] = \\left[\\matrix{\\ast\\cr 0}\\right]\n\ -$$\n\ -with $x$ and $y$ scalars.\n\ -@end tex\n\ -@ifnottex\n\ -The Givens matrix is a 2 by 2 orthogonal matrix\n\ -\n\ -@code{@var{g} = [@var{c} @var{s}; -@var{s}' @var{c}]}\n\ -\n\ -such that\n\ -\n\ -@code{@var{g} [@var{x}; @var{y}] = [*; 0]}\n\ -\n\ -with @var{x} and @var{y} scalars.\n\ -@end ifnottex\n\ -\n\ -If two output arguments are requested, return the factors @var{c} and\n\ -@var{s} rather than the Givens rotation matrix.\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -givens (1, 1)\n\ - @result{} 0.70711 0.70711\n\ - -0.70711 0.70711\n\ -@end group\n\ -@end example\n\ -@seealso{planerot}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{G} =} givens (@var{x}, @var{y}) +@deftypefnx {} {[@var{c}, @var{s}] =} givens (@var{x}, @var{y}) +Compute the Givens rotation matrix @var{G}. + +@tex +The Givens matrix is a $2\times 2$ orthogonal matrix +$$ + G = \left[\matrix{c & s\cr -s'& c\cr}\right] +$$ +such that +$$ + G \left[\matrix{x\cr y}\right] = \left[\matrix{\ast\cr 0}\right] +$$ +with $x$ and $y$ scalars. +@end tex +@ifnottex +The Givens matrix is a 2 by 2 orthogonal matrix + +@code{@var{g} = [@var{c} @var{s}; -@var{s}' @var{c}]} + +such that + +@code{@var{g} [@var{x}; @var{y}] = [*; 0]} + +with @var{x} and @var{y} scalars. +@end ifnottex + +If two output arguments are requested, return the factors @var{c} and +@var{s} rather than the Givens rotation matrix. + +For example: + +@example +@group +givens (1, 1) + @result{} 0.70711 0.70711 + -0.70711 0.70711 +@end group +@end example +@seealso{planerot} +@end deftypefn */) { if (args.length () != 2) print_usage ();
--- a/libinterp/corefcn/graphics.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/graphics.cc Tue Jun 21 16:07:51 2016 -0400 @@ -9747,15 +9747,15 @@ // --------------------------------------------------------------------- DEFUN (ishandle, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} ishandle (@var{h})\n\ -Return true if @var{h} is a graphics handle and false otherwise.\n\ -\n\ -@var{h} may also be a matrix of handles in which case a logical array is\n\ -returned that is true where the elements of @var{h} are graphics handles and\n\ -false where they are not.\n\ -@seealso{isaxes, isfigure}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} ishandle (@var{h}) +Return true if @var{h} is a graphics handle and false otherwise. + +@var{h} may also be a matrix of handles in which case a logical array is +returned that is true where the elements of @var{h} are graphics handles and +false where they are not. +@seealso{isaxes, isfigure} +@end deftypefn */) { gh_manager::auto_lock guard; @@ -9800,10 +9800,10 @@ } DEFUN (__is_handle_visible__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __is_handle_visible__ (@var{h})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __is_handle_visible__ (@var{h}) +Undocumented internal function. +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -9812,19 +9812,19 @@ } DEFUN (reset, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} reset (@var{h})\n\ -Reset the properties of the graphic object @var{h} to their default values.\n\ -\n\ -For figures, the properties @qcode{\"position\"}, @qcode{\"units\"},\n\ -@qcode{\"windowstyle\"}, and @qcode{\"paperunits\"} are not affected.\n\ -For axes, the properties @qcode{\"position\"} and @qcode{\"units\"} are\n\ -not affected.\n\ -\n\ -The input @var{h} may also be a vector of graphic handles in which case\n\ -each individual object will be reset.\n\ -@seealso{cla, clf, newplot}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} reset (@var{h}) +Reset the properties of the graphic object @var{h} to their default values. + +For figures, the properties @qcode{"position"}, @qcode{"units"}, +@qcode{"windowstyle"}, and @qcode{"paperunits"} are not affected. +For axes, the properties @qcode{"position"} and @qcode{"units"} are +not affected. + +The input @var{h} may also be a vector of graphic handles in which case +each individual object will be reset. +@seealso{cla, clf, newplot} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -9963,69 +9963,69 @@ */ DEFUN (set, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} set (@var{h}, @var{property}, @var{value}, @dots{})\n\ -@deftypefnx {} {} set (@var{h}, @var{properties}, @var{values})\n\ -@deftypefnx {} {} set (@var{h}, @var{pv})\n\ -@deftypefnx {} {@var{value_list} =} set (@var{h}, @var{property})\n\ -@deftypefnx {} {@var{all_value_list} =} set (@var{h})\n\ -Set named property values for the graphics handle (or vector of graphics\n\ -handles) @var{h}.\n\ -\n\ -There are three ways to give the property names and values:\n\ -\n\ -@itemize\n\ -@item as a comma separated list of @var{property}, @var{value} pairs\n\ -\n\ -Here, each @var{property} is a string containing the property name, each\n\ -@var{value} is a value of the appropriate type for the property.\n\ -\n\ -@item as a cell array of strings @var{properties} containing property names\n\ -and a cell array @var{values} containing property values.\n\ -\n\ -In this case, the number of columns of @var{values} must match the number of\n\ -elements in @var{properties}. The first column of @var{values} contains\n\ -values for the first entry in @var{properties}, etc. The number of rows of\n\ -@var{values} must be 1 or match the number of elements of @var{h}. In the\n\ -first case, each handle in @var{h} will be assigned the same values. In the\n\ -latter case, the first handle in @var{h} will be assigned the values from\n\ -the first row of @var{values} and so on.\n\ -\n\ -@item as a structure array @var{pv}\n\ -\n\ -Here, the field names of @var{pv} represent the property names, and the\n\ -field values give the property values. In contrast to the previous case,\n\ -all elements of @var{pv} will be set in all handles in @var{h} independent\n\ -of the dimensions of @var{pv}.\n\ -@end itemize\n\ -\n\ -@code{set} is also used to query the list of values a named property will\n\ -take. @code{@var{clist} = set (@var{h}, \"property\")} will return the list\n\ -of possible values for @qcode{\"property\"} in the cell list @var{clist}.\n\ -If no output variable is used then the list is formatted and printed to the\n\ -screen.\n\ -\n\ -If no property is specified (@code{@var{slist} = set (@var{h})}) then a\n\ -structure @var{slist} is returned where the fieldnames are the properties of\n\ -the object @var{h} and the fields are the list of possible values for each\n\ -property. If no output variable is used then the list is formatted and\n\ -printed to the screen.\n\ -\n\ -For example,\n\ -\n\ -@example\n\ -@group\n\ -hf = figure ();\n\ -set (hf, \"paperorientation\")\n\ -@result{} paperorientation: [ landscape | @{portrait@} | rotated ]\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -shows the paperorientation property can take three values with the default\n\ -being @qcode{\"portrait\"}.\n\ -@seealso{get}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} set (@var{h}, @var{property}, @var{value}, @dots{}) +@deftypefnx {} {} set (@var{h}, @var{properties}, @var{values}) +@deftypefnx {} {} set (@var{h}, @var{pv}) +@deftypefnx {} {@var{value_list} =} set (@var{h}, @var{property}) +@deftypefnx {} {@var{all_value_list} =} set (@var{h}) +Set named property values for the graphics handle (or vector of graphics +handles) @var{h}. + +There are three ways to give the property names and values: + +@itemize +@item as a comma separated list of @var{property}, @var{value} pairs + +Here, each @var{property} is a string containing the property name, each +@var{value} is a value of the appropriate type for the property. + +@item as a cell array of strings @var{properties} containing property names +and a cell array @var{values} containing property values. + +In this case, the number of columns of @var{values} must match the number of +elements in @var{properties}. The first column of @var{values} contains +values for the first entry in @var{properties}, etc. The number of rows of +@var{values} must be 1 or match the number of elements of @var{h}. In the +first case, each handle in @var{h} will be assigned the same values. In the +latter case, the first handle in @var{h} will be assigned the values from +the first row of @var{values} and so on. + +@item as a structure array @var{pv} + +Here, the field names of @var{pv} represent the property names, and the +field values give the property values. In contrast to the previous case, +all elements of @var{pv} will be set in all handles in @var{h} independent +of the dimensions of @var{pv}. +@end itemize + +@code{set} is also used to query the list of values a named property will +take. @code{@var{clist} = set (@var{h}, "property")} will return the list +of possible values for @qcode{"property"} in the cell list @var{clist}. +If no output variable is used then the list is formatted and printed to the +screen. + +If no property is specified (@code{@var{slist} = set (@var{h})}) then a +structure @var{slist} is returned where the fieldnames are the properties of +the object @var{h} and the fields are the list of possible values for each +property. If no output variable is used then the list is formatted and +printed to the screen. + +For example, + +@example +@group +hf = figure (); +set (hf, "paperorientation") +@result{} paperorientation: [ landscape | @{portrait@} | rotated ] +@end group +@end example + +@noindent +shows the paperorientation property can take three values with the default +being @qcode{"portrait"}. +@seealso{get} +@end deftypefn */) { gh_manager::auto_lock guard; @@ -10127,18 +10127,18 @@ } DEFUN (get, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} get (@var{h})\n\ -@deftypefnx {} {@var{val} =} get (@var{h}, @var{p})\n\ -Return the value of the named property @var{p} from the graphics handle\n\ -@var{h}.\n\ -\n\ -If @var{p} is omitted, return the complete property list for @var{h}.\n\ -\n\ -If @var{h} is a vector, return a cell array including the property values or\n\ -lists respectively.\n\ -@seealso{set}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} get (@var{h}) +@deftypefnx {} {@var{val} =} get (@var{h}, @var{p}) +Return the value of the named property @var{p} from the graphics handle +@var{h}. + +If @var{p} is omitted, return the complete property list for @var{h}. + +If @var{h} is a vector, return a cell array including the property values or +lists respectively. +@seealso{set} +@end deftypefn */) { gh_manager::auto_lock guard; @@ -10254,10 +10254,10 @@ // property values or lists respectively. DEFUN (__get__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __get__ (@var{h})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __get__ (@var{h}) +Undocumented internal function. +@end deftypefn */) { gh_manager::auto_lock guard; @@ -10356,10 +10356,10 @@ } DEFUN (__go_figure__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __go_figure__ (@var{fignum})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __go_figure__ (@var{fignum}) +Undocumented internal function. +@end deftypefn */) { gh_manager::auto_lock guard; @@ -10484,12 +10484,12 @@ } DEFUN (__calc_dimensions__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __calc_dimensions__ (@var{axes})\n\ -Internal function.\n\ -\n\ -Determine the number of dimensions in a graphics object, either 2 or 3.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __calc_dimensions__ (@var{axes}) +Internal function. + +Determine the number of dimensions in a graphics object, either 2 or 3. +@end deftypefn */) { gh_manager::auto_lock guard; @@ -10502,154 +10502,154 @@ } DEFUN (__go_axes__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __go_axes__ (@var{parent})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __go_axes__ (@var{parent}) +Undocumented internal function. +@end deftypefn */) { GO_BODY (axes); } DEFUN (__go_line__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __go_line__ (@var{parent})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __go_line__ (@var{parent}) +Undocumented internal function. +@end deftypefn */) { GO_BODY (line); } DEFUN (__go_text__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __go_text__ (@var{parent})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __go_text__ (@var{parent}) +Undocumented internal function. +@end deftypefn */) { GO_BODY (text); } DEFUN (__go_image__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __go_image__ (@var{parent})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __go_image__ (@var{parent}) +Undocumented internal function. +@end deftypefn */) { GO_BODY (image); } DEFUN (__go_surface__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __go_surface__ (@var{parent})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __go_surface__ (@var{parent}) +Undocumented internal function. +@end deftypefn */) { GO_BODY (surface); } DEFUN (__go_patch__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __go_patch__ (@var{parent})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __go_patch__ (@var{parent}) +Undocumented internal function. +@end deftypefn */) { GO_BODY (patch); } DEFUN (__go_light__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __go_light__ (@var{parent})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __go_light__ (@var{parent}) +Undocumented internal function. +@end deftypefn */) { GO_BODY (light); } DEFUN (__go_hggroup__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __go_hggroup__ (@var{parent})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __go_hggroup__ (@var{parent}) +Undocumented internal function. +@end deftypefn */) { GO_BODY (hggroup); } DEFUN (__go_uimenu__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __go_uimenu__ (@var{parent})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __go_uimenu__ (@var{parent}) +Undocumented internal function. +@end deftypefn */) { GO_BODY (uimenu); } DEFUN (__go_uicontrol__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __go_uicontrol__ (@var{parent})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __go_uicontrol__ (@var{parent}) +Undocumented internal function. +@end deftypefn */) { GO_BODY (uicontrol); } DEFUN (__go_uibuttongroup__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __go_uibuttongroup__ (@var{parent})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __go_uibuttongroup__ (@var{parent}) +Undocumented internal function. +@end deftypefn */) { GO_BODY (uibuttongroup); } DEFUN (__go_uipanel__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __go_uipanel__ (@var{parent})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __go_uipanel__ (@var{parent}) +Undocumented internal function. +@end deftypefn */) { GO_BODY (uipanel); } DEFUN (__go_uicontextmenu__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __go_uicontextmenu__ (@var{parent})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __go_uicontextmenu__ (@var{parent}) +Undocumented internal function. +@end deftypefn */) { GO_BODY (uicontextmenu); } DEFUN (__go_uitoolbar__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __go_uitoolbar__ (@var{parent})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __go_uitoolbar__ (@var{parent}) +Undocumented internal function. +@end deftypefn */) { GO_BODY (uitoolbar); } DEFUN (__go_uipushtool__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __go_uipushtool__ (@var{parent})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __go_uipushtool__ (@var{parent}) +Undocumented internal function. +@end deftypefn */) { GO_BODY (uipushtool); } DEFUN (__go_uitoggletool__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __go_uitoggletool__ (@var{parent})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __go_uitoggletool__ (@var{parent}) +Undocumented internal function. +@end deftypefn */) { GO_BODY (uitoggletool); } DEFUN (__go_delete__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __go_delete__ (@var{h})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __go_delete__ (@var{h}) +Undocumented internal function. +@end deftypefn */) { gh_manager::auto_lock guard; @@ -10676,10 +10676,10 @@ } DEFUN (__go_axes_init__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __go_axes_init__ (@var{h}, @var{mode})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __go_axes_init__ (@var{h}, @var{mode}) +Undocumented internal function. +@end deftypefn */) { gh_manager::auto_lock guard; @@ -10713,10 +10713,10 @@ } DEFUN (__go_handles__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __go_handles__ (@var{show_hidden})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __go_handles__ (@var{show_hidden}) +Undocumented internal function. +@end deftypefn */) { gh_manager::auto_lock guard; @@ -10729,10 +10729,10 @@ } DEFUN (__go_figure_handles__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __go_figure_handles__ (@var{show_hidden})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __go_figure_handles__ (@var{show_hidden}) +Undocumented internal function. +@end deftypefn */) { gh_manager::auto_lock guard; @@ -10745,11 +10745,11 @@ } DEFUN (__go_execute_callback__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __go_execute_callback__ (@var{h}, @var{name})\n\ -@deftypefnx {} {} __go_execute_callback__ (@var{h}, @var{name}, @var{param})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __go_execute_callback__ (@var{h}, @var{name}) +@deftypefnx {} {} __go_execute_callback__ (@var{h}, @var{name}, @var{param}) +Undocumented internal function. +@end deftypefn */) { int nargin = args.length (); @@ -10779,10 +10779,10 @@ } DEFUN (__image_pixel_size__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{px}, @var{py}} __image_pixel_size__ (@var{h})\n\ -Internal function: returns the pixel size of the image in normalized units.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{px}, @var{py}} __image_pixel_size__ (@var{h}) +Internal function: returns the pixel size of the image in normalized units. +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -10889,11 +10889,11 @@ } DEFUN (available_graphics_toolkits, , , - "-*- texinfo -*-\n\ -@deftypefn {} {} available_graphics_toolkits ()\n\ -Return a cell array of registered graphics toolkits.\n\ -@seealso{graphics_toolkit, register_graphics_toolkit}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} available_graphics_toolkits () +Return a cell array of registered graphics toolkits. +@seealso{graphics_toolkit, register_graphics_toolkit} +@end deftypefn */) { gh_manager::auto_lock guard; @@ -10901,11 +10901,11 @@ } DEFUN (register_graphics_toolkit, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} register_graphics_toolkit (@var{toolkit})\n\ -List @var{toolkit} as an available graphics toolkit.\n\ -@seealso{available_graphics_toolkits}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} register_graphics_toolkit (@var{toolkit}) +List @var{toolkit} as an available graphics toolkit. +@seealso{available_graphics_toolkits} +@end deftypefn */) { gh_manager::auto_lock guard; @@ -10920,11 +10920,11 @@ } DEFUN (loaded_graphics_toolkits, , , - "-*- texinfo -*-\n\ -@deftypefn {} {} loaded_graphics_toolkits ()\n\ -Return a cell array of the currently loaded graphics toolkits.\n\ -@seealso{available_graphics_toolkits}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} loaded_graphics_toolkits () +Return a cell array of the currently loaded graphics toolkits. +@seealso{available_graphics_toolkits} +@end deftypefn */) { gh_manager::auto_lock guard; @@ -10932,21 +10932,21 @@ } DEFUN (drawnow, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} drawnow ()\n\ -@deftypefnx {} {} drawnow (\"expose\")\n\ -@deftypefnx {} {} drawnow (@var{term}, @var{file}, @var{debug_file})\n\ -Update figure windows and their children.\n\ -\n\ -The event queue is flushed and any callbacks generated are executed.\n\ -\n\ -With the optional argument @qcode{\"expose\"}, only graphic objects are\n\ -updated and no other events or callbacks are processed.\n\ -\n\ -The third calling form of @code{drawnow} is for debugging and is\n\ -undocumented.\n\ -@seealso{refresh}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} drawnow () +@deftypefnx {} {} drawnow ("expose") +@deftypefnx {} {} drawnow (@var{term}, @var{file}, @var{debug_file}) +Update figure windows and their children. + +The event queue is flushed and any callbacks generated are executed. + +With the optional argument @qcode{"expose"}, only graphic objects are +updated and no other events or callbacks are processed. + +The third calling form of @code{drawnow} is for debugging and is +undocumented. +@seealso{refresh} +@end deftypefn */) { static int drawnow_executing = 0; @@ -11072,39 +11072,39 @@ } DEFUN (addlistener, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} addlistener (@var{h}, @var{prop}, @var{fcn})\n\ -Register @var{fcn} as listener for the property @var{prop} of the graphics\n\ -object @var{h}.\n\ -\n\ -Property listeners are executed (in order of registration) when the property\n\ -is set. The new value is already available when the listeners are executed.\n\ -\n\ -@var{prop} must be a string naming a valid property in @var{h}.\n\ -\n\ -@var{fcn} can be a function handle, a string or a cell array whose first\n\ -element is a function handle. If @var{fcn} is a function handle, the\n\ -corresponding function should accept at least 2 arguments, that will be\n\ -set to the object handle and the empty matrix respectively. If @var{fcn}\n\ -is a string, it must be any valid octave expression. If @var{fcn} is a cell\n\ -array, the first element must be a function handle with the same signature\n\ -as described above. The next elements of the cell array are passed\n\ -as additional arguments to the function.\n\ -\n\ -Example:\n\ -\n\ -@example\n\ -@group\n\ -function my_listener (h, dummy, p1)\n\ - fprintf (\"my_listener called with p1=%s\\n\", p1);\n\ -endfunction\n\ -\n\ -addlistener (gcf, \"position\", @{@@my_listener, \"my string\"@})\n\ -@end group\n\ -@end example\n\ -\n\ -@seealso{addproperty, hggroup}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} addlistener (@var{h}, @var{prop}, @var{fcn}) +Register @var{fcn} as listener for the property @var{prop} of the graphics +object @var{h}. + +Property listeners are executed (in order of registration) when the property +is set. The new value is already available when the listeners are executed. + +@var{prop} must be a string naming a valid property in @var{h}. + +@var{fcn} can be a function handle, a string or a cell array whose first +element is a function handle. If @var{fcn} is a function handle, the +corresponding function should accept at least 2 arguments, that will be +set to the object handle and the empty matrix respectively. If @var{fcn} +is a string, it must be any valid octave expression. If @var{fcn} is a cell +array, the first element must be a function handle with the same signature +as described above. The next elements of the cell array are passed +as additional arguments to the function. + +Example: + +@example +@group +function my_listener (h, dummy, p1) + fprintf ("my_listener called with p1=%s\n", p1); +endfunction + +addlistener (gcf, "position", @{@@my_listener, "my string"@}) +@end group +@end example + +@seealso{addproperty, hggroup} +@end deftypefn */) { gh_manager::auto_lock guard; @@ -11137,32 +11137,32 @@ } DEFUN (dellistener, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} dellistener (@var{h}, @var{prop}, @var{fcn})\n\ -Remove the registration of @var{fcn} as a listener for the property\n\ -@var{prop} of the graphics object @var{h}.\n\ -\n\ -The function @var{fcn} must be the same variable (not just the same value),\n\ -as was passed to the original call to @code{addlistener}.\n\ -\n\ -If @var{fcn} is not defined then all listener functions of @var{prop}\n\ -are removed.\n\ -\n\ -Example:\n\ -\n\ -@example\n\ -@group\n\ -function my_listener (h, dummy, p1)\n\ - fprintf (\"my_listener called with p1=%s\\n\", p1);\n\ -endfunction\n\ -\n\ -c = @{@@my_listener, \"my string\"@};\n\ -addlistener (gcf, \"position\", c);\n\ -dellistener (gcf, \"position\", c);\n\ -@end group\n\ -@end example\n\ -\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} dellistener (@var{h}, @var{prop}, @var{fcn}) +Remove the registration of @var{fcn} as a listener for the property +@var{prop} of the graphics object @var{h}. + +The function @var{fcn} must be the same variable (not just the same value), +as was passed to the original call to @code{addlistener}. + +If @var{fcn} is not defined then all listener functions of @var{prop} +are removed. + +Example: + +@example +@group +function my_listener (h, dummy, p1) + fprintf ("my_listener called with p1=%s\n", p1); +endfunction + +c = @{@@my_listener, "my string"@}; +addlistener (gcf, "position", c); +dellistener (gcf, "position", c); +@end group +@end example + +@end deftypefn */) { gh_manager::auto_lock guard; @@ -11200,76 +11200,76 @@ } DEFUN (addproperty, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} addproperty (@var{name}, @var{h}, @var{type})\n\ -@deftypefnx {} {} addproperty (@var{name}, @var{h}, @var{type}, @var{arg}, @dots{})\n\ -Create a new property named @var{name} in graphics object @var{h}.\n\ -\n\ -@var{type} determines the type of the property to create. @var{args}\n\ -usually contains the default value of the property, but additional\n\ -arguments might be given, depending on the type of the property.\n\ -\n\ -The supported property types are:\n\ -\n\ -@table @code\n\ -@item string\n\ -A string property. @var{arg} contains the default string value.\n\ -\n\ -@item any\n\ -An @nospell{un-typed} property. This kind of property can hold any octave\n\ -value. @var{args} contains the default value.\n\ -\n\ -@item radio\n\ -A string property with a limited set of accepted values. The first\n\ -argument must be a string with all accepted values separated by\n\ -a vertical bar ('|'). The default value can be marked by enclosing\n\ -it with a '@{' '@}' pair. The default value may also be given as\n\ -an optional second string argument.\n\ -\n\ -@item boolean\n\ -A boolean property. This property type is equivalent to a radio\n\ -property with \"on|off\" as accepted values. @var{arg} contains\n\ -the default property value.\n\ -\n\ -@item double\n\ -A scalar double property. @var{arg} contains the default value.\n\ -\n\ -@item handle\n\ -A handle property. This kind of property holds the handle of a\n\ -graphics object. @var{arg} contains the default handle value.\n\ -When no default value is given, the property is initialized to\n\ -the empty matrix.\n\ -\n\ -@item data\n\ -A data (matrix) property. @var{arg} contains the default data\n\ -value. When no default value is given, the data is initialized to\n\ -the empty matrix.\n\ -\n\ -@item color\n\ -A color property. @var{arg} contains the default color value.\n\ -When no default color is given, the property is set to black.\n\ -An optional second string argument may be given to specify an\n\ -additional set of accepted string values (like a radio property).\n\ -@end table\n\ -\n\ -@var{type} may also be the concatenation of a core object type and\n\ -a valid property name for that object type. The property created\n\ -then has the same characteristics as the referenced property (type,\n\ -possible values, hidden state@dots{}). This allows one to clone an\n\ -existing property into the graphics object @var{h}.\n\ -\n\ -Examples:\n\ -\n\ -@example\n\ -@group\n\ -addproperty (\"my_property\", gcf, \"string\", \"a string value\");\n\ -addproperty (\"my_radio\", gcf, \"radio\", \"val_1|val_2|@{val_3@}\");\n\ -addproperty (\"my_style\", gcf, \"linelinestyle\", \"--\");\n\ -@end group\n\ -@end example\n\ -\n\ -@seealso{addlistener, hggroup}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} addproperty (@var{name}, @var{h}, @var{type}) +@deftypefnx {} {} addproperty (@var{name}, @var{h}, @var{type}, @var{arg}, @dots{}) +Create a new property named @var{name} in graphics object @var{h}. + +@var{type} determines the type of the property to create. @var{args} +usually contains the default value of the property, but additional +arguments might be given, depending on the type of the property. + +The supported property types are: + +@table @code +@item string +A string property. @var{arg} contains the default string value. + +@item any +An @nospell{un-typed} property. This kind of property can hold any octave +value. @var{args} contains the default value. + +@item radio +A string property with a limited set of accepted values. The first +argument must be a string with all accepted values separated by +a vertical bar ('|'). The default value can be marked by enclosing +it with a '@{' '@}' pair. The default value may also be given as +an optional second string argument. + +@item boolean +A boolean property. This property type is equivalent to a radio +property with "on|off" as accepted values. @var{arg} contains +the default property value. + +@item double +A scalar double property. @var{arg} contains the default value. + +@item handle +A handle property. This kind of property holds the handle of a +graphics object. @var{arg} contains the default handle value. +When no default value is given, the property is initialized to +the empty matrix. + +@item data +A data (matrix) property. @var{arg} contains the default data +value. When no default value is given, the data is initialized to +the empty matrix. + +@item color +A color property. @var{arg} contains the default color value. +When no default color is given, the property is set to black. +An optional second string argument may be given to specify an +additional set of accepted string values (like a radio property). +@end table + +@var{type} may also be the concatenation of a core object type and +a valid property name for that object type. The property created +then has the same characteristics as the referenced property (type, +possible values, hidden state@dots{}). This allows one to clone an +existing property into the graphics object @var{h}. + +Examples: + +@example +@group +addproperty ("my_property", gcf, "string", "a string value"); +addproperty ("my_radio", gcf, "radio", "val_1|val_2|@{val_3@}"); +addproperty ("my_style", gcf, "linelinestyle", "--"); +@end group +@end example + +@seealso{addlistener, hggroup} +@end deftypefn */) { gh_manager::auto_lock guard; @@ -11444,46 +11444,46 @@ } DEFUN (waitfor, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} waitfor (@var{h})\n\ -@deftypefnx {} {} waitfor (@var{h}, @var{prop})\n\ -@deftypefnx {} {} waitfor (@var{h}, @var{prop}, @var{value})\n\ -@deftypefnx {} {} waitfor (@dots{}, \"timeout\", @var{timeout})\n\ -Suspend the execution of the current program until a condition is\n\ -satisfied on the graphics handle @var{h}.\n\ -\n\ -While the program is suspended graphics events are still processed normally,\n\ -allowing callbacks to modify the state of graphics objects. This function\n\ -is reentrant and can be called from a callback, while another @code{waitfor}\n\ -call is pending at the top-level.\n\ -\n\ -In the first form, program execution is suspended until the graphics object\n\ -@var{h} is destroyed. If the graphics handle is invalid, the function\n\ -returns immediately.\n\ -\n\ -In the second form, execution is suspended until the graphics object is\n\ -destroyed or the property named @var{prop} is modified. If the graphics\n\ -handle is invalid or the property does not exist, the function returns\n\ -immediately.\n\ -\n\ -In the third form, execution is suspended until the graphics object is\n\ -destroyed or the property named @var{prop} is set to @var{value}. The\n\ -function @code{isequal} is used to compare property values. If the graphics\n\ -handle is invalid, the property does not exist or the property is already\n\ -set to @var{value}, the function returns immediately.\n\ -\n\ -An optional timeout can be specified using the property @code{timeout}.\n\ -This timeout value is the number of seconds to wait for the condition to be\n\ -true. @var{timeout} must be at least 1. If a smaller value is specified, a\n\ -warning is issued and a value of 1 is used instead. If the timeout value is\n\ -not an integer, it is truncated towards 0.\n\ -\n\ -To define a condition on a property named @code{timeout}, use the string\n\ -@code{\\timeout} instead.\n\ -\n\ -In all cases, typing CTRL-C stops program execution immediately.\n\ -@seealso{waitforbuttonpress, isequal}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} waitfor (@var{h}) +@deftypefnx {} {} waitfor (@var{h}, @var{prop}) +@deftypefnx {} {} waitfor (@var{h}, @var{prop}, @var{value}) +@deftypefnx {} {} waitfor (@dots{}, "timeout", @var{timeout}) +Suspend the execution of the current program until a condition is +satisfied on the graphics handle @var{h}. + +While the program is suspended graphics events are still processed normally, +allowing callbacks to modify the state of graphics objects. This function +is reentrant and can be called from a callback, while another @code{waitfor} +call is pending at the top-level. + +In the first form, program execution is suspended until the graphics object +@var{h} is destroyed. If the graphics handle is invalid, the function +returns immediately. + +In the second form, execution is suspended until the graphics object is +destroyed or the property named @var{prop} is modified. If the graphics +handle is invalid or the property does not exist, the function returns +immediately. + +In the third form, execution is suspended until the graphics object is +destroyed or the property named @var{prop} is set to @var{value}. The +function @code{isequal} is used to compare property values. If the graphics +handle is invalid, the property does not exist or the property is already +set to @var{value}, the function returns immediately. + +An optional timeout can be specified using the property @code{timeout}. +This timeout value is the number of seconds to wait for the condition to be +true. @var{timeout} must be at least 1. If a smaller value is specified, a +warning is issued and a value of 1 is used instead. If the timeout value is +not an integer, it is truncated towards 0. + +To define a condition on a property named @code{timeout}, use the string +@code{\timeout} instead. + +In all cases, typing CTRL-C stops program execution immediately. +@seealso{waitforbuttonpress, isequal} +@end deftypefn */) { if (args.length () == 0) print_usage (); @@ -11679,12 +11679,12 @@ } DEFUN (__zoom__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __zoom__ (@var{axes}, @var{mode}, @var{factor})\n\ -@deftypefnx {} {} __zoom__ (@var{axes}, \"out\")\n\ -@deftypefnx {} {} __zoom__ (@var{axes}, \"reset\")\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __zoom__ (@var{axes}, @var{mode}, @var{factor}) +@deftypefnx {} {} __zoom__ (@var{axes}, "out") +@deftypefnx {} {} __zoom__ (@var{axes}, "reset") +Undocumented internal function. +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/hash.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/hash.cc Tue Jun 21 16:07:51 2016 -0400 @@ -48,68 +48,68 @@ #include "ovl.h" DEFUN (hash, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} hash (@var{hfun}, @var{str})\n\ -Calculate the hash value of the string @var{str} using the hash function\n\ -@var{hfun}.\n\ -\n\ -The available hash functions are given in the table below.\n\ -\n\ -@table @samp\n\ -@item MD2\n\ -Message-Digest Algorithm 2 (RFC 1319).\n\ -\n\ -@item MD4\n\ -Message-Digest Algorithm 4 (RFC 1320).\n\ -\n\ -@item MD5\n\ -Message-Digest Algorithm 5 (RFC 1321).\n\ -\n\ -@item SHA1\n\ -Secure Hash Algorithm 1 (RFC 3174)\n\ -\n\ -@item SHA224\n\ -Secure Hash Algorithm 2 (224 Bits, RFC 3874)\n\ -\n\ -@item SHA256\n\ -Secure Hash Algorithm 2 (256 Bits, RFC 6234)\n\ -\n\ -@item SHA384\n\ -Secure Hash Algorithm 2 (384 Bits, RFC 6234)\n\ -\n\ -@item SHA512\n\ -Secure Hash Algorithm 2 (512 Bits, RFC 6234)\n\ -@end table\n\ -\n\ -To calculate for example the MD5 hash value of the string\n\ -@nospell{@qcode{\"abc\"}} the @code{hash} function is called as follows:\n\ -\n\ -@example\n\ -@group\n\ -hash (\"md5\", \"abc\")\n\ - @print{} ans = 900150983cd24fb0d6963f7d28e17f72\n\ -@end group\n\ -@end example\n\ -\n\ -For the same string, the SHA-1 hash value is calculated with:\n\ -\n\ -@example\n\ -@group\n\ -hash (\"sha1\", \"abc\")\n\ - @print{} ans = a9993e364706816aba3e25717850c26c9cd0d89d\n\ -@end group\n\ -@end example\n\ -\n\ -And to compute the hash value of a file, e.g., @code{file = \"file.txt\"},\n\ -call @code{hash} in combination with the @code{fileread}:\n\ -\n\ -@example\n\ -@group\n\ -hash (\"md5\", fileread (file));\n\ -@end group\n\ -@end example\n\ -\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} hash (@var{hfun}, @var{str}) +Calculate the hash value of the string @var{str} using the hash function +@var{hfun}. + +The available hash functions are given in the table below. + +@table @samp +@item MD2 +Message-Digest Algorithm 2 (RFC 1319). + +@item MD4 +Message-Digest Algorithm 4 (RFC 1320). + +@item MD5 +Message-Digest Algorithm 5 (RFC 1321). + +@item SHA1 +Secure Hash Algorithm 1 (RFC 3174) + +@item SHA224 +Secure Hash Algorithm 2 (224 Bits, RFC 3874) + +@item SHA256 +Secure Hash Algorithm 2 (256 Bits, RFC 6234) + +@item SHA384 +Secure Hash Algorithm 2 (384 Bits, RFC 6234) + +@item SHA512 +Secure Hash Algorithm 2 (512 Bits, RFC 6234) +@end table + +To calculate for example the MD5 hash value of the string +@nospell{@qcode{"abc"}} the @code{hash} function is called as follows: + +@example +@group +hash ("md5", "abc") + @print{} ans = 900150983cd24fb0d6963f7d28e17f72 +@end group +@end example + +For the same string, the SHA-1 hash value is calculated with: + +@example +@group +hash ("sha1", "abc") + @print{} ans = a9993e364706816aba3e25717850c26c9cd0d89d +@end group +@end example + +And to compute the hash value of a file, e.g., @code{file = "file.txt"}, +call @code{hash} in combination with the @code{fileread}: + +@example +@group +hash ("md5", fileread (file)); +@end group +@end example + +@end deftypefn */) { if (args.length () != 2) print_usage ();
--- a/libinterp/corefcn/help.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/help.cc Tue Jun 21 16:07:51 2016 -0400 @@ -951,24 +951,24 @@ } DEFUN (built_in_docstrings_file, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} built_in_docstrings_file ()\n\ -@deftypefnx {} {@var{old_val} =} built_in_docstrings_file (@var{new_val})\n\ -@deftypefnx {} {} built_in_docstrings_file (@var{new_val}, \"local\")\n\ -Query or set the internal variable that specifies the name of the\n\ -file containing docstrings for built-in Octave functions.\n\ -\n\ -The default value is\n\ -@file{@var{octave-home}/share/octave/@var{version}/etc/built-in-docstrings},\n\ -in which @var{octave-home} is the root directory of the Octave installation,\n\ -and @var{version} is the Octave version number. The default value may be\n\ -overridden by the environment variable\n\ -@w{@env{OCTAVE_BUILT_IN_DOCSTRINGS_FILE}}, or the command line argument\n\ -@option{--built-in-docstrings-file FNAME}.\n\ -\n\ -Note: This variable is only used when Octave is initializing itself.\n\ -Modifying it during a running session of Octave will have no effect.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} built_in_docstrings_file () +@deftypefnx {} {@var{old_val} =} built_in_docstrings_file (@var{new_val}) +@deftypefnx {} {} built_in_docstrings_file (@var{new_val}, "local") +Query or set the internal variable that specifies the name of the +file containing docstrings for built-in Octave functions. + +The default value is +@file{@var{octave-home}/share/octave/@var{version}/etc/built-in-docstrings}, +in which @var{octave-home} is the root directory of the Octave installation, +and @var{version} is the Octave version number. The default value may be +overridden by the environment variable +@w{@env{OCTAVE_BUILT_IN_DOCSTRINGS_FILE}}, or the command line argument +@option{--built-in-docstrings-file FNAME}. + +Note: This variable is only used when Octave is initializing itself. +Modifying it during a running session of Octave will have no effect. +@end deftypefn */) { return SET_NONEMPTY_INTERNAL_STRING_VARIABLE (built_in_docstrings_file); } @@ -1077,15 +1077,16 @@ } } -DEFUN (get_help_text, args, , "-*- texinfo -*-\n\ -@deftypefn {} {[@var{text}, @var{format}] =} get_help_text (@var{name})\n\ -Return the raw help text of function @var{name}.\n\ -\n\ -The raw help text is returned in @var{text} and the format in @var{format}\n\ -The format is a string which is one of @qcode{\"texinfo\"},\n\ -@qcode{\"html\"}, or @qcode{\"plain text\"}.\n\ -@seealso{get_help_text_from_file}\n\ -@end deftypefn") +DEFUN (get_help_text, args, , + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{text}, @var{format}] =} get_help_text (@var{name}) +Return the raw help text of function @var{name}. + +The raw help text is returned in @var{text} and the format in @var{format} +The format is a string which is one of @qcode{"texinfo"}, +@qcode{"html"}, or @qcode{"plain text"}. +@seealso{get_help_text_from_file} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1134,15 +1135,15 @@ } DEFUN (get_help_text_from_file, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{text}, @var{format}] =} get_help_text_from_file (@var{fname})\n\ -Return the raw help text from the file @var{fname}.\n\ -\n\ -The raw help text is returned in @var{text} and the format in @var{format}\n\ -The format is a string which is one of @qcode{\"texinfo\"},\n\ -@qcode{\"html\"}, or @qcode{\"plain text\"}.\n\ -@seealso{get_help_text}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{text}, @var{format}] =} get_help_text_from_file (@var{fname}) +Return the raw help text from the file @var{fname}. + +The raw help text is returned in @var{text} and the format in @var{format} +The format is a string which is one of @qcode{"texinfo"}, +@qcode{"html"}, or @qcode{"plain text"}. +@seealso{get_help_text} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1160,10 +1161,10 @@ // operators. DEFUN (__operators__, , , - "-*- texinfo -*-\n\ -@deftypefn {} {} __operators__ ()\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __operators__ () +Undocumented internal function. +@end deftypefn */) { return ovl (Cell (names (operators_map))); } @@ -1172,10 +1173,10 @@ // keywords. DEFUN (__keywords__, , , - "-*- texinfo -*-\n\ -@deftypefn {} {} __keywords__ ()\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __keywords__ () +Undocumented internal function. +@end deftypefn */) { return ovl (Cell (names (keywords_map))); } @@ -1184,10 +1185,10 @@ // functions. DEFUN (__builtins__, , , - "-*- texinfo -*-\n\ -@deftypefn {} {} __builtins__ ()\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __builtins__ () +Undocumented internal function. +@end deftypefn */) { const string_vector bif = symbol_table::built_in_function_names (); @@ -1195,21 +1196,21 @@ } DEFUN (localfunctions, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} localfunctions ()\n\ -Return a list of all local functions, i.e., subfunctions, within the current\n\ -file.\n\ -\n\ -The return value is a column cell array of function handles to all local\n\ -functions accessible from the function from which @code{localfunctions} is\n\ -called. Nested functions are @emph{not} included in the list.\n\ -\n\ -If the call is from the command line, an anonymous function, or a script,\n\ -the return value is an empty cell array.\n\ -\n\ -Compatibility Note: Subfunctions which contain nested functions are not\n\ -included in the list. This is a known issue.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} localfunctions () +Return a list of all local functions, i.e., subfunctions, within the current +file. + +The return value is a column cell array of function handles to all local +functions accessible from the function from which @code{localfunctions} is +called. Nested functions are @emph{not} included in the list. + +If the call is from the command line, an anonymous function, or a script, +the return value is an empty cell array. + +Compatibility Note: Subfunctions which contain nested functions are not +included in the list. This is a known issue. +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -1336,10 +1337,10 @@ } DEFUN (__which__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __which__ (@var{name}, @dots{})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __which__ (@var{name}, @dots{}) +Undocumented internal function. +@end deftypefn */) { string_vector argv = args.make_argv (); @@ -1398,11 +1399,11 @@ // the current path. DEFUN (__list_functions__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{retval} =} __list_functions__ ()\n\ -@deftypefnx {} {@var{retval} =} __list_functions__ (@var{directory})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{retval} =} __list_functions__ () +@deftypefnx {} {@var{retval} =} __list_functions__ (@var{directory}) +Undocumented internal function. +@end deftypefn */) { octave_value retval; @@ -1430,141 +1431,141 @@ } DEFUN (doc_cache_file, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} doc_cache_file ()\n\ -@deftypefnx {} {@var{old_val} =} doc_cache_file (@var{new_val})\n\ -@deftypefnx {} {} doc_cache_file (@var{new_val}, \"local\")\n\ -Query or set the internal variable that specifies the name of the\n\ -Octave documentation cache file.\n\ -\n\ -A cache file significantly improves the performance of the @code{lookfor}\n\ -command. The default value is\n\ -@file{@var{octave-home}/share/octave/@var{version}/etc/doc-cache},\n\ -in which @var{octave-home} is the root directory of the Octave installation,\n\ -and @var{version} is the Octave version number.\n\ -The default value may be overridden by the environment variable\n\ -@w{@env{OCTAVE_DOC_CACHE_FILE}}, or the command line argument\n\ -@option{--doc-cache-file FNAME}.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{doc_cache_create, lookfor, info_program, doc, help, makeinfo_program}\n\ -@seealso{lookfor}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} doc_cache_file () +@deftypefnx {} {@var{old_val} =} doc_cache_file (@var{new_val}) +@deftypefnx {} {} doc_cache_file (@var{new_val}, "local") +Query or set the internal variable that specifies the name of the +Octave documentation cache file. + +A cache file significantly improves the performance of the @code{lookfor} +command. The default value is +@file{@var{octave-home}/share/octave/@var{version}/etc/doc-cache}, +in which @var{octave-home} is the root directory of the Octave installation, +and @var{version} is the Octave version number. +The default value may be overridden by the environment variable +@w{@env{OCTAVE_DOC_CACHE_FILE}}, or the command line argument +@option{--doc-cache-file FNAME}. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{doc_cache_create, lookfor, info_program, doc, help, makeinfo_program} +@seealso{lookfor} +@end deftypefn */) { return SET_NONEMPTY_INTERNAL_STRING_VARIABLE (doc_cache_file); } DEFUN (texi_macros_file, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} texi_macros_file ()\n\ -@deftypefnx {} {@var{old_val} =} texi_macros_file (@var{new_val})\n\ -@deftypefnx {} {} texi_macros_file (@var{new_val}, \"local\")\n\ -Query or set the internal variable that specifies the name of the\n\ -file containing Texinfo macros that are prepended to documentation strings\n\ -before they are passed to makeinfo.\n\ -\n\ -The default value is\n\ -@file{@var{octave-home}/share/octave/@var{version}/etc/macros.texi},\n\ -in which @var{octave-home} is the root directory of the Octave installation,\n\ -and @var{version} is the Octave version number.\n\ -The default value may be overridden by the environment variable\n\ -@w{@env{OCTAVE_TEXI_MACROS_FILE}}, or the command line argument\n\ -@option{--texi-macros-file FNAME}.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{makeinfo_program}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} texi_macros_file () +@deftypefnx {} {@var{old_val} =} texi_macros_file (@var{new_val}) +@deftypefnx {} {} texi_macros_file (@var{new_val}, "local") +Query or set the internal variable that specifies the name of the +file containing Texinfo macros that are prepended to documentation strings +before they are passed to makeinfo. + +The default value is +@file{@var{octave-home}/share/octave/@var{version}/etc/macros.texi}, +in which @var{octave-home} is the root directory of the Octave installation, +and @var{version} is the Octave version number. +The default value may be overridden by the environment variable +@w{@env{OCTAVE_TEXI_MACROS_FILE}}, or the command line argument +@option{--texi-macros-file FNAME}. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{makeinfo_program} +@end deftypefn */) { return SET_NONEMPTY_INTERNAL_STRING_VARIABLE (texi_macros_file); } DEFUN (info_file, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} info_file ()\n\ -@deftypefnx {} {@var{old_val} =} info_file (@var{new_val})\n\ -@deftypefnx {} {} info_file (@var{new_val}, \"local\")\n\ -Query or set the internal variable that specifies the name of the\n\ -Octave info file.\n\ -\n\ -The default value is\n\ -@file{@var{octave-home}/info/octave.info}, in\n\ -which @var{octave-home} is the root directory of the Octave installation.\n\ -The default value may be overridden by the environment variable\n\ -@w{@env{OCTAVE_INFO_FILE}}, or the command line argument\n\ -@option{--info-file FNAME}.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{info_program, doc, help, makeinfo_program}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} info_file () +@deftypefnx {} {@var{old_val} =} info_file (@var{new_val}) +@deftypefnx {} {} info_file (@var{new_val}, "local") +Query or set the internal variable that specifies the name of the +Octave info file. + +The default value is +@file{@var{octave-home}/info/octave.info}, in +which @var{octave-home} is the root directory of the Octave installation. +The default value may be overridden by the environment variable +@w{@env{OCTAVE_INFO_FILE}}, or the command line argument +@option{--info-file FNAME}. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{info_program, doc, help, makeinfo_program} +@end deftypefn */) { return SET_NONEMPTY_INTERNAL_STRING_VARIABLE (info_file); } DEFUN (info_program, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} info_program ()\n\ -@deftypefnx {} {@var{old_val} =} info_program (@var{new_val})\n\ -@deftypefnx {} {} info_program (@var{new_val}, \"local\")\n\ -Query or set the internal variable that specifies the name of the\n\ -info program to run.\n\ -\n\ -The default value is\n\ -@file{@var{octave-home}/libexec/octave/@var{version}/exec/@var{arch}/info}\n\ -in which @var{octave-home} is the root directory of the Octave installation,\n\ -@var{version} is the Octave version number, and @var{arch} is the system\n\ -type (for example, @code{i686-pc-linux-gnu}). The default value may be\n\ -overridden by the environment variable\n\ -@w{@env{OCTAVE_INFO_PROGRAM}}, or the command line argument\n\ -@option{--info-program NAME}.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{info_file, doc, help, makeinfo_program}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} info_program () +@deftypefnx {} {@var{old_val} =} info_program (@var{new_val}) +@deftypefnx {} {} info_program (@var{new_val}, "local") +Query or set the internal variable that specifies the name of the +info program to run. + +The default value is +@file{@var{octave-home}/libexec/octave/@var{version}/exec/@var{arch}/info} +in which @var{octave-home} is the root directory of the Octave installation, +@var{version} is the Octave version number, and @var{arch} is the system +type (for example, @code{i686-pc-linux-gnu}). The default value may be +overridden by the environment variable +@w{@env{OCTAVE_INFO_PROGRAM}}, or the command line argument +@option{--info-program NAME}. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{info_file, doc, help, makeinfo_program} +@end deftypefn */) { return SET_NONEMPTY_INTERNAL_STRING_VARIABLE (info_program); } DEFUN (makeinfo_program, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} makeinfo_program ()\n\ -@deftypefnx {} {@var{old_val} =} makeinfo_program (@var{new_val})\n\ -@deftypefnx {} {} makeinfo_program (@var{new_val}, \"local\")\n\ -Query or set the internal variable that specifies the name of the\n\ -program that Octave runs to format help text containing\n\ -Texinfo markup commands.\n\ -\n\ -The default value is @code{makeinfo}.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{texi_macros_file, info_file, info_program, doc, help}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} makeinfo_program () +@deftypefnx {} {@var{old_val} =} makeinfo_program (@var{new_val}) +@deftypefnx {} {} makeinfo_program (@var{new_val}, "local") +Query or set the internal variable that specifies the name of the +program that Octave runs to format help text containing +Texinfo markup commands. + +The default value is @code{makeinfo}. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{texi_macros_file, info_file, info_program, doc, help} +@end deftypefn */) { return SET_NONEMPTY_INTERNAL_STRING_VARIABLE (makeinfo_program); } DEFUN (suppress_verbose_help_message, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} suppress_verbose_help_message ()\n\ -@deftypefnx {} {@var{old_val} =} suppress_verbose_help_message (@var{new_val})\n\ -@deftypefnx {} {} suppress_verbose_help_message (@var{new_val}, \"local\")\n\ -Query or set the internal variable that controls whether Octave\n\ -will add additional help information to the end of the output from\n\ -the @code{help} command and usage messages for built-in commands.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} suppress_verbose_help_message () +@deftypefnx {} {@var{old_val} =} suppress_verbose_help_message (@var{new_val}) +@deftypefnx {} {} suppress_verbose_help_message (@var{new_val}, "local") +Query or set the internal variable that controls whether Octave +will add additional help information to the end of the output from +the @code{help} command and usage messages for built-in commands. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@end deftypefn */) { return SET_INTERNAL_VARIABLE (suppress_verbose_help_message); }
--- a/libinterp/corefcn/hess.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/hess.cc Tue Jun 21 16:07:51 2016 -0400 @@ -33,33 +33,33 @@ #include "utils.h" DEFUN (hess, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{H} =} hess (@var{A})\n\ -@deftypefnx {} {[@var{P}, @var{H}] =} hess (@var{A})\n\ -@cindex Hessenberg decomposition\n\ -Compute the Hessenberg decomposition of the matrix @var{A}.\n\ -\n\ -The Hessenberg decomposition is\n\ -@tex\n\ -$$\n\ -A = PHP^T\n\ -$$\n\ -where $P$ is a square unitary matrix ($P^TP = I$), and $H$\n\ -is upper Hessenberg ($H_{i,j} = 0, \\forall i > j+1$).\n\ -@end tex\n\ -@ifnottex\n\ -@code{@var{P} * @var{H} * @var{P}' = @var{A}} where @var{P} is a square\n\ -unitary matrix (@code{@var{P}' * @var{P} = I}, using complex-conjugate\n\ -transposition) and @var{H} is upper Hessenberg\n\ -(@code{@var{H}(i, j) = 0 forall i > j+1)}.\n\ -@end ifnottex\n\ -\n\ -The Hessenberg decomposition is usually used as the first step in an\n\ -eigenvalue computation, but has other applications as well\n\ -(see @nospell{Golub, Nash, and Van Loan},\n\ -IEEE Transactions on Automatic Control, 1979).\n\ -@seealso{eig, chol, lu, qr, qz, schur, svd}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{H} =} hess (@var{A}) +@deftypefnx {} {[@var{P}, @var{H}] =} hess (@var{A}) +@cindex Hessenberg decomposition +Compute the Hessenberg decomposition of the matrix @var{A}. + +The Hessenberg decomposition is +@tex +$$ +A = PHP^T +$$ +where $P$ is a square unitary matrix ($P^TP = I$), and $H$ +is upper Hessenberg ($H_{i,j} = 0, \forall i > j+1$). +@end tex +@ifnottex +@code{@var{P} * @var{H} * @var{P}' = @var{A}} where @var{P} is a square +unitary matrix (@code{@var{P}' * @var{P} = I}, using complex-conjugate +transposition) and @var{H} is upper Hessenberg +(@code{@var{H}(i, j) = 0 forall i > j+1)}. +@end ifnottex + +The Hessenberg decomposition is usually used as the first step in an +eigenvalue computation, but has other applications as well +(see @nospell{Golub, Nash, and Van Loan}, +IEEE Transactions on Automatic Control, 1979). +@seealso{eig, chol, lu, qr, qz, schur, svd} +@end deftypefn */) { if (args.length () != 1) print_usage ();
--- a/libinterp/corefcn/hex2num.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/hex2num.cc Tue Jun 21 16:07:51 2016 -0400 @@ -33,37 +33,37 @@ #include "utils.h" DEFUN (hex2num, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{n} =} hex2num (@var{s})\n\ -@deftypefnx {} {@var{n} =} hex2num (@var{s}, @var{class})\n\ -Typecast the 16 character hexadecimal character string to an IEEE 754\n\ -double precision number.\n\ -\n\ -If fewer than 16 characters are given the strings are right padded with\n\ -@qcode{'0'} characters.\n\ -\n\ -Given a string matrix, @code{hex2num} treats each row as a separate number.\n\ -\n\ -@example\n\ -@group\n\ -hex2num ([\"4005bf0a8b145769\"; \"4024000000000000\"])\n\ - @result{} [2.7183; 10.000]\n\ -@end group\n\ -@end example\n\ -\n\ -The optional argument @var{class} can be passed as the string\n\ -@qcode{\"single\"} to specify that the given string should be interpreted as\n\ -a single precision number. In this case, @var{s} should be an 8 character\n\ -hexadecimal string. For example:\n\ -\n\ -@example\n\ -@group\n\ -hex2num ([\"402df854\"; \"41200000\"], \"single\")\n\ - @result{} [2.7183; 10.000]\n\ -@end group\n\ -@end example\n\ -@seealso{num2hex, hex2dec, dec2hex}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{n} =} hex2num (@var{s}) +@deftypefnx {} {@var{n} =} hex2num (@var{s}, @var{class}) +Typecast the 16 character hexadecimal character string to an IEEE 754 +double precision number. + +If fewer than 16 characters are given the strings are right padded with +@qcode{'0'} characters. + +Given a string matrix, @code{hex2num} treats each row as a separate number. + +@example +@group +hex2num (["4005bf0a8b145769"; "4024000000000000"]) + @result{} [2.7183; 10.000] +@end group +@end example + +The optional argument @var{class} can be passed as the string +@qcode{"single"} to specify that the given string should be interpreted as +a single precision number. In this case, @var{s} should be an 8 character +hexadecimal string. For example: + +@example +@group +hex2num (["402df854"; "41200000"], "single") + @result{} [2.7183; 10.000] +@end group +@end example +@seealso{num2hex, hex2dec, dec2hex} +@end deftypefn */) { int nargin = args.length (); @@ -173,37 +173,37 @@ */ DEFUN (num2hex, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{s} =} num2hex (@var{n})\n\ -Typecast a double or single precision number or vector to a 8 or 16\n\ -character hexadecimal string of the IEEE 754 representation of the number.\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -num2hex ([-1, 1, e, Inf])\n\ -@result{} \"bff0000000000000\n\ - 3ff0000000000000\n\ - 4005bf0a8b145769\n\ - 7ff0000000000000\"\n\ -@end group\n\ -@end example\n\ -\n\ -If the argument @var{n} is a single precision number or vector, the returned\n\ -string has a length of 8. For example:\n\ -\n\ -@example\n\ -@group\n\ -num2hex (single ([-1, 1, e, Inf]))\n\ -@result{} \"bf800000\n\ - 3f800000\n\ - 402df854\n\ - 7f800000\"\n\ -@end group\n\ -@end example\n\ -@seealso{hex2num, hex2dec, dec2hex}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{s} =} num2hex (@var{n}) +Typecast a double or single precision number or vector to a 8 or 16 +character hexadecimal string of the IEEE 754 representation of the number. + +For example: + +@example +@group +num2hex ([-1, 1, e, Inf]) +@result{} "bff0000000000000 + 3ff0000000000000 + 4005bf0a8b145769 + 7ff0000000000000" +@end group +@end example + +If the argument @var{n} is a single precision number or vector, the returned +string has a length of 8. For example: + +@example +@group +num2hex (single ([-1, 1, e, Inf])) +@result{} "bf800000 + 3f800000 + 402df854 + 7f800000" +@end group +@end example +@seealso{hex2num, hex2dec, dec2hex} +@end deftypefn */) { if (args.length () != 1) print_usage ();
--- a/libinterp/corefcn/input.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/input.cc Tue Jun 21 16:07:51 2016 -0400 @@ -758,43 +758,43 @@ } DEFUN (input, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{ans} =} input (@var{prompt})\n\ -@deftypefnx {} {@var{ans} =} input (@var{prompt}, \"s\")\n\ -Print @var{prompt} and wait for user input.\n\ -\n\ -For example,\n\ -\n\ -@example\n\ -input (\"Pick a number, any number! \")\n\ -@end example\n\ -\n\ -@noindent\n\ -prints the prompt\n\ -\n\ -@example\n\ -Pick a number, any number!\n\ -@end example\n\ -\n\ -@noindent\n\ -and waits for the user to enter a value. The string entered by the user\n\ -is evaluated as an expression, so it may be a literal constant, a variable\n\ -name, or any other valid Octave code.\n\ -\n\ -The number of return arguments, their size, and their class depend on the\n\ -expression entered.\n\ -\n\ -If you are only interested in getting a literal string value, you can call\n\ -@code{input} with the character string @qcode{\"s\"} as the second argument.\n\ -This tells Octave to return the string entered by the user directly, without\n\ -evaluating it first.\n\ -\n\ -Because there may be output waiting to be displayed by the pager, it is a\n\ -good idea to always call @code{fflush (stdout)} before calling @code{input}.\n\ - This will ensure that all pending output is written to the screen before\n\ -your prompt.\n\ -@seealso{yes_or_no, kbhit, pause, menu, listdlg}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{ans} =} input (@var{prompt}) +@deftypefnx {} {@var{ans} =} input (@var{prompt}, "s") +Print @var{prompt} and wait for user input. + +For example, + +@example +input ("Pick a number, any number! ") +@end example + +@noindent +prints the prompt + +@example +Pick a number, any number! +@end example + +@noindent +and waits for the user to enter a value. The string entered by the user +is evaluated as an expression, so it may be a literal constant, a variable +name, or any other valid Octave code. + +The number of return arguments, their size, and their class depend on the +expression entered. + +If you are only interested in getting a literal string value, you can call +@code{input} with the character string @qcode{"s"} as the second argument. +This tells Octave to return the string entered by the user directly, without +evaluating it first. + +Because there may be output waiting to be displayed by the pager, it is a +good idea to always call @code{fflush (stdout)} before calling @code{input}. + This will ensure that all pending output is written to the screen before +your prompt. +@seealso{yes_or_no, kbhit, pause, menu, listdlg} +@end deftypefn */) { int nargin = args.length (); @@ -825,18 +825,18 @@ } DEFUN (yes_or_no, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{ans} =} yes_or_no (\"@var{prompt}\")\n\ -Ask the user a yes-or-no question.\n\ -\n\ -Return logical true if the answer is yes or false if the answer is no.\n\ -\n\ -Takes one argument, @var{prompt}, which is the string to display when asking\n\ -the question. @var{prompt} should end in a space; @code{yes-or-no} adds the\n\ -string @samp{(yes or no) } to it. The user must confirm the answer with\n\ -@key{RET} and can edit it until it has been confirmed.\n\ -@seealso{input}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{ans} =} yes_or_no ("@var{prompt}") +Ask the user a yes-or-no question. + +Return logical true if the answer is yes or false if the answer is no. + +Takes one argument, @var{prompt}, which is the string to display when asking +the question. @var{prompt} should end in a space; @code{yes-or-no} adds the +string @samp{(yes or no) } to it. The user must confirm the answer with +@key{RET} and can edit it until it has been confirmed. +@seealso{input} +@end deftypefn */) { int nargin = args.length (); @@ -890,22 +890,22 @@ } DEFUN (keyboard, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} keyboard ()\n\ -@deftypefnx {} {} keyboard (\"@var{prompt}\")\n\ -Stop m-file execution and enter debug mode.\n\ -\n\ -When the @code{keyboard} function is executed, Octave prints a prompt and\n\ -waits for user input. The input strings are then evaluated and the results\n\ -are printed. This makes it possible to examine the values of variables\n\ -within a function, and to assign new values if necessary. To leave the\n\ -prompt and return to normal execution type @samp{return} or @samp{dbcont}.\n\ -The @code{keyboard} function does not return an exit status.\n\ -\n\ -If @code{keyboard} is invoked without arguments, a default prompt of\n\ -@samp{debug> } is used.\n\ -@seealso{dbstop, dbcont, dbquit}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} keyboard () +@deftypefnx {} {} keyboard ("@var{prompt}") +Stop m-file execution and enter debug mode. + +When the @code{keyboard} function is executed, Octave prints a prompt and +waits for user input. The input strings are then evaluated and the results +are printed. This makes it possible to examine the values of variables +within a function, and to assign new values if necessary. To leave the +prompt and return to normal execution type @samp{return} or @samp{dbcont}. +The @code{keyboard} function does not return an exit status. + +If @code{keyboard} is invoked without arguments, a default prompt of +@samp{debug> } is used. +@seealso{dbstop, dbcont, dbquit} +@end deftypefn */) { if (args.length () > 1) print_usage (); @@ -929,35 +929,35 @@ } DEFUN (echo, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} echo\n\ -@deftypefnx {} {} echo on\n\ -@deftypefnx {} {} echo off\n\ -@deftypefnx {} {} echo on all\n\ -@deftypefnx {} {} echo off all\n\ -Control whether commands are displayed as they are executed.\n\ -\n\ -Valid options are:\n\ -\n\ -@table @code\n\ -@item on\n\ -Enable echoing of commands as they are executed in script files.\n\ -\n\ -@item off\n\ -Disable echoing of commands as they are executed in script files.\n\ -\n\ -@item on all\n\ -Enable echoing of commands as they are executed in script files and\n\ -functions.\n\ -\n\ -@item off all\n\ -Disable echoing of commands as they are executed in script files and\n\ -functions.\n\ -@end table\n\ -\n\ -@noindent\n\ -With no arguments, @code{echo} toggles the current echo state.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} echo +@deftypefnx {} {} echo on +@deftypefnx {} {} echo off +@deftypefnx {} {} echo on all +@deftypefnx {} {} echo off all +Control whether commands are displayed as they are executed. + +Valid options are: + +@table @code +@item on +Enable echoing of commands as they are executed in script files. + +@item off +Disable echoing of commands as they are executed in script files. + +@item on all +Enable echoing of commands as they are executed in script files and +functions. + +@item off all +Disable echoing of commands as they are executed in script files and +functions. +@end table + +@noindent +With no arguments, @code{echo} toggles the current echo state. +@end deftypefn */) { string_vector argv = args.make_argv (); @@ -1058,24 +1058,24 @@ */ DEFUN (__echostate__, , , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{state} =} __echostate__ ()\n\ -Undocumented internal function\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{state} =} __echostate__ () +Undocumented internal function +@end deftypefn */) { return ovl (Vecho_executing_commands == ECHO_SCRIPTS); } DEFUN (completion_matches, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} completion_matches (@var{hint})\n\ -Generate possible completions given @var{hint}.\n\ -\n\ -This function is provided for the benefit of programs like Emacs which\n\ -might be controlling Octave and handling user input. The current\n\ -command number is not incremented when this function is called. This is\n\ -a feature, not a bug.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} completion_matches (@var{hint}) +Generate possible completions given @var{hint}. + +This function is provided for the benefit of programs like Emacs which +might be controlling Octave and handling user input. The current +command number is not incremented when this function is called. This is +a feature, not a bug. +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1151,17 +1151,17 @@ */ DEFUN (readline_read_init_file, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} readline_read_init_file (@var{file})\n\ -Read the readline library initialization file @var{file}.\n\ -\n\ -If @var{file} is omitted, read the default initialization file\n\ -(normally @file{~/.inputrc}).\n\ -\n\ -@xref{Readline Init File, , , readline, GNU Readline Library},\n\ -for details.\n\ -@seealso{readline_re_read_init_file}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} readline_read_init_file (@var{file}) +Read the readline library initialization file @var{file}. + +If @var{file} is omitted, read the default initialization file +(normally @file{~/.inputrc}). + +@xref{Readline Init File, , , readline, GNU Readline Library}, +for details. +@seealso{readline_re_read_init_file} +@end deftypefn */) { int nargin = args.length (); @@ -1181,14 +1181,14 @@ } DEFUN (readline_re_read_init_file, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} readline_re_read_init_file ()\n\ -Re-read the last readline library initialization file that was read.\n\ -\n\ -@xref{Readline Init File, , , readline, GNU Readline Library},\n\ -for details.\n\ -@seealso{readline_read_init_file}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} readline_re_read_init_file () +Re-read the last readline library initialization file that was read. + +@xref{Readline Init File, , , readline, GNU Readline Library}, +for details. +@seealso{readline_read_init_file} +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -1210,24 +1210,24 @@ } DEFUN (add_input_event_hook, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{id} =} add_input_event_hook (@var{fcn})\n\ -@deftypefnx {} {@var{id} =} add_input_event_hook (@var{fcn}, @var{data})\n\ -Add the named function or function handle @var{fcn} to the list of functions\n\ -to call periodically when Octave is waiting for input.\n\ -\n\ -The function should have the form\n\ -\n\ -@example\n\ -@var{fcn} (@var{data})\n\ -@end example\n\ -\n\ -If @var{data} is omitted, Octave calls the function without any arguments.\n\ -\n\ -The returned identifier may be used to remove the function handle from the\n\ -list of input hook functions.\n\ -@seealso{remove_input_event_hook}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{id} =} add_input_event_hook (@var{fcn}) +@deftypefnx {} {@var{id} =} add_input_event_hook (@var{fcn}, @var{data}) +Add the named function or function handle @var{fcn} to the list of functions +to call periodically when Octave is waiting for input. + +The function should have the form + +@example +@var{fcn} (@var{data}) +@end example + +If @var{data} is omitted, Octave calls the function without any arguments. + +The returned identifier may be used to remove the function handle from the +list of input hook functions. +@seealso{remove_input_event_hook} +@end deftypefn */) { int nargin = args.length (); @@ -1250,14 +1250,14 @@ } DEFUN (remove_input_event_hook, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} remove_input_event_hook (@var{name})\n\ -@deftypefnx {} {} remove_input_event_hook (@var{fcn_id})\n\ -Remove the named function or function handle with the given identifier\n\ -from the list of functions to call periodically when Octave is waiting\n\ -for input.\n\ -@seealso{add_input_event_hook}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} remove_input_event_hook (@var{name}) +@deftypefnx {} {} remove_input_event_hook (@var{fcn_id}) +Remove the named function or function handle with the given identifier +from the list of functions to call periodically when Octave is waiting +for input. +@seealso{add_input_event_hook} +@end deftypefn */) { int nargin = args.length (); @@ -1284,147 +1284,147 @@ } DEFUN (PS1, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} PS1 ()\n\ -@deftypefnx {} {@var{old_val} =} PS1 (@var{new_val})\n\ -@deftypefnx {} {} PS1 (@var{new_val}, \"local\")\n\ -Query or set the primary prompt string.\n\ -\n\ -When executing interactively, Octave displays the primary prompt when it is\n\ -ready to read a command.\n\ -\n\ -The default value of the primary prompt string is @qcode{\"octave:\\#> \"}.\n\ -To change it, use a command like\n\ -\n\ -@example\n\ -PS1 (\"\\\\u@@\\\\H> \")\n\ -@end example\n\ -\n\ -@noindent\n\ -which will result in the prompt @samp{boris@@kremvax> } for the user\n\ -@samp{boris} logged in on the host @samp{kremvax.kgb.su}. Note that two\n\ -backslashes are required to enter a backslash into a double-quoted\n\ -character string. @xref{Strings}.\n\ -\n\ -You can also use ANSI escape sequences if your terminal supports them.\n\ -This can be useful for coloring the prompt. For example,\n\ -\n\ -@example\n\ -PS1 (\"\\\\[\\\\033[01;31m\\\\]\\\\s:\\\\#> \\\\[\\\\033[0m\\\\]\")\n\ -@end example\n\ -\n\ -@noindent\n\ -will give the default Octave prompt a red coloring.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{PS2, PS4}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} PS1 () +@deftypefnx {} {@var{old_val} =} PS1 (@var{new_val}) +@deftypefnx {} {} PS1 (@var{new_val}, "local") +Query or set the primary prompt string. + +When executing interactively, Octave displays the primary prompt when it is +ready to read a command. + +The default value of the primary prompt string is @qcode{"octave:\#> "}. +To change it, use a command like + +@example +PS1 ("\\u@@\\H> ") +@end example + +@noindent +which will result in the prompt @samp{boris@@kremvax> } for the user +@samp{boris} logged in on the host @samp{kremvax.kgb.su}. Note that two +backslashes are required to enter a backslash into a double-quoted +character string. @xref{Strings}. + +You can also use ANSI escape sequences if your terminal supports them. +This can be useful for coloring the prompt. For example, + +@example +PS1 ('\[\033[01;31m\]\s:\#> \[\033[0m\]') +@end example + +@noindent +will give the default Octave prompt a red coloring. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{PS2, PS4} +@end deftypefn */) { return SET_INTERNAL_VARIABLE (PS1); } DEFUN (PS2, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} PS2 ()\n\ -@deftypefnx {} {@var{old_val} =} PS2 (@var{new_val})\n\ -@deftypefnx {} {} PS2 (@var{new_val}, \"local\")\n\ -Query or set the secondary prompt string.\n\ -\n\ -The secondary prompt is printed when Octave is expecting additional input to\n\ -complete a command. For example, if you are typing a @code{for} loop that\n\ -spans several lines, Octave will print the secondary prompt at the beginning\n\ -of each line after the first. The default value of the secondary prompt\n\ -string is @qcode{\"> \"}.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{PS1, PS4}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} PS2 () +@deftypefnx {} {@var{old_val} =} PS2 (@var{new_val}) +@deftypefnx {} {} PS2 (@var{new_val}, "local") +Query or set the secondary prompt string. + +The secondary prompt is printed when Octave is expecting additional input to +complete a command. For example, if you are typing a @code{for} loop that +spans several lines, Octave will print the secondary prompt at the beginning +of each line after the first. The default value of the secondary prompt +string is @qcode{"> "}. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{PS1, PS4} +@end deftypefn */) { return SET_INTERNAL_VARIABLE (PS2); } DEFUN (PS4, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} PS4 ()\n\ -@deftypefnx {} {@var{old_val} =} PS4 (@var{new_val})\n\ -@deftypefnx {} {} PS4 (@var{new_val}, \"local\")\n\ -Query or set the character string used to prefix output produced\n\ -when echoing commands is enabled.\n\ -\n\ -The default value is @qcode{\"+ \"}.\n\ -@xref{Diary and Echo Commands}, for a description of echoing commands.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{echo, echo_executing_commands, PS1, PS2}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} PS4 () +@deftypefnx {} {@var{old_val} =} PS4 (@var{new_val}) +@deftypefnx {} {} PS4 (@var{new_val}, "local") +Query or set the character string used to prefix output produced +when echoing commands is enabled. + +The default value is @qcode{"+ "}. +@xref{Diary and Echo Commands}, for a description of echoing commands. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{echo, echo_executing_commands, PS1, PS2} +@end deftypefn */) { return SET_INTERNAL_VARIABLE (PS4); } DEFUN (completion_append_char, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} completion_append_char ()\n\ -@deftypefnx {} {@var{old_val} =} completion_append_char (@var{new_val})\n\ -@deftypefnx {} {} completion_append_char (@var{new_val}, \"local\")\n\ -Query or set the internal character variable that is appended to\n\ -successful command-line completion attempts.\n\ -\n\ -The default value is @qcode{\" \"} (a single space).\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} completion_append_char () +@deftypefnx {} {@var{old_val} =} completion_append_char (@var{new_val}) +@deftypefnx {} {} completion_append_char (@var{new_val}, "local") +Query or set the internal character variable that is appended to +successful command-line completion attempts. + +The default value is @qcode{" "} (a single space). + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@end deftypefn */) { return SET_INTERNAL_VARIABLE (completion_append_char); } DEFUN (echo_executing_commands, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} echo_executing_commands ()\n\ -@deftypefnx {} {@var{old_val} =} echo_executing_commands (@var{new_val})\n\ -@deftypefnx {} {} echo_executing_commands (@var{new_val}, \"local\")\n\ -Query or set the internal variable that controls the echo state.\n\ -\n\ -It may be the sum of the following values:\n\ -\n\ -@table @asis\n\ -@item 1\n\ -Echo commands read from script files.\n\ -\n\ -@item 2\n\ -Echo commands from functions.\n\ -\n\ -@item 4\n\ -Echo commands read from command line.\n\ -@end table\n\ -\n\ -More than one state can be active at once. For example, a value of 3 is\n\ -equivalent to the command @kbd{echo on all}.\n\ -\n\ -The value of @code{echo_executing_commands} may be set by the @kbd{echo}\n\ -command or the command line option @option{--echo-commands}.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} echo_executing_commands () +@deftypefnx {} {@var{old_val} =} echo_executing_commands (@var{new_val}) +@deftypefnx {} {} echo_executing_commands (@var{new_val}, "local") +Query or set the internal variable that controls the echo state. + +It may be the sum of the following values: + +@table @asis +@item 1 +Echo commands read from script files. + +@item 2 +Echo commands from functions. + +@item 4 +Echo commands read from command line. +@end table + +More than one state can be active at once. For example, a value of 3 is +equivalent to the command @kbd{echo on all}. + +The value of @code{echo_executing_commands} may be set by the @kbd{echo} +command or the command line option @option{--echo-commands}. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@end deftypefn */) { return SET_INTERNAL_VARIABLE (echo_executing_commands); } DEFUN (__request_drawnow__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __request_drawnow__ ()\n\ -@deftypefnx {} {} __request_drawnow__ (@var{flag})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __request_drawnow__ () +@deftypefnx {} {} __request_drawnow__ (@var{flag}) +Undocumented internal function. +@end deftypefn */) { int nargin = args.length (); @@ -1440,10 +1440,10 @@ } DEFUN (__gud_mode__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __gud_mode__ ()\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __gud_mode__ () +Undocumented internal function. +@end deftypefn */) { int nargin = args.length (); @@ -1461,40 +1461,40 @@ } DEFUN (filemarker, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} filemarker ()\n\ -@deftypefnx {} {@var{old_val} =} filemarker (@var{new_val})\n\ -@deftypefnx {} {} filemarker (@var{new_val}, \"local\")\n\ -Query or set the character used to separate the filename from the\n\ -subfunction names contained within the file.\n\ -\n\ -By default this is the character @samp{>}.\n\ -This can be used in a generic manner to interact with subfunctions.\n\ -For example,\n\ -\n\ -@example\n\ -help ([\"myfunc\", filemarker, \"mysubfunc\"])\n\ -@end example\n\ -\n\ -@noindent\n\ -returns the help string associated with the subfunction @code{mysubfunc}\n\ -located in the file @file{myfunc.m}.\n\ -\n\ -@code{filemarker} is also useful during debugging for placing breakpoints\n\ -within subfunctions or nested functions.\n\ -For example,\n\ -\n\ -@example\n\ -dbstop ([\"myfunc\", filemarker, \"mysubfunc\"])\n\ -@end example\n\ -\n\ -@noindent\n\ -will set a breakpoint at the first line of the subfunction @code{mysubfunc}.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} filemarker () +@deftypefnx {} {@var{old_val} =} filemarker (@var{new_val}) +@deftypefnx {} {} filemarker (@var{new_val}, "local") +Query or set the character used to separate the filename from the +subfunction names contained within the file. + +By default this is the character @samp{>}. +This can be used in a generic manner to interact with subfunctions. +For example, + +@example +help (["myfunc", filemarker, "mysubfunc"]) +@end example + +@noindent +returns the help string associated with the subfunction @code{mysubfunc} +located in the file @file{myfunc.m}. + +@code{filemarker} is also useful during debugging for placing breakpoints +within subfunctions or nested functions. +For example, + +@example +dbstop (["myfunc", filemarker, "mysubfunc"]) +@end example + +@noindent +will set a breakpoint at the first line of the subfunction @code{mysubfunc}. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@end deftypefn */) { char tmp = Vfilemarker; octave_value retval = SET_INTERNAL_VARIABLE (filemarker);
--- a/libinterp/corefcn/inv.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/inv.cc Tue Jun 21 16:07:51 2016 -0400 @@ -37,26 +37,26 @@ #include "utils.h" DEFUN (inv, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{x} =} inv (@var{A})\n\ -@deftypefnx {} {[@var{x}, @var{rcond}] =} inv (@var{A})\n\ -Compute the inverse of the square matrix @var{A}.\n\ -\n\ -Return an estimate of the reciprocal condition number if requested,\n\ -otherwise warn of an ill-conditioned matrix if the reciprocal condition\n\ -number is small.\n\ -\n\ -In general it is best to avoid calculating the inverse of a matrix directly.\n\ -For example, it is both faster and more accurate to solve systems of\n\ -equations (@var{A}*@math{x} = @math{b}) with\n\ -@code{@var{y} = @var{A} \\ @math{b}}, rather than\n\ -@code{@var{y} = inv (@var{A}) * @math{b}}.\n\ -\n\ -If called with a sparse matrix, then in general @var{x} will be a full\n\ -matrix requiring significantly more storage. Avoid forming the inverse of a\n\ -sparse matrix if possible.\n\ -@seealso{ldivide, rdivide}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{x} =} inv (@var{A}) +@deftypefnx {} {[@var{x}, @var{rcond}] =} inv (@var{A}) +Compute the inverse of the square matrix @var{A}. + +Return an estimate of the reciprocal condition number if requested, +otherwise warn of an ill-conditioned matrix if the reciprocal condition +number is small. + +In general it is best to avoid calculating the inverse of a matrix directly. +For example, it is both faster and more accurate to solve systems of +equations (@var{A}*@math{x} = @math{b}) with +@code{@var{y} = @var{A} \ @math{b}}, rather than +@code{@var{y} = inv (@var{A}) * @math{b}}. + +If called with a sparse matrix, then in general @var{x} will be a full +matrix requiring significantly more storage. Avoid forming the inverse of a +sparse matrix if possible. +@seealso{ldivide, rdivide} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -235,14 +235,14 @@ // dynamic linking. DEFUN (inverse, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{x} =} inverse (@var{A})\n\ -@deftypefnx {} {[@var{x}, @var{rcond}] =} inverse (@var{A})\n\ -Compute the inverse of the square matrix @var{A}.\n\ -\n\ -This is an alias for @code{inv}.\n\ -@seealso{inv}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{x} =} inverse (@var{A}) +@deftypefnx {} {[@var{x}, @var{rcond}] =} inverse (@var{A}) +Compute the inverse of the square matrix @var{A}. + +This is an alias for @code{inv}. +@seealso{inv} +@end deftypefn */) { return Finv (args, nargout); }
--- a/libinterp/corefcn/kron.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/kron.cc Tue Jun 21 16:07:51 2016 -0400 @@ -232,38 +232,39 @@ } -DEFUN (kron, args, , "-*- texinfo -*-\n\ -@deftypefn {} {} kron (@var{A}, @var{B})\n\ -@deftypefnx {} {} kron (@var{A1}, @var{A2}, @dots{})\n\ -Form the Kronecker product of two or more matrices.\n\ -\n\ -This is defined block by block as\n\ -\n\ -@example\n\ -x = [ a(i,j)*b ]\n\ -@end example\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -kron (1:4, ones (3, 1))\n\ - @result{} 1 2 3 4\n\ - 1 2 3 4\n\ - 1 2 3 4\n\ -@end group\n\ -@end example\n\ -\n\ -If there are more than two input arguments @var{A1}, @var{A2}, @dots{},\n\ -@var{An} the Kronecker product is computed as\n\ -\n\ -@example\n\ -kron (kron (@var{A1}, @var{A2}), @dots{}, @var{An})\n\ -@end example\n\ -\n\ -@noindent\n\ -Since the Kronecker product is associative, this is well-defined.\n\ -@end deftypefn") +DEFUN (kron, args, , + doc: /* -*- texinfo -*- +@deftypefn {} {} kron (@var{A}, @var{B}) +@deftypefnx {} {} kron (@var{A1}, @var{A2}, @dots{}) +Form the Kronecker product of two or more matrices. + +This is defined block by block as + +@example +x = [ a(i,j)*b ] +@end example + +For example: + +@example +@group +kron (1:4, ones (3, 1)) + @result{} 1 2 3 4 + 1 2 3 4 + 1 2 3 4 +@end group +@end example + +If there are more than two input arguments @var{A1}, @var{A2}, @dots{}, +@var{An} the Kronecker product is computed as + +@example +kron (kron (@var{A1}, @var{A2}), @dots{}, @var{An}) +@end example + +@noindent +Since the Kronecker product is associative, this is well-defined. +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/load-path.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/load-path.cc Tue Jun 21 16:07:51 2016 -0400 @@ -2230,14 +2230,14 @@ } DEFUN (genpath, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} genpath (@var{dir})\n\ -@deftypefnx {} {} genpath (@var{dir}, @var{skip}, @dots{})\n\ -Return a path constructed from @var{dir} and all its subdirectories.\n\ -\n\ -If additional string parameters are given, the resulting path will exclude\n\ -directories with those names.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} genpath (@var{dir}) +@deftypefnx {} {} genpath (@var{dir}, @var{skip}, @dots{}) +Return a path constructed from @var{dir} and all its subdirectories. + +If additional string parameters are given, the resulting path will exclude +directories with those names. +@end deftypefn */) { int nargin = args.length (); @@ -2280,10 +2280,10 @@ } DEFUN (rehash, , , - "-*- texinfo -*-\n\ -@deftypefn {} {} rehash ()\n\ -Reinitialize Octave's load path directory cache.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} rehash () +Reinitialize Octave's load path directory cache. +@end deftypefn */) { rehash_internal (); @@ -2291,23 +2291,23 @@ } DEFUN (command_line_path, , , - "-*- texinfo -*-\n\ -@deftypefn {} {} command_line_path (@dots{})\n\ -Return the command line path variable.\n\ -\n\ -@seealso{path, addpath, rmpath, genpath, pathdef, savepath, pathsep}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} command_line_path (@dots{}) +Return the command line path variable. + +@seealso{path, addpath, rmpath, genpath, pathdef, savepath, pathsep} +@end deftypefn */) { return ovl (load_path::get_command_line_path ()); } DEFUN (restoredefaultpath, , , - "-*- texinfo -*-\n\ -@deftypefn {} {} restoredefaultpath (@dots{})\n\ -Restore Octave's path to its initial state at startup.\n\ -\n\ -@seealso{path, addpath, rmpath, genpath, pathdef, savepath, pathsep}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} restoredefaultpath (@dots{}) +Restore Octave's path to its initial state at startup. + +@seealso{path, addpath, rmpath, genpath, pathdef, savepath, pathsep} +@end deftypefn */) { load_path::initialize (true); @@ -2320,34 +2320,34 @@ // ~/.octaverc file DEFUN (__pathorig__, , , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} __pathorig__ ()\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} __pathorig__ () +Undocumented internal function. +@end deftypefn */) { return ovl (load_path::system_path ()); } DEFUN (path, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} path ()\n\ -@deftypefnx {} {@var{str} =} path ()\n\ -@deftypefnx {} {@var{str} =} path (@var{path1}, @dots{})\n\ -Modify or display Octave's load path.\n\ -\n\ -If @var{nargin} and @var{nargout} are zero, display the elements of\n\ -Octave's load path in an easy to read format.\n\ -\n\ -If @var{nargin} is zero and nargout is greater than zero, return the\n\ -current load path.\n\ -\n\ -If @var{nargin} is greater than zero, concatenate the arguments,\n\ -separating them with @code{pathsep}. Set the internal search path\n\ -to the result and return it.\n\ -\n\ -No checks are made for duplicate elements.\n\ -@seealso{addpath, rmpath, genpath, pathdef, savepath, pathsep}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} path () +@deftypefnx {} {@var{str} =} path () +@deftypefnx {} {@var{str} =} path (@var{path1}, @dots{}) +Modify or display Octave's load path. + +If @var{nargin} and @var{nargout} are zero, display the elements of +Octave's load path in an easy to read format. + +If @var{nargin} is zero and nargout is greater than zero, return the +current load path. + +If @var{nargin} is greater than zero, concatenate the arguments, +separating them with @code{pathsep}. Set the internal search path +to the result and return it. + +No checks are made for duplicate elements. +@seealso{addpath, rmpath, genpath, pathdef, savepath, pathsep} +@end deftypefn */) { int nargin = args.length (); @@ -2383,24 +2383,24 @@ } DEFUN (addpath, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} addpath (@var{dir1}, @dots{})\n\ -@deftypefnx {} {} addpath (@var{dir1}, @dots{}, @var{option})\n\ -Add named directories to the function search path.\n\ -\n\ -If @var{option} is @qcode{\"-begin\"} or 0 (the default), prepend the\n\ -directory name to the current path. If @var{option} is @qcode{\"-end\"}\n\ -or 1, append the directory name to the current path.\n\ -Directories added to the path must exist.\n\ -\n\ -In addition to accepting individual directory arguments, lists of\n\ -directory names separated by @code{pathsep} are also accepted. For example:\n\ -\n\ -@example\n\ -addpath (\"dir1:/dir2:~/dir3\")\n\ -@end example\n\ -@seealso{path, rmpath, genpath, pathdef, savepath, pathsep}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} addpath (@var{dir1}, @dots{}) +@deftypefnx {} {} addpath (@var{dir1}, @dots{}, @var{option}) +Add named directories to the function search path. + +If @var{option} is @qcode{"-begin"} or 0 (the default), prepend the +directory name to the current path. If @var{option} is @qcode{"-end"} +or 1, append the directory name to the current path. +Directories added to the path must exist. + +In addition to accepting individual directory arguments, lists of +directory names separated by @code{pathsep} are also accepted. For example: + +@example +addpath ("dir1:/dir2:~/dir3") +@end example +@seealso{path, rmpath, genpath, pathdef, savepath, pathsep} +@end deftypefn */) { // Originally written by Bill Denney and Etienne Grossman. // Heavily modified and translated to C++ by jwe. @@ -2490,18 +2490,18 @@ } DEFUN (rmpath, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} rmpath (@var{dir1}, @dots{})\n\ -Remove @var{dir1}, @dots{} from the current function search path.\n\ -\n\ -In addition to accepting individual directory arguments, lists of\n\ -directory names separated by @code{pathsep} are also accepted. For example:\n\ -\n\ -@example\n\ -rmpath (\"dir1:/dir2:~/dir3\")\n\ -@end example\n\ -@seealso{path, addpath, genpath, pathdef, savepath, pathsep}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} rmpath (@var{dir1}, @dots{}) +Remove @var{dir1}, @dots{} from the current function search path. + +In addition to accepting individual directory arguments, lists of +directory names separated by @code{pathsep} are also accepted. For example: + +@example +rmpath ("dir1:/dir2:~/dir3") +@end example +@seealso{path, addpath, genpath, pathdef, savepath, pathsep} +@end deftypefn */) { // Originally written by Etienne Grossmann. Heavily modified and translated // to C++ by jwe. @@ -2545,7 +2545,11 @@ return retval; } -DEFUN (__dump_load_path__, , , "") +DEFUN (__dump_load_path__, , , + doc: /* -*- texinfo -*- +@deftypefn {} {} __dump_load_path__ () +Undocumented internal function. +@end deftypefn */) { load_path::display (octave_stdout);
--- a/libinterp/corefcn/load-save.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/load-save.cc Tue Jun 21 16:07:51 2016 -0400 @@ -529,103 +529,103 @@ } DEFUN (load, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} load file\n\ -@deftypefnx {} {} load options file\n\ -@deftypefnx {} {} load options file v1 v2 @dots{}\n\ -@deftypefnx {} {S =} load (\"options\", \"file\", \"v1\", \"v2\", @dots{})\n\ -@deftypefnx {} {} load file options\n\ -@deftypefnx {} {} load file options v1 v2 @dots{}\n\ -@deftypefnx {} {S =} load (\"file\", \"options\", \"v1\", \"v2\", @dots{})\n\ -Load the named variables @var{v1}, @var{v2}, @dots{}, from the file\n\ -@var{file}.\n\ -\n\ -If no variables are specified then all variables found in the\n\ -file will be loaded. As with @code{save}, the list of variables to extract\n\ -can be full names or use a pattern syntax. The format of the file is\n\ -automatically detected but may be overridden by supplying the appropriate\n\ -option.\n\ -\n\ -If load is invoked using the functional form\n\ -\n\ -@example\n\ -load (\"-option1\", @dots{}, \"file\", \"v1\", @dots{})\n\ -@end example\n\ -\n\ -@noindent\n\ -then the @var{options}, @var{file}, and variable name arguments\n\ -(@var{v1}, @dots{}) must be specified as character strings.\n\ -\n\ -If a variable that is not marked as global is loaded from a file when a\n\ -global symbol with the same name already exists, it is loaded in the\n\ -global symbol table. Also, if a variable is marked as global in a file\n\ -and a local symbol exists, the local symbol is moved to the global\n\ -symbol table and given the value from the file.\n\ -\n\ -If invoked with a single output argument, Octave returns data instead\n\ -of inserting variables in the symbol table. If the data file contains\n\ -only numbers (TAB- or space-delimited columns), a matrix of values is\n\ -returned. Otherwise, @code{load} returns a structure with members\n\ - corresponding to the names of the variables in the file.\n\ -\n\ -The @code{load} command can read data stored in Octave's text and\n\ -binary formats, and @sc{matlab}'s binary format. If compiled with zlib\n\ -support, it can also load gzip-compressed files. It will automatically\n\ -detect the type of file and do conversion from different floating point\n\ -formats (currently only IEEE big and little endian, though other formats\n\ -may be added in the future).\n\ -\n\ -Valid options for @code{load} are listed in the following table.\n\ -\n\ -@table @code\n\ -@item -force\n\ -This option is accepted for backward compatibility but is ignored.\n\ -Octave now overwrites variables currently in memory with\n\ -those of the same name found in the file.\n\ -\n\ -@item -ascii\n\ -Force Octave to assume the file contains columns of numbers in text format\n\ -without any header or other information. Data in the file will be loaded\n\ -as a single numeric matrix with the name of the variable derived from the\n\ -name of the file.\n\ -\n\ -@item -binary\n\ -Force Octave to assume the file is in Octave's binary format.\n\ -\n\ -@item -hdf5\n\ -Force Octave to assume the file is in @sc{hdf5} format.\n\ -(@sc{hdf5} is a free, portable binary format developed by the National\n\ -Center for Supercomputing Applications at the University of Illinois.)\n\ -Note that Octave can read @sc{hdf5} files not created by itself, but may\n\ -skip some datasets in formats that it cannot support. This format is\n\ -only available if Octave was built with a link to the @sc{hdf5} libraries.\n\ -\n\ -@item -import\n\ -This option is accepted for backward compatibility but is ignored.\n\ -Octave can now support multi-dimensional HDF data and automatically\n\ -modifies variable names if they are invalid Octave identifiers.\n\ -\n\ -@item -mat\n\ -@itemx -mat-binary\n\ -@itemx -6\n\ -@itemx -v6\n\ -@itemx -7\n\ -@itemx -v7\n\ -Force Octave to assume the file is in @sc{matlab}'s version 6 or 7 binary\n\ -format.\n\ -\n\ -@item -mat4-binary\n\ -@itemx -4\n\ -@itemx -v4\n\ -@itemx -V4\n\ -Force Octave to assume the file is in the binary format written by\n\ -@sc{matlab} version 4.\n\ -\n\ -@item -text\n\ -Force Octave to assume the file is in Octave's text format.\n\ -@end table\n\ -@seealso{save, dlmwrite, csvwrite, fwrite}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} load file +@deftypefnx {} {} load options file +@deftypefnx {} {} load options file v1 v2 @dots{} +@deftypefnx {} {S =} load ("options", "file", "v1", "v2", @dots{}) +@deftypefnx {} {} load file options +@deftypefnx {} {} load file options v1 v2 @dots{} +@deftypefnx {} {S =} load ("file", "options", "v1", "v2", @dots{}) +Load the named variables @var{v1}, @var{v2}, @dots{}, from the file +@var{file}. + +If no variables are specified then all variables found in the +file will be loaded. As with @code{save}, the list of variables to extract +can be full names or use a pattern syntax. The format of the file is +automatically detected but may be overridden by supplying the appropriate +option. + +If load is invoked using the functional form + +@example +load ("-option1", @dots{}, "file", "v1", @dots{}) +@end example + +@noindent +then the @var{options}, @var{file}, and variable name arguments +(@var{v1}, @dots{}) must be specified as character strings. + +If a variable that is not marked as global is loaded from a file when a +global symbol with the same name already exists, it is loaded in the +global symbol table. Also, if a variable is marked as global in a file +and a local symbol exists, the local symbol is moved to the global +symbol table and given the value from the file. + +If invoked with a single output argument, Octave returns data instead +of inserting variables in the symbol table. If the data file contains +only numbers (TAB- or space-delimited columns), a matrix of values is +returned. Otherwise, @code{load} returns a structure with members + corresponding to the names of the variables in the file. + +The @code{load} command can read data stored in Octave's text and +binary formats, and @sc{matlab}'s binary format. If compiled with zlib +support, it can also load gzip-compressed files. It will automatically +detect the type of file and do conversion from different floating point +formats (currently only IEEE big and little endian, though other formats +may be added in the future). + +Valid options for @code{load} are listed in the following table. + +@table @code +@item -force +This option is accepted for backward compatibility but is ignored. +Octave now overwrites variables currently in memory with +those of the same name found in the file. + +@item -ascii +Force Octave to assume the file contains columns of numbers in text format +without any header or other information. Data in the file will be loaded +as a single numeric matrix with the name of the variable derived from the +name of the file. + +@item -binary +Force Octave to assume the file is in Octave's binary format. + +@item -hdf5 +Force Octave to assume the file is in @sc{hdf5} format. +(@sc{hdf5} is a free, portable binary format developed by the National +Center for Supercomputing Applications at the University of Illinois.) +Note that Octave can read @sc{hdf5} files not created by itself, but may +skip some datasets in formats that it cannot support. This format is +only available if Octave was built with a link to the @sc{hdf5} libraries. + +@item -import +This option is accepted for backward compatibility but is ignored. +Octave can now support multi-dimensional HDF data and automatically +modifies variable names if they are invalid Octave identifiers. + +@item -mat +@itemx -mat-binary +@itemx -6 +@itemx -v6 +@itemx -7 +@itemx -v7 +Force Octave to assume the file is in @sc{matlab}'s version 6 or 7 binary +format. + +@item -mat4-binary +@itemx -4 +@itemx -v4 +@itemx -V4 +Force Octave to assume the file is in the binary format written by +@sc{matlab} version 4. + +@item -text +Force Octave to assume the file is in Octave's text format. +@end table +@seealso{save, dlmwrite, csvwrite, fwrite} +@end deftypefn */) { octave_value_list retval; @@ -1444,135 +1444,135 @@ } DEFUN (save, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} save file\n\ -@deftypefnx {} {} save options file\n\ -@deftypefnx {} {} save options file @var{v1} @var{v2} @dots{}\n\ -@deftypefnx {} {} save options file -struct @var{STRUCT} @var{f1} @var{f2} @dots{}\n\ -@deftypefnx {} {} save @code{\"-\"} @var{v1} @var{v2} @dots{}\n\ -@deftypefnx {} {@var{s} =} save (@code{\"-\"} @var{v1} @var{v2} @dots{})\n\ -Save the named variables @var{v1}, @var{v2}, @dots{}, in the file\n\ -@var{file}.\n\ -\n\ -The special filename @samp{-} may be used to return the\n\ -content of the variables as a string. If no variable names are listed,\n\ -Octave saves all the variables in the current scope. Otherwise, full\n\ -variable names or pattern syntax can be used to specify the variables to\n\ -save. If the @option{-struct} modifier is used, fields @var{f1} @var{f2}\n\ -@dots{} of the scalar structure @var{STRUCT} are saved as if they were\n\ -variables with corresponding names. Valid options for the @code{save}\n\ -command are listed in the following table. Options that modify the output\n\ -format override the format specified by @code{save_default_options}.\n\ -\n\ -If save is invoked using the functional form\n\ -\n\ -@example\n\ -save (\"-option1\", @dots{}, \"file\", \"v1\", @dots{})\n\ -@end example\n\ -\n\ -@noindent\n\ -then the @var{options}, @var{file}, and variable name arguments\n\ -(@var{v1}, @dots{}) must be specified as character strings.\n\ -\n\ -If called with a filename of @qcode{\"-\"}, write the output to stdout\n\ -if nargout is 0, otherwise return the output in a character string.\n\ -\n\ -@table @code\n\ -@item -append\n\ -Append to the destination instead of overwriting.\n\ -\n\ -@item -ascii\n\ -Save a single matrix in a text file without header or any other information.\n\ -\n\ -@item -binary\n\ -Save the data in Octave's binary data format.\n\ -\n\ -@item -float-binary\n\ -Save the data in Octave's binary data format but only using single\n\ -precision. Only use this format if you know that all the\n\ -values to be saved can be represented in single precision.\n\ -\n\ -@item -hdf5\n\ -Save the data in @sc{hdf5} format.\n\ -(HDF5 is a free, portable binary format developed by the National\n\ -Center for Supercomputing Applications at the University of Illinois.)\n\ -This format is only available if Octave was built with a link to the\n\ -@sc{hdf5} libraries.\n\ -\n\ -@item -float-hdf5\n\ -Save the data in @sc{hdf5} format but only using single precision.\n\ -Only use this format if you know that all the\n\ -values to be saved can be represented in single precision.\n\ -\n\ -@item -V7\n\ -@itemx -v7\n\ -@itemx -7\n\ -@itemx -mat7-binary\n\ -Save the data in @sc{matlab}'s v7 binary data format.\n\ -\n\ -@item -V6\n\ -@itemx -v6\n\ -@itemx -6\n\ -@itemx -mat\n\ -@itemx -mat-binary\n\ -Save the data in @sc{matlab}'s v6 binary data format.\n\ -\n\ -@item -V4\n\ -@itemx -v4\n\ -@itemx -4\n\ -@itemx -mat4-binary\n\ -Save the data in the binary format written by @sc{matlab} version 4.\n\ -\n\ -@item -text\n\ -Save the data in Octave's text data format. (default).\n\ -\n\ -@item -zip\n\ -@itemx -z\n\ -Use the gzip algorithm to compress the file. This works equally on files\n\ -that are compressed with gzip outside of octave, and gzip can equally be\n\ -used to convert the files for backward compatibility.\n\ -This option is only available if Octave was built with a link to the zlib\n\ -libraries.\n\ -@end table\n\ -\n\ -The list of variables to save may use wildcard patterns containing\n\ -the following special characters:\n\ -\n\ -@table @code\n\ -@item ?\n\ -Match any single character.\n\ -\n\ -@item *\n\ -Match zero or more characters.\n\ -\n\ -@item [ @var{list} ]\n\ -Match the list of characters specified by @var{list}. If the first\n\ -character is @code{!} or @code{^}, match all characters except those\n\ -specified by @var{list}. For example, the pattern @code{[a-zA-Z]} will\n\ -match all lower and uppercase alphabetic characters.\n\ -\n\ -Wildcards may also be used in the field name specifications when using\n\ -the @option{-struct} modifier (but not in the struct name itself).\n\ -\n\ -@end table\n\ -\n\ -Except when using the @sc{matlab} binary data file format or the\n\ -@samp{-ascii} format, saving global\n\ -variables also saves the global status of the variable. If the variable\n\ -is restored at a later time using @samp{load}, it will be restored as a\n\ -global variable.\n\ -\n\ -The command\n\ -\n\ -@example\n\ -save -binary data a b*\n\ -@end example\n\ -\n\ -@noindent\n\ -saves the variable @samp{a} and all variables beginning with @samp{b} to\n\ -the file @file{data} in Octave's binary format.\n\ -@seealso{load, save_default_options, save_header_format_string, dlmread, csvread, fread}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} save file +@deftypefnx {} {} save options file +@deftypefnx {} {} save options file @var{v1} @var{v2} @dots{} +@deftypefnx {} {} save options file -struct @var{STRUCT} @var{f1} @var{f2} @dots{} +@deftypefnx {} {} save @code{"-"} @var{v1} @var{v2} @dots{} +@deftypefnx {} {@var{s} =} save (@code{"-"} @var{v1} @var{v2} @dots{}) +Save the named variables @var{v1}, @var{v2}, @dots{}, in the file +@var{file}. + +The special filename @samp{-} may be used to return the +content of the variables as a string. If no variable names are listed, +Octave saves all the variables in the current scope. Otherwise, full +variable names or pattern syntax can be used to specify the variables to +save. If the @option{-struct} modifier is used, fields @var{f1} @var{f2} +@dots{} of the scalar structure @var{STRUCT} are saved as if they were +variables with corresponding names. Valid options for the @code{save} +command are listed in the following table. Options that modify the output +format override the format specified by @code{save_default_options}. + +If save is invoked using the functional form + +@example +save ("-option1", @dots{}, "file", "v1", @dots{}) +@end example + +@noindent +then the @var{options}, @var{file}, and variable name arguments +(@var{v1}, @dots{}) must be specified as character strings. + +If called with a filename of @qcode{"-"}, write the output to stdout +if nargout is 0, otherwise return the output in a character string. + +@table @code +@item -append +Append to the destination instead of overwriting. + +@item -ascii +Save a single matrix in a text file without header or any other information. + +@item -binary +Save the data in Octave's binary data format. + +@item -float-binary +Save the data in Octave's binary data format but only using single +precision. Only use this format if you know that all the +values to be saved can be represented in single precision. + +@item -hdf5 +Save the data in @sc{hdf5} format. +(HDF5 is a free, portable binary format developed by the National +Center for Supercomputing Applications at the University of Illinois.) +This format is only available if Octave was built with a link to the +@sc{hdf5} libraries. + +@item -float-hdf5 +Save the data in @sc{hdf5} format but only using single precision. +Only use this format if you know that all the +values to be saved can be represented in single precision. + +@item -V7 +@itemx -v7 +@itemx -7 +@itemx -mat7-binary +Save the data in @sc{matlab}'s v7 binary data format. + +@item -V6 +@itemx -v6 +@itemx -6 +@itemx -mat +@itemx -mat-binary +Save the data in @sc{matlab}'s v6 binary data format. + +@item -V4 +@itemx -v4 +@itemx -4 +@itemx -mat4-binary +Save the data in the binary format written by @sc{matlab} version 4. + +@item -text +Save the data in Octave's text data format. (default). + +@item -zip +@itemx -z +Use the gzip algorithm to compress the file. This works equally on files +that are compressed with gzip outside of octave, and gzip can equally be +used to convert the files for backward compatibility. +This option is only available if Octave was built with a link to the zlib +libraries. +@end table + +The list of variables to save may use wildcard patterns containing +the following special characters: + +@table @code +@item ? +Match any single character. + +@item * +Match zero or more characters. + +@item [ @var{list} ] +Match the list of characters specified by @var{list}. If the first +character is @code{!} or @code{^}, match all characters except those +specified by @var{list}. For example, the pattern @code{[a-zA-Z]} will +match all lower and uppercase alphabetic characters. + +Wildcards may also be used in the field name specifications when using +the @option{-struct} modifier (but not in the struct name itself). + +@end table + +Except when using the @sc{matlab} binary data file format or the +@samp{-ascii} format, saving global +variables also saves the global status of the variable. If the variable +is restored at a later time using @samp{load}, it will be restored as a +global variable. + +The command + +@example +save -binary data a b* +@end example + +@noindent +saves the variable @samp{a} and all variables beginning with @samp{b} to +the file @file{data} in Octave's binary format. +@seealso{load, save_default_options, save_header_format_string, dlmread, csvread, fread} +@end deftypefn */) { // Here is where we would get the default save format if it were // stored in a user preference variable. @@ -1715,131 +1715,131 @@ } DEFUN (crash_dumps_octave_core, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} crash_dumps_octave_core ()\n\ -@deftypefnx {} {@var{old_val} =} crash_dumps_octave_core (@var{new_val})\n\ -@deftypefnx {} {} crash_dumps_octave_core (@var{new_val}, \"local\")\n\ -Query or set the internal variable that controls whether Octave tries\n\ -to save all current variables to the file @file{octave-workspace} if it\n\ -crashes or receives a hangup, terminate or similar signal.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{octave_core_file_limit, octave_core_file_name, octave_core_file_options}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} crash_dumps_octave_core () +@deftypefnx {} {@var{old_val} =} crash_dumps_octave_core (@var{new_val}) +@deftypefnx {} {} crash_dumps_octave_core (@var{new_val}, "local") +Query or set the internal variable that controls whether Octave tries +to save all current variables to the file @file{octave-workspace} if it +crashes or receives a hangup, terminate or similar signal. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{octave_core_file_limit, octave_core_file_name, octave_core_file_options} +@end deftypefn */) { return SET_INTERNAL_VARIABLE (crash_dumps_octave_core); } DEFUN (save_default_options, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} save_default_options ()\n\ -@deftypefnx {} {@var{old_val} =} save_default_options (@var{new_val})\n\ -@deftypefnx {} {} save_default_options (@var{new_val}, \"local\")\n\ -Query or set the internal variable that specifies the default options\n\ -for the @code{save} command, and defines the default format.\n\ -\n\ -Typical values include @qcode{\"-ascii\"}, @qcode{\"-text -zip\"}.\n\ -The default value is @option{-text}.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{save}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} save_default_options () +@deftypefnx {} {@var{old_val} =} save_default_options (@var{new_val}) +@deftypefnx {} {} save_default_options (@var{new_val}, "local") +Query or set the internal variable that specifies the default options +for the @code{save} command, and defines the default format. + +Typical values include @qcode{"-ascii"}, @qcode{"-text -zip"}. +The default value is @option{-text}. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{save} +@end deftypefn */) { return SET_NONEMPTY_INTERNAL_STRING_VARIABLE (save_default_options); } DEFUN (octave_core_file_limit, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} octave_core_file_limit ()\n\ -@deftypefnx {} {@var{old_val} =} octave_core_file_limit (@var{new_val})\n\ -@deftypefnx {} {} octave_core_file_limit (@var{new_val}, \"local\")\n\ -Query or set the internal variable that specifies the maximum amount\n\ -of memory (in kilobytes) of the top-level workspace that Octave will\n\ -attempt to save when writing data to the crash dump file (the name of\n\ -the file is specified by @var{octave_core_file_name}).\n\ -\n\ -If @var{octave_core_file_options} flags specify a binary format,\n\ -then @var{octave_core_file_limit} will be approximately the maximum\n\ -size of the file. If a text file format is used, then the file could\n\ -be much larger than the limit. The default value is -1 (unlimited)\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{crash_dumps_octave_core, octave_core_file_name, octave_core_file_options}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} octave_core_file_limit () +@deftypefnx {} {@var{old_val} =} octave_core_file_limit (@var{new_val}) +@deftypefnx {} {} octave_core_file_limit (@var{new_val}, "local") +Query or set the internal variable that specifies the maximum amount +of memory (in kilobytes) of the top-level workspace that Octave will +attempt to save when writing data to the crash dump file (the name of +the file is specified by @var{octave_core_file_name}). + +If @var{octave_core_file_options} flags specify a binary format, +then @var{octave_core_file_limit} will be approximately the maximum +size of the file. If a text file format is used, then the file could +be much larger than the limit. The default value is -1 (unlimited) + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{crash_dumps_octave_core, octave_core_file_name, octave_core_file_options} +@end deftypefn */) { return SET_INTERNAL_VARIABLE (octave_core_file_limit); } DEFUN (octave_core_file_name, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} octave_core_file_name ()\n\ -@deftypefnx {} {@var{old_val} =} octave_core_file_name (@var{new_val})\n\ -@deftypefnx {} {} octave_core_file_name (@var{new_val}, \"local\")\n\ -Query or set the internal variable that specifies the name of the file\n\ -used for saving data from the top-level workspace if Octave aborts.\n\ -\n\ -The default value is @qcode{\"octave-workspace\"}\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{crash_dumps_octave_core, octave_core_file_name, octave_core_file_options}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} octave_core_file_name () +@deftypefnx {} {@var{old_val} =} octave_core_file_name (@var{new_val}) +@deftypefnx {} {} octave_core_file_name (@var{new_val}, "local") +Query or set the internal variable that specifies the name of the file +used for saving data from the top-level workspace if Octave aborts. + +The default value is @qcode{"octave-workspace"} + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{crash_dumps_octave_core, octave_core_file_name, octave_core_file_options} +@end deftypefn */) { return SET_NONEMPTY_INTERNAL_STRING_VARIABLE (octave_core_file_name); } DEFUN (octave_core_file_options, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} octave_core_file_options ()\n\ -@deftypefnx {} {@var{old_val} =} octave_core_file_options (@var{new_val})\n\ -@deftypefnx {} {} octave_core_file_options (@var{new_val}, \"local\")\n\ -Query or set the internal variable that specifies the options used for\n\ -saving the workspace data if Octave aborts.\n\ -\n\ -The value of @code{octave_core_file_options} should follow the same format\n\ -as the options for the @code{save} function. The default value is Octave's\n\ -binary format.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{crash_dumps_octave_core, octave_core_file_name, octave_core_file_limit}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} octave_core_file_options () +@deftypefnx {} {@var{old_val} =} octave_core_file_options (@var{new_val}) +@deftypefnx {} {} octave_core_file_options (@var{new_val}, "local") +Query or set the internal variable that specifies the options used for +saving the workspace data if Octave aborts. + +The value of @code{octave_core_file_options} should follow the same format +as the options for the @code{save} function. The default value is Octave's +binary format. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{crash_dumps_octave_core, octave_core_file_name, octave_core_file_limit} +@end deftypefn */) { return SET_NONEMPTY_INTERNAL_STRING_VARIABLE (octave_core_file_options); } DEFUN (save_header_format_string, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} save_header_format_string ()\n\ -@deftypefnx {} {@var{old_val} =} save_header_format_string (@var{new_val})\n\ -@deftypefnx {} {} save_header_format_string (@var{new_val}, \"local\")\n\ -Query or set the internal variable that specifies the format\n\ -string used for the comment line written at the beginning of\n\ -text-format data files saved by Octave.\n\ -\n\ -The format string is passed to @code{strftime} and should begin with the\n\ -character @samp{#} and contain no newline characters. If the value of\n\ -@code{save_header_format_string} is the empty string, the header comment is\n\ -omitted from text-format data files. The default value is\n\ -@c Set example in small font to prevent overfull line\n\ -\n\ -@smallexample\n\ -\"# Created by Octave VERSION, %a %b %d %H:%M:%S %Y %Z <USER@@HOST>\"\n\ -@end smallexample\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{strftime, save}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} save_header_format_string () +@deftypefnx {} {@var{old_val} =} save_header_format_string (@var{new_val}) +@deftypefnx {} {} save_header_format_string (@var{new_val}, "local") +Query or set the internal variable that specifies the format +string used for the comment line written at the beginning of +text-format data files saved by Octave. + +The format string is passed to @code{strftime} and should begin with the +character @samp{#} and contain no newline characters. If the value of +@code{save_header_format_string} is the empty string, the header comment is +omitted from text-format data files. The default value is +@c Set example in small font to prevent overfull line + +@smallexample +"# Created by Octave VERSION, %a %b %d %H:%M:%S %Y %Z <USER@@HOST>" +@end smallexample + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{strftime, save} +@end deftypefn */) { return SET_INTERNAL_VARIABLE (save_header_format_string); }
--- a/libinterp/corefcn/lookup.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/lookup.cc Tue Jun 21 16:07:51 2016 -0400 @@ -188,55 +188,55 @@ } DEFUN (lookup, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{idx} =} lookup (@var{table}, @var{y})\n\ -@deftypefnx {} {@var{idx} =} lookup (@var{table}, @var{y}, @var{opt})\n\ -Lookup values in a sorted table.\n\ -\n\ -This function is usually used as a prelude to interpolation.\n\ -\n\ -If table is increasing and @code{idx = lookup (table, y)}, then\n\ -@code{table(idx(i)) <= y(i) < table(idx(i+1))} for all @code{y(i)} within\n\ -the table. If @code{y(i) < table(1)} then @code{idx(i)} is 0. If\n\ -@code{y(i) >= table(end)} or @code{isnan (y(i))} then @code{idx(i)} is\n\ -@code{n}.\n\ -\n\ -If the table is decreasing, then the tests are reversed.\n\ -For non-strictly monotonic tables, empty intervals are always skipped.\n\ -The result is undefined if @var{table} is not monotonic, or if\n\ -@var{table} contains a NaN.\n\ -\n\ -The complexity of the lookup is O(M*log(N)) where N is the size of\n\ -@var{table} and M is the size of @var{y}. In the special case when @var{y}\n\ -is also sorted, the complexity is O(min(M*log(N),M+N)).\n\ -\n\ -@var{table} and @var{y} can also be cell arrays of strings\n\ -(or @var{y} can be a single string). In this case, string lookup\n\ -is performed using lexicographical comparison.\n\ -\n\ -If @var{opts} is specified, it must be a string with letters indicating\n\ -additional options.\n\ -\n\ -@table @code\n\ -@item m\n\ -@code{table(idx(i)) == val(i)} if @code{val(i)}\n\ -occurs in table; otherwise, @code{idx(i)} is zero.\n\ -\n\ -@item b\n\ -@code{idx(i)} is a logical 1 or 0, indicating whether\n\ -@code{val(i)} is contained in table or not.\n\ -\n\ -@item l\n\ -For numeric lookups\n\ -the leftmost subinterval shall be extended to infinity (i.e., all indices\n\ -at least 1)\n\ -\n\ -@item r\n\ -For numeric lookups\n\ -the rightmost subinterval shall be extended to infinity (i.e., all indices\n\ -at most n-1).\n\ -@end table\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{idx} =} lookup (@var{table}, @var{y}) +@deftypefnx {} {@var{idx} =} lookup (@var{table}, @var{y}, @var{opt}) +Lookup values in a sorted table. + +This function is usually used as a prelude to interpolation. + +If table is increasing and @code{idx = lookup (table, y)}, then +@code{table(idx(i)) <= y(i) < table(idx(i+1))} for all @code{y(i)} within +the table. If @code{y(i) < table(1)} then @code{idx(i)} is 0. If +@code{y(i) >= table(end)} or @code{isnan (y(i))} then @code{idx(i)} is +@code{n}. + +If the table is decreasing, then the tests are reversed. +For non-strictly monotonic tables, empty intervals are always skipped. +The result is undefined if @var{table} is not monotonic, or if +@var{table} contains a NaN. + +The complexity of the lookup is O(M*log(N)) where N is the size of +@var{table} and M is the size of @var{y}. In the special case when @var{y} +is also sorted, the complexity is O(min(M*log(N),M+N)). + +@var{table} and @var{y} can also be cell arrays of strings +(or @var{y} can be a single string). In this case, string lookup +is performed using lexicographical comparison. + +If @var{opts} is specified, it must be a string with letters indicating +additional options. + +@table @code +@item m +@code{table(idx(i)) == val(i)} if @code{val(i)} +occurs in table; otherwise, @code{idx(i)} is zero. + +@item b +@code{idx(i)} is a logical 1 or 0, indicating whether +@code{val(i)} is contained in table or not. + +@item l +For numeric lookups +the leftmost subinterval shall be extended to infinity (i.e., all indices +at least 1) + +@item r +For numeric lookups +the rightmost subinterval shall be extended to infinity (i.e., all indices +at most n-1). +@end table +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/ls-oct-text.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/ls-oct-text.cc Tue Jun 21 16:07:51 2016 -0400 @@ -399,17 +399,17 @@ } DEFUN (save_precision, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} save_precision ()\n\ -@deftypefnx {} {@var{old_val} =} save_precision (@var{new_val})\n\ -@deftypefnx {} {} save_precision (@var{new_val}, \"local\")\n\ -Query or set the internal variable that specifies the number of digits to\n\ -keep when saving data in text format.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} save_precision () +@deftypefnx {} {@var{old_val} =} save_precision (@var{new_val}) +@deftypefnx {} {} save_precision (@var{new_val}, "local") +Query or set the internal variable that specifies the number of digits to +keep when saving data in text format. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@end deftypefn */) { return SET_INTERNAL_VARIABLE_WITH_LIMITS (save_precision, -1, std::numeric_limits<int>::max ());
--- a/libinterp/corefcn/lsode.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/lsode.cc Tue Jun 21 16:07:51 2016 -0400 @@ -140,122 +140,122 @@ } DEFUN (lsode, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{x}, @var{istate}, @var{msg}] =} lsode (@var{fcn}, @var{x_0}, @var{t})\n\ -@deftypefnx {} {[@var{x}, @var{istate}, @var{msg}] =} lsode (@var{fcn}, @var{x_0}, @var{t}, @var{t_crit})\n\ -Ordinary Differential Equation (ODE) solver.\n\ -\n\ -The set of differential equations to solve is\n\ -@tex\n\ -$$ {dx \\over dt} = f (x, t) $$\n\ -with\n\ -$$ x(t_0) = x_0 $$\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ -@group\n\ -dx\n\ --- = f (x, t)\n\ -dt\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -with\n\ -\n\ -@example\n\ -x(t_0) = x_0\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -The solution is returned in the matrix @var{x}, with each row\n\ -corresponding to an element of the vector @var{t}. The first element\n\ -of @var{t} should be @math{t_0} and should correspond to the initial\n\ -state of the system @var{x_0}, so that the first row of the output\n\ -is @var{x_0}.\n\ -\n\ -The first argument, @var{fcn}, is a string, inline, or function handle\n\ -that names the function @math{f} to call to compute the vector of right\n\ -hand sides for the set of equations. The function must have the form\n\ -\n\ -@example\n\ -@var{xdot} = f (@var{x}, @var{t})\n\ -@end example\n\ -\n\ -@noindent\n\ -in which @var{xdot} and @var{x} are vectors and @var{t} is a scalar.\n\ -\n\ -If @var{fcn} is a two-element string array or a two-element cell array\n\ -of strings, inline functions, or function handles, the first element names\n\ -the function @math{f} described above, and the second element names a\n\ -function to compute the Jacobian of @math{f}. The Jacobian function\n\ -must have the form\n\ -\n\ -@example\n\ -@var{jac} = j (@var{x}, @var{t})\n\ -@end example\n\ -\n\ -@noindent\n\ -in which @var{jac} is the matrix of partial derivatives\n\ -@tex\n\ -$$ J = {\\partial f_i \\over \\partial x_j} = \\left[\\matrix{\n\ -{\\partial f_1 \\over \\partial x_1}\n\ - & {\\partial f_1 \\over \\partial x_2}\n\ - & \\cdots\n\ - & {\\partial f_1 \\over \\partial x_N} \\cr\n\ -{\\partial f_2 \\over \\partial x_1}\n\ - & {\\partial f_2 \\over \\partial x_2}\n\ - & \\cdots\n\ - & {\\partial f_2 \\over \\partial x_N} \\cr\n\ - \\vdots & \\vdots & \\ddots & \\vdots \\cr\n\ -{\\partial f_3 \\over \\partial x_1}\n\ - & {\\partial f_3 \\over \\partial x_2}\n\ - & \\cdots\n\ - & {\\partial f_3 \\over \\partial x_N} \\cr}\\right]$$\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ -@group\n\ - | df_1 df_1 df_1 |\n\ - | ---- ---- ... ---- |\n\ - | dx_1 dx_2 dx_N |\n\ - | |\n\ - | df_2 df_2 df_2 |\n\ - | ---- ---- ... ---- |\n\ - df_i | dx_1 dx_2 dx_N |\n\ -jac = ---- = | |\n\ - dx_j | . . . . |\n\ - | . . . . |\n\ - | . . . . |\n\ - | |\n\ - | df_N df_N df_N |\n\ - | ---- ---- ... ---- |\n\ - | dx_1 dx_2 dx_N |\n\ -@end group\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -\n\ -The second and third arguments specify the initial state of the system,\n\ -@math{x_0}, and the initial value of the independent variable @math{t_0}.\n\ -\n\ -The fourth argument is optional, and may be used to specify a set of\n\ -times that the ODE solver should not integrate past. It is useful for\n\ -avoiding difficulties with singularities and points where there is a\n\ -discontinuity in the derivative.\n\ -\n\ -After a successful computation, the value of @var{istate} will be 2\n\ -(consistent with the Fortran version of @sc{lsode}).\n\ -\n\ -If the computation is not successful, @var{istate} will be something\n\ -other than 2 and @var{msg} will contain additional information.\n\ -\n\ -You can use the function @code{lsode_options} to set optional\n\ -parameters for @code{lsode}.\n\ -@seealso{daspk, dassl, dasrt}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{x}, @var{istate}, @var{msg}] =} lsode (@var{fcn}, @var{x_0}, @var{t}) +@deftypefnx {} {[@var{x}, @var{istate}, @var{msg}] =} lsode (@var{fcn}, @var{x_0}, @var{t}, @var{t_crit}) +Ordinary Differential Equation (ODE) solver. + +The set of differential equations to solve is +@tex +$$ {dx \over dt} = f (x, t) $$ +with +$$ x(t_0) = x_0 $$ +@end tex +@ifnottex + +@example +@group +dx +-- = f (x, t) +dt +@end group +@end example + +@noindent +with + +@example +x(t_0) = x_0 +@end example + +@end ifnottex +The solution is returned in the matrix @var{x}, with each row +corresponding to an element of the vector @var{t}. The first element +of @var{t} should be @math{t_0} and should correspond to the initial +state of the system @var{x_0}, so that the first row of the output +is @var{x_0}. + +The first argument, @var{fcn}, is a string, inline, or function handle +that names the function @math{f} to call to compute the vector of right +hand sides for the set of equations. The function must have the form + +@example +@var{xdot} = f (@var{x}, @var{t}) +@end example + +@noindent +in which @var{xdot} and @var{x} are vectors and @var{t} is a scalar. + +If @var{fcn} is a two-element string array or a two-element cell array +of strings, inline functions, or function handles, the first element names +the function @math{f} described above, and the second element names a +function to compute the Jacobian of @math{f}. The Jacobian function +must have the form + +@example +@var{jac} = j (@var{x}, @var{t}) +@end example + +@noindent +in which @var{jac} is the matrix of partial derivatives +@tex +$$ J = {\partial f_i \over \partial x_j} = \left[\matrix{ +{\partial f_1 \over \partial x_1} + & {\partial f_1 \over \partial x_2} + & \cdots + & {\partial f_1 \over \partial x_N} \cr +{\partial f_2 \over \partial x_1} + & {\partial f_2 \over \partial x_2} + & \cdots + & {\partial f_2 \over \partial x_N} \cr + \vdots & \vdots & \ddots & \vdots \cr +{\partial f_3 \over \partial x_1} + & {\partial f_3 \over \partial x_2} + & \cdots + & {\partial f_3 \over \partial x_N} \cr}\right]$$ +@end tex +@ifnottex + +@example +@group + | df_1 df_1 df_1 | + | ---- ---- ... ---- | + | dx_1 dx_2 dx_N | + | | + | df_2 df_2 df_2 | + | ---- ---- ... ---- | + df_i | dx_1 dx_2 dx_N | +jac = ---- = | | + dx_j | . . . . | + | . . . . | + | . . . . | + | | + | df_N df_N df_N | + | ---- ---- ... ---- | + | dx_1 dx_2 dx_N | +@end group +@end example + +@end ifnottex + +The second and third arguments specify the initial state of the system, +@math{x_0}, and the initial value of the independent variable @math{t_0}. + +The fourth argument is optional, and may be used to specify a set of +times that the ODE solver should not integrate past. It is useful for +avoiding difficulties with singularities and points where there is a +discontinuity in the derivative. + +After a successful computation, the value of @var{istate} will be 2 +(consistent with the Fortran version of @sc{lsode}). + +If the computation is not successful, @var{istate} will be something +other than 2 and @var{msg} will contain additional information. + +You can use the function @code{lsode_options} to set optional +parameters for @code{lsode}. +@seealso{daspk, dassl, dasrt} +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/lu.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/lu.cc Tue Jun 21 16:07:51 2016 -0400 @@ -58,85 +58,85 @@ } DEFUN (lu, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{L}, @var{U}] =} lu (@var{A})\n\ -@deftypefnx {} {[@var{L}, @var{U}, @var{P}] =} lu (@var{A})\n\ -@deftypefnx {} {[@var{L}, @var{U}, @var{P}, @var{Q}] =} lu (@var{S})\n\ -@deftypefnx {} {[@var{L}, @var{U}, @var{P}, @var{Q}, @var{R}] =} lu (@var{S})\n\ -@deftypefnx {} {[@dots{}] =} lu (@var{S}, @var{thres})\n\ -@deftypefnx {} {@var{y} =} lu (@dots{})\n\ -@deftypefnx {} {[@dots{}] =} lu (@dots{}, \"vector\")\n\ -@cindex LU decomposition\n\ -Compute the LU@tie{}decomposition of @var{A}.\n\ -\n\ -If @var{A} is full then subroutines from @sc{lapack} are used, and if\n\ -@var{A} is sparse then @sc{umfpack} is used.\n\ -\n\ -The result is returned in a permuted form, according to the optional return\n\ -value @var{P}. For example, given the matrix @code{a = [1, 2; 3, 4]},\n\ -\n\ -@example\n\ -[l, u, p] = lu (@var{a})\n\ -@end example\n\ -\n\ -@noindent\n\ -returns\n\ -\n\ -@example\n\ -@group\n\ -l =\n\ -\n\ - 1.00000 0.00000\n\ - 0.33333 1.00000\n\ -\n\ -u =\n\ -\n\ - 3.00000 4.00000\n\ - 0.00000 0.66667\n\ -\n\ -p =\n\ -\n\ - 0 1\n\ - 1 0\n\ -@end group\n\ -@end example\n\ -\n\ -The matrix is not required to be square.\n\ -\n\ -When called with two or three output arguments and a sparse input matrix,\n\ -@code{lu} does not attempt to perform sparsity preserving column\n\ -permutations. Called with a fourth output argument, the sparsity\n\ -preserving column transformation @var{Q} is returned, such that\n\ -@code{@var{P} * @var{A} * @var{Q} = @var{L} * @var{U}}.\n\ -\n\ -Called with a fifth output argument and a sparse input matrix,\n\ -@code{lu} attempts to use a scaling factor @var{R} on the input matrix\n\ -such that\n\ -@code{@var{P} * (@var{R} \\ @var{A}) * @var{Q} = @var{L} * @var{U}}.\n\ -This typically leads to a sparser and more stable factorization.\n\ -\n\ -An additional input argument @var{thres}, that defines the pivoting\n\ -threshold can be given. @var{thres} can be a scalar, in which case\n\ -it defines the @sc{umfpack} pivoting tolerance for both symmetric and\n\ -unsymmetric cases. If @var{thres} is a 2-element vector, then the first\n\ -element defines the pivoting tolerance for the unsymmetric @sc{umfpack}\n\ -pivoting strategy and the second for the symmetric strategy. By default,\n\ -the values defined by @code{spparms} are used ([0.1, 0.001]).\n\ -\n\ -Given the string argument @qcode{\"vector\"}, @code{lu} returns the values\n\ -of @var{P} and @var{Q} as vector values, such that for full matrix,\n\ -@code{@var{A}(@var{P},:) = @var{L} * @var{U}}, and @code{@var{R}(@var{P},:)\n\ -* @var{A}(:,@var{Q}) = @var{L} * @var{U}}.\n\ -\n\ -With two output arguments, returns the permuted forms of the upper and\n\ -lower triangular matrices, such that @code{@var{A} = @var{L} * @var{U}}.\n\ -With one output argument @var{y}, then the matrix returned by the\n\ -@sc{lapack} routines is returned. If the input matrix is sparse then the\n\ -matrix @var{L} is embedded into @var{U} to give a return value similar to\n\ -the full case. For both full and sparse matrices, @code{lu} loses the\n\ -permutation information.\n\ -@seealso{luupdate, ilu, chol, hess, qr, qz, schur, svd}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{L}, @var{U}] =} lu (@var{A}) +@deftypefnx {} {[@var{L}, @var{U}, @var{P}] =} lu (@var{A}) +@deftypefnx {} {[@var{L}, @var{U}, @var{P}, @var{Q}] =} lu (@var{S}) +@deftypefnx {} {[@var{L}, @var{U}, @var{P}, @var{Q}, @var{R}] =} lu (@var{S}) +@deftypefnx {} {[@dots{}] =} lu (@var{S}, @var{thres}) +@deftypefnx {} {@var{y} =} lu (@dots{}) +@deftypefnx {} {[@dots{}] =} lu (@dots{}, "vector") +@cindex LU decomposition +Compute the LU@tie{}decomposition of @var{A}. + +If @var{A} is full then subroutines from @sc{lapack} are used, and if +@var{A} is sparse then @sc{umfpack} is used. + +The result is returned in a permuted form, according to the optional return +value @var{P}. For example, given the matrix @code{a = [1, 2; 3, 4]}, + +@example +[l, u, p] = lu (@var{a}) +@end example + +@noindent +returns + +@example +@group +l = + + 1.00000 0.00000 + 0.33333 1.00000 + +u = + + 3.00000 4.00000 + 0.00000 0.66667 + +p = + + 0 1 + 1 0 +@end group +@end example + +The matrix is not required to be square. + +When called with two or three output arguments and a sparse input matrix, +@code{lu} does not attempt to perform sparsity preserving column +permutations. Called with a fourth output argument, the sparsity +preserving column transformation @var{Q} is returned, such that +@code{@var{P} * @var{A} * @var{Q} = @var{L} * @var{U}}. + +Called with a fifth output argument and a sparse input matrix, +@code{lu} attempts to use a scaling factor @var{R} on the input matrix +such that +@code{@var{P} * (@var{R} \ @var{A}) * @var{Q} = @var{L} * @var{U}}. +This typically leads to a sparser and more stable factorization. + +An additional input argument @var{thres}, that defines the pivoting +threshold can be given. @var{thres} can be a scalar, in which case +it defines the @sc{umfpack} pivoting tolerance for both symmetric and +unsymmetric cases. If @var{thres} is a 2-element vector, then the first +element defines the pivoting tolerance for the unsymmetric @sc{umfpack} +pivoting strategy and the second for the symmetric strategy. By default, +the values defined by @code{spparms} are used ([0.1, 0.001]). + +Given the string argument @qcode{"vector"}, @code{lu} returns the values +of @var{P} and @var{Q} as vector values, such that for full matrix, +@code{@var{A}(@var{P},:) = @var{L} * @var{U}}, and @code{@var{R}(@var{P},:) +* @var{A}(:,@var{Q}) = @var{L} * @var{U}}. + +With two output arguments, returns the permuted forms of the upper and +lower triangular matrices, such that @code{@var{A} = @var{L} * @var{U}}. +With one output argument @var{y}, then the matrix returned by the +@sc{lapack} routines is returned. If the input matrix is sparse then the +matrix @var{L} is embedded into @var{U} to give a return value similar to +the full case. For both full and sparse matrices, @code{lu} loses the +permutation information. +@seealso{luupdate, ilu, chol, hess, qr, qz, schur, svd} +@end deftypefn */) { int nargin = args.length (); bool issparse = (nargin > 0 && args(0).is_sparse_type ()); @@ -566,49 +566,49 @@ } DEFUN (luupdate, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{L}, @var{U}] =} luupdate (@var{L}, @var{U}, @var{x}, @var{y})\n\ -@deftypefnx {} {[@var{L}, @var{U}, @var{P}] =} luupdate (@var{L}, @var{U}, @var{P}, @var{x}, @var{y})\n\ -Given an LU@tie{}factorization of a real or complex matrix\n\ -@w{@var{A} = @var{L}*@var{U}}, @var{L}@tie{}lower unit trapezoidal and\n\ -@var{U}@tie{}upper trapezoidal, return the LU@tie{}factorization\n\ -of @w{@var{A} + @var{x}*@var{y}.'}, where @var{x} and @var{y} are\n\ -column vectors (rank-1 update) or matrices with equal number of columns\n\ -(rank-k update).\n\ -\n\ -Optionally, row-pivoted updating can be used by supplying a row permutation\n\ -(pivoting) matrix @var{P}; in that case, an updated permutation matrix is\n\ -returned. Note that if @var{L}, @var{U}, @var{P} is a pivoted\n\ -LU@tie{}factorization as obtained by @code{lu}:\n\ -\n\ -@example\n\ -[@var{L}, @var{U}, @var{P}] = lu (@var{A});\n\ -@end example\n\ -\n\ -@noindent\n\ -then a factorization of @tcode{@var{A}+@var{x}*@var{y}.'} can be obtained\n\ -either as\n\ -\n\ -@example\n\ -[@var{L1}, @var{U1}] = lu (@var{L}, @var{U}, @var{P}*@var{x}, @var{y})\n\ -@end example\n\ -\n\ -@noindent\n\ -or\n\ -\n\ -@example\n\ -[@var{L1}, @var{U1}, @var{P1}] = lu (@var{L}, @var{U}, @var{P}, @var{x}, @var{y})\n\ -@end example\n\ -\n\ -The first form uses the unpivoted algorithm, which is faster, but less\n\ -stable. The second form uses a slower pivoted algorithm, which is more\n\ -stable.\n\ -\n\ -The matrix case is done as a sequence of rank-1 updates; thus, for large\n\ -enough k, it will be both faster and more accurate to recompute the\n\ -factorization from scratch.\n\ -@seealso{lu, cholupdate, qrupdate}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{L}, @var{U}] =} luupdate (@var{L}, @var{U}, @var{x}, @var{y}) +@deftypefnx {} {[@var{L}, @var{U}, @var{P}] =} luupdate (@var{L}, @var{U}, @var{P}, @var{x}, @var{y}) +Given an LU@tie{}factorization of a real or complex matrix +@w{@var{A} = @var{L}*@var{U}}, @var{L}@tie{}lower unit trapezoidal and +@var{U}@tie{}upper trapezoidal, return the LU@tie{}factorization +of @w{@var{A} + @var{x}*@var{y}.'}, where @var{x} and @var{y} are +column vectors (rank-1 update) or matrices with equal number of columns +(rank-k update). + +Optionally, row-pivoted updating can be used by supplying a row permutation +(pivoting) matrix @var{P}; in that case, an updated permutation matrix is +returned. Note that if @var{L}, @var{U}, @var{P} is a pivoted +LU@tie{}factorization as obtained by @code{lu}: + +@example +[@var{L}, @var{U}, @var{P}] = lu (@var{A}); +@end example + +@noindent +then a factorization of @tcode{@var{A}+@var{x}*@var{y}.'} can be obtained +either as + +@example +[@var{L1}, @var{U1}] = lu (@var{L}, @var{U}, @var{P}*@var{x}, @var{y}) +@end example + +@noindent +or + +@example +[@var{L1}, @var{U1}, @var{P1}] = lu (@var{L}, @var{U}, @var{P}, @var{x}, @var{y}) +@end example + +The first form uses the unpivoted algorithm, which is faster, but less +stable. The second form uses a slower pivoted algorithm, which is more +stable. + +The matrix case is done as a sequence of rank-1 updates; thus, for large +enough k, it will be both faster and more accurate to recompute the +factorization from scratch. +@seealso{lu, cholupdate, qrupdate} +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/mappers.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/mappers.cc Tue Jun 21 16:07:51 2016 -0400 @@ -37,28 +37,28 @@ #include "variables.h" DEFUN (abs, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} abs (@var{z})\n\ -Compute the magnitude of @var{z}.\n\ -\n\ -The magnitude is defined as\n\ -@tex\n\ -$|z| = \\sqrt{x^2 + y^2}$.\n\ -@end tex\n\ -@ifnottex\n\ -|@var{z}| = @code{sqrt (x^2 + y^2)}.\n\ -@end ifnottex\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -abs (3 + 4i)\n\ - @result{} 5\n\ -@end group\n\ -@end example\n\ -@seealso{arg}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} abs (@var{z}) +Compute the magnitude of @var{z}. + +The magnitude is defined as +@tex +$|z| = \sqrt{x^2 + y^2}$. +@end tex +@ifnottex +|@var{z}| = @code{sqrt (x^2 + y^2)}. +@end ifnottex + +For example: + +@example +@group +abs (3 + 4i) + @result{} 5 +@end group +@end example +@seealso{arg} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -84,11 +84,11 @@ */ DEFUN (acos, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} acos (@var{x})\n\ -Compute the inverse cosine in radians for each element of @var{x}.\n\ -@seealso{cos, acosd}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} acos (@var{x}) +Compute the inverse cosine in radians for each element of @var{x}. +@seealso{cos, acosd} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -135,11 +135,11 @@ */ DEFUN (acosh, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} acosh (@var{x})\n\ -Compute the inverse hyperbolic cosine for each element of @var{x}.\n\ -@seealso{cosh}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} acosh (@var{x}) +Compute the inverse hyperbolic cosine for each element of @var{x}. +@seealso{cosh} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -180,11 +180,11 @@ */ DEFUN (angle, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} angle (@var{z})\n\ -See @code{arg}.\n\ -@seealso{arg}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} angle (@var{z}) +See @code{arg}. +@seealso{arg} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -193,30 +193,30 @@ } DEFUN (arg, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} arg (@var{z})\n\ -@deftypefnx {} {} angle (@var{z})\n\ -Compute the argument, i.e., angle of @var{z}.\n\ -\n\ -This is defined as,\n\ -@tex\n\ -$\\theta = atan2 (y, x),$\n\ -@end tex\n\ -@ifnottex\n\ -@var{theta} = @code{atan2 (@var{y}, @var{x})},\n\ -@end ifnottex\n\ -in radians.\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -arg (3 + 4i)\n\ - @result{} 0.92730\n\ -@end group\n\ -@end example\n\ -@seealso{abs}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} arg (@var{z}) +@deftypefnx {} {} angle (@var{z}) +Compute the argument, i.e., angle of @var{z}. + +This is defined as, +@tex +$\theta = atan2 (y, x),$ +@end tex +@ifnottex +@var{theta} = @code{atan2 (@var{y}, @var{x})}, +@end ifnottex +in radians. + +For example: + +@example +@group +arg (3 + 4i) + @result{} 0.92730 +@end group +@end example +@seealso{abs} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -248,11 +248,11 @@ */ DEFUN (asin, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} asin (@var{x})\n\ -Compute the inverse sine in radians for each element of @var{x}.\n\ -@seealso{sin, asind}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} asin (@var{x}) +Compute the inverse sine in radians for each element of @var{x}. +@seealso{sin, asind} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -298,11 +298,11 @@ */ DEFUN (asinh, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} asinh (@var{x})\n\ -Compute the inverse hyperbolic sine for each element of @var{x}.\n\ -@seealso{sinh}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} asinh (@var{x}) +Compute the inverse hyperbolic sine for each element of @var{x}. +@seealso{sinh} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -331,11 +331,11 @@ */ DEFUN (atan, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} atan (@var{x})\n\ -Compute the inverse tangent in radians for each element of @var{x}.\n\ -@seealso{tan, atand}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} atan (@var{x}) +Compute the inverse tangent in radians for each element of @var{x}. +@seealso{tan, atand} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -369,11 +369,11 @@ */ DEFUN (atanh, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} atanh (@var{x})\n\ -Compute the inverse hyperbolic tangent for each element of @var{x}.\n\ -@seealso{tanh}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} atanh (@var{x}) +Compute the inverse hyperbolic tangent for each element of @var{x}. +@seealso{tanh} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -403,14 +403,14 @@ */ DEFUN (cbrt, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} cbrt (@var{x})\n\ -Compute the real cube root of each element of @var{x}.\n\ -\n\ -Unlike @code{@var{x}^(1/3)}, the result will be negative if @var{x} is\n\ -negative.\n\ -@seealso{nthroot}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} cbrt (@var{x}) +Compute the real cube root of each element of @var{x}. + +Unlike @code{@var{x}^(1/3)}, the result will be negative if @var{x} is +negative. +@seealso{nthroot} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -433,23 +433,23 @@ */ DEFUN (ceil, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} ceil (@var{x})\n\ -Return the smallest integer not less than @var{x}.\n\ -\n\ -This is equivalent to rounding towards positive infinity.\n\ -\n\ -If @var{x} is complex, return\n\ -@code{ceil (real (@var{x})) + ceil (imag (@var{x})) * I}.\n\ -\n\ -@example\n\ -@group\n\ -ceil ([-2.7, 2.7])\n\ - @result{} -2 3\n\ -@end group\n\ -@end example\n\ -@seealso{floor, round, fix}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} ceil (@var{x}) +Return the smallest integer not less than @var{x}. + +This is equivalent to rounding towards positive infinity. + +If @var{x} is complex, return +@code{ceil (real (@var{x})) + ceil (imag (@var{x})) * I}. + +@example +@group +ceil ([-2.7, 2.7]) + @result{} -2 3 +@end group +@end example +@seealso{floor, round, fix} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -475,19 +475,19 @@ */ DEFUN (conj, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} conj (@var{z})\n\ -Return the complex conjugate of @var{z}.\n\ -\n\ -The complex conjugate is defined as\n\ -@tex\n\ -$\\bar{z} = x - iy$.\n\ -@end tex\n\ -@ifnottex\n\ -@code{conj (@var{z})} = @var{x} - @var{i}@var{y}.\n\ -@end ifnottex\n\ -@seealso{real, imag}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} conj (@var{z}) +Return the complex conjugate of @var{z}. + +The complex conjugate is defined as +@tex +$\bar{z} = x - iy$. +@end tex +@ifnottex +@code{conj (@var{z})} = @var{x} - @var{i}@var{y}. +@end ifnottex +@seealso{real, imag} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -513,11 +513,11 @@ */ DEFUN (cos, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} cos (@var{x})\n\ -Compute the cosine for each element of @var{x} in radians.\n\ -@seealso{acos, cosd, cosh}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} cos (@var{x}) +Compute the cosine for each element of @var{x} in radians. +@seealso{acos, cosd, cosh} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -547,11 +547,11 @@ */ DEFUN (cosh, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} cosh (@var{x})\n\ -Compute the hyperbolic cosine for each element of @var{x}.\n\ -@seealso{acosh, sinh, tanh}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} cosh (@var{x}) +Compute the hyperbolic cosine for each element of @var{x}. +@seealso{acosh, sinh, tanh} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -575,31 +575,31 @@ */ DEFUN (erf, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} erf (@var{z})\n\ -Compute the error function.\n\ -\n\ -The error function is defined as\n\ -@tex\n\ -$$\n\ - {\\rm erf} (z) = {2 \\over \\sqrt{\\pi}}\\int_0^z e^{-t^2} dt\n\ -$$\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ -@group\n\ - z\n\ - 2 /\n\ -erf (z) = --------- * | e^(-t^2) dt\n\ - sqrt (pi) /\n\ - t=0\n\ -@end group\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -@seealso{erfc, erfcx, erfi, dawson, erfinv, erfcinv}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} erf (@var{z}) +Compute the error function. + +The error function is defined as +@tex +$$ + {\rm erf} (z) = {2 \over \sqrt{\pi}}\int_0^z e^{-t^2} dt +$$ +@end tex +@ifnottex + +@example +@group + z + 2 / +erf (z) = --------- * | e^(-t^2) dt + sqrt (pi) / + t=0 +@end group +@end example + +@end ifnottex +@seealso{erfc, erfcx, erfi, dawson, erfinv, erfcinv} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -644,17 +644,17 @@ */ DEFUN (erfinv, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} erfinv (@var{x})\n\ -Compute the inverse error function.\n\ -\n\ -The inverse error function is defined such that\n\ -\n\ -@example\n\ -erf (@var{y}) == @var{x}\n\ -@end example\n\ -@seealso{erf, erfc, erfcx, erfi, dawson, erfcinv}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} erfinv (@var{x}) +Compute the inverse error function. + +The inverse error function is defined such that + +@example +erf (@var{y}) == @var{x} +@end example +@seealso{erf, erfc, erfcx, erfi, dawson, erfcinv} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -681,17 +681,17 @@ */ DEFUN (erfcinv, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} erfcinv (@var{x})\n\ -Compute the inverse complementary error function.\n\ -\n\ -The inverse complementary error function is defined such that\n\ -\n\ -@example\n\ -erfc (@var{y}) == @var{x}\n\ -@end example\n\ -@seealso{erfc, erf, erfcx, erfi, dawson, erfinv}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} erfcinv (@var{x}) +Compute the inverse complementary error function. + +The inverse complementary error function is defined such that + +@example +erfc (@var{y}) == @var{x} +@end example +@seealso{erfc, erf, erfcx, erfi, dawson, erfinv} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -718,19 +718,19 @@ */ DEFUN (erfc, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} erfc (@var{z})\n\ -Compute the complementary error function.\n\ -\n\ -The complementary error function is defined as\n\ -@tex\n\ -$1 - {\\rm erf} (z)$.\n\ -@end tex\n\ -@ifnottex\n\ -@w{@code{1 - erf (@var{z})}}.\n\ -@end ifnottex\n\ -@seealso{erfcinv, erfcx, erfi, dawson, erf, erfinv}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} erfc (@var{z}) +Compute the complementary error function. + +The complementary error function is defined as +@tex +$1 - {\rm erf} (z)$. +@end tex +@ifnottex +@w{@code{1 - erf (@var{z})}}. +@end ifnottex +@seealso{erfcinv, erfcx, erfi, dawson, erf, erfinv} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -748,25 +748,25 @@ */ DEFUN (erfcx, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} erfcx (@var{z})\n\ -Compute the scaled complementary error function.\n\ -\n\ -The scaled complementary error function is defined as\n\ -@tex\n\ -$$\n\ - e^{z^2} {\\rm erfc} (z) \\equiv e^{z^2} (1 - {\\rm erf} (z))\n\ -$$\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ -exp (z^2) * erfc (z)\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -@seealso{erfc, erf, erfi, dawson, erfinv, erfcinv}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} erfcx (@var{z}) +Compute the scaled complementary error function. + +The scaled complementary error function is defined as +@tex +$$ + e^{z^2} {\rm erfc} (z) \equiv e^{z^2} (1 - {\rm erf} (z)) +$$ +@end tex +@ifnottex + +@example +exp (z^2) * erfc (z) +@end example + +@end ifnottex +@seealso{erfc, erf, erfi, dawson, erfinv, erfcinv} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -790,25 +790,25 @@ */ DEFUN (erfi, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} erfi (@var{z})\n\ -Compute the imaginary error function.\n\ -\n\ -The imaginary error function is defined as\n\ -@tex\n\ -$$\n\ - -i {\\rm erf} (iz)\n\ -$$\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ --i * erf (i*z)\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -@seealso{erfc, erf, erfcx, dawson, erfinv, erfcinv}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} erfi (@var{z}) +Compute the imaginary error function. + +The imaginary error function is defined as +@tex +$$ + -i {\rm erf} (iz) +$$ +@end tex +@ifnottex + +@example +-i * erf (i*z) +@end example + +@end ifnottex +@seealso{erfc, erf, erfcx, dawson, erfinv, erfcinv} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -827,25 +827,25 @@ */ DEFUN (dawson, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} dawson (@var{z})\n\ -Compute the Dawson (scaled imaginary error) function.\n\ -\n\ -The Dawson function is defined as\n\ -@tex\n\ -$$\n\ - {\\sqrt{\\pi} \\over 2} e^{-z^2} {\\rm erfi} (z) \\equiv -i {\\sqrt{\\pi} \\over 2} e^{-z^2} {\\rm erf} (iz)\n\ -$$\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ -(sqrt (pi) / 2) * exp (-z^2) * erfi (z)\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -@seealso{erfc, erf, erfcx, erfi, erfinv, erfcinv}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} dawson (@var{z}) +Compute the Dawson (scaled imaginary error) function. + +The Dawson function is defined as +@tex +$$ + {\sqrt{\pi} \over 2} e^{-z^2} {\rm erfi} (z) \equiv -i {\sqrt{\pi} \over 2} e^{-z^2} {\rm erf} (iz) +$$ +@end tex +@ifnottex + +@example +(sqrt (pi) / 2) * exp (-z^2) * erfi (z) +@end example + +@end ifnottex +@seealso{erfc, erf, erfcx, erfi, erfinv, erfcinv} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -866,20 +866,20 @@ */ DEFUN (exp, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} exp (@var{x})\n\ -Compute\n\ -@tex\n\ -$e^{x}$\n\ -@end tex\n\ -@ifnottex\n\ -@code{e^x}\n\ -@end ifnottex\n\ -for each element of @var{x}.\n\ -\n\ -To compute the matrix exponential, see @ref{Linear Algebra}.\n\ -@seealso{log}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} exp (@var{x}) +Compute +@tex +$e^{x}$ +@end tex +@ifnottex +@code{e^x} +@end ifnottex +for each element of @var{x}. + +To compute the matrix exponential, see @ref{Linear Algebra}. +@seealso{log} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -901,18 +901,18 @@ */ DEFUN (expm1, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} expm1 (@var{x})\n\ -Compute\n\ -@tex\n\ -$ e^{x} - 1 $\n\ -@end tex\n\ -@ifnottex\n\ -@code{exp (@var{x}) - 1}\n\ -@end ifnottex\n\ -accurately in the neighborhood of zero.\n\ -@seealso{exp}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} expm1 (@var{x}) +Compute +@tex +$ e^{x} - 1 $ +@end tex +@ifnottex +@code{exp (@var{x}) - 1} +@end ifnottex +accurately in the neighborhood of zero. +@seealso{exp} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -931,21 +931,21 @@ */ DEFUN (isfinite, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isfinite (@var{x})\n\ -Return a logical array which is true where the elements of @var{x} are\n\ -finite values and false where they are not.\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -isfinite ([13, Inf, NA, NaN])\n\ - @result{} [ 1, 0, 0, 0 ]\n\ -@end group\n\ -@end example\n\ -@seealso{isinf, isnan, isna}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isfinite (@var{x}) +Return a logical array which is true where the elements of @var{x} are +finite values and false where they are not. + +For example: + +@example +@group +isfinite ([13, Inf, NA, NaN]) + @result{} [ 1, 0, 0, 0 ] +@end group +@end example +@seealso{isinf, isnan, isna} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -967,21 +967,21 @@ */ DEFUN (fix, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} fix (@var{x})\n\ -Truncate fractional portion of @var{x} and return the integer portion.\n\ -\n\ -This is equivalent to rounding towards zero. If @var{x} is complex, return\n\ -@code{fix (real (@var{x})) + fix (imag (@var{x})) * I}.\n\ -\n\ -@example\n\ -@group\n\ -fix ([-2.7, 2.7])\n\ - @result{} -2 2\n\ -@end group\n\ -@end example\n\ -@seealso{ceil, floor, round}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} fix (@var{x}) +Truncate fractional portion of @var{x} and return the integer portion. + +This is equivalent to rounding towards zero. If @var{x} is complex, return +@code{fix (real (@var{x})) + fix (imag (@var{x})) * I}. + +@example +@group +fix ([-2.7, 2.7]) + @result{} -2 2 +@end group +@end example +@seealso{ceil, floor, round} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1000,21 +1000,21 @@ */ DEFUN (floor, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} floor (@var{x})\n\ -Return the largest integer not greater than @var{x}.\n\ -\n\ -This is equivalent to rounding towards negative infinity. If @var{x} is\n\ -complex, return @code{floor (real (@var{x})) + floor (imag (@var{x})) * I}.\n\ -\n\ -@example\n\ -@group\n\ -floor ([-2.7, 2.7])\n\ - @result{} -3 2\n\ -@end group\n\ -@end example\n\ -@seealso{ceil, round, fix}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} floor (@var{x}) +Return the largest integer not greater than @var{x}. + +This is equivalent to rounding towards negative infinity. If @var{x} is +complex, return @code{floor (real (@var{x})) + floor (imag (@var{x})) * I}. + +@example +@group +floor ([-2.7, 2.7]) + @result{} -3 2 +@end group +@end example +@seealso{ceil, round, fix} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1033,37 +1033,37 @@ */ DEFUN (gamma, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} gamma (@var{z})\n\ -Compute the Gamma function.\n\ -\n\ -The Gamma function is defined as\n\ -@tex\n\ -$$\n\ - \\Gamma (z) = \\int_0^\\infty t^{z-1} e^{-t} dt.\n\ -$$\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ -@group\n\ - infinity\n\ - /\n\ -gamma (z) = | t^(z-1) exp (-t) dt.\n\ - /\n\ - t=0\n\ -@end group\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -\n\ -Programming Note: The gamma function can grow quite large even for small\n\ -input values. In many cases it may be preferable to use the natural\n\ -logarithm of the gamma function (@code{gammaln}) in calculations to minimize\n\ -loss of precision. The final result is then\n\ -@code{exp (@var{result_using_gammaln}).}\n\ -@seealso{gammainc, gammaln, factorial}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} gamma (@var{z}) +Compute the Gamma function. + +The Gamma function is defined as +@tex +$$ + \Gamma (z) = \int_0^\infty t^{z-1} e^{-t} dt. +$$ +@end tex +@ifnottex + +@example +@group + infinity + / +gamma (z) = | t^(z-1) exp (-t) dt. + / + t=0 +@end group +@end example + +@end ifnottex + +Programming Note: The gamma function can grow quite large even for small +input values. In many cases it may be preferable to use the natural +logarithm of the gamma function (@code{gammaln}) in calculations to minimize +loss of precision. The final result is then +@code{exp (@var{result_using_gammaln}).} +@seealso{gammainc, gammaln, factorial} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1102,11 +1102,11 @@ */ DEFUN (imag, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} imag (@var{z})\n\ -Return the imaginary part of @var{z} as a real number.\n\ -@seealso{real, conj}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} imag (@var{z}) +Return the imaginary part of @var{z} as a real number. +@seealso{real, conj} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1130,14 +1130,14 @@ */ DEFUNX ("isalnum", Fisalnum, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isalnum (@var{s})\n\ -Return a logical array which is true where the elements of @var{s} are\n\ -letters or digits and false where they are not.\n\ -\n\ -This is equivalent to (@code{isalpha (@var{s}) | isdigit (@var{s})}).\n\ -@seealso{isalpha, isdigit, ispunct, isspace, iscntrl}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isalnum (@var{s}) +Return a logical array which is true where the elements of @var{s} are +letters or digits and false where they are not. + +This is equivalent to (@code{isalpha (@var{s}) | isdigit (@var{s})}). +@seealso{isalpha, isdigit, ispunct, isspace, iscntrl} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1159,14 +1159,14 @@ */ DEFUNX ("isalpha", Fisalpha, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isalpha (@var{s})\n\ -Return a logical array which is true where the elements of @var{s} are\n\ -letters and false where they are not.\n\ -\n\ -This is equivalent to (@code{islower (@var{s}) | isupper (@var{s})}).\n\ -@seealso{isdigit, ispunct, isspace, iscntrl, isalnum, islower, isupper}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isalpha (@var{s}) +Return a logical array which is true where the elements of @var{s} are +letters and false where they are not. + +This is equivalent to (@code{islower (@var{s}) | isupper (@var{s})}). +@seealso{isdigit, ispunct, isspace, iscntrl, isalnum, islower, isupper} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1187,12 +1187,12 @@ */ DEFUNX ("isascii", Fisascii, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isascii (@var{s})\n\ -Return a logical array which is true where the elements of @var{s} are\n\ -ASCII characters (in the range 0 to 127 decimal) and false where they are\n\ -not.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isascii (@var{s}) +Return a logical array which is true where the elements of @var{s} are +ASCII characters (in the range 0 to 127 decimal) and false where they are +not. +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1211,12 +1211,12 @@ */ DEFUNX ("iscntrl", Fiscntrl, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} iscntrl (@var{s})\n\ -Return a logical array which is true where the elements of @var{s} are\n\ -control characters and false where they are not.\n\ -@seealso{ispunct, isspace, isalpha, isdigit}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} iscntrl (@var{s}) +Return a logical array which is true where the elements of @var{s} are +control characters and false where they are not. +@seealso{ispunct, isspace, isalpha, isdigit} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1237,12 +1237,12 @@ */ DEFUNX ("isdigit", Fisdigit, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isdigit (@var{s})\n\ -Return a logical array which is true where the elements of @var{s} are\n\ -decimal digits (0-9) and false where they are not.\n\ -@seealso{isxdigit, isalpha, isletter, ispunct, isspace, iscntrl}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isdigit (@var{s}) +Return a logical array which is true where the elements of @var{s} are +decimal digits (0-9) and false where they are not. +@seealso{isxdigit, isalpha, isletter, ispunct, isspace, iscntrl} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1262,21 +1262,21 @@ */ DEFUN (isinf, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isinf (@var{x})\n\ -Return a logical array which is true where the elements of @var{x} are\n\ -infinite and false where they are not.\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -isinf ([13, Inf, NA, NaN])\n\ - @result{} [ 0, 1, 0, 0 ]\n\ -@end group\n\ -@end example\n\ -@seealso{isfinite, isnan, isna}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isinf (@var{x}) +Return a logical array which is true where the elements of @var{x} are +infinite and false where they are not. + +For example: + +@example +@group +isinf ([13, Inf, NA, NaN]) + @result{} [ 0, 1, 0, 0 ] +@end group +@end example +@seealso{isfinite, isnan, isna} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1302,13 +1302,13 @@ */ DEFUNX ("isgraph", Fisgraph, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isgraph (@var{s})\n\ -Return a logical array which is true where the elements of @var{s} are\n\ -printable characters (but not the space character) and false where they are\n\ -not.\n\ -@seealso{isprint}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isgraph (@var{s}) +Return a logical array which is true where the elements of @var{s} are +printable characters (but not the space character) and false where they are +not. +@seealso{isprint} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1328,12 +1328,12 @@ */ DEFUNX ("islower", Fislower, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} islower (@var{s})\n\ -Return a logical array which is true where the elements of @var{s} are\n\ -lowercase letters and false where they are not.\n\ -@seealso{isupper, isalpha, isletter, isalnum}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} islower (@var{s}) +Return a logical array which is true where the elements of @var{s} are +lowercase letters and false where they are not. +@seealso{isupper, isalpha, isletter, isalnum} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1353,21 +1353,21 @@ */ DEFUN (isna, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isna (@var{x})\n\ -Return a logical array which is true where the elements of @var{x} are\n\ -NA (missing) values and false where they are not.\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -isna ([13, Inf, NA, NaN])\n\ - @result{} [ 0, 0, 1, 0 ]\n\ -@end group\n\ -@end example\n\ -@seealso{isnan, isinf, isfinite}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isna (@var{x}) +Return a logical array which is true where the elements of @var{x} are +NA (missing) values and false where they are not. + +For example: + +@example +@group +isna ([13, Inf, NA, NaN]) + @result{} [ 0, 0, 1, 0 ] +@end group +@end example +@seealso{isnan, isinf, isfinite} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1393,21 +1393,21 @@ */ DEFUN (isnan, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isnan (@var{x})\n\ -Return a logical array which is true where the elements of @var{x} are\n\ -NaN values and false where they are not.\n\ -\n\ -NA values are also considered NaN values. For example:\n\ -\n\ -@example\n\ -@group\n\ -isnan ([13, Inf, NA, NaN])\n\ - @result{} [ 0, 0, 1, 1 ]\n\ -@end group\n\ -@end example\n\ -@seealso{isna, isinf, isfinite}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isnan (@var{x}) +Return a logical array which is true where the elements of @var{x} are +NaN values and false where they are not. + +NA values are also considered NaN values. For example: + +@example +@group +isnan ([13, Inf, NA, NaN]) + @result{} [ 0, 0, 1, 1 ] +@end group +@end example +@seealso{isna, isinf, isfinite} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1433,13 +1433,13 @@ */ DEFUNX ("isprint", Fisprint, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isprint (@var{s})\n\ -Return a logical array which is true where the elements of @var{s} are\n\ -printable characters (including the space character) and false where they\n\ -are not.\n\ -@seealso{isgraph}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isprint (@var{s}) +Return a logical array which is true where the elements of @var{s} are +printable characters (including the space character) and false where they +are not. +@seealso{isgraph} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1459,12 +1459,12 @@ */ DEFUNX ("ispunct", Fispunct, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} ispunct (@var{s})\n\ -Return a logical array which is true where the elements of @var{s} are\n\ -punctuation characters and false where they are not.\n\ -@seealso{isalpha, isdigit, isspace, iscntrl}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} ispunct (@var{s}) +Return a logical array which is true where the elements of @var{s} are +punctuation characters and false where they are not. +@seealso{isalpha, isdigit, isspace, iscntrl} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1487,13 +1487,13 @@ */ DEFUNX ("isspace", Fisspace, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isspace (@var{s})\n\ -Return a logical array which is true where the elements of @var{s} are\n\ -whitespace characters (space, formfeed, newline, carriage return, tab, and\n\ -vertical tab) and false where they are not.\n\ -@seealso{iscntrl, ispunct, isalpha, isdigit}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isspace (@var{s}) +Return a logical array which is true where the elements of @var{s} are +whitespace characters (space, formfeed, newline, carriage return, tab, and +vertical tab) and false where they are not. +@seealso{iscntrl, ispunct, isalpha, isdigit} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1513,12 +1513,12 @@ */ DEFUNX ("isupper", Fisupper, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isupper (@var{s})\n\ -Return a logical array which is true where the elements of @var{s} are\n\ -uppercase letters and false where they are not.\n\ -@seealso{islower, isalpha, isletter, isalnum}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isupper (@var{s}) +Return a logical array which is true where the elements of @var{s} are +uppercase letters and false where they are not. +@seealso{islower, isalpha, isletter, isalnum} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1538,12 +1538,12 @@ */ DEFUNX ("isxdigit", Fisxdigit, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isxdigit (@var{s})\n\ -Return a logical array which is true where the elements of @var{s} are\n\ -hexadecimal digits (0-9 and @nospell{a-fA-F}).\n\ -@seealso{isdigit}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isxdigit (@var{s}) +Return a logical array which is true where the elements of @var{s} are +hexadecimal digits (0-9 and @nospell{a-fA-F}). +@seealso{isdigit} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1565,12 +1565,12 @@ */ DEFUN (lgamma, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} gammaln (@var{x})\n\ -@deftypefnx {} {} lgamma (@var{x})\n\ -Return the natural logarithm of the gamma function of @var{x}.\n\ -@seealso{gamma, gammainc}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} gammaln (@var{x}) +@deftypefnx {} {} lgamma (@var{x}) +Return the natural logarithm of the gamma function of @var{x}. +@seealso{gamma, gammainc} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1608,20 +1608,20 @@ */ DEFUN (log, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} log (@var{x})\n\ -Compute the natural logarithm,\n\ -@tex\n\ -$\\ln{(x)},$\n\ -@end tex\n\ -@ifnottex\n\ -@code{ln (@var{x})},\n\ -@end ifnottex\n\ -for each element of @var{x}.\n\ -\n\ -To compute the matrix logarithm, see @ref{Linear Algebra}.\n\ -@seealso{exp, log1p, log2, log10, logspace}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} log (@var{x}) +Compute the natural logarithm, +@tex +$\ln{(x)},$ +@end tex +@ifnottex +@code{ln (@var{x})}, +@end ifnottex +for each element of @var{x}. + +To compute the matrix logarithm, see @ref{Linear Algebra}. +@seealso{exp, log1p, log2, log10, logspace} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1641,11 +1641,11 @@ */ DEFUN (log10, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} log10 (@var{x})\n\ -Compute the base-10 logarithm of each element of @var{x}.\n\ -@seealso{log, log2, logspace, exp}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} log10 (@var{x}) +Compute the base-10 logarithm of each element of @var{x}. +@seealso{log, log2, logspace, exp} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1662,18 +1662,18 @@ */ DEFUN (log1p, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} log1p (@var{x})\n\ -Compute\n\ -@tex\n\ -$\\ln{(1 + x)}$\n\ -@end tex\n\ -@ifnottex\n\ -@code{log (1 + @var{x})}\n\ -@end ifnottex\n\ -accurately in the neighborhood of zero.\n\ -@seealso{log, exp, expm1}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} log1p (@var{x}) +Compute +@tex +$\ln{(1 + x)}$ +@end tex +@ifnottex +@code{log (1 + @var{x})} +@end ifnottex +accurately in the neighborhood of zero. +@seealso{log, exp, expm1} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1690,11 +1690,11 @@ */ DEFUN (real, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} real (@var{z})\n\ -Return the real part of @var{z}.\n\ -@seealso{imag, conj}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} real (@var{z}) +Return the real part of @var{z}. +@seealso{imag, conj} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1711,29 +1711,29 @@ %!assert (real (single (1)), single (1)) %!assert (real (single (i)), single (0)) %!assert (real (single (1+i)), single (1)) -%!assert (real (single ([1, i; i, 1])), full (eye (2,"single"))) +%!assert (real (single ([1, i; i, 1])), full (eye (2, "single"))) %!error real () %!error real (1, 2) */ DEFUN (round, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} round (@var{x})\n\ -Return the integer nearest to @var{x}.\n\ -\n\ -If @var{x} is complex, return\n\ -@code{round (real (@var{x})) + round (imag (@var{x})) * I}. If there\n\ -are two nearest integers, return the one further away from zero.\n\ -\n\ -@example\n\ -@group\n\ -round ([-2.7, 2.7])\n\ - @result{} -3 3\n\ -@end group\n\ -@end example\n\ -@seealso{ceil, floor, fix, roundb}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} round (@var{x}) +Return the integer nearest to @var{x}. + +If @var{x} is complex, return +@code{round (real (@var{x})) + round (imag (@var{x})) * I}. If there +are two nearest integers, return the one further away from zero. + +@example +@group +round ([-2.7, 2.7]) + @result{} -3 3 +@end group +@end example +@seealso{ceil, floor, fix, roundb} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1763,15 +1763,15 @@ */ DEFUN (roundb, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} roundb (@var{x})\n\ -Return the integer nearest to @var{x}. If there are two nearest\n\ -integers, return the even one (banker's rounding).\n\ -\n\ -If @var{x} is complex,\n\ -return @code{roundb (real (@var{x})) + roundb (imag (@var{x})) * I}.\n\ -@seealso{round}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} roundb (@var{x}) +Return the integer nearest to @var{x}. If there are two nearest +integers, return the even one (banker's rounding). + +If @var{x} is complex, +return @code{roundb (real (@var{x})) + roundb (imag (@var{x})) * I}. +@seealso{round} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1803,35 +1803,35 @@ */ DEFUN (sign, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} sign (@var{x})\n\ -Compute the @dfn{signum} function.\n\ -\n\ -This is defined as\n\ -@tex\n\ -$$\n\ -{\\rm sign} (@var{x}) = \\cases{1,&$x>0$;\\cr 0,&$x=0$;\\cr -1,&$x<0$.\\cr}\n\ -$$\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ -@group\n\ - -1, x < 0;\n\ -sign (x) = 0, x = 0;\n\ - 1, x > 0.\n\ -@end group\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -\n\ -For complex arguments, @code{sign} returns @code{x ./ abs (@var{x})}.\n\ -\n\ -Note that @code{sign (-0.0)} is 0. Although IEEE 754 floating point\n\ -allows zero to be signed, 0.0 and -0.0 compare equal. If you must test\n\ -whether zero is signed, use the @code{signbit} function.\n\ -@seealso{signbit}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} sign (@var{x}) +Compute the @dfn{signum} function. + +This is defined as +@tex +$$ +{\rm sign} (@var{x}) = \cases{1,&$x>0$;\cr 0,&$x=0$;\cr -1,&$x<0$.\cr} +$$ +@end tex +@ifnottex + +@example +@group + -1, x < 0; +sign (x) = 0, x = 0; + 1, x > 0. +@end group +@end example + +@end ifnottex + +For complex arguments, @code{sign} returns @code{x ./ abs (@var{x})}. + +Note that @code{sign (-0.0)} is 0. Although IEEE 754 floating point +allows zero to be signed, 0.0 and -0.0 compare equal. If you must test +whether zero is signed, use the @code{signbit} function. +@seealso{signbit} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1855,20 +1855,20 @@ */ DEFUNX ("signbit", Fsignbit, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} signbit (@var{x})\n\ -Return logical true if the value of @var{x} has its sign bit set and false\n\ -otherwise.\n\ -\n\ -This behavior is consistent with the other logical functions.\n\ -See @ref{Logical Values}. The behavior differs from the C language function\n\ -which returns nonzero if the sign bit is set.\n\ -\n\ -This is not the same as @code{x < 0.0}, because IEEE 754 floating point\n\ -allows zero to be signed. The comparison @code{-0.0 < 0.0} is false,\n\ -but @code{signbit (-0.0)} will return a nonzero value.\n\ -@seealso{sign}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} signbit (@var{x}) +Return logical true if the value of @var{x} has its sign bit set and false +otherwise. + +This behavior is consistent with the other logical functions. +See @ref{Logical Values}. The behavior differs from the C language function +which returns nonzero if the sign bit is set. + +This is not the same as @code{x < 0.0}, because IEEE 754 floating point +allows zero to be signed. The comparison @code{-0.0 < 0.0} is false, +but @code{signbit (-0.0)} will return a nonzero value. +@seealso{sign} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1894,11 +1894,11 @@ */ DEFUN (sin, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} sin (@var{x})\n\ -Compute the sine for each element of @var{x} in radians.\n\ -@seealso{asin, sind, sinh}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} sin (@var{x}) +Compute the sine for each element of @var{x} in radians. +@seealso{asin, sind, sinh} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1926,11 +1926,11 @@ */ DEFUN (sinh, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} sinh (@var{x})\n\ -Compute the hyperbolic sine for each element of @var{x}.\n\ -@seealso{asinh, cosh, tanh}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} sinh (@var{x}) +Compute the hyperbolic sine for each element of @var{x}. +@seealso{asinh, cosh, tanh} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1954,15 +1954,15 @@ */ DEFUN (sqrt, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} sqrt (@var{x})\n\ -Compute the square root of each element of @var{x}.\n\ -\n\ -If @var{x} is negative, a complex result is returned.\n\ -\n\ -To compute the matrix square root, see @ref{Linear Algebra}.\n\ -@seealso{realsqrt, nthroot}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} sqrt (@var{x}) +Compute the square root of each element of @var{x}. + +If @var{x} is negative, a complex result is returned. + +To compute the matrix square root, see @ref{Linear Algebra}. +@seealso{realsqrt, nthroot} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1986,11 +1986,11 @@ */ DEFUN (tan, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} tan (@var{z})\n\ -Compute the tangent for each element of @var{x} in radians.\n\ -@seealso{atan, tand, tanh}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} tan (@var{z}) +Compute the tangent for each element of @var{x} in radians. +@seealso{atan, tand, tanh} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -2018,11 +2018,11 @@ */ DEFUN (tanh, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} tanh (@var{x})\n\ -Compute hyperbolic tangent for each element of @var{x}.\n\ -@seealso{atanh, sinh, cosh}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} tanh (@var{x}) +Compute hyperbolic tangent for each element of @var{x}. +@seealso{atanh, sinh, cosh} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -2046,21 +2046,21 @@ */ DEFUNX ("toascii", Ftoascii, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} toascii (@var{s})\n\ -Return ASCII representation of @var{s} in a matrix.\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -toascii (\"ASCII\")\n\ - @result{} [ 65, 83, 67, 73, 73 ]\n\ -@end group\n\ -\n\ -@end example\n\ -@seealso{char}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} toascii (@var{s}) +Return ASCII representation of @var{s} in a matrix. + +For example: + +@example +@group +toascii ("ASCII") + @result{} [ 65, 83, 67, 73, 73 ] +@end group + +@end example +@seealso{char} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -2081,23 +2081,23 @@ */ DEFUNX ("tolower", Ftolower, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} tolower (@var{s})\n\ -@deftypefnx {} {} lower (@var{s})\n\ -Return a copy of the string or cell string @var{s}, with each uppercase\n\ -character replaced by the corresponding lowercase one; non-alphabetic\n\ -characters are left unchanged.\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -tolower (\"MiXeD cAsE 123\")\n\ - @result{} \"mixed case 123\"\n\ -@end group\n\ -@end example\n\ -@seealso{toupper}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} tolower (@var{s}) +@deftypefnx {} {} lower (@var{s}) +Return a copy of the string or cell string @var{s}, with each uppercase +character replaced by the corresponding lowercase one; non-alphabetic +characters are left unchanged. + +For example: + +@example +@group +tolower ("MiXeD cAsE 123") + @result{} "mixed case 123" +@end group +@end example +@seealso{toupper} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -2140,23 +2140,23 @@ */ DEFUNX ("toupper", Ftoupper, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} toupper (@var{s})\n\ -@deftypefnx {} {} upper (@var{s})\n\ -Return a copy of the string or cell string @var{s}, with each lowercase\n\ -character replaced by the corresponding uppercase one; non-alphabetic\n\ -characters are left unchanged.\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -toupper (\"MiXeD cAsE 123\")\n\ - @result{} \"MIXED CASE 123\"\n\ -@end group\n\ -@end example\n\ -@seealso{tolower}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} toupper (@var{s}) +@deftypefnx {} {} upper (@var{s}) +Return a copy of the string or cell string @var{s}, with each lowercase +character replaced by the corresponding uppercase one; non-alphabetic +characters are left unchanged. + +For example: + +@example +@group +toupper ("MiXeD cAsE 123") + @result{} "MIXED CASE 123" +@end group +@end example +@seealso{tolower} +@end deftypefn */) { if (args.length () != 1) print_usage ();
--- a/libinterp/corefcn/matrix_type.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/matrix_type.cc Tue Jun 21 16:07:51 2016 -0400 @@ -37,87 +37,87 @@ #include "oct-locbuf.h" DEFUN (matrix_type, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{type} =} matrix_type (@var{A})\n\ -@deftypefnx {} {@var{type} =} matrix_type (@var{A}, \"nocompute\")\n\ -@deftypefnx {} {@var{A} =} matrix_type (@var{A}, @var{type})\n\ -@deftypefnx {} {@var{A} =} matrix_type (@var{A}, \"upper\", @var{perm})\n\ -@deftypefnx {} {@var{A} =} matrix_type (@var{A}, \"lower\", @var{perm})\n\ -@deftypefnx {} {@var{A} =} matrix_type (@var{A}, \"banded\", @var{nl}, @var{nu})\n\ -Identify the matrix type or mark a matrix as a particular type.\n\ -\n\ -This allows more rapid solutions of linear equations involving @var{A} to be\n\ -performed.\n\ -\n\ -Called with a single argument, @code{matrix_type} returns the type of the\n\ -matrix and caches it for future use.\n\ -\n\ -Called with more than one argument, @code{matrix_type} allows the type of\n\ -the matrix to be defined.\n\ -\n\ -If the option @qcode{\"nocompute\"} is given, the function will not attempt\n\ -to guess the type if it is still unknown. This is useful for debugging\n\ -purposes.\n\ -\n\ -The possible matrix types depend on whether the matrix is full or sparse,\n\ -and can be one of the following\n\ -\n\ -@table @asis\n\ -@item @qcode{\"unknown\"}\n\ -Remove any previously cached matrix type, and mark type as unknown.\n\ -\n\ -@item @qcode{\"full\"}\n\ -Mark the matrix as full.\n\ -\n\ -@item @qcode{\"positive definite\"}\n\ -Probable full positive definite matrix.\n\ -\n\ -@item @qcode{\"diagonal\"}\n\ -Diagonal matrix. (Sparse matrices only)\n\ -\n\ -@item @qcode{\"permuted diagonal\"}\n\ -Permuted Diagonal matrix. The permutation does not need to be specifically\n\ -indicated, as the structure of the matrix explicitly gives this. (Sparse\n\ -matrices only)\n\ -\n\ -@item @qcode{\"upper\"}\n\ -Upper triangular. If the optional third argument @var{perm} is given, the\n\ -matrix is assumed to be a permuted upper triangular with the permutations\n\ -defined by the vector @var{perm}.\n\ -\n\ -@item @qcode{\"lower\"}\n\ -Lower triangular. If the optional third argument @var{perm} is given, the\n\ -matrix is assumed to be a permuted lower triangular with the permutations\n\ -defined by the vector @var{perm}.\n\ -\n\ -@item @qcode{\"banded\"}\n\ -@itemx @qcode{\"banded positive definite\"}\n\ -Banded matrix with the band size of @var{nl} below the diagonal and @var{nu}\n\ -above it. If @var{nl} and @var{nu} are 1, then the matrix is tridiagonal\n\ -and treated with specialized code. In addition the matrix can be marked as\n\ -probably a positive definite. (Sparse matrices only)\n\ -\n\ -@item @qcode{\"singular\"}\n\ -The matrix is assumed to be singular and will be treated with a minimum norm\n\ -solution.\n\ -\n\ -@end table\n\ -\n\ -Note that the matrix type will be discovered automatically on the first\n\ -attempt to solve a linear equation involving @var{A}. Therefore\n\ -@code{matrix_type} is only useful to give Octave hints of the matrix type.\n\ -Incorrectly defining the matrix type will result in incorrect results from\n\ -solutions of linear equations; it is entirely @strong{the responsibility of\n\ -the user} to correctly identify the matrix type.\n\ -\n\ -Also, the test for positive definiteness is a low-cost test for a Hermitian\n\ -matrix with a real positive diagonal. This does not guarantee that the\n\ -matrix is positive definite, but only that it is a probable candidate. When\n\ -such a matrix is factorized, a Cholesky@tie{}factorization is first\n\ -attempted, and if that fails the matrix is then treated with an\n\ -LU@tie{}factorization. Once the matrix has been factorized,\n\ -@code{matrix_type} will return the correct classification of the matrix.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{type} =} matrix_type (@var{A}) +@deftypefnx {} {@var{type} =} matrix_type (@var{A}, "nocompute") +@deftypefnx {} {@var{A} =} matrix_type (@var{A}, @var{type}) +@deftypefnx {} {@var{A} =} matrix_type (@var{A}, "upper", @var{perm}) +@deftypefnx {} {@var{A} =} matrix_type (@var{A}, "lower", @var{perm}) +@deftypefnx {} {@var{A} =} matrix_type (@var{A}, "banded", @var{nl}, @var{nu}) +Identify the matrix type or mark a matrix as a particular type. + +This allows more rapid solutions of linear equations involving @var{A} to be +performed. + +Called with a single argument, @code{matrix_type} returns the type of the +matrix and caches it for future use. + +Called with more than one argument, @code{matrix_type} allows the type of +the matrix to be defined. + +If the option @qcode{"nocompute"} is given, the function will not attempt +to guess the type if it is still unknown. This is useful for debugging +purposes. + +The possible matrix types depend on whether the matrix is full or sparse, +and can be one of the following + +@table @asis +@item @qcode{"unknown"} +Remove any previously cached matrix type, and mark type as unknown. + +@item @qcode{"full"} +Mark the matrix as full. + +@item @qcode{"positive definite"} +Probable full positive definite matrix. + +@item @qcode{"diagonal"} +Diagonal matrix. (Sparse matrices only) + +@item @qcode{"permuted diagonal"} +Permuted Diagonal matrix. The permutation does not need to be specifically +indicated, as the structure of the matrix explicitly gives this. (Sparse +matrices only) + +@item @qcode{"upper"} +Upper triangular. If the optional third argument @var{perm} is given, the +matrix is assumed to be a permuted upper triangular with the permutations +defined by the vector @var{perm}. + +@item @qcode{"lower"} +Lower triangular. If the optional third argument @var{perm} is given, the +matrix is assumed to be a permuted lower triangular with the permutations +defined by the vector @var{perm}. + +@item @qcode{"banded"} +@itemx @qcode{"banded positive definite"} +Banded matrix with the band size of @var{nl} below the diagonal and @var{nu} +above it. If @var{nl} and @var{nu} are 1, then the matrix is tridiagonal +and treated with specialized code. In addition the matrix can be marked as +probably a positive definite. (Sparse matrices only) + +@item @qcode{"singular"} +The matrix is assumed to be singular and will be treated with a minimum norm +solution. + +@end table + +Note that the matrix type will be discovered automatically on the first +attempt to solve a linear equation involving @var{A}. Therefore +@code{matrix_type} is only useful to give Octave hints of the matrix type. +Incorrectly defining the matrix type will result in incorrect results from +solutions of linear equations; it is entirely @strong{the responsibility of +the user} to correctly identify the matrix type. + +Also, the test for positive definiteness is a low-cost test for a Hermitian +matrix with a real positive diagonal. This does not guarantee that the +matrix is positive definite, but only that it is a probable candidate. When +such a matrix is factorized, a Cholesky@tie{}factorization is first +attempted, and if that fails the matrix is then treated with an +LU@tie{}factorization. Once the matrix has been factorized, +@code{matrix_type} will return the correct classification of the matrix. +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/max.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/max.cc Tue Jun 21 16:07:51 2016 -0400 @@ -433,71 +433,71 @@ } DEFUN (min, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} min (@var{x})\n\ -@deftypefnx {} {} min (@var{x}, [], @var{dim})\n\ -@deftypefnx {} {[@var{w}, @var{iw}] =} min (@var{x})\n\ -@deftypefnx {} {} min (@var{x}, @var{y})\n\ -Find minimum values in the array @var{x}.\n\ -\n\ -For a vector argument, return the minimum value. For a matrix argument,\n\ -return a row vector with the minimum value of each column. For a\n\ -multi-dimensional array, @code{min} operates along the first non-singleton\n\ -dimension.\n\ -\n\ -If the optional third argument @var{dim} is present then operate along\n\ -this dimension. In this case the second argument is ignored and should be\n\ -set to the empty matrix.\n\ -\n\ -For two matrices (or a matrix and a scalar), return the pairwise minimum.\n\ -\n\ -Thus,\n\ -\n\ -@example\n\ -min (min (@var{x}))\n\ -@end example\n\ -\n\ -@noindent\n\ -returns the smallest element of the 2-D matrix @var{x}, and\n\ -\n\ -@example\n\ -@group\n\ -min (2:5, pi)\n\ - @result{} 2.0000 3.0000 3.1416 3.1416\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -compares each element of the range @code{2:5} with @code{pi}, and returns a\n\ -row vector of the minimum values.\n\ -\n\ -For complex arguments, the magnitude of the elements are used for\n\ -comparison. If the magnitudes are identical, then the results are ordered\n\ -by phase angle in the range (-pi, pi]. Hence,\n\ -\n\ -@example\n\ -@group\n\ -min ([-1 i 1 -i])\n\ - @result{} -i\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -because all entries have magnitude 1, but -i has the smallest phase angle\n\ -with value -pi/2.\n\ -\n\ -If called with one input and two output arguments, @code{min} also returns\n\ -the first index of the minimum value(s). Thus,\n\ -\n\ -@example\n\ -@group\n\ -[x, ix] = min ([1, 3, 0, 2, 0])\n\ - @result{} x = 0\n\ - ix = 3\n\ -@end group\n\ -@end example\n\ -@seealso{max, cummin, cummax}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} min (@var{x}) +@deftypefnx {} {} min (@var{x}, [], @var{dim}) +@deftypefnx {} {[@var{w}, @var{iw}] =} min (@var{x}) +@deftypefnx {} {} min (@var{x}, @var{y}) +Find minimum values in the array @var{x}. + +For a vector argument, return the minimum value. For a matrix argument, +return a row vector with the minimum value of each column. For a +multi-dimensional array, @code{min} operates along the first non-singleton +dimension. + +If the optional third argument @var{dim} is present then operate along +this dimension. In this case the second argument is ignored and should be +set to the empty matrix. + +For two matrices (or a matrix and a scalar), return the pairwise minimum. + +Thus, + +@example +min (min (@var{x})) +@end example + +@noindent +returns the smallest element of the 2-D matrix @var{x}, and + +@example +@group +min (2:5, pi) + @result{} 2.0000 3.0000 3.1416 3.1416 +@end group +@end example + +@noindent +compares each element of the range @code{2:5} with @code{pi}, and returns a +row vector of the minimum values. + +For complex arguments, the magnitude of the elements are used for +comparison. If the magnitudes are identical, then the results are ordered +by phase angle in the range (-pi, pi]. Hence, + +@example +@group +min ([-1 i 1 -i]) + @result{} -i +@end group +@end example + +@noindent +because all entries have magnitude 1, but -i has the smallest phase angle +with value -pi/2. + +If called with one input and two output arguments, @code{min} also returns +the first index of the minimum value(s). Thus, + +@example +@group +[x, ix] = min ([1, 3, 0, 2, 0]) + @result{} x = 0 + ix = 3 +@end group +@end example +@seealso{max, cummin, cummax} +@end deftypefn */) { return do_minmax_body (args, nargout, true); } @@ -654,71 +654,71 @@ */ DEFUN (max, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} max (@var{x})\n\ -@deftypefnx {} {} max (@var{x}, [], @var{dim})\n\ -@deftypefnx {} {[@var{w}, @var{iw}] =} max (@var{x})\n\ -@deftypefnx {} {} max (@var{x}, @var{y})\n\ -Find maximum values in the array @var{x}.\n\ -\n\ -For a vector argument, return the maximum value. For a matrix argument,\n\ -return a row vector with the maximum value of each column. For a\n\ -multi-dimensional array, @code{max} operates along the first non-singleton\n\ -dimension.\n\ -\n\ -If the optional third argument @var{dim} is present then operate along\n\ -this dimension. In this case the second argument is ignored and should be\n\ -set to the empty matrix.\n\ -\n\ -For two matrices (or a matrix and a scalar), return the pairwise maximum.\n\ -\n\ -Thus,\n\ -\n\ -@example\n\ -max (max (@var{x}))\n\ -@end example\n\ -\n\ -@noindent\n\ -returns the largest element of the 2-D matrix @var{x}, and\n\ -\n\ -@example\n\ -@group\n\ -max (2:5, pi)\n\ - @result{} 3.1416 3.1416 4.0000 5.0000\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -compares each element of the range @code{2:5} with @code{pi}, and returns a\n\ -row vector of the maximum values.\n\ -\n\ -For complex arguments, the magnitude of the elements are used for\n\ -comparison. If the magnitudes are identical, then the results are ordered\n\ -by phase angle in the range (-pi, pi]. Hence,\n\ -\n\ -@example\n\ -@group\n\ -max ([-1 i 1 -i])\n\ - @result{} -1\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -because all entries have magnitude 1, but -1 has the largest phase angle\n\ -with value pi.\n\ -\n\ -If called with one input and two output arguments, @code{max} also returns\n\ -the first index of the maximum value(s). Thus,\n\ -\n\ -@example\n\ -@group\n\ -[x, ix] = max ([1, 3, 5, 2, 5])\n\ - @result{} x = 5\n\ - ix = 3\n\ -@end group\n\ -@end example\n\ -@seealso{min, cummax, cummin}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} max (@var{x}) +@deftypefnx {} {} max (@var{x}, [], @var{dim}) +@deftypefnx {} {[@var{w}, @var{iw}] =} max (@var{x}) +@deftypefnx {} {} max (@var{x}, @var{y}) +Find maximum values in the array @var{x}. + +For a vector argument, return the maximum value. For a matrix argument, +return a row vector with the maximum value of each column. For a +multi-dimensional array, @code{max} operates along the first non-singleton +dimension. + +If the optional third argument @var{dim} is present then operate along +this dimension. In this case the second argument is ignored and should be +set to the empty matrix. + +For two matrices (or a matrix and a scalar), return the pairwise maximum. + +Thus, + +@example +max (max (@var{x})) +@end example + +@noindent +returns the largest element of the 2-D matrix @var{x}, and + +@example +@group +max (2:5, pi) + @result{} 3.1416 3.1416 4.0000 5.0000 +@end group +@end example + +@noindent +compares each element of the range @code{2:5} with @code{pi}, and returns a +row vector of the maximum values. + +For complex arguments, the magnitude of the elements are used for +comparison. If the magnitudes are identical, then the results are ordered +by phase angle in the range (-pi, pi]. Hence, + +@example +@group +max ([-1 i 1 -i]) + @result{} -1 +@end group +@end example + +@noindent +because all entries have magnitude 1, but -1 has the largest phase angle +with value pi. + +If called with one input and two output arguments, @code{max} also returns +the first index of the maximum value(s). Thus, + +@example +@group +[x, ix] = max ([1, 3, 5, 2, 5]) + @result{} x = 5 + ix = 3 +@end group +@end example +@seealso{min, cummax, cummin} +@end deftypefn */) { return do_minmax_body (args, nargout, false); } @@ -984,36 +984,36 @@ } DEFUN (cummin, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} cummin (@var{x})\n\ -@deftypefnx {} {} cummin (@var{x}, @var{dim})\n\ -@deftypefnx {} {[@var{w}, @var{iw}] =} cummin (@var{x})\n\ -Return the cumulative minimum values along dimension @var{dim}.\n\ -\n\ -If @var{dim} is unspecified it defaults to column-wise operation. For\n\ -example:\n\ -\n\ -@example\n\ -@group\n\ -cummin ([5 4 6 2 3 1])\n\ - @result{} 5 4 4 2 2 1\n\ -@end group\n\ -@end example\n\ -\n\ -If called with two output arguments the index of the minimum value is also\n\ -returned.\n\ -\n\ -@example\n\ -@group\n\ -[w, iw] = cummin ([5 4 6 2 3 1])\n\ -@result{}\n\ -w = 5 4 4 2 2 1\n\ -iw = 1 2 2 4 4 6\n\ -@end group\n\ -@end example\n\ -\n\ -@seealso{cummax, min, max}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} cummin (@var{x}) +@deftypefnx {} {} cummin (@var{x}, @var{dim}) +@deftypefnx {} {[@var{w}, @var{iw}] =} cummin (@var{x}) +Return the cumulative minimum values along dimension @var{dim}. + +If @var{dim} is unspecified it defaults to column-wise operation. For +example: + +@example +@group +cummin ([5 4 6 2 3 1]) + @result{} 5 4 4 2 2 1 +@end group +@end example + +If called with two output arguments the index of the minimum value is also +returned. + +@example +@group +[w, iw] = cummin ([5 4 6 2 3 1]) +@result{} +w = 5 4 4 2 2 1 +iw = 1 2 2 4 4 6 +@end group +@end example + +@seealso{cummax, min, max} +@end deftypefn */) { return do_cumminmax_body (args, nargout, true); } @@ -1040,36 +1040,36 @@ */ DEFUN (cummax, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} cummax (@var{x})\n\ -@deftypefnx {} {} cummax (@var{x}, @var{dim})\n\ -@deftypefnx {} {[@var{w}, @var{iw}] =} cummax (@dots{})\n\ -Return the cumulative maximum values along dimension @var{dim}.\n\ -\n\ -If @var{dim} is unspecified it defaults to column-wise operation. For\n\ -example:\n\ -\n\ -@example\n\ -@group\n\ -cummax ([1 3 2 6 4 5])\n\ - @result{} 1 3 3 6 6 6\n\ -@end group\n\ -@end example\n\ -\n\ -If called with two output arguments the index of the maximum value is also\n\ -returned.\n\ -\n\ -@example\n\ -@group\n\ -[w, iw] = cummax ([1 3 2 6 4 5])\n\ -@result{}\n\ -w = 1 3 3 6 6 6\n\ -iw = 1 2 2 4 4 4\n\ -@end group\n\ -@end example\n\ -\n\ -@seealso{cummin, max, min}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} cummax (@var{x}) +@deftypefnx {} {} cummax (@var{x}, @var{dim}) +@deftypefnx {} {[@var{w}, @var{iw}] =} cummax (@dots{}) +Return the cumulative maximum values along dimension @var{dim}. + +If @var{dim} is unspecified it defaults to column-wise operation. For +example: + +@example +@group +cummax ([1 3 2 6 4 5]) + @result{} 1 3 3 6 6 6 +@end group +@end example + +If called with two output arguments the index of the maximum value is also +returned. + +@example +@group +[w, iw] = cummax ([1 3 2 6 4 5]) +@result{} +w = 1 3 3 6 6 6 +iw = 1 2 2 4 4 4 +@end group +@end example + +@seealso{cummin, max, min} +@end deftypefn */) { return do_cumminmax_body (args, nargout, false); }
--- a/libinterp/corefcn/mgorth.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/mgorth.cc Tue Jun 21 16:07:51 2016 -0400 @@ -49,23 +49,23 @@ } DEFUN (mgorth, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{y}, @var{h}] =} mgorth (@var{x}, @var{v})\n\ -Orthogonalize a given column vector @var{x} with respect to a set of\n\ -orthonormal vectors comprising the columns of @var{v} using the modified\n\ -Gram-Schmidt method.\n\ -\n\ -On exit, @var{y} is a unit vector such that:\n\ -\n\ -@example\n\ -@group\n\ - norm (@var{y}) = 1\n\ - @var{v}' * @var{y} = 0\n\ - @var{x} = [@var{v}, @var{y}]*@var{h}'\n\ -@end group\n\ -@end example\n\ -\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{y}, @var{h}] =} mgorth (@var{x}, @var{v}) +Orthogonalize a given column vector @var{x} with respect to a set of +orthonormal vectors comprising the columns of @var{v} using the modified +Gram-Schmidt method. + +On exit, @var{y} is a unit vector such that: + +@example +@group + norm (@var{y}) = 1 + @var{v}' * @var{y} = 0 + @var{x} = [@var{v}, @var{y}]*@var{h}' +@end group +@end example + +@end deftypefn */) { if (args.length () != 2) print_usage ();
--- a/libinterp/corefcn/nproc.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/nproc.cc Tue Jun 21 16:07:51 2016 -0400 @@ -28,26 +28,26 @@ #include "nproc-wrapper.h" DEFUN (nproc, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} nproc ()\n\ -@deftypefnx {} {} nproc (@var{query})\n\ -Return the current number of available processors.\n\ -\n\ -If called with the optional argument @var{query}, modify how processors\n\ -are counted as follows:\n\ -\n\ -@table @code\n\ -@item all\n\ -total number of processors.\n\ -\n\ -@item current\n\ -processors available to the current process.\n\ -\n\ -@item overridable\n\ -same as @code{current}, but overridable through the\n\ -@w{@env{OMP_NUM_THREADS}} environment variable.\n\ -@end table\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} nproc () +@deftypefnx {} {} nproc (@var{query}) +Return the current number of available processors. + +If called with the optional argument @var{query}, modify how processors +are counted as follows: + +@table @code +@item all +total number of processors. + +@item current +processors available to the current process. + +@item overridable +same as @code{current}, but overridable through the +@w{@env{OMP_NUM_THREADS}} environment variable. +@end table +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/oct-hist.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/oct-hist.cc Tue Jun 21 16:07:51 2016 -0400 @@ -552,39 +552,39 @@ } DEFUN (edit_history, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} edit_history\n\ -@deftypefnx {} {} edit_history @var{cmd_number}\n\ -@deftypefnx {} {} edit_history @var{first} @var{last}\n\ -Edit the history list using the editor named by the variable @env{EDITOR}.\n\ -\n\ -The commands to be edited are first copied to a temporary file. When you\n\ -exit the editor, Octave executes the commands that remain in the file. It\n\ -is often more convenient to use @code{edit_history} to define functions\n\ -rather than attempting to enter them directly on the command line.\n\ -The block of commands is executed as soon as you exit the editor.\n\ -To avoid executing any commands, simply delete all the lines from the buffer\n\ -before leaving the editor.\n\ -\n\ -When invoked with no arguments, edit the previously executed command;\n\ -With one argument, edit the specified command @var{cmd_number};\n\ -With two arguments, edit the list of commands between @var{first} and\n\ -@var{last}. Command number specifiers may also be negative where -1\n\ -refers to the most recently executed command.\n\ -The following are equivalent and edit the most recently executed command.\n\ -\n\ -@example\n\ -@group\n\ -edit_history\n\ -edit_history -1\n\ -@end group\n\ -@end example\n\ -\n\ -When using ranges, specifying a larger number for the first command than the\n\ -last command reverses the list of commands before they are placed in the\n\ -buffer to be edited.\n\ -@seealso{run_history, history}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} edit_history +@deftypefnx {} {} edit_history @var{cmd_number} +@deftypefnx {} {} edit_history @var{first} @var{last} +Edit the history list using the editor named by the variable @env{EDITOR}. + +The commands to be edited are first copied to a temporary file. When you +exit the editor, Octave executes the commands that remain in the file. It +is often more convenient to use @code{edit_history} to define functions +rather than attempting to enter them directly on the command line. +The block of commands is executed as soon as you exit the editor. +To avoid executing any commands, simply delete all the lines from the buffer +before leaving the editor. + +When invoked with no arguments, edit the previously executed command; +With one argument, edit the specified command @var{cmd_number}; +With two arguments, edit the list of commands between @var{first} and +@var{last}. Command number specifiers may also be negative where -1 +refers to the most recently executed command. +The following are equivalent and edit the most recently executed command. + +@example +@group +edit_history +edit_history -1 +@end group +@end example + +When using ranges, specifying a larger number for the first command than the +last command reverses the list of commands before they are placed in the +buffer to be edited. +@seealso{run_history, history} +@end deftypefn */) { if (args.length () > 2) print_usage (); @@ -595,46 +595,46 @@ } DEFUN (history, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} history\n\ -@deftypefnx {} {} history @var{opt1} @dots{}\n\ -@deftypefnx {} {@var{h} =} history ()\n\ -@deftypefnx {} {@var{h} =} history (@var{opt1}, @dots{})\n\ -If invoked with no arguments, @code{history} displays a list of commands\n\ -that you have executed.\n\ -\n\ -Valid options are:\n\ -\n\ -@table @code\n\ -@item @var{n}\n\ -@itemx -@var{n}\n\ -Display only the most recent @var{n} lines of history.\n\ -\n\ -@item -c\n\ -Clear the history list.\n\ -\n\ -@item -q\n\ -Don't number the displayed lines of history. This is useful for cutting\n\ -and pasting commands using the X Window System.\n\ -\n\ -@item -r @var{file}\n\ -Read the file @var{file}, appending its contents to the current\n\ -history list. If the name is omitted, use the default history file\n\ -(normally @file{~/.octave_hist}).\n\ -\n\ -@item -w @var{file}\n\ -Write the current history to the file @var{file}. If the name is\n\ -omitted, use the default history file (normally @file{~/.octave_hist}).\n\ -@end table\n\ -\n\ -For example, to display the five most recent commands that you have\n\ -typed without displaying line numbers, use the command\n\ -@kbd{history -q 5}.\n\ -\n\ -If invoked with a single output argument, the history will be saved to that\n\ -argument as a cell string and will not be output to screen.\n\ -@seealso{edit_history, run_history}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} history +@deftypefnx {} {} history @var{opt1} @dots{} +@deftypefnx {} {@var{h} =} history () +@deftypefnx {} {@var{h} =} history (@var{opt1}, @dots{}) +If invoked with no arguments, @code{history} displays a list of commands +that you have executed. + +Valid options are: + +@table @code +@item @var{n} +@itemx -@var{n} +Display only the most recent @var{n} lines of history. + +@item -c +Clear the history list. + +@item -q +Don't number the displayed lines of history. This is useful for cutting +and pasting commands using the X Window System. + +@item -r @var{file} +Read the file @var{file}, appending its contents to the current +history list. If the name is omitted, use the default history file +(normally @file{~/.octave_hist}). + +@item -w @var{file} +Write the current history to the file @var{file}. If the name is +omitted, use the default history file (normally @file{~/.octave_hist}). +@end table + +For example, to display the five most recent commands that you have +typed without displaying line numbers, use the command +@kbd{history -q 5}. + +If invoked with a single output argument, the history will be saved to that +argument as a cell string and will not be output to screen. +@seealso{edit_history, run_history} +@end deftypefn */) { // Call do_history even if nargout is zero to display history list. @@ -644,56 +644,56 @@ } DEFUN (run_history, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} run_history\n\ -@deftypefnx {} {} run_history @var{cmd_number}\n\ -@deftypefnx {} {} run_history @var{first} @var{last}\n\ -Run commands from the history list.\n\ -\n\ -When invoked with no arguments, run the previously executed command;\n\ -\n\ -With one argument, run the specified command @var{cmd_number};\n\ -\n\ -With two arguments, run the list of commands between @var{first} and\n\ -@var{last}. Command number specifiers may also be negative where -1\n\ -refers to the most recently executed command. For example, the command\n\ -\n\ -@example\n\ -@group\n\ -run_history\n\ - OR\n\ -run_history -1\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -executes the most recent command again.\n\ -The command\n\ -\n\ -@example\n\ -run_history 13 169\n\ -@end example\n\ -\n\ -@noindent\n\ -executes commands 13 through 169.\n\ -\n\ -Specifying a larger number for the first command than the last command\n\ -reverses the list of commands before executing them.\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -disp (1)\n\ -disp (2)\n\ -run_history -1 -2\n\ -@result{}\n\ - 2\n\ - 1\n\ -@end group\n\ -@end example\n\ -\n\ -@seealso{edit_history, history}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} run_history +@deftypefnx {} {} run_history @var{cmd_number} +@deftypefnx {} {} run_history @var{first} @var{last} +Run commands from the history list. + +When invoked with no arguments, run the previously executed command; + +With one argument, run the specified command @var{cmd_number}; + +With two arguments, run the list of commands between @var{first} and +@var{last}. Command number specifiers may also be negative where -1 +refers to the most recently executed command. For example, the command + +@example +@group +run_history + OR +run_history -1 +@end group +@end example + +@noindent +executes the most recent command again. +The command + +@example +run_history 13 169 +@end example + +@noindent +executes commands 13 through 169. + +Specifying a larger number for the first command than the last command +reverses the list of commands before executing them. +For example: + +@example +@group +disp (1) +disp (2) +run_history -1 -2 +@result{} + 2 + 1 +@end group +@end example + +@seealso{edit_history, history} +@end deftypefn */) { if (args.length () > 2) print_usage (); @@ -704,28 +704,28 @@ } DEFUN (history_control, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} history_control ()\n\ -@deftypefnx {} {@var{old_val} =} history_control (@var{new_val})\n\ -Query or set the internal variable that specifies how commands are saved\n\ -to the history list.\n\ -\n\ -The default value is an empty character string, but may be overridden by the\n\ -environment variable @w{@env{OCTAVE_HISTCONTROL}}.\n\ -\n\ -The value of @code{history_control} is a colon-separated list of values\n\ -controlling how commands are saved on the history list. If the list\n\ -of values includes @code{ignorespace}, lines which begin with a space\n\ -character are not saved in the history list. A value of @code{ignoredups}\n\ -causes lines matching the previous history entry to not be saved.\n\ -A value of @code{ignoreboth} is shorthand for @code{ignorespace} and\n\ -@code{ignoredups}. A value of @code{erasedups} causes all previous lines\n\ -matching the current line to be removed from the history list before that\n\ -line is saved. Any value not in the above list is ignored. If\n\ -@code{history_control} is the empty string, all commands are saved on\n\ -the history list, subject to the value of @code{history_save}.\n\ -@seealso{history_file, history_size, history_timestamp_format_string, history_save}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} history_control () +@deftypefnx {} {@var{old_val} =} history_control (@var{new_val}) +Query or set the internal variable that specifies how commands are saved +to the history list. + +The default value is an empty character string, but may be overridden by the +environment variable @w{@env{OCTAVE_HISTCONTROL}}. + +The value of @code{history_control} is a colon-separated list of values +controlling how commands are saved on the history list. If the list +of values includes @code{ignorespace}, lines which begin with a space +character are not saved in the history list. A value of @code{ignoredups} +causes lines matching the previous history entry to not be saved. +A value of @code{ignoreboth} is shorthand for @code{ignorespace} and +@code{ignoredups}. A value of @code{erasedups} causes all previous lines +matching the current line to be removed from the history list before that +line is saved. Any value not in the above list is ignored. If +@code{history_control} is the empty string, all commands are saved on +the history list, subject to the value of @code{history_save}. +@seealso{history_file, history_size, history_timestamp_format_string, history_save} +@end deftypefn */) { octave_value retval; @@ -742,16 +742,16 @@ } DEFUN (history_size, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} history_size ()\n\ -@deftypefnx {} {@var{old_val} =} history_size (@var{new_val})\n\ -Query or set the internal variable that specifies how many entries\n\ -to store in the history file.\n\ -\n\ -The default value is @code{1000}, but may be overridden by the environment\n\ -variable @w{@env{OCTAVE_HISTSIZE}}.\n\ -@seealso{history_file, history_timestamp_format_string, history_save}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} history_size () +@deftypefnx {} {@var{old_val} =} history_size (@var{new_val}) +Query or set the internal variable that specifies how many entries +to store in the history file. + +The default value is @code{1000}, but may be overridden by the environment +variable @w{@env{OCTAVE_HISTSIZE}}. +@seealso{history_file, history_timestamp_format_string, history_save} +@end deftypefn */) { octave_value retval; @@ -770,16 +770,16 @@ } DEFUN (history_file, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} history_file ()\n\ -@deftypefnx {} {@var{old_val} =} history_file (@var{new_val})\n\ -Query or set the internal variable that specifies the name of the\n\ -file used to store command history.\n\ -\n\ -The default value is @file{~/.octave_hist}, but may be overridden by the\n\ -environment variable @w{@env{OCTAVE_HISTFILE}}.\n\ -@seealso{history_size, history_save, history_timestamp_format_string}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} history_file () +@deftypefnx {} {@var{old_val} =} history_file (@var{new_val}) +Query or set the internal variable that specifies the name of the +file used to store command history. + +The default value is @file{~/.octave_hist}, but may be overridden by the +environment variable @w{@env{OCTAVE_HISTFILE}}. +@seealso{history_size, history_save, history_timestamp_format_string} +@end deftypefn */) { octave_value retval; @@ -796,42 +796,42 @@ } DEFUN (history_timestamp_format_string, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} history_timestamp_format_string ()\n\ -@deftypefnx {} {@var{old_val} =} history_timestamp_format_string (@var{new_val})\n\ -@deftypefnx {} {} history_timestamp_format_string (@var{new_val}, \"local\")\n\ -Query or set the internal variable that specifies the format string\n\ -for the comment line that is written to the history file when Octave\n\ -exits.\n\ -\n\ -The format string is passed to @code{strftime}. The default value is\n\ -\n\ -@example\n\ -\"# Octave VERSION, %a %b %d %H:%M:%S %Y %Z <USER@@HOST>\"\n\ -@end example\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{strftime, history_file, history_size, history_save}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} history_timestamp_format_string () +@deftypefnx {} {@var{old_val} =} history_timestamp_format_string (@var{new_val}) +@deftypefnx {} {} history_timestamp_format_string (@var{new_val}, "local") +Query or set the internal variable that specifies the format string +for the comment line that is written to the history file when Octave +exits. + +The format string is passed to @code{strftime}. The default value is + +@example +"# Octave VERSION, %a %b %d %H:%M:%S %Y %Z <USER@@HOST>" +@end example + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{strftime, history_file, history_size, history_save} +@end deftypefn */) { return SET_INTERNAL_VARIABLE (history_timestamp_format_string); } DEFUN (history_save, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} history_save ()\n\ -@deftypefnx {} {@var{old_val} =} history_save (@var{new_val})\n\ -@deftypefnx {} {} history_save (@var{new_val}, \"local\")\n\ -Query or set the internal variable that controls whether commands entered\n\ -on the command line are saved in the history file.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{history_control, history_file, history_size, history_timestamp_format_string}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} history_save () +@deftypefnx {} {@var{old_val} =} history_save (@var{new_val}) +@deftypefnx {} {} history_save (@var{new_val}, "local") +Query or set the internal variable that controls whether commands entered +on the command line are saved in the history file. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{history_control, history_file, history_size, history_timestamp_format_string} +@end deftypefn */) { octave_value retval;
--- a/libinterp/corefcn/octave-link.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/octave-link.cc Tue Jun 21 16:07:51 2016 -0400 @@ -109,19 +109,19 @@ } DEFUN (__octave_link_enabled__, , , - "-*- texinfo -*-\n\ -@deftypefn {} {} __octave_link_enabled__ ()\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __octave_link_enabled__ () +Undocumented internal function. +@end deftypefn */) { return ovl (octave_link::enabled ()); } DEFUN (__octave_link_edit_file__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __octave_link_edit_file__ (@var{file})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __octave_link_edit_file__ (@var{file}) +Undocumented internal function. +@end deftypefn */) { octave_value retval; @@ -146,10 +146,10 @@ } DEFUN (__octave_link_message_dialog__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __octave_link_message_dialog__ (@var{dlg}, @var{msg}, @var{title})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __octave_link_message_dialog__ (@var{dlg}, @var{msg}, @var{title}) +Undocumented internal function. +@end deftypefn */) { octave_value retval; @@ -168,10 +168,10 @@ } DEFUN (__octave_link_question_dialog__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __octave_link_question_dialog__ (@var{msg}, @var{title}, @var{btn1}, @var{btn2}, @var{btn3}, @var{default})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __octave_link_question_dialog__ (@var{msg}, @var{title}, @var{btn1}, @var{btn2}, @var{btn3}, @var{default}) +Undocumented internal function. +@end deftypefn */) { octave_value retval; @@ -194,10 +194,10 @@ } DEFUN (__octave_link_file_dialog__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __octave_link_file_dialog__ (@var{filterlist}, @var{title}, @var{filename}, @var{size} @var{multiselect}, @var{pathname})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __octave_link_file_dialog__ (@var{filterlist}, @var{title}, @var{filename}, @var{size} @var{multiselect}, @var{pathname}) +Undocumented internal function. +@end deftypefn */) { if (args.length () != 6) return ovl (); @@ -263,10 +263,10 @@ } DEFUN (__octave_link_list_dialog__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __octave_link_list_dialog__ (@var{list}, @var{mode}, @var{size}, @var{intial}, @var{name}, @var{prompt}, @var{ok_string}, @var{cancel_string})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __octave_link_list_dialog__ (@var{list}, @var{mode}, @var{size}, @var{intial}, @var{name}, @var{prompt}, @var{ok_string}, @var{cancel_string}) +Undocumented internal function. +@end deftypefn */) { if (args.length () != 8) return ovl (); @@ -321,10 +321,10 @@ } DEFUN (__octave_link_input_dialog__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __octave_link_input_dialog__ (@var{prompt}, @var{title}, @var{rowscols}, @var{defaults})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __octave_link_input_dialog__ (@var{prompt}, @var{title}, @var{rowscols}, @var{defaults}) +Undocumented internal function. +@end deftypefn */) { if (args.length () != 4) return ovl (); @@ -374,19 +374,19 @@ } DEFUN (__octave_link_show_preferences__, , , - "-*- texinfo -*-\n\ -@deftypefn {} {} __octave_link_show_preferences__ ()\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __octave_link_show_preferences__ () +Undocumented internal function. +@end deftypefn */) { return ovl (octave_link::show_preferences ()); } DEFUN (__octave_link_show_doc__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __octave_link_show_doc__ (@var{filename})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __octave_link_show_doc__ (@var{filename}) +Undocumented internal function. +@end deftypefn */) { std::string file;
--- a/libinterp/corefcn/ordschur.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/ordschur.cc Tue Jun 21 16:07:51 2016 -0400 @@ -63,49 +63,49 @@ } DEFUN (ordschur, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{UR}, @var{SR}] =} ordschur (@var{U}, @var{S}, @var{select})\n\ -Reorders the real Schur factorization (@var{U},@var{S}) obtained with the\n\ -@code{schur} function, so that selected eigenvalues appear in the upper left\n\ -diagonal blocks of the quasi triangular Schur matrix.\n\ -\n\ -The logical vector @var{select} specifies the selected eigenvalues as they\n\ -appear along @var{S}'s diagonal.\n\ -\n\ -For example, given the matrix @code{@var{A} = [1, 2; 3, 4]}, and its Schur\n\ -decomposition\n\ -\n\ -@example\n\ -[@var{U}, @var{S}] = schur (@var{A})\n\ -@end example\n\ -\n\ -@noindent\n\ -which returns\n\ -\n\ -@example\n\ -@group\n\ -@var{U} =\n\ -\n\ - -0.82456 -0.56577\n\ - 0.56577 -0.82456\n\ -\n\ -@var{S} =\n\ -\n\ - -0.37228 -1.00000\n\ - 0.00000 5.37228\n\ -\n\ -@end group\n\ -@end example\n\ -\n\ -It is possible to reorder the decomposition so that the positive eigenvalue\n\ -is in the upper left corner, by doing:\n\ -\n\ -@example\n\ -[@var{U}, @var{S}] = ordschur (@var{U}, @var{S}, [0,1])\n\ -@end example\n\ -\n\ -@seealso{schur}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{UR}, @var{SR}] =} ordschur (@var{U}, @var{S}, @var{select}) +Reorders the real Schur factorization (@var{U},@var{S}) obtained with the +@code{schur} function, so that selected eigenvalues appear in the upper left +diagonal blocks of the quasi triangular Schur matrix. + +The logical vector @var{select} specifies the selected eigenvalues as they +appear along @var{S}'s diagonal. + +For example, given the matrix @code{@var{A} = [1, 2; 3, 4]}, and its Schur +decomposition + +@example +[@var{U}, @var{S}] = schur (@var{A}) +@end example + +@noindent +which returns + +@example +@group +@var{U} = + + -0.82456 -0.56577 + 0.56577 -0.82456 + +@var{S} = + + -0.37228 -1.00000 + 0.00000 5.37228 + +@end group +@end example + +It is possible to reorder the decomposition so that the positive eigenvalue +is in the upper left corner, by doing: + +@example +[@var{U}, @var{S}] = ordschur (@var{U}, @var{S}, [0,1]) +@end example + +@seealso{schur} +@end deftypefn */) { if (args.length () != 3) print_usage ();
--- a/libinterp/corefcn/pager.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/pager.cc Tue Jun 21 16:07:51 2016 -0400 @@ -506,31 +506,31 @@ } DEFUN (diary, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} diary\n\ -@deftypefnx {} {} diary on\n\ -@deftypefnx {} {} diary off\n\ -@deftypefnx {} {} diary @var{filename}\n\ -Record a list of all commands @emph{and} the output they produce, mixed\n\ -together just as they appear on the terminal.\n\ -\n\ -Valid options are:\n\ -\n\ -@table @asis\n\ -@item on\n\ -Start recording a session in a file called @file{diary} in the\n\ -current working directory.\n\ -\n\ -@item off\n\ -Stop recording the session in the diary file.\n\ -\n\ -@item @var{filename}\n\ -Record the session in the file named @var{filename}.\n\ -@end table\n\ -\n\ -With no arguments, @code{diary} toggles the current diary state.\n\ -@seealso{history, evalc}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} diary +@deftypefnx {} {} diary on +@deftypefnx {} {} diary off +@deftypefnx {} {} diary @var{filename} +Record a list of all commands @emph{and} the output they produce, mixed +together just as they appear on the terminal. + +Valid options are: + +@table @asis +@item on +Start recording a session in a file called @file{diary} in the +current working directory. + +@item off +Stop recording the session in the diary file. + +@item @var{filename} +Record the session in the file named @var{filename}. +@end table + +With no arguments, @code{diary} toggles the current diary state. +@seealso{history, evalc} +@end deftypefn */) { int nargin = args.length (); @@ -571,35 +571,35 @@ } DEFUN (__diaryfile__, , , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{fname} =} __diaryfile__ ()\n\ -Undocumented internal function\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{fname} =} __diaryfile__ () +Undocumented internal function +@end deftypefn */) { return ovl (diary_file); } DEFUN (__diarystate__, , , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{state} =} __diarystate__ ()\n\ -Undocumented internal function\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{state} =} __diarystate__ () +Undocumented internal function +@end deftypefn */) { return ovl (write_to_diary_file); } DEFUN (more, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} more\n\ -@deftypefnx {} {} more on\n\ -@deftypefnx {} {} more off\n\ -Turn output pagination on or off.\n\ -\n\ -Without an argument, @code{more} toggles the current state.\n\ -\n\ -The current state can be determined via @code{page_screen_output}.\n\ -@seealso{page_screen_output, page_output_immediately, PAGER, PAGER_FLAGS}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} more +@deftypefnx {} {} more on +@deftypefnx {} {} more off +Turn output pagination on or off. + +Without an argument, @code{more} toggles the current state. + +The current state can be determined via @code{page_screen_output}. +@seealso{page_screen_output, page_output_immediately, PAGER, PAGER_FLAGS} +@end deftypefn */) { int nargin = args.length (); @@ -624,12 +624,12 @@ } DEFUN (terminal_size, , , - "-*- texinfo -*-\n\ -@deftypefn {} {} terminal_size ()\n\ -Return a two-element row vector containing the current size of the terminal\n\ -window in characters (rows and columns).\n\ -@seealso{list_in_columns}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} terminal_size () +Return a two-element row vector containing the current size of the terminal +window in characters (rows and columns). +@seealso{list_in_columns} +@end deftypefn */) { RowVector size (2, 0.0); @@ -640,81 +640,81 @@ } DEFUN (page_output_immediately, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} page_output_immediately ()\n\ -@deftypefnx {} {@var{old_val} =} page_output_immediately (@var{new_val})\n\ -@deftypefnx {} {} page_output_immediately (@var{new_val}, \"local\")\n\ -Query or set the internal variable that controls whether Octave sends\n\ -output to the pager as soon as it is available.\n\ -\n\ -Otherwise, Octave buffers its output and waits until just before the prompt\n\ -is printed to flush it to the pager.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{page_screen_output, more, PAGER, PAGER_FLAGS}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} page_output_immediately () +@deftypefnx {} {@var{old_val} =} page_output_immediately (@var{new_val}) +@deftypefnx {} {} page_output_immediately (@var{new_val}, "local") +Query or set the internal variable that controls whether Octave sends +output to the pager as soon as it is available. + +Otherwise, Octave buffers its output and waits until just before the prompt +is printed to flush it to the pager. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{page_screen_output, more, PAGER, PAGER_FLAGS} +@end deftypefn */) { return SET_INTERNAL_VARIABLE (page_output_immediately); } DEFUN (page_screen_output, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} page_screen_output ()\n\ -@deftypefnx {} {@var{old_val} =} page_screen_output (@var{new_val})\n\ -@deftypefnx {} {} page_screen_output (@var{new_val}, \"local\")\n\ -Query or set the internal variable that controls whether output intended\n\ -for the terminal window that is longer than one page is sent through a\n\ -pager.\n\ -\n\ -This allows you to view one screenful at a time. Some pagers\n\ -(such as @code{less}---see @ref{Installation}) are also capable of moving\n\ -backward on the output.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{more, page_output_immediately, PAGER, PAGER_FLAGS}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} page_screen_output () +@deftypefnx {} {@var{old_val} =} page_screen_output (@var{new_val}) +@deftypefnx {} {} page_screen_output (@var{new_val}, "local") +Query or set the internal variable that controls whether output intended +for the terminal window that is longer than one page is sent through a +pager. + +This allows you to view one screenful at a time. Some pagers +(such as @code{less}---see @ref{Installation}) are also capable of moving +backward on the output. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{more, page_output_immediately, PAGER, PAGER_FLAGS} +@end deftypefn */) { return SET_INTERNAL_VARIABLE (page_screen_output); } DEFUN (PAGER, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} PAGER ()\n\ -@deftypefnx {} {@var{old_val} =} PAGER (@var{new_val})\n\ -@deftypefnx {} {} PAGER (@var{new_val}, \"local\")\n\ -Query or set the internal variable that specifies the program to use\n\ -to display terminal output on your system.\n\ -\n\ -The default value is normally @qcode{\"less\"}, @qcode{\"more\"}, or\n\ -@qcode{\"pg\"}, depending on what programs are installed on your system.\n\ -@xref{Installation}.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{PAGER_FLAGS, page_output_immediately, more, page_screen_output}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} PAGER () +@deftypefnx {} {@var{old_val} =} PAGER (@var{new_val}) +@deftypefnx {} {} PAGER (@var{new_val}, "local") +Query or set the internal variable that specifies the program to use +to display terminal output on your system. + +The default value is normally @qcode{"less"}, @qcode{"more"}, or +@qcode{"pg"}, depending on what programs are installed on your system. +@xref{Installation}. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{PAGER_FLAGS, page_output_immediately, more, page_screen_output} +@end deftypefn */) { return SET_NONEMPTY_INTERNAL_STRING_VARIABLE (PAGER); } DEFUN (PAGER_FLAGS, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} PAGER_FLAGS ()\n\ -@deftypefnx {} {@var{old_val} =} PAGER_FLAGS (@var{new_val})\n\ -@deftypefnx {} {} PAGER_FLAGS (@var{new_val}, \"local\")\n\ -Query or set the internal variable that specifies the options to pass\n\ -to the pager.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{PAGER, more, page_screen_output, page_output_immediately}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} PAGER_FLAGS () +@deftypefnx {} {@var{old_val} =} PAGER_FLAGS (@var{new_val}) +@deftypefnx {} {} PAGER_FLAGS (@var{new_val}, "local") +Query or set the internal variable that specifies the options to pass +to the pager. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{PAGER, more, page_screen_output, page_output_immediately} +@end deftypefn */) { return SET_NONEMPTY_INTERNAL_STRING_VARIABLE (PAGER_FLAGS); }
--- a/libinterp/corefcn/pinv.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/pinv.cc Tue Jun 21 16:07:51 2016 -0400 @@ -37,22 +37,22 @@ #include "ov-perm.h" DEFUN (pinv, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} pinv (@var{x})\n\ -@deftypefnx {} {} pinv (@var{x}, @var{tol})\n\ -Return the pseudoinverse of @var{x}.\n\ -\n\ -Singular values less than @var{tol} are ignored.\n\ -\n\ -If the second argument is omitted, it is taken to be\n\ -\n\ -@example\n\ -tol = max (size (@var{x})) * sigma_max (@var{x}) * eps,\n\ -@end example\n\ -\n\ -@noindent\n\ -where @code{sigma_max (@var{x})} is the maximal singular value of @var{x}.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} pinv (@var{x}) +@deftypefnx {} {} pinv (@var{x}, @var{tol}) +Return the pseudoinverse of @var{x}. + +Singular values less than @var{tol} are ignored. + +If the second argument is omitted, it is taken to be + +@example +tol = max (size (@var{x})) * sigma_max (@var{x}) * eps, +@end example + +@noindent +where @code{sigma_max (@var{x})} is the maximal singular value of @var{x}. +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/pr-output.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/pr-output.cc Tue Jun 21 16:07:51 2016 -0400 @@ -3408,26 +3408,26 @@ } DEFUN (rats, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} rats (@var{x}, @var{len})\n\ -Convert @var{x} into a rational approximation represented as a string.\n\ -\n\ -The string can be converted back into a matrix as follows:\n\ -\n\ -@example\n\ -@group\n\ -r = rats (hilb (4));\n\ -x = str2num (r)\n\ -@end group\n\ -@end example\n\ -\n\ -The optional second argument defines the maximum length of the string\n\ -representing the elements of @var{x}. By default @var{len} is 9.\n\ -\n\ -If the length of the smallest possible rational approximation exceeds\n\ -@var{len}, an asterisk (*) padded with spaces will be returned instead.\n\ -@seealso{format, rat}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} rats (@var{x}, @var{len}) +Convert @var{x} into a rational approximation represented as a string. + +The string can be converted back into a matrix as follows: + +@example +@group +r = rats (hilb (4)); +x = str2num (r) +@end group +@end example + +The optional second argument defines the maximum length of the string +representing the elements of @var{x}. By default @var{len} is 9. + +If the length of the smallest possible rational approximation exceeds +@var{len}, an asterisk (*) padded with spaces will be returned instead. +@seealso{format, rat} +@end deftypefn */) { int nargin = args.length (); @@ -3480,28 +3480,28 @@ } DEFUN (disp, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} disp (@var{x})\n\ -Display the value of @var{x}.\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -disp (\"The value of pi is:\"), disp (pi)\n\ -\n\ - @print{} the value of pi is:\n\ - @print{} 3.1416\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -Note that the output from @code{disp} always ends with a newline.\n\ -\n\ -If an output value is requested, @code{disp} prints nothing and returns the\n\ -formatted output in a string.\n\ -@seealso{fdisp}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} disp (@var{x}) +Display the value of @var{x}. + +For example: + +@example +@group +disp ("The value of pi is:"), disp (pi) + + @print{} the value of pi is: + @print{} 3.1416 +@end group +@end example + +@noindent +Note that the output from @code{disp} always ends with a newline. + +If an output value is requested, @code{disp} prints nothing and returns the +formatted output in a string. +@seealso{fdisp} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -3523,25 +3523,25 @@ } DEFUN (fdisp, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} fdisp (@var{fid}, @var{x})\n\ -Display the value of @var{x} on the stream @var{fid}.\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -fdisp (stdout, \"The value of pi is:\"), fdisp (stdout, pi)\n\ -\n\ - @print{} the value of pi is:\n\ - @print{} 3.1416\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -Note that the output from @code{fdisp} always ends with a newline.\n\ -@seealso{disp}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} fdisp (@var{fid}, @var{x}) +Display the value of @var{x} on the stream @var{fid}. + +For example: + +@example +@group +fdisp (stdout, "The value of pi is:"), fdisp (stdout, pi) + + @print{} the value of pi is: + @print{} 3.1416 +@end group +@end example + +@noindent +Note that the output from @code{fdisp} always ends with a newline. +@seealso{disp} +@end deftypefn */) { if (args.length () != 2) print_usage (); @@ -3856,177 +3856,177 @@ DEFUN (format, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} format\n\ -@deftypefnx {} {} format options\n\ -Reset or specify the format of the output produced by @code{disp} and\n\ -Octave's normal echoing mechanism.\n\ -\n\ -This command only affects the display of numbers but not how they are stored\n\ -or computed. To change the internal representation from the default double\n\ -use one of the conversion functions such as @code{single}, @code{uint8},\n\ -@code{int64}, etc.\n\ -\n\ -By default, Octave displays 5 significant digits in a human readable form\n\ -(option @samp{short} paired with @samp{loose} format for matrices).\n\ -If @code{format} is invoked without any options, this default format\n\ -is restored.\n\ -\n\ -Valid formats for floating point numbers are listed in the following\n\ -table.\n\ -\n\ -@table @code\n\ -@item short\n\ -Fixed point format with 5 significant figures in a field that is a maximum\n\ -of 10 characters wide. (default).\n\ -\n\ -If Octave is unable to format a matrix so that columns line up on the\n\ -decimal point and all numbers fit within the maximum field width then\n\ -it switches to an exponential @samp{e} format.\n\ -\n\ -@item long\n\ -Fixed point format with 15 significant figures in a field that is a maximum\n\ -of 20 characters wide.\n\ -\n\ -As with the @samp{short} format, Octave will switch to an exponential\n\ -@samp{e} format if it is unable to format a matrix properly using the\n\ -current format.\n\ -\n\ -@item short e\n\ -@itemx long e\n\ -Exponential format. The number to be represented is split between a\n\ -mantissa and an exponent (power of 10). The mantissa has 5 significant\n\ -digits in the short format and 15 digits in the long format. For example,\n\ -with the @samp{short e} format, @code{pi} is displayed as\n\ -@code{3.1416e+00}.\n\ -\n\ -@item short E\n\ -@itemx long E\n\ -Identical to @samp{short e} or @samp{long e} but displays an uppercase\n\ -@samp{E} to indicate the exponent.\n\ -For example, with the @samp{long E} format, @code{pi} is displayed as\n\ -@code{3.14159265358979E+00}.\n\ -\n\ -@item short g\n\ -@itemx long g\n\ -Optimally choose between fixed point and exponential format based on\n\ -the magnitude of the number.\n\ -For example, with the @samp{short g} format,\n\ -@code{pi .^ [2; 4; 8; 16; 32]} is displayed as\n\ -\n\ -@example\n\ -@group\n\ -ans =\n\ -\n\ - 9.8696\n\ - 97.409\n\ - 9488.5\n\ - 9.0032e+07\n\ - 8.1058e+15\n\ -@end group\n\ -@end example\n\ -\n\ -@item short eng\n\ -@itemx long eng\n\ -Identical to @samp{short e} or @samp{long e} but displays the value\n\ -using an engineering format, where the exponent is divisible by 3. For\n\ -example, with the @samp{short eng} format, @code{10 * pi} is displayed as\n\ -@code{31.4159e+00}.\n\ -\n\ -@item long G\n\ -@itemx short G\n\ -Identical to @samp{short g} or @samp{long g} but displays an uppercase\n\ -@samp{E} to indicate the exponent.\n\ -\n\ -@item free\n\ -@itemx none\n\ -Print output in free format, without trying to line up columns of\n\ -matrices on the decimal point. This also causes complex numbers to be\n\ -formatted as numeric pairs like this @samp{(0.60419, 0.60709)} instead\n\ -of like this @samp{0.60419 + 0.60709i}.\n\ -@end table\n\ -\n\ -The following formats affect all numeric output (floating point and\n\ -integer types).\n\ -\n\ -@table @code\n\ -@item \"+\"\n\ -@itemx \"+\" @var{chars}\n\ -@itemx plus\n\ -@itemx plus @var{chars}\n\ -Print a @samp{+} symbol for matrix elements greater than zero, a\n\ -@samp{-} symbol for elements less than zero and a space for zero matrix\n\ -elements. This format can be very useful for examining the structure\n\ -of a large sparse matrix.\n\ -\n\ -The optional argument @var{chars} specifies a list of 3 characters to use\n\ -for printing values greater than zero, less than zero and equal to zero.\n\ -For example, with the @samp{\"+\" \"+-.\"} format,\n\ -@code{[1, 0, -1; -1, 0, 1]} is displayed as\n\ -\n\ -@example\n\ -@group\n\ -ans =\n\ -\n\ -+.-\n\ --.+\n\ -@end group\n\ -@end example\n\ -\n\ -@item bank\n\ -Print in a fixed format with two digits to the right of the decimal\n\ -point.\n\ -\n\ -@item native-hex\n\ -Print the hexadecimal representation of numbers as they are stored in\n\ -memory. For example, on a workstation which stores 8 byte real values\n\ -in IEEE format with the least significant byte first, the value of\n\ -@code{pi} when printed in @code{native-hex} format is\n\ -@code{400921fb54442d18}.\n\ -\n\ -@item hex\n\ -The same as @code{native-hex}, but always print the most significant\n\ -byte first.\n\ -\n\ -@item native-bit\n\ -Print the bit representation of numbers as stored in memory.\n\ -For example, the value of @code{pi} is\n\ -\n\ -@example\n\ -@group\n\ -01000000000010010010000111111011\n\ -01010100010001000010110100011000\n\ -@end group\n\ -@end example\n\ -\n\ -(shown here in two 32 bit sections for typesetting purposes) when\n\ -printed in native-bit format on a workstation which stores 8 byte real\n\ -values in IEEE format with the least significant byte first.\n\ -\n\ -@item bit\n\ -The same as @code{native-bit}, but always print the most significant\n\ -bits first.\n\ -\n\ -@item rat\n\ -Print a rational approximation, i.e., values are approximated\n\ -as the ratio of small integers.\n\ -For example, with the @samp{rat} format,\n\ -@code{pi} is displayed as @code{355/113}.\n\ -@end table\n\ -\n\ -The following two options affect the display of all matrices.\n\ -\n\ -@table @code\n\ -@item compact\n\ -Remove blank lines around column number labels and between\n\ -matrices producing more compact output with more data per page.\n\ -\n\ -@item loose\n\ -Insert blank lines above and below column number labels and between matrices\n\ -to produce a more readable output with less data per page. (default).\n\ -@end table\n\ -@seealso{fixed_point_format, output_max_field_width, output_precision, split_long_rows, print_empty_dimensions, rats}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} format +@deftypefnx {} {} format options +Reset or specify the format of the output produced by @code{disp} and +Octave's normal echoing mechanism. + +This command only affects the display of numbers but not how they are stored +or computed. To change the internal representation from the default double +use one of the conversion functions such as @code{single}, @code{uint8}, +@code{int64}, etc. + +By default, Octave displays 5 significant digits in a human readable form +(option @samp{short} paired with @samp{loose} format for matrices). +If @code{format} is invoked without any options, this default format +is restored. + +Valid formats for floating point numbers are listed in the following +table. + +@table @code +@item short +Fixed point format with 5 significant figures in a field that is a maximum +of 10 characters wide. (default). + +If Octave is unable to format a matrix so that columns line up on the +decimal point and all numbers fit within the maximum field width then +it switches to an exponential @samp{e} format. + +@item long +Fixed point format with 15 significant figures in a field that is a maximum +of 20 characters wide. + +As with the @samp{short} format, Octave will switch to an exponential +@samp{e} format if it is unable to format a matrix properly using the +current format. + +@item short e +@itemx long e +Exponential format. The number to be represented is split between a +mantissa and an exponent (power of 10). The mantissa has 5 significant +digits in the short format and 15 digits in the long format. For example, +with the @samp{short e} format, @code{pi} is displayed as +@code{3.1416e+00}. + +@item short E +@itemx long E +Identical to @samp{short e} or @samp{long e} but displays an uppercase +@samp{E} to indicate the exponent. +For example, with the @samp{long E} format, @code{pi} is displayed as +@code{3.14159265358979E+00}. + +@item short g +@itemx long g +Optimally choose between fixed point and exponential format based on +the magnitude of the number. +For example, with the @samp{short g} format, +@code{pi .^ [2; 4; 8; 16; 32]} is displayed as + +@example +@group +ans = + + 9.8696 + 97.409 + 9488.5 + 9.0032e+07 + 8.1058e+15 +@end group +@end example + +@item short eng +@itemx long eng +Identical to @samp{short e} or @samp{long e} but displays the value +using an engineering format, where the exponent is divisible by 3. For +example, with the @samp{short eng} format, @code{10 * pi} is displayed as +@code{31.4159e+00}. + +@item long G +@itemx short G +Identical to @samp{short g} or @samp{long g} but displays an uppercase +@samp{E} to indicate the exponent. + +@item free +@itemx none +Print output in free format, without trying to line up columns of +matrices on the decimal point. This also causes complex numbers to be +formatted as numeric pairs like this @samp{(0.60419, 0.60709)} instead +of like this @samp{0.60419 + 0.60709i}. +@end table + +The following formats affect all numeric output (floating point and +integer types). + +@table @code +@item "+" +@itemx "+" @var{chars} +@itemx plus +@itemx plus @var{chars} +Print a @samp{+} symbol for matrix elements greater than zero, a +@samp{-} symbol for elements less than zero and a space for zero matrix +elements. This format can be very useful for examining the structure +of a large sparse matrix. + +The optional argument @var{chars} specifies a list of 3 characters to use +for printing values greater than zero, less than zero and equal to zero. +For example, with the @samp{"+" "+-."} format, +@code{[1, 0, -1; -1, 0, 1]} is displayed as + +@example +@group +ans = + ++.- +-.+ +@end group +@end example + +@item bank +Print in a fixed format with two digits to the right of the decimal +point. + +@item native-hex +Print the hexadecimal representation of numbers as they are stored in +memory. For example, on a workstation which stores 8 byte real values +in IEEE format with the least significant byte first, the value of +@code{pi} when printed in @code{native-hex} format is +@code{400921fb54442d18}. + +@item hex +The same as @code{native-hex}, but always print the most significant +byte first. + +@item native-bit +Print the bit representation of numbers as stored in memory. +For example, the value of @code{pi} is + +@example +@group +01000000000010010010000111111011 +01010100010001000010110100011000 +@end group +@end example + +(shown here in two 32 bit sections for typesetting purposes) when +printed in native-bit format on a workstation which stores 8 byte real +values in IEEE format with the least significant byte first. + +@item bit +The same as @code{native-bit}, but always print the most significant +bits first. + +@item rat +Print a rational approximation, i.e., values are approximated +as the ratio of small integers. +For example, with the @samp{rat} format, +@code{pi} is displayed as @code{355/113}. +@end table + +The following two options affect the display of all matrices. + +@table @code +@item compact +Remove blank lines around column number labels and between +matrices producing more compact output with more data per page. + +@item loose +Insert blank lines above and below column number labels and between matrices +to produce a more readable output with less data per page. (default). +@end table +@seealso{fixed_point_format, output_max_field_width, output_precision, split_long_rows, print_empty_dimensions, rats} +@end deftypefn */) { int argc = args.length () + 1; @@ -4038,165 +4038,165 @@ } DEFUN (__compactformat__, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} __compactformat__ ()\n\ -@deftypefnx {} {} __compactformat__ (@var{TRUE|FALSE})\n\ -Undocumented internal function\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} __compactformat__ () +@deftypefnx {} {} __compactformat__ (@var{TRUE|FALSE}) +Undocumented internal function +@end deftypefn */) { return SET_INTERNAL_VARIABLE (compact_format); } DEFUN (__formatstring__, , , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} __formatstring__ ()\n\ -Undocumented internal function\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} __formatstring__ () +Undocumented internal function +@end deftypefn */) { return ovl (format_string); } DEFUN (fixed_point_format, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} fixed_point_format ()\n\ -@deftypefnx {} {@var{old_val} =} fixed_point_format (@var{new_val})\n\ -@deftypefnx {} {} fixed_point_format (@var{new_val}, \"local\")\n\ -Query or set the internal variable that controls whether Octave will\n\ -use a scaled format to print matrix values.\n\ -\n\ -The scaled format prints a scaling factor on the first line of output chosen\n\ -such that the largest matrix element can be written with a single leading\n\ -digit. For example:\n\ -\n\ -@example\n\ -@group\n\ -logspace (1, 7, 5)'\n\ -ans =\n\ -\n\ - 1.0e+07 *\n\ -\n\ - 0.00000\n\ - 0.00003\n\ - 0.00100\n\ - 0.03162\n\ - 1.00000\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -Notice that the first value appears to be 0 when it is actually 1. Because\n\ -of the possibility for confusion you should be careful about enabling\n\ -@code{fixed_point_format}.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{format, output_max_field_width, output_precision}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} fixed_point_format () +@deftypefnx {} {@var{old_val} =} fixed_point_format (@var{new_val}) +@deftypefnx {} {} fixed_point_format (@var{new_val}, "local") +Query or set the internal variable that controls whether Octave will +use a scaled format to print matrix values. + +The scaled format prints a scaling factor on the first line of output chosen +such that the largest matrix element can be written with a single leading +digit. For example: + +@example +@group +logspace (1, 7, 5)' +ans = + + 1.0e+07 * + + 0.00000 + 0.00003 + 0.00100 + 0.03162 + 1.00000 +@end group +@end example + +@noindent +Notice that the first value appears to be 0 when it is actually 1. Because +of the possibility for confusion you should be careful about enabling +@code{fixed_point_format}. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{format, output_max_field_width, output_precision} +@end deftypefn */) { return SET_INTERNAL_VARIABLE (fixed_point_format); } DEFUN (print_empty_dimensions, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} print_empty_dimensions ()\n\ -@deftypefnx {} {@var{old_val} =} print_empty_dimensions (@var{new_val})\n\ -@deftypefnx {} {} print_empty_dimensions (@var{new_val}, \"local\")\n\ -Query or set the internal variable that controls whether the dimensions of\n\ -empty matrices are printed along with the empty matrix symbol, @samp{[]}.\n\ -\n\ -For example, the expression\n\ -\n\ -@example\n\ -zeros (3, 0)\n\ -@end example\n\ -\n\ -@noindent\n\ -will print\n\ -\n\ -@example\n\ -ans = [](3x0)\n\ -@end example\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{format}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} print_empty_dimensions () +@deftypefnx {} {@var{old_val} =} print_empty_dimensions (@var{new_val}) +@deftypefnx {} {} print_empty_dimensions (@var{new_val}, "local") +Query or set the internal variable that controls whether the dimensions of +empty matrices are printed along with the empty matrix symbol, @samp{[]}. + +For example, the expression + +@example +zeros (3, 0) +@end example + +@noindent +will print + +@example +ans = [](3x0) +@end example + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{format} +@end deftypefn */) { return SET_INTERNAL_VARIABLE (print_empty_dimensions); } DEFUN (split_long_rows, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} split_long_rows ()\n\ -@deftypefnx {} {@var{old_val} =} split_long_rows (@var{new_val})\n\ -@deftypefnx {} {} split_long_rows (@var{new_val}, \"local\")\n\ -Query or set the internal variable that controls whether rows of a matrix\n\ -may be split when displayed to a terminal window.\n\ -\n\ -If the rows are split, Octave will display the matrix in a series of smaller\n\ -pieces, each of which can fit within the limits of your terminal width and\n\ -each set of rows is labeled so that you can easily see which columns are\n\ -currently being displayed. For example:\n\ -\n\ -@example\n\ -@group\n\ -octave:13> rand (2,10)\n\ -ans =\n\ -\n\ - Columns 1 through 6:\n\ -\n\ - 0.75883 0.93290 0.40064 0.43818 0.94958 0.16467\n\ - 0.75697 0.51942 0.40031 0.61784 0.92309 0.40201\n\ -\n\ - Columns 7 through 10:\n\ -\n\ - 0.90174 0.11854 0.72313 0.73326\n\ - 0.44672 0.94303 0.56564 0.82150\n\ -@end group\n\ -@end example\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{format}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} split_long_rows () +@deftypefnx {} {@var{old_val} =} split_long_rows (@var{new_val}) +@deftypefnx {} {} split_long_rows (@var{new_val}, "local") +Query or set the internal variable that controls whether rows of a matrix +may be split when displayed to a terminal window. + +If the rows are split, Octave will display the matrix in a series of smaller +pieces, each of which can fit within the limits of your terminal width and +each set of rows is labeled so that you can easily see which columns are +currently being displayed. For example: + +@example +@group +octave:13> rand (2,10) +ans = + + Columns 1 through 6: + + 0.75883 0.93290 0.40064 0.43818 0.94958 0.16467 + 0.75697 0.51942 0.40031 0.61784 0.92309 0.40201 + + Columns 7 through 10: + + 0.90174 0.11854 0.72313 0.73326 + 0.44672 0.94303 0.56564 0.82150 +@end group +@end example + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{format} +@end deftypefn */) { return SET_INTERNAL_VARIABLE (split_long_rows); } DEFUN (output_max_field_width, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} output_max_field_width ()\n\ -@deftypefnx {} {@var{old_val} =} output_max_field_width (@var{new_val})\n\ -@deftypefnx {} {} output_max_field_width (@var{new_val}, \"local\")\n\ -Query or set the internal variable that specifies the maximum width\n\ -of a numeric output field.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{format, fixed_point_format, output_precision}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} output_max_field_width () +@deftypefnx {} {@var{old_val} =} output_max_field_width (@var{new_val}) +@deftypefnx {} {} output_max_field_width (@var{new_val}, "local") +Query or set the internal variable that specifies the maximum width +of a numeric output field. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{format, fixed_point_format, output_precision} +@end deftypefn */) { return SET_INTERNAL_VARIABLE_WITH_LIMITS (output_max_field_width, 0, std::numeric_limits<int>::max ()); } DEFUN (output_precision, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} output_precision ()\n\ -@deftypefnx {} {@var{old_val} =} output_precision (@var{new_val})\n\ -@deftypefnx {} {} output_precision (@var{new_val}, \"local\")\n\ -Query or set the internal variable that specifies the minimum number of\n\ -significant figures to display for numeric output.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{format, fixed_point_format, output_max_field_width}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} output_precision () +@deftypefnx {} {@var{old_val} =} output_precision (@var{new_val}) +@deftypefnx {} {} output_precision (@var{new_val}, "local") +Query or set the internal variable that specifies the minimum number of +significant figures to display for numeric output. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{format, fixed_point_format, output_max_field_width} +@end deftypefn */) { return SET_INTERNAL_VARIABLE_WITH_LIMITS (output_precision, -1, std::numeric_limits<int>::max ());
--- a/libinterp/corefcn/profiler.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/profiler.cc Tue Jun 21 16:07:51 2016 -0400 @@ -393,10 +393,10 @@ // Enable or disable the profiler data collection. DEFUN (__profiler_enable__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __profiler_enable__ ()\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __profiler_enable__ () +Undocumented internal function. +@end deftypefn */) { int nargin = args.length (); @@ -411,10 +411,10 @@ // Clear all collected profiling data. DEFUN (__profiler_reset__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __profiler_reset__ ()\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __profiler_reset__ () +Undocumented internal function. +@end deftypefn */) { if (args.length () > 0) warning ("profiler_reset: ignoring extra arguments"); @@ -426,10 +426,10 @@ // Query the timings collected by the profiler. DEFUN (__profiler_data__, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} __profiler_data__ ()\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __profiler_data__ () +Undocumented internal function. +@end deftypefn */) { if (args.length () > 0) warning ("profiler_data: ignoring extra arguments");
--- a/libinterp/corefcn/psi.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/psi.cc Tue Jun 21 16:07:51 2016 -0400 @@ -33,39 +33,39 @@ #include "lo-specfun.h" DEFUN (psi, args, , -"-*- texinfo -*-\n\ -@deftypefn {} {} psi (@var{z})\n\ -@deftypefnx {} {} psi (@var{k}, @var{z})\n\ -Compute the psi (polygamma) function.\n\ -\n\ -The polygamma functions are the @var{k}th derivative of the logarithm\n\ -of the gamma function. If unspecified, @var{k} defaults to zero. A value\n\ -of zero computes the digamma function, a value of 1, the trigamma function,\n\ -and so on.\n\ -\n\ -The digamma function is defined:\n\ -\n\ -@tex\n\ -$$\n\ -\\Psi (z) = {d (log (\\Gamma (z))) \\over dx}\n\ -$$\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ -@group\n\ -psi (z) = d (log (gamma (z))) / dx\n\ -@end group\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -\n\ -When computing the digamma function (when @var{k} equals zero), @var{z}\n\ -can have any value real or complex value. However, for polygamma functions\n\ -(@var{k} higher than 0), @var{z} must be real and non-negative.\n\ -\n\ -@seealso{gamma, gammainc, gammaln}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} psi (@var{z}) +@deftypefnx {} {} psi (@var{k}, @var{z}) +Compute the psi (polygamma) function. + +The polygamma functions are the @var{k}th derivative of the logarithm +of the gamma function. If unspecified, @var{k} defaults to zero. A value +of zero computes the digamma function, a value of 1, the trigamma function, +and so on. + +The digamma function is defined: + +@tex +$$ +\Psi (z) = {d (log (\Gamma (z))) \over dx} +$$ +@end tex +@ifnottex + +@example +@group +psi (z) = d (log (gamma (z))) / dx +@end group +@end example + +@end ifnottex + +When computing the digamma function (when @var{k} equals zero), @var{z} +can have any value real or complex value. However, for polygamma functions +(@var{k} higher than 0), @var{z} must be real and non-negative. + +@seealso{gamma, gammainc, gammaln} +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/pt-jit.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/pt-jit.cc Tue Jun 21 16:07:51 2016 -0400 @@ -2510,103 +2510,101 @@ #endif -#if defined (HAVE_LLVM) -# define UNUSED_WITHOUT_LLVM(x) x -#else -# define UNUSED_WITHOUT_LLVM(x) x OCTAVE_UNUSED -#endif - -DEFUN (jit_failcnt, UNUSED_WITHOUT_LLVM (args), - UNUSED_WITHOUT_LLVM (nargout), - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} jit_failcnt ()\n\ -@deftypefnx {} {@var{old_val} =} jit_failcnt (@var{new_val})\n\ -@deftypefnx {} {} jit_failcnt (@var{new_val}, \"local\")\n\ -Query or set the internal variable that counts the number of JIT fail\n\ -exceptions for Octave's JIT compiler.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{jit_enable, jit_startcnt, debug_jit}\n\ -@end deftypefn") +DEFUN (jit_failcnt, args, nargout, + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} jit_failcnt () +@deftypefnx {} {@var{old_val} =} jit_failcnt (@var{new_val}) +@deftypefnx {} {} jit_failcnt (@var{new_val}, "local") +Query or set the internal variable that counts the number of JIT fail +exceptions for Octave's JIT compiler. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{jit_enable, jit_startcnt, debug_jit} +@end deftypefn */) { #if defined (HAVE_LLVM) return SET_INTERNAL_VARIABLE (jit_failcnt); #else + octave_unused_parameter (args); + octave_unused_parameter (nargout); warn_disabled_feature ("jit_failcnt", "JIT compiling"); return ovl (); #endif } -DEFUN (debug_jit, UNUSED_WITHOUT_LLVM (args), - UNUSED_WITHOUT_LLVM (nargout), - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} debug_jit ()\n\ -@deftypefnx {} {@var{old_val} =} debug_jit (@var{new_val})\n\ -@deftypefnx {} {} debug_jit (@var{new_val}, \"local\")\n\ -Query or set the internal variable that determines whether\n\ -debugging/tracing is enabled for Octave's JIT compiler.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{jit_enable, jit_startcnt}\n\ -@end deftypefn") +DEFUN (debug_jit, args, nargout, + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} debug_jit () +@deftypefnx {} {@var{old_val} =} debug_jit (@var{new_val}) +@deftypefnx {} {} debug_jit (@var{new_val}, "local") +Query or set the internal variable that determines whether +debugging/tracing is enabled for Octave's JIT compiler. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{jit_enable, jit_startcnt} +@end deftypefn */) { #if defined (HAVE_LLVM) return SET_INTERNAL_VARIABLE (debug_jit); #else + octave_unused_parameter (args); + octave_unused_parameter (nargout); warn_disabled_feature ("debug_jit", "JIT"); return ovl (); #endif } -DEFUN (jit_enable, UNUSED_WITHOUT_LLVM (args), - UNUSED_WITHOUT_LLVM (nargout), - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} jit_enable ()\n\ -@deftypefnx {} {@var{old_val} =} jit_enable (@var{new_val})\n\ -@deftypefnx {} {} jit_enable (@var{new_val}, \"local\")\n\ -Query or set the internal variable that enables Octave's JIT compiler.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{jit_startcnt, debug_jit}\n\ -@end deftypefn") +DEFUN (jit_enable, args, nargout, + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} jit_enable () +@deftypefnx {} {@var{old_val} =} jit_enable (@var{new_val}) +@deftypefnx {} {} jit_enable (@var{new_val}, "local") +Query or set the internal variable that enables Octave's JIT compiler. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{jit_startcnt, debug_jit} +@end deftypefn */) { #if defined (HAVE_LLVM) return SET_INTERNAL_VARIABLE (jit_enable); #else + octave_unused_parameter (args); + octave_unused_parameter (nargout); warn_disabled_feature ("jit_enable", "JIT"); return ovl (); #endif } -DEFUN (jit_startcnt, UNUSED_WITHOUT_LLVM (args), - UNUSED_WITHOUT_LLVM (nargout), - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} jit_startcnt ()\n\ -@deftypefnx {} {@var{old_val} =} jit_startcnt (@var{new_val})\n\ -@deftypefnx {} {} jit_startcnt (@var{new_val}, \"local\")\n\ -Query or set the internal variable that determines whether JIT compilation\n\ -will take place for a specific loop.\n\ -\n\ -Because compilation is a costly operation it does not make sense to employ\n\ -JIT when the loop count is low. By default only loops with greater than\n\ -1000 iterations will be accelerated.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{jit_enable, jit_failcnt, debug_jit}\n\ -@end deftypefn") +DEFUN (jit_startcnt, args, nargout, + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} jit_startcnt () +@deftypefnx {} {@var{old_val} =} jit_startcnt (@var{new_val}) +@deftypefnx {} {} jit_startcnt (@var{new_val}, "local") +Query or set the internal variable that determines whether JIT compilation +will take place for a specific loop. + +Because compilation is a costly operation it does not make sense to employ +JIT when the loop count is low. By default only loops with greater than +1000 iterations will be accelerated. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{jit_enable, jit_failcnt, debug_jit} +@end deftypefn */) { #if defined (HAVE_LLVM) return SET_INTERNAL_VARIABLE_WITH_LIMITS (jit_startcnt, 1, std::numeric_limits<int>::max ()); #else + octave_unused_parameter (args); + octave_unused_parameter (nargout); warn_disabled_feature ("jit_enable", "JIT"); return ovl (); #endif
--- a/libinterp/corefcn/quad.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/quad.cc Tue Jun 21 16:07:51 2016 -0400 @@ -130,50 +130,50 @@ } DEFUN (quad, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{q} =} quad (@var{f}, @var{a}, @var{b})\n\ -@deftypefnx {} {@var{q} =} quad (@var{f}, @var{a}, @var{b}, @var{tol})\n\ -@deftypefnx {} {@var{q} =} quad (@var{f}, @var{a}, @var{b}, @var{tol}, @var{sing})\n\ -@deftypefnx {} {[@var{q}, @var{ier}, @var{nfun}, @var{err}] =} quad (@dots{})\n\ -Numerically evaluate the integral of @var{f} from @var{a} to @var{b} using\n\ -Fortran routines from @w{@sc{quadpack}}.\n\ -\n\ -@var{f} is a function handle, inline function, or a string containing the\n\ -name of the function to evaluate. The function must have the form @code{y =\n\ -f (x)} where @var{y} and @var{x} are scalars.\n\ -\n\ -@var{a} and @var{b} are the lower and upper limits of integration. Either\n\ -or both may be infinite.\n\ -\n\ -The optional argument @var{tol} is a vector that specifies the desired\n\ -accuracy of the result. The first element of the vector is the desired\n\ -absolute tolerance, and the second element is the desired relative\n\ -tolerance. To choose a relative test only, set the absolute\n\ -tolerance to zero. To choose an absolute test only, set the relative\n\ -tolerance to zero. Both tolerances default to @code{sqrt (eps)} or\n\ -approximately @math{1.5e^{-8}}.\n\ -\n\ -The optional argument @var{sing} is a vector of values at which the\n\ -integrand is known to be singular.\n\ -\n\ -The result of the integration is returned in @var{q}.\n\ -\n\ -@var{ier} contains an integer error code (0 indicates a successful\n\ -integration).\n\ -\n\ -@var{nfun} indicates the number of function evaluations that were\n\ -made.\n\ -\n\ -@var{err} contains an estimate of the error in the solution.\n\ -\n\ -The function @code{quad_options} can set other optional parameters for\n\ -@code{quad}.\n\ -\n\ -Note: because @code{quad} is written in Fortran it cannot be called\n\ -recursively. This prevents its use in integrating over more than one\n\ -variable by routines @code{dblquad} and @code{triplequad}.\n\ -@seealso{quad_options, quadv, quadl, quadgk, quadcc, trapz, dblquad, triplequad}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{q} =} quad (@var{f}, @var{a}, @var{b}) +@deftypefnx {} {@var{q} =} quad (@var{f}, @var{a}, @var{b}, @var{tol}) +@deftypefnx {} {@var{q} =} quad (@var{f}, @var{a}, @var{b}, @var{tol}, @var{sing}) +@deftypefnx {} {[@var{q}, @var{ier}, @var{nfun}, @var{err}] =} quad (@dots{}) +Numerically evaluate the integral of @var{f} from @var{a} to @var{b} using +Fortran routines from @w{@sc{quadpack}}. + +@var{f} is a function handle, inline function, or a string containing the +name of the function to evaluate. The function must have the form @code{y = +f (x)} where @var{y} and @var{x} are scalars. + +@var{a} and @var{b} are the lower and upper limits of integration. Either +or both may be infinite. + +The optional argument @var{tol} is a vector that specifies the desired +accuracy of the result. The first element of the vector is the desired +absolute tolerance, and the second element is the desired relative +tolerance. To choose a relative test only, set the absolute +tolerance to zero. To choose an absolute test only, set the relative +tolerance to zero. Both tolerances default to @code{sqrt (eps)} or +approximately @math{1.5e^{-8}}. + +The optional argument @var{sing} is a vector of values at which the +integrand is known to be singular. + +The result of the integration is returned in @var{q}. + +@var{ier} contains an integer error code (0 indicates a successful +integration). + +@var{nfun} indicates the number of function evaluations that were +made. + +@var{err} contains an estimate of the error in the solution. + +The function @code{quad_options} can set other optional parameters for +@code{quad}. + +Note: because @code{quad} is written in Fortran it cannot be called +recursively. This prevents its use in integrating over more than one +variable by routines @code{dblquad} and @code{triplequad}. +@seealso{quad_options, quadv, quadl, quadgk, quadcc, trapz, dblquad, triplequad} +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/quadcc.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/quadcc.cc Tue Jun 21 16:07:51 2016 -0400 @@ -1478,75 +1478,75 @@ // The actual integration routine. DEFUN (quadcc, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{q} =} quadcc (@var{f}, @var{a}, @var{b})\n\ -@deftypefnx {} {@var{q} =} quadcc (@var{f}, @var{a}, @var{b}, @var{tol})\n\ -@deftypefnx {} {@var{q} =} quadcc (@var{f}, @var{a}, @var{b}, @var{tol}, @var{sing})\n\ -@deftypefnx {} {[@var{q}, @var{err}, @var{nr_points}] =} quadcc (@dots{})\n\ -Numerically evaluate the integral of @var{f} from @var{a} to @var{b}\n\ -using doubly-adaptive @nospell{Clenshaw-Curtis} quadrature.\n\ -\n\ -@var{f} is a function handle, inline function, or string containing the name\n\ -of the function to evaluate. The function @var{f} must be vectorized and\n\ -must return a vector of output values if given a vector of input values.\n\ -For example,\n\ -\n\ -@example\n\ -f = @@(x) x .* sin (1./x) .* sqrt (abs (1 - x));\n\ -@end example\n\ -\n\ -@noindent\n\ -which uses the element-by-element ``dot'' form for all operators.\n\ -\n\ -@var{a} and @var{b} are the lower and upper limits of integration. Either\n\ -or both limits may be infinite. @code{quadcc} handles an inifinite limit\n\ -by substituting the variable of integration with @code{x = tan (pi/2*u)}.\n\ -\n\ -The optional argument @var{tol} defines the relative tolerance used to stop\n\ -the integration procedure. The default value is @math{1e^{-6}}.\n\ -\n\ -The optional argument @var{sing} contains a list of points where the\n\ -integrand has known singularities, or discontinuities\n\ -in any of its derivatives, inside the integration interval.\n\ -For the example above, which has a discontinuity at x=1, the call to\n\ -@code{quadcc} would be as follows\n\ -\n\ -@example\n\ -int = quadcc (f, a, b, 1.0e-6, [ 1 ]);\n\ -@end example\n\ -\n\ -The result of the integration is returned in @var{q}.\n\ -\n\ -@var{err} is an estimate of the absolute integration error.\n\ -\n\ -@var{nr_points} is the number of points at which the integrand was\n\ -evaluated.\n\ -\n\ -If the adaptive integration did not converge, the value of @var{err} will be\n\ -larger than the requested tolerance. Therefore, it is recommended to verify\n\ -this value for difficult integrands.\n\ -\n\ -@code{quadcc} is capable of dealing with non-numeric values of the integrand\n\ -such as @code{NaN} or @code{Inf}. If the integral diverges, and\n\ -@code{quadcc} detects this, then a warning is issued and @code{Inf} or\n\ -@code{-Inf} is returned.\n\ -\n\ -Note: @code{quadcc} is a general purpose quadrature algorithm and, as such,\n\ -may be less efficient for a smooth or otherwise well-behaved integrand than\n\ -other methods such as @code{quadgk}.\n\ -\n\ -The algorithm uses @nospell{Clenshaw-Curtis} quadrature rules of increasing\n\ -degree in each interval and bisects the interval if either the function does\n\ -not appear to be smooth or a rule of maximum degree has been reached. The\n\ -error estimate is computed from the L2-norm of the difference between two\n\ -successive interpolations of the integrand over the nodes of the respective\n\ -quadrature rules.\n\ -\n\ -Reference: @nospell{P. Gonnet}, @cite{Increasing the Reliability of Adaptive\n\ -Quadrature Using Explicit Interpolants}, ACM Transactions on\n\ -Mathematical Software, Vol. 37, Issue 3, Article No. 3, 2010.\n\ -@seealso{quad, quadv, quadl, quadgk, trapz, dblquad, triplequad}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{q} =} quadcc (@var{f}, @var{a}, @var{b}) +@deftypefnx {} {@var{q} =} quadcc (@var{f}, @var{a}, @var{b}, @var{tol}) +@deftypefnx {} {@var{q} =} quadcc (@var{f}, @var{a}, @var{b}, @var{tol}, @var{sing}) +@deftypefnx {} {[@var{q}, @var{err}, @var{nr_points}] =} quadcc (@dots{}) +Numerically evaluate the integral of @var{f} from @var{a} to @var{b} +using doubly-adaptive @nospell{Clenshaw-Curtis} quadrature. + +@var{f} is a function handle, inline function, or string containing the name +of the function to evaluate. The function @var{f} must be vectorized and +must return a vector of output values if given a vector of input values. +For example, + +@example +f = @@(x) x .* sin (1./x) .* sqrt (abs (1 - x)); +@end example + +@noindent +which uses the element-by-element ``dot'' form for all operators. + +@var{a} and @var{b} are the lower and upper limits of integration. Either +or both limits may be infinite. @code{quadcc} handles an inifinite limit +by substituting the variable of integration with @code{x = tan (pi/2*u)}. + +The optional argument @var{tol} defines the relative tolerance used to stop +the integration procedure. The default value is @math{1e^{-6}}. + +The optional argument @var{sing} contains a list of points where the +integrand has known singularities, or discontinuities +in any of its derivatives, inside the integration interval. +For the example above, which has a discontinuity at x=1, the call to +@code{quadcc} would be as follows + +@example +int = quadcc (f, a, b, 1.0e-6, [ 1 ]); +@end example + +The result of the integration is returned in @var{q}. + +@var{err} is an estimate of the absolute integration error. + +@var{nr_points} is the number of points at which the integrand was +evaluated. + +If the adaptive integration did not converge, the value of @var{err} will be +larger than the requested tolerance. Therefore, it is recommended to verify +this value for difficult integrands. + +@code{quadcc} is capable of dealing with non-numeric values of the integrand +such as @code{NaN} or @code{Inf}. If the integral diverges, and +@code{quadcc} detects this, then a warning is issued and @code{Inf} or +@code{-Inf} is returned. + +Note: @code{quadcc} is a general purpose quadrature algorithm and, as such, +may be less efficient for a smooth or otherwise well-behaved integrand than +other methods such as @code{quadgk}. + +The algorithm uses @nospell{Clenshaw-Curtis} quadrature rules of increasing +degree in each interval and bisects the interval if either the function does +not appear to be smooth or a rule of maximum degree has been reached. The +error estimate is computed from the L2-norm of the difference between two +successive interpolations of the integrand over the nodes of the respective +quadrature rules. + +Reference: @nospell{P. Gonnet}, @cite{Increasing the Reliability of Adaptive +Quadrature Using Explicit Interpolants}, ACM Transactions on +Mathematical Software, Vol. 37, Issue 3, Article No. 3, 2010. +@seealso{quad, quadv, quadl, quadgk, trapz, dblquad, triplequad} +@end deftypefn */) { // Some constants that we will need. static const int n[4] = { 4, 8, 16, 32 };
--- a/libinterp/corefcn/qz.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/qz.cc Tue Jun 21 16:07:51 2016 -0400 @@ -290,87 +290,87 @@ //FIXME: Matlab does not produce lambda as the first output argument. // Compatibility problem? DEFUN (qz, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{lambda} =} qz (@var{A}, @var{B})\n\ -@deftypefnx {} {@var{lambda} =} qz (@var{A}, @var{B}, @var{opt})\n\ -QZ@tie{}decomposition of the generalized eigenvalue problem\n\ -(@math{A x = s B x}).\n\ -\n\ -There are three ways to call this function:\n\ -@enumerate\n\ -@item @code{@var{lambda} = qz (@var{A}, @var{B})}\n\ -\n\ -Computes the generalized eigenvalues\n\ -@tex\n\ -$\\lambda$\n\ -@end tex\n\ -@ifnottex\n\ -@var{lambda}\n\ -@end ifnottex\n\ -of @math{(A - s B)}.\n\ -\n\ -@item @code{[AA, BB, Q, Z, V, W, @var{lambda}] = qz (@var{A}, @var{B})}\n\ -\n\ -Computes QZ@tie{}decomposition, generalized eigenvectors, and generalized\n\ -eigenvalues of @math{(A - s B)}\n\ -@tex\n\ -$$ AV = BV{ \\rm diag }(\\lambda) $$\n\ -$$ W^T A = { \\rm diag }(\\lambda)W^T B $$\n\ -$$ AA = Q^T AZ, BB = Q^T BZ $$\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ -@group\n\ -\n\ -A * V = B * V * diag (@var{lambda})\n\ -W' * A = diag (@var{lambda}) * W' * B\n\ -AA = Q * A * Z, BB = Q * B * Z\n\ -\n\ -@end group\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -with @var{Q} and @var{Z} orthogonal (unitary)= @var{I}\n\ -\n\ -@item @code{[AA,BB,Z@{, @var{lambda}@}] = qz (@var{A}, @var{B}, @var{opt})}\n\ -\n\ -As in form [2], but allows ordering of generalized eigenpairs for, e.g.,\n\ -solution of discrete time algebraic Riccati equations. Form 3 is not\n\ -available for complex matrices, and does not compute the generalized\n\ -eigenvectors @var{V}, @var{W}, nor the orthogonal matrix @var{Q}.\n\ -\n\ -@table @var\n\ -@item opt\n\ -for ordering eigenvalues of the @nospell{GEP} pencil. The leading block of\n\ -the revised pencil contains all eigenvalues that satisfy:\n\ -\n\ -@table @asis\n\ -@item @qcode{\"N\"}\n\ -= unordered (default)\n\ -\n\ -@item @qcode{\"S\"}\n\ -= small: leading block has all |lambda| @leq{} 1\n\ -\n\ -@item @qcode{\"B\"}\n\ -= big: leading block has all |lambda| @geq{} 1\n\ -\n\ -@item @qcode{\"-\"}\n\ -= negative real part: leading block has all eigenvalues\n\ -in the open left half-plane\n\ -\n\ -@item @qcode{\"+\"}\n\ -= non-negative real part: leading block has all eigenvalues\n\ -in the closed right half-plane\n\ -@end table\n\ -@end table\n\ -@end enumerate\n\ -\n\ -Note: @code{qz} performs permutation balancing, but not scaling\n\ -(@pxref{XREFbalance}). The order of output arguments was selected for\n\ -compatibility with @sc{matlab}.\n\ -@seealso{eig, balance, lu, chol, hess, qr, qzhess, schur, svd}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{lambda} =} qz (@var{A}, @var{B}) +@deftypefnx {} {@var{lambda} =} qz (@var{A}, @var{B}, @var{opt}) +QZ@tie{}decomposition of the generalized eigenvalue problem +(@math{A x = s B x}). + +There are three ways to call this function: +@enumerate +@item @code{@var{lambda} = qz (@var{A}, @var{B})} + +Computes the generalized eigenvalues +@tex +$\lambda$ +@end tex +@ifnottex +@var{lambda} +@end ifnottex +of @math{(A - s B)}. + +@item @code{[AA, BB, Q, Z, V, W, @var{lambda}] = qz (@var{A}, @var{B})} + +Computes QZ@tie{}decomposition, generalized eigenvectors, and generalized +eigenvalues of @math{(A - s B)} +@tex +$$ AV = BV{ \rm diag }(\lambda) $$ +$$ W^T A = { \rm diag }(\lambda)W^T B $$ +$$ AA = Q^T AZ, BB = Q^T BZ $$ +@end tex +@ifnottex + +@example +@group + +A * V = B * V * diag (@var{lambda}) +W' * A = diag (@var{lambda}) * W' * B +AA = Q * A * Z, BB = Q * B * Z + +@end group +@end example + +@end ifnottex +with @var{Q} and @var{Z} orthogonal (unitary)= @var{I} + +@item @code{[AA,BB,Z@{, @var{lambda}@}] = qz (@var{A}, @var{B}, @var{opt})} + +As in form [2], but allows ordering of generalized eigenpairs for, e.g., +solution of discrete time algebraic Riccati equations. Form 3 is not +available for complex matrices, and does not compute the generalized +eigenvectors @var{V}, @var{W}, nor the orthogonal matrix @var{Q}. + +@table @var +@item opt +for ordering eigenvalues of the @nospell{GEP} pencil. The leading block of +the revised pencil contains all eigenvalues that satisfy: + +@table @asis +@item @qcode{"N"} += unordered (default) + +@item @qcode{"S"} += small: leading block has all |lambda| @leq{} 1 + +@item @qcode{"B"} += big: leading block has all |lambda| @geq{} 1 + +@item @qcode{"-"} += negative real part: leading block has all eigenvalues +in the open left half-plane + +@item @qcode{"+"} += non-negative real part: leading block has all eigenvalues +in the closed right half-plane +@end table +@end table +@end enumerate + +Note: @code{qz} performs permutation balancing, but not scaling +(@pxref{XREFbalance}). The order of output arguments was selected for +compatibility with @sc{matlab}. +@seealso{eig, balance, lu, chol, hess, qr, qzhess, schur, svd} +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/rand.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/rand.cc Tue Jun 21 16:07:51 2016 -0400 @@ -329,93 +329,93 @@ } DEFUN (rand, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} rand (@var{n})\n\ -@deftypefnx {} {} rand (@var{m}, @var{n}, @dots{})\n\ -@deftypefnx {} {} rand ([@var{m} @var{n} @dots{}])\n\ -@deftypefnx {} {@var{v} =} rand (\"state\")\n\ -@deftypefnx {} {} rand (\"state\", @var{v})\n\ -@deftypefnx {} {} rand (\"state\", \"reset\")\n\ -@deftypefnx {} {@var{v} =} rand (\"seed\")\n\ -@deftypefnx {} {} rand (\"seed\", @var{v})\n\ -@deftypefnx {} {} rand (\"seed\", \"reset\")\n\ -@deftypefnx {} {} rand (@dots{}, \"single\")\n\ -@deftypefnx {} {} rand (@dots{}, \"double\")\n\ -Return a matrix with random elements uniformly distributed on the\n\ -interval (0, 1).\n\ -\n\ -The arguments are handled the same as the arguments for @code{eye}.\n\ -\n\ -You can query the state of the random number generator using the form\n\ -\n\ -@example\n\ -v = rand (\"state\")\n\ -@end example\n\ -\n\ -This returns a column vector @var{v} of length 625. Later, you can restore\n\ -the random number generator to the state @var{v} using the form\n\ -\n\ -@example\n\ -rand (\"state\", v)\n\ -@end example\n\ -\n\ -@noindent\n\ -You may also initialize the state vector from an arbitrary vector of length\n\ -@leq{} 625 for @var{v}. This new state will be a hash based on the value of\n\ -@var{v}, not @var{v} itself.\n\ -\n\ -By default, the generator is initialized from @code{/dev/urandom} if it is\n\ -available, otherwise from CPU time, wall clock time, and the current\n\ -fraction of a second. Note that this differs from @sc{matlab}, which\n\ -always initializes the state to the same state at startup. To obtain\n\ -behavior comparable to @sc{matlab}, initialize with a deterministic state\n\ -vector in Octave's startup files (@pxref{Startup Files}).\n\ -\n\ -To compute the pseudo-random sequence, @code{rand} uses the Mersenne\n\ -Twister with a period of @math{2^{19937}-1}\n\ -(See @nospell{M. Matsumoto and T. Nishimura},\n\ -@cite{Mersenne Twister: A 623-dimensionally equidistributed uniform\n\ -pseudorandom number generator},\n\ -ACM Trans. on Modeling and Computer Simulation Vol. 8, No. 1, pp. 3--30,\n\ -January 1998,\n\ -@url{http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html}).\n\ -Do @strong{not} use for cryptography without securely hashing several\n\ -returned values together, otherwise the generator state can be learned after\n\ -reading 624 consecutive values.\n\ -\n\ -Older versions of Octave used a different random number generator.\n\ -The new generator is used by default as it is significantly faster than the\n\ -old generator, and produces random numbers with a significantly longer cycle\n\ -time. However, in some circumstances it might be desirable to obtain the\n\ -same random sequences as produced by the old generators. To do this the\n\ -keyword @qcode{\"seed\"} is used to specify that the old generators should\n\ -be used, as in\n\ -\n\ -@example\n\ -rand (\"seed\", val)\n\ -@end example\n\ -\n\ -@noindent\n\ -which sets the seed of the generator to @var{val}. The seed of the\n\ -generator can be queried with\n\ -\n\ -@example\n\ -s = rand (\"seed\")\n\ -@end example\n\ -\n\ -However, it should be noted that querying the seed will not cause\n\ -@code{rand} to use the old generators, only setting the seed will. To cause\n\ -@code{rand} to once again use the new generators, the keyword\n\ -@qcode{\"state\"} should be used to reset the state of the @code{rand}.\n\ -\n\ -The state or seed of the generator can be reset to a new random value using\n\ -the @qcode{\"reset\"} keyword.\n\ -\n\ -The class of the value returned can be controlled by a trailing\n\ -@qcode{\"double\"} or @qcode{\"single\"} argument. These are the only valid\n\ -classes.\n\ -@seealso{randn, rande, randg, randp}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} rand (@var{n}) +@deftypefnx {} {} rand (@var{m}, @var{n}, @dots{}) +@deftypefnx {} {} rand ([@var{m} @var{n} @dots{}]) +@deftypefnx {} {@var{v} =} rand ("state") +@deftypefnx {} {} rand ("state", @var{v}) +@deftypefnx {} {} rand ("state", "reset") +@deftypefnx {} {@var{v} =} rand ("seed") +@deftypefnx {} {} rand ("seed", @var{v}) +@deftypefnx {} {} rand ("seed", "reset") +@deftypefnx {} {} rand (@dots{}, "single") +@deftypefnx {} {} rand (@dots{}, "double") +Return a matrix with random elements uniformly distributed on the +interval (0, 1). + +The arguments are handled the same as the arguments for @code{eye}. + +You can query the state of the random number generator using the form + +@example +v = rand ("state") +@end example + +This returns a column vector @var{v} of length 625. Later, you can restore +the random number generator to the state @var{v} using the form + +@example +rand ("state", v) +@end example + +@noindent +You may also initialize the state vector from an arbitrary vector of length +@leq{} 625 for @var{v}. This new state will be a hash based on the value of +@var{v}, not @var{v} itself. + +By default, the generator is initialized from @code{/dev/urandom} if it is +available, otherwise from CPU time, wall clock time, and the current +fraction of a second. Note that this differs from @sc{matlab}, which +always initializes the state to the same state at startup. To obtain +behavior comparable to @sc{matlab}, initialize with a deterministic state +vector in Octave's startup files (@pxref{Startup Files}). + +To compute the pseudo-random sequence, @code{rand} uses the Mersenne +Twister with a period of @math{2^{19937}-1} +(See @nospell{M. Matsumoto and T. Nishimura}, +@cite{Mersenne Twister: A 623-dimensionally equidistributed uniform +pseudorandom number generator}, +ACM Trans. on Modeling and Computer Simulation Vol. 8, No. 1, pp. 3--30, +January 1998, +@url{http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html}). +Do @strong{not} use for cryptography without securely hashing several +returned values together, otherwise the generator state can be learned after +reading 624 consecutive values. + +Older versions of Octave used a different random number generator. +The new generator is used by default as it is significantly faster than the +old generator, and produces random numbers with a significantly longer cycle +time. However, in some circumstances it might be desirable to obtain the +same random sequences as produced by the old generators. To do this the +keyword @qcode{"seed"} is used to specify that the old generators should +be used, as in + +@example +rand ("seed", val) +@end example + +@noindent +which sets the seed of the generator to @var{val}. The seed of the +generator can be queried with + +@example +s = rand ("seed") +@end example + +However, it should be noted that querying the seed will not cause +@code{rand} to use the old generators, only setting the seed will. To cause +@code{rand} to once again use the new generators, the keyword +@qcode{"state"} should be used to reset the state of the @code{rand}. + +The state or seed of the generator can be reset to a new random value using +the @qcode{"reset"} keyword. + +The class of the value returned can be controlled by a trailing +@qcode{"double"} or @qcode{"single"} argument. These are the only valid +classes. +@seealso{randn, rande, randg, randp} +@end deftypefn */) { return do_rand (args, args.length (), "rand", "uniform"); } @@ -508,37 +508,37 @@ static std::string current_distribution = octave_rand::distribution (); DEFUN (randn, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} randn (@var{n})\n\ -@deftypefnx {} {} randn (@var{m}, @var{n}, @dots{})\n\ -@deftypefnx {} {} randn ([@var{m} @var{n} @dots{}])\n\ -@deftypefnx {} {@var{v} =} randn (\"state\")\n\ -@deftypefnx {} {} randn (\"state\", @var{v})\n\ -@deftypefnx {} {} randn (\"state\", \"reset\")\n\ -@deftypefnx {} {@var{v} =} randn (\"seed\")\n\ -@deftypefnx {} {} randn (\"seed\", @var{v})\n\ -@deftypefnx {} {} randn (\"seed\", \"reset\")\n\ -@deftypefnx {} {} randn (@dots{}, \"single\")\n\ -@deftypefnx {} {} randn (@dots{}, \"double\")\n\ -Return a matrix with normally distributed random elements having zero mean\n\ -and variance one.\n\ -\n\ -The arguments are handled the same as the arguments for @code{rand}.\n\ -\n\ -By default, @code{randn} uses the @nospell{Marsaglia and Tsang}\n\ -``Ziggurat technique'' to transform from a uniform to a normal distribution.\n\ -\n\ -The class of the value returned can be controlled by a trailing\n\ -@qcode{\"double\"} or @qcode{\"single\"} argument. These are the only valid\n\ -classes.\n\ -\n\ -Reference: @nospell{G. Marsaglia and W.W. Tsang},\n\ -@cite{Ziggurat Method for Generating Random Variables},\n\ -J. Statistical Software, vol 5, 2000,\n\ -@url{http://www.jstatsoft.org/v05/i08/}\n\ -\n\ -@seealso{rand, rande, randg, randp}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} randn (@var{n}) +@deftypefnx {} {} randn (@var{m}, @var{n}, @dots{}) +@deftypefnx {} {} randn ([@var{m} @var{n} @dots{}]) +@deftypefnx {} {@var{v} =} randn ("state") +@deftypefnx {} {} randn ("state", @var{v}) +@deftypefnx {} {} randn ("state", "reset") +@deftypefnx {} {@var{v} =} randn ("seed") +@deftypefnx {} {} randn ("seed", @var{v}) +@deftypefnx {} {} randn ("seed", "reset") +@deftypefnx {} {} randn (@dots{}, "single") +@deftypefnx {} {} randn (@dots{}, "double") +Return a matrix with normally distributed random elements having zero mean +and variance one. + +The arguments are handled the same as the arguments for @code{rand}. + +By default, @code{randn} uses the @nospell{Marsaglia and Tsang} +``Ziggurat technique'' to transform from a uniform to a normal distribution. + +The class of the value returned can be controlled by a trailing +@qcode{"double"} or @qcode{"single"} argument. These are the only valid +classes. + +Reference: @nospell{G. Marsaglia and W.W. Tsang}, +@cite{Ziggurat Method for Generating Random Variables}, +J. Statistical Software, vol 5, 2000, +@url{http://www.jstatsoft.org/v05/i08/} + +@seealso{rand, rande, randg, randp} +@end deftypefn */) { return do_rand (args, args.length (), "randn", "normal"); } @@ -575,37 +575,37 @@ */ DEFUN (rande, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} rande (@var{n})\n\ -@deftypefnx {} {} rande (@var{m}, @var{n}, @dots{})\n\ -@deftypefnx {} {} rande ([@var{m} @var{n} @dots{}])\n\ -@deftypefnx {} {@var{v} =} rande (\"state\")\n\ -@deftypefnx {} {} rande (\"state\", @var{v})\n\ -@deftypefnx {} {} rande (\"state\", \"reset\")\n\ -@deftypefnx {} {@var{v} =} rande (\"seed\")\n\ -@deftypefnx {} {} rande (\"seed\", @var{v})\n\ -@deftypefnx {} {} rande (\"seed\", \"reset\")\n\ -@deftypefnx {} {} rande (@dots{}, \"single\")\n\ -@deftypefnx {} {} rande (@dots{}, \"double\")\n\ -Return a matrix with exponentially distributed random elements.\n\ -\n\ -The arguments are handled the same as the arguments for @code{rand}.\n\ -\n\ -By default, @code{rande} uses the @nospell{Marsaglia and Tsang}\n\ -``Ziggurat technique'' to transform from a uniform to an exponential\n\ -distribution.\n\ -\n\ -The class of the value returned can be controlled by a trailing\n\ -@qcode{\"double\"} or @qcode{\"single\"} argument. These are the only valid\n\ -classes.\n\ -\n\ -Reference: @nospell{G. Marsaglia and W.W. Tsang},\n\ -@cite{Ziggurat Method for Generating Random Variables},\n\ -J. Statistical Software, vol 5, 2000,\n\ -@url{http://www.jstatsoft.org/v05/i08/}\n\ -\n\ -@seealso{rand, randn, randg, randp}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} rande (@var{n}) +@deftypefnx {} {} rande (@var{m}, @var{n}, @dots{}) +@deftypefnx {} {} rande ([@var{m} @var{n} @dots{}]) +@deftypefnx {} {@var{v} =} rande ("state") +@deftypefnx {} {} rande ("state", @var{v}) +@deftypefnx {} {} rande ("state", "reset") +@deftypefnx {} {@var{v} =} rande ("seed") +@deftypefnx {} {} rande ("seed", @var{v}) +@deftypefnx {} {} rande ("seed", "reset") +@deftypefnx {} {} rande (@dots{}, "single") +@deftypefnx {} {} rande (@dots{}, "double") +Return a matrix with exponentially distributed random elements. + +The arguments are handled the same as the arguments for @code{rand}. + +By default, @code{rande} uses the @nospell{Marsaglia and Tsang} +``Ziggurat technique'' to transform from a uniform to an exponential +distribution. + +The class of the value returned can be controlled by a trailing +@qcode{"double"} or @qcode{"single"} argument. These are the only valid +classes. + +Reference: @nospell{G. Marsaglia and W.W. Tsang}, +@cite{Ziggurat Method for Generating Random Variables}, +J. Statistical Software, vol 5, 2000, +@url{http://www.jstatsoft.org/v05/i08/} + +@seealso{rand, randn, randg, randp} +@end deftypefn */) { return do_rand (args, args.length (), "rande", "exponential"); } @@ -644,104 +644,104 @@ */ DEFUN (randg, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} randg (@var{n})\n\ -@deftypefnx {} {} randg (@var{m}, @var{n}, @dots{})\n\ -@deftypefnx {} {} randg ([@var{m} @var{n} @dots{}])\n\ -@deftypefnx {} {@var{v} =} randg (\"state\")\n\ -@deftypefnx {} {} randg (\"state\", @var{v})\n\ -@deftypefnx {} {} randg (\"state\", \"reset\")\n\ -@deftypefnx {} {@var{v} =} randg (\"seed\")\n\ -@deftypefnx {} {} randg (\"seed\", @var{v})\n\ -@deftypefnx {} {} randg (\"seed\", \"reset\")\n\ -@deftypefnx {} {} randg (@dots{}, \"single\")\n\ -@deftypefnx {} {} randg (@dots{}, \"double\")\n\ -Return a matrix with @code{gamma (@var{a},1)} distributed random elements.\n\ -\n\ -The arguments are handled the same as the arguments for @code{rand}, except\n\ -for the argument @var{a}.\n\ -\n\ -This can be used to generate many distributions:\n\ -\n\ -@table @asis\n\ -@item @code{gamma (a, b)} for @code{a > -1}, @code{b > 0}\n\ -\n\ -@example\n\ -r = b * randg (a)\n\ -@end example\n\ -\n\ -@item @code{beta (a, b)} for @code{a > -1}, @code{b > -1}\n\ -\n\ -@example\n\ -@group\n\ -r1 = randg (a, 1)\n\ -r = r1 / (r1 + randg (b, 1))\n\ -@end group\n\ -@end example\n\ -\n\ -@item @code{Erlang (a, n)}\n\ -\n\ -@example\n\ -r = a * randg (n)\n\ -@end example\n\ -\n\ -@item @code{chisq (df)} for @code{df > 0}\n\ -\n\ -@example\n\ -r = 2 * randg (df / 2)\n\ -@end example\n\ -\n\ -@item @code{t (df)} for @code{0 < df < inf} (use randn if df is infinite)\n\ -\n\ -@example\n\ -r = randn () / sqrt (2 * randg (df / 2) / df)\n\ -@end example\n\ -\n\ -@item @code{F (n1, n2)} for @code{0 < n1}, @code{0 < n2}\n\ -\n\ -@example\n\ -@group\n\ -## r1 equals 1 if n1 is infinite\n\ -r1 = 2 * randg (n1 / 2) / n1\n\ -## r2 equals 1 if n2 is infinite\n\ -r2 = 2 * randg (n2 / 2) / n2\n\ -r = r1 / r2\n\n\ -@end group\n\ -@end example\n\ -\n\ -@item negative @code{binomial (n, p)} for @code{n > 0}, @code{0 < p <= 1}\n\ -\n\ -@example\n\ -r = randp ((1 - p) / p * randg (n))\n\ -@end example\n\ -\n\ -@item non-central @code{chisq (df, L)}, for @code{df >= 0} and @code{L > 0}\n\ -(use chisq if @code{L = 0})\n\ -\n\ -@example\n\ -@group\n\ -r = randp (L / 2)\n\ -r(r > 0) = 2 * randg (r(r > 0))\n\ -r(df > 0) += 2 * randg (df(df > 0)/2)\n\ -@end group\n\ -@end example\n\ -\n\ -@item @code{Dirichlet (a1, @dots{} ak)}\n\ -\n\ -@example\n\ -@group\n\ -r = (randg (a1), @dots{}, randg (ak))\n\ -r = r / sum (r)\n\ -@end group\n\ -@end example\n\ -\n\ -@end table\n\ -\n\ -The class of the value returned can be controlled by a trailing\n\ -@qcode{\"double\"} or @qcode{\"single\"} argument. These are the only valid\n\ -classes.\n\ -@seealso{rand, randn, rande, randp}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} randg (@var{n}) +@deftypefnx {} {} randg (@var{m}, @var{n}, @dots{}) +@deftypefnx {} {} randg ([@var{m} @var{n} @dots{}]) +@deftypefnx {} {@var{v} =} randg ("state") +@deftypefnx {} {} randg ("state", @var{v}) +@deftypefnx {} {} randg ("state", "reset") +@deftypefnx {} {@var{v} =} randg ("seed") +@deftypefnx {} {} randg ("seed", @var{v}) +@deftypefnx {} {} randg ("seed", "reset") +@deftypefnx {} {} randg (@dots{}, "single") +@deftypefnx {} {} randg (@dots{}, "double") +Return a matrix with @code{gamma (@var{a},1)} distributed random elements. + +The arguments are handled the same as the arguments for @code{rand}, except +for the argument @var{a}. + +This can be used to generate many distributions: + +@table @asis +@item @code{gamma (a, b)} for @code{a > -1}, @code{b > 0} + +@example +r = b * randg (a) +@end example + +@item @code{beta (a, b)} for @code{a > -1}, @code{b > -1} + +@example +@group +r1 = randg (a, 1) +r = r1 / (r1 + randg (b, 1)) +@end group +@end example + +@item @code{Erlang (a, n)} + +@example +r = a * randg (n) +@end example + +@item @code{chisq (df)} for @code{df > 0} + +@example +r = 2 * randg (df / 2) +@end example + +@item @code{t (df)} for @code{0 < df < inf} (use randn if df is infinite) + +@example +r = randn () / sqrt (2 * randg (df / 2) / df) +@end example + +@item @code{F (n1, n2)} for @code{0 < n1}, @code{0 < n2} + +@example +@group +## r1 equals 1 if n1 is infinite +r1 = 2 * randg (n1 / 2) / n1 +## r2 equals 1 if n2 is infinite +r2 = 2 * randg (n2 / 2) / n2 +r = r1 / r2\n +@end group +@end example + +@item negative @code{binomial (n, p)} for @code{n > 0}, @code{0 < p <= 1} + +@example +r = randp ((1 - p) / p * randg (n)) +@end example + +@item non-central @code{chisq (df, L)}, for @code{df >= 0} and @code{L > 0} +(use chisq if @code{L = 0}) + +@example +@group +r = randp (L / 2) +r(r > 0) = 2 * randg (r(r > 0)) +r(df > 0) += 2 * randg (df(df > 0)/2) +@end group +@end example + +@item @code{Dirichlet (a1, @dots{} ak)} + +@example +@group +r = (randg (a1), @dots{}, randg (ak)) +r = r / sum (r) +@end group +@end example + +@end table + +The class of the value returned can be controlled by a trailing +@qcode{"double"} or @qcode{"single"} argument. These are the only valid +classes. +@seealso{rand, randn, rande, randp} +@end deftypefn */) { int nargin = args.length (); @@ -918,55 +918,55 @@ */ DEFUN (randp, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} randp (@var{l}, @var{n})\n\ -@deftypefnx {} {} randp (@var{l}, @var{m}, @var{n}, @dots{})\n\ -@deftypefnx {} {} randp (@var{l}, [@var{m} @var{n} @dots{}])\n\ -@deftypefnx {} {@var{v} =} randp (\"state\")\n\ -@deftypefnx {} {} randp (\"state\", @var{v})\n\ -@deftypefnx {} {} randp (\"state\", \"reset\")\n\ -@deftypefnx {} {@var{v} =} randp (\"seed\")\n\ -@deftypefnx {} {} randp (\"seed\", @var{v})\n\ -@deftypefnx {} {} randp (\"seed\", \"reset\")\n\ -@deftypefnx {} {} randp (@dots{}, \"single\")\n\ -@deftypefnx {} {} randp (@dots{}, \"double\")\n\ -Return a matrix with Poisson distributed random elements with mean value\n\ -parameter given by the first argument, @var{l}.\n\ -\n\ -The arguments are handled the same as the arguments for @code{rand}, except\n\ -for the argument @var{l}.\n\ -\n\ -Five different algorithms are used depending on the range of @var{l} and\n\ -whether or not @var{l} is a scalar or a matrix.\n\ -\n\ -@table @asis\n\ -@item For scalar @var{l} @leq{} 12, use direct method.\n\ -W.H. Press, et al., @cite{Numerical Recipes in C},\n\ -Cambridge University Press, 1992.\n\ -\n\ -@item For scalar @var{l} > 12, use rejection method.[1]\n\ -W.H. Press, et al., @cite{Numerical Recipes in C},\n\ -Cambridge University Press, 1992.\n\ -\n\ -@item For matrix @var{l} @leq{} 10, use inversion method.[2]\n\ -@nospell{E. Stadlober, et al., WinRand source code}, available via FTP.\n\ -\n\ -@item For matrix @var{l} > 10, use patchwork rejection method.\n\ -@nospell{E. Stadlober, et al., WinRand source code}, available via FTP, or\n\ -@nospell{H. Zechner}, @cite{Efficient sampling from continuous and discrete\n\ -unimodal distributions}, Doctoral Dissertation, 156pp., Technical\n\ -University @nospell{Graz}, Austria, 1994.\n\ -\n\ -@item For @var{l} > 1e8, use normal approximation.\n\ -@nospell{L. Montanet}, et al., @cite{Review of Particle Properties},\n\ -Physical Review D 50 p1284, 1994.\n\ -@end table\n\ -\n\ -The class of the value returned can be controlled by a trailing\n\ -@qcode{\"double\"} or @qcode{\"single\"} argument. These are the only valid\n\ -classes.\n\ -@seealso{rand, randn, rande, randg}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} randp (@var{l}, @var{n}) +@deftypefnx {} {} randp (@var{l}, @var{m}, @var{n}, @dots{}) +@deftypefnx {} {} randp (@var{l}, [@var{m} @var{n} @dots{}]) +@deftypefnx {} {@var{v} =} randp ("state") +@deftypefnx {} {} randp ("state", @var{v}) +@deftypefnx {} {} randp ("state", "reset") +@deftypefnx {} {@var{v} =} randp ("seed") +@deftypefnx {} {} randp ("seed", @var{v}) +@deftypefnx {} {} randp ("seed", "reset") +@deftypefnx {} {} randp (@dots{}, "single") +@deftypefnx {} {} randp (@dots{}, "double") +Return a matrix with Poisson distributed random elements with mean value +parameter given by the first argument, @var{l}. + +The arguments are handled the same as the arguments for @code{rand}, except +for the argument @var{l}. + +Five different algorithms are used depending on the range of @var{l} and +whether or not @var{l} is a scalar or a matrix. + +@table @asis +@item For scalar @var{l} @leq{} 12, use direct method. +W.H. Press, et al., @cite{Numerical Recipes in C}, +Cambridge University Press, 1992. + +@item For scalar @var{l} > 12, use rejection method.[1] +W.H. Press, et al., @cite{Numerical Recipes in C}, +Cambridge University Press, 1992. + +@item For matrix @var{l} @leq{} 10, use inversion method.[2] +@nospell{E. Stadlober, et al., WinRand source code}, available via FTP. + +@item For matrix @var{l} > 10, use patchwork rejection method. +@nospell{E. Stadlober, et al., WinRand source code}, available via FTP, or +@nospell{H. Zechner}, @cite{Efficient sampling from continuous and discrete +unimodal distributions}, Doctoral Dissertation, 156pp., Technical +University @nospell{Graz}, Austria, 1994. + +@item For @var{l} > 1e8, use normal approximation. +@nospell{L. Montanet}, et al., @cite{Review of Particle Properties}, +Physical Review D 50 p1284, 1994. +@end table + +The class of the value returned can be controlled by a trailing +@qcode{"double"} or @qcode{"single"} argument. These are the only valid +classes. +@seealso{rand, randn, rande, randg} +@end deftypefn */) { int nargin = args.length (); @@ -1063,20 +1063,20 @@ */ DEFUN (randperm, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} randperm (@var{n})\n\ -@deftypefnx {} {} randperm (@var{n}, @var{m})\n\ -Return a row vector containing a random permutation of @code{1:@var{n}}.\n\ -\n\ -If @var{m} is supplied, return @var{m} unique entries, sampled without\n\ -replacement from @code{1:@var{n}}.\n\ -\n\ -The complexity is O(@var{n}) in memory and O(@var{m}) in time, unless\n\ -@var{m} < @var{n}/5, in which case O(@var{m}) memory is used as well. The\n\ -randomization is performed using rand(). All permutations are equally\n\ -likely.\n\ -@seealso{perms}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} randperm (@var{n}) +@deftypefnx {} {} randperm (@var{n}, @var{m}) +Return a row vector containing a random permutation of @code{1:@var{n}}. + +If @var{m} is supplied, return @var{m} unique entries, sampled without +replacement from @code{1:@var{n}}. + +The complexity is O(@var{n}) in memory and O(@var{m}) in time, unless +@var{m} < @var{n}/5, in which case O(@var{m}) memory is used as well. The +randomization is performed using rand(). All permutations are equally +likely. +@seealso{perms} +@end deftypefn */) { #if defined (USE_UNORDERED_MAP_WITH_TR1) using std::tr1::unordered_map;
--- a/libinterp/corefcn/rcond.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/rcond.cc Tue Jun 21 16:07:51 2016 -0400 @@ -31,19 +31,19 @@ #include "utils.h" DEFUN (rcond, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{c} =} rcond (@var{A})\n\ -Compute the 1-norm estimate of the reciprocal condition number as returned\n\ -by @sc{lapack}.\n\ -\n\ -If the matrix is well-conditioned then @var{c} will be near 1 and if the\n\ -matrix is poorly conditioned it will be close to 0.\n\ -\n\ -The matrix @var{A} must not be sparse. If the matrix is sparse then\n\ -@code{condest (@var{A})} or @code{rcond (full (@var{A}))} should be used\n\ -instead.\n\ -@seealso{cond, condest}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{c} =} rcond (@var{A}) +Compute the 1-norm estimate of the reciprocal condition number as returned +by @sc{lapack}. + +If the matrix is well-conditioned then @var{c} will be near 1 and if the +matrix is poorly conditioned it will be close to 0. + +The matrix @var{A} must not be sparse. If the matrix is sparse then +@code{condest (@var{A})} or @code{rcond (full (@var{A}))} should be used +instead. +@seealso{cond, condest} +@end deftypefn */) { if (args.length () != 1) print_usage ();
--- a/libinterp/corefcn/regexp.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/regexp.cc Tue Jun 21 16:07:51 2016 -0400 @@ -645,210 +645,210 @@ } DEFUN (regexp, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{s}, @var{e}, @var{te}, @var{m}, @var{t}, @var{nm}, @var{sp}] =} regexp (@var{str}, @var{pat})\n\ -@deftypefnx {} {[@dots{}] =} regexp (@var{str}, @var{pat}, \"@var{opt1}\", @dots{})\n\ -Regular expression string matching.\n\ -\n\ -Search for @var{pat} in @var{str} and return the positions and substrings of\n\ -any matches, or empty values if there are none.\n\ -\n\ -The matched pattern @var{pat} can include any of the standard regex\n\ -operators, including:\n\ -\n\ -@table @code\n\ -@item .\n\ -Match any character\n\ -\n\ -@item * + ? @{@}\n\ -Repetition operators, representing\n\ -\n\ -@table @code\n\ -@item *\n\ -Match zero or more times\n\ -\n\ -@item +\n\ -Match one or more times\n\ -\n\ -@item ?\n\ -Match zero or one times\n\ -\n\ -@item @{@var{n}@}\n\ -Match exactly @var{n} times\n\ -\n\ -@item @{@var{n},@}\n\ -Match @var{n} or more times\n\ -\n\ -@item @{@var{m},@var{n}@}\n\ -Match between @var{m} and @var{n} times\n\ -@end table\n\ -\n\ -@item [@dots{}] [^@dots{}]\n\ -\n\ -List operators. The pattern will match any character listed between \"[\"\n\ -and \"]\". If the first character is \"^\" then the pattern is inverted and\n\ -any character except those listed between brackets will match.\n\ -\n\ -Escape sequences defined below can also be used inside list operators. For\n\ -example, a template for a floating point number might be @code{[-+.\\d]+}.\n\ -\n\ -@item () (?:)\n\ -Grouping operator. The first form, parentheses only, also creates a token.\n\ -\n\ -@item |\n\ -Alternation operator. Match one of a choice of regular expressions. The\n\ -alternatives must be delimited by the grouping operator @code{()} above.\n\ -\n\ -@item ^ $\n\ -Anchoring operators. Requires pattern to occur at the start (@code{^}) or\n\ -end (@code{$}) of the string.\n\ -@end table\n\ -\n\ -In addition, the following escaped characters have special meaning.\n\ -\n\ -@table @code\n\ -\n\ -@item \\d\n\ -Match any digit\n\ -\n\ -@item \\D\n\ -Match any non-digit\n\ -\n\ -@item \\s\n\ -Match any whitespace character\n\ -\n\ -@item \\S\n\ -Match any non-whitespace character\n\ -\n\ -@item \\w\n\ -Match any word character\n\ -\n\ -@item \\W\n\ -Match any non-word character\n\ -\n\ -@item \\<\n\ -Match the beginning of a word\n\ -\n\ -@item \\>\n\ -Match the end of a word\n\ -\n\ -@item \\B\n\ -Match within a word\n\ -@end table\n\ -\n\ -Implementation Note: For compatibility with @sc{matlab}, escape sequences\n\ -in @var{pat} (e.g., @qcode{\"@xbackslashchar{}n\"} => newline) are expanded\n\ -even when @var{pat} has been defined with single quotes. To disable\n\ -expansion use a second backslash before the escape sequence (e.g.,\n\ -\"@xbackslashchar{}@xbackslashchar{}n\") or use the @code{regexptranslate}\n\ -function.\n\ -\n\ -The outputs of @code{regexp} default to the order given below\n\ -\n\ -@table @var\n\ -@item s\n\ -The start indices of each matching substring\n\ -\n\ -@item e\n\ -The end indices of each matching substring\n\ -\n\ -@item te\n\ -The extents of each matched token surrounded by @code{(@dots{})} in\n\ -@var{pat}\n\ -\n\ -@item m\n\ -A cell array of the text of each match\n\ -\n\ -@item t\n\ -A cell array of the text of each token matched\n\ -\n\ -@item nm\n\ -A structure containing the text of each matched named token, with the name\n\ -being used as the fieldname. A named token is denoted by\n\ -@code{(?<name>@dots{})}.\n\ -\n\ -@item sp\n\ -A cell array of the text not returned by match, i.e., what remains if you\n\ -split the string based on @var{pat}.\n\ -@end table\n\ -\n\ -Particular output arguments, or the order of the output arguments, can be\n\ -selected by additional @var{opt} arguments. These are strings and the\n\ -correspondence between the output arguments and the optional argument\n\ -are\n\ -\n\ -@multitable @columnfractions 0.2 0.3 0.3 0.2\n\ -@item @tab @qcode{'start'} @tab @var{s} @tab\n\ -@item @tab @qcode{'end'} @tab @var{e} @tab\n\ -@item @tab @qcode{'tokenExtents'} @tab @var{te} @tab\n\ -@item @tab @qcode{'match'} @tab @var{m} @tab\n\ -@item @tab @qcode{'tokens'} @tab @var{t} @tab\n\ -@item @tab @qcode{'names'} @tab @var{nm} @tab\n\ -@item @tab @qcode{'split'} @tab @var{sp} @tab\n\ -@end multitable\n\ -\n\ -Additional arguments are summarized below.\n\ -\n\ -@table @samp\n\ -@item once\n\ -Return only the first occurrence of the pattern.\n\ -\n\ -@item matchcase\n\ -Make the matching case sensitive. (default)\n\ -\n\ -Alternatively, use (?-i) in the pattern.\n\ -\n\ -@item ignorecase\n\ -Ignore case when matching the pattern to the string.\n\ -\n\ -Alternatively, use (?i) in the pattern.\n\ -\n\ -@item stringanchors\n\ -Match the anchor characters at the beginning and end of the string.\n\ -(default)\n\ -\n\ -Alternatively, use (?-m) in the pattern.\n\ -\n\ -@item lineanchors\n\ -Match the anchor characters at the beginning and end of the line.\n\ -\n\ -Alternatively, use (?m) in the pattern.\n\ -\n\ -@item dotall\n\ -The pattern @code{.} matches all characters including the newline character.\n\ - (default)\n\ -\n\ -Alternatively, use (?s) in the pattern.\n\ -\n\ -@item dotexceptnewline\n\ -The pattern @code{.} matches all characters except the newline character.\n\ -\n\ -Alternatively, use (?-s) in the pattern.\n\ -\n\ -@item literalspacing\n\ -All characters in the pattern, including whitespace, are significant and are\n\ -used in pattern matching. (default)\n\ -\n\ -Alternatively, use (?-x) in the pattern.\n\ -\n\ -@item freespacing\n\ -The pattern may include arbitrary whitespace and also comments beginning\n\ -with the character @samp{#}.\n\ -\n\ -Alternatively, use (?x) in the pattern.\n\ -\n\ -@item noemptymatch\n\ -Zero-length matches are not returned. (default)\n\ -\n\ -@item emptymatch\n\ -Return zero-length matches.\n\ -\n\ -@code{regexp ('a', 'b*', 'emptymatch')} returns @code{[1 2]} because there\n\ -are zero or more @qcode{'b'} characters at positions 1 and end-of-string.\n\ -\n\ -@end table\n\ -@seealso{regexpi, strfind, regexprep}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{s}, @var{e}, @var{te}, @var{m}, @var{t}, @var{nm}, @var{sp}] =} regexp (@var{str}, @var{pat}) +@deftypefnx {} {[@dots{}] =} regexp (@var{str}, @var{pat}, "@var{opt1}", @dots{}) +Regular expression string matching. + +Search for @var{pat} in @var{str} and return the positions and substrings of +any matches, or empty values if there are none. + +The matched pattern @var{pat} can include any of the standard regex +operators, including: + +@table @code +@item . +Match any character + +@item * + ? @{@} +Repetition operators, representing + +@table @code +@item * +Match zero or more times + +@item + +Match one or more times + +@item ? +Match zero or one times + +@item @{@var{n}@} +Match exactly @var{n} times + +@item @{@var{n},@} +Match @var{n} or more times + +@item @{@var{m},@var{n}@} +Match between @var{m} and @var{n} times +@end table + +@item [@dots{}] [^@dots{}] + +List operators. The pattern will match any character listed between "[" +and "]". If the first character is "^" then the pattern is inverted and +any character except those listed between brackets will match. + +Escape sequences defined below can also be used inside list operators. For +example, a template for a floating point number might be @code{[-+.\d]+}. + +@item () (?:) +Grouping operator. The first form, parentheses only, also creates a token. + +@item | +Alternation operator. Match one of a choice of regular expressions. The +alternatives must be delimited by the grouping operator @code{()} above. + +@item ^ $ +Anchoring operators. Requires pattern to occur at the start (@code{^}) or +end (@code{$}) of the string. +@end table + +In addition, the following escaped characters have special meaning. + +@table @code + +@item \d +Match any digit + +@item \D +Match any non-digit + +@item \s +Match any whitespace character + +@item \S +Match any non-whitespace character + +@item \w +Match any word character + +@item \W +Match any non-word character + +@item \< +Match the beginning of a word + +@item \> +Match the end of a word + +@item \B +Match within a word +@end table + +Implementation Note: For compatibility with @sc{matlab}, escape sequences +in @var{pat} (e.g., @qcode{"@xbackslashchar{}n"} => newline) are expanded +even when @var{pat} has been defined with single quotes. To disable +expansion use a second backslash before the escape sequence (e.g., +"@xbackslashchar{}@xbackslashchar{}n") or use the @code{regexptranslate} +function. + +The outputs of @code{regexp} default to the order given below + +@table @var +@item s +The start indices of each matching substring + +@item e +The end indices of each matching substring + +@item te +The extents of each matched token surrounded by @code{(@dots{})} in +@var{pat} + +@item m +A cell array of the text of each match + +@item t +A cell array of the text of each token matched + +@item nm +A structure containing the text of each matched named token, with the name +being used as the fieldname. A named token is denoted by +@code{(?<name>@dots{})}. + +@item sp +A cell array of the text not returned by match, i.e., what remains if you +split the string based on @var{pat}. +@end table + +Particular output arguments, or the order of the output arguments, can be +selected by additional @var{opt} arguments. These are strings and the +correspondence between the output arguments and the optional argument +are + +@multitable @columnfractions 0.2 0.3 0.3 0.2 +@item @tab @qcode{'start'} @tab @var{s} @tab +@item @tab @qcode{'end'} @tab @var{e} @tab +@item @tab @qcode{'tokenExtents'} @tab @var{te} @tab +@item @tab @qcode{'match'} @tab @var{m} @tab +@item @tab @qcode{'tokens'} @tab @var{t} @tab +@item @tab @qcode{'names'} @tab @var{nm} @tab +@item @tab @qcode{'split'} @tab @var{sp} @tab +@end multitable + +Additional arguments are summarized below. + +@table @samp +@item once +Return only the first occurrence of the pattern. + +@item matchcase +Make the matching case sensitive. (default) + +Alternatively, use (?-i) in the pattern. + +@item ignorecase +Ignore case when matching the pattern to the string. + +Alternatively, use (?i) in the pattern. + +@item stringanchors +Match the anchor characters at the beginning and end of the string. +(default) + +Alternatively, use (?-m) in the pattern. + +@item lineanchors +Match the anchor characters at the beginning and end of the line. + +Alternatively, use (?m) in the pattern. + +@item dotall +The pattern @code{.} matches all characters including the newline character. + (default) + +Alternatively, use (?s) in the pattern. + +@item dotexceptnewline +The pattern @code{.} matches all characters except the newline character. + +Alternatively, use (?-s) in the pattern. + +@item literalspacing +All characters in the pattern, including whitespace, are significant and are +used in pattern matching. (default) + +Alternatively, use (?-x) in the pattern. + +@item freespacing +The pattern may include arbitrary whitespace and also comments beginning +with the character @samp{#}. + +Alternatively, use (?x) in the pattern. + +@item noemptymatch +Zero-length matches are not returned. (default) + +@item emptymatch +Return zero-length matches. + +@code{regexp ('a', 'b*', 'emptymatch')} returns @code{[1 2]} because there +are zero or more @qcode{'b'} characters at positions 1 and end-of-string. + +@end table +@seealso{regexpi, strfind, regexprep} +@end deftypefn */) { if (args.length () < 2) print_usage (); @@ -1132,17 +1132,17 @@ */ DEFUN (regexpi, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{s}, @var{e}, @var{te}, @var{m}, @var{t}, @var{nm}, @var{sp}] =} regexpi (@var{str}, @var{pat})\n\ -@deftypefnx {} {[@dots{}] =} regexpi (@var{str}, @var{pat}, \"@var{opt1}\", @dots{})\n\ -\n\ -Case insensitive regular expression string matching.\n\ -\n\ -Search for @var{pat} in @var{str} and return the positions and substrings of\n\ -any matches, or empty values if there are none. @xref{XREFregexp,,regexp},\n\ -for details on the syntax of the search pattern.\n\ -@seealso{regexp}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{s}, @var{e}, @var{te}, @var{m}, @var{t}, @var{nm}, @var{sp}] =} regexpi (@var{str}, @var{pat}) +@deftypefnx {} {[@dots{}] =} regexpi (@var{str}, @var{pat}, "@var{opt1}", @dots{}) + +Case insensitive regular expression string matching. + +Search for @var{pat} in @var{str} and return the positions and substrings of +any matches, or empty values if there are none. @xref{XREFregexp,,regexp}, +for details on the syntax of the search pattern. +@seealso{regexp} +@end deftypefn */) { if (args.length () < 2) print_usage (); @@ -1332,44 +1332,44 @@ } DEFUN (regexprep, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{outstr} =} regexprep (@var{string}, @var{pat}, @var{repstr})\n\ -@deftypefnx {} {@var{outstr} =} regexprep (@var{string}, @var{pat}, @var{repstr}, \"@var{opt1}\", @dots{})\n\ -Replace occurrences of pattern @var{pat} in @var{string} with @var{repstr}.\n\ -\n\ -The pattern is a regular expression as documented for @code{regexp}.\n\ -@xref{XREFregexp,,regexp}.\n\ -\n\ -The replacement string may contain @code{$i}, which substitutes for the ith\n\ -set of parentheses in the match string. For example,\n\ -\n\ -@example\n\ -regexprep (\"Bill Dunn\", '(\\w+) (\\w+)', '$2, $1')\n\ -@end example\n\ -\n\ -@noindent\n\ -returns \"Dunn, Bill\"\n\ -\n\ -Options in addition to those of @code{regexp} are\n\ -\n\ -@table @samp\n\ -\n\ -@item once\n\ -Replace only the first occurrence of @var{pat} in the result.\n\ -\n\ -@item warnings\n\ -This option is present for compatibility but is ignored.\n\ -\n\ -@end table\n\ -\n\ -Implementation Note: For compatibility with @sc{matlab}, escape sequences\n\ -in @var{pat} (e.g., @qcode{\"@xbackslashchar{}n\"} => newline) are expanded\n\ -even when @var{pat} has been defined with single quotes. To disable\n\ -expansion use a second backslash before the escape sequence (e.g.,\n\ -\"@xbackslashchar{}@xbackslashchar{}n\") or use the @code{regexptranslate}\n\ -function.\n\ -@seealso{regexp, regexpi, strrep}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{outstr} =} regexprep (@var{string}, @var{pat}, @var{repstr}) +@deftypefnx {} {@var{outstr} =} regexprep (@var{string}, @var{pat}, @var{repstr}, "@var{opt1}", @dots{}) +Replace occurrences of pattern @var{pat} in @var{string} with @var{repstr}. + +The pattern is a regular expression as documented for @code{regexp}. +@xref{XREFregexp,,regexp}. + +The replacement string may contain @code{$i}, which substitutes for the ith +set of parentheses in the match string. For example, + +@example +regexprep ("Bill Dunn", '(\w+) (\w+)', '$2, $1') +@end example + +@noindent +returns "Dunn, Bill" + +Options in addition to those of @code{regexp} are + +@table @samp + +@item once +Replace only the first occurrence of @var{pat} in the result. + +@item warnings +This option is present for compatibility but is ignored. + +@end table + +Implementation Note: For compatibility with @sc{matlab}, escape sequences +in @var{pat} (e.g., @qcode{"@xbackslashchar{}n"} => newline) are expanded +even when @var{pat} has been defined with single quotes. To disable +expansion use a second backslash before the escape sequence (e.g., +"@xbackslashchar{}@xbackslashchar{}n") or use the @code{regexptranslate} +function. +@seealso{regexp, regexpi, strrep} +@end deftypefn */) { if (args.length () < 3) print_usage ();
--- a/libinterp/corefcn/schur.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/schur.cc Tue Jun 21 16:07:51 2016 -0400 @@ -55,75 +55,75 @@ } DEFUN (schur, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{S} =} schur (@var{A})\n\ -@deftypefnx {} {@var{S} =} schur (@var{A}, \"real\")\n\ -@deftypefnx {} {@var{S} =} schur (@var{A}, \"complex\")\n\ -@deftypefnx {} {@var{S} =} schur (@var{A}, @var{opt})\n\ -@deftypefnx {} {[@var{U}, @var{S}] =} schur (@dots{})\n\ -@cindex Schur decomposition\n\ -Compute the Schur@tie{}decomposition of @var{A}.\n\ -\n\ -The Schur@tie{}decomposition is defined as\n\ -@tex\n\ -$$\n\ - S = U^T A U\n\ -$$\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ -@code{@var{S} = @var{U}' * @var{A} * @var{U}}\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -where @var{U} is a unitary matrix\n\ -@tex\n\ -($U^T U$ is identity)\n\ -@end tex\n\ -@ifnottex\n\ -(@code{@var{U}'* @var{U}} is identity)\n\ -@end ifnottex\n\ -and @var{S} is upper triangular. The eigenvalues of @var{A} (and @var{S})\n\ -are the diagonal elements of @var{S}. If the matrix @var{A} is real, then\n\ -the real Schur@tie{}decomposition is computed, in which the matrix @var{U}\n\ -is orthogonal and @var{S} is block upper triangular with blocks of size at\n\ -most\n\ -@tex\n\ -$2 \\times 2$\n\ -@end tex\n\ -@ifnottex\n\ -@code{2 x 2}\n\ -@end ifnottex\n\ -along the diagonal. The diagonal elements of @var{S}\n\ -(or the eigenvalues of the\n\ -@tex\n\ -$2 \\times 2$\n\ -@end tex\n\ -@ifnottex\n\ -@code{2 x 2}\n\ -@end ifnottex\n\ -blocks, when appropriate) are the eigenvalues of @var{A} and @var{S}.\n\ -\n\ -The default for real matrices is a real Schur@tie{}decomposition.\n\ -A complex decomposition may be forced by passing the flag\n\ -@qcode{\"complex\"}.\n\ -\n\ -The eigenvalues are optionally ordered along the diagonal according to the\n\ -value of @var{opt}. @code{@var{opt} = \"a\"} indicates that all eigenvalues\n\ -with negative real parts should be moved to the leading block of @var{S}\n\ -(used in @code{are}), @code{@var{opt} = \"d\"} indicates that all\n\ -eigenvalues with magnitude less than one should be moved to the leading\n\ -block of @var{S} (used in @code{dare}), and @code{@var{opt} = \"u\"}, the\n\ -default, indicates that no ordering of eigenvalues should occur. The\n\ -leading @var{k} columns of @var{U} always span the @var{A}-invariant\n\ -subspace corresponding to the @var{k} leading eigenvalues of @var{S}.\n\ -\n\ -The Schur@tie{}decomposition is used to compute eigenvalues of a square\n\ -matrix, and has applications in the solution of algebraic Riccati equations\n\ -in control (see @code{are} and @code{dare}).\n\ -@seealso{rsf2csf, ordschur, lu, chol, hess, qr, qz, svd}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{S} =} schur (@var{A}) +@deftypefnx {} {@var{S} =} schur (@var{A}, "real") +@deftypefnx {} {@var{S} =} schur (@var{A}, "complex") +@deftypefnx {} {@var{S} =} schur (@var{A}, @var{opt}) +@deftypefnx {} {[@var{U}, @var{S}] =} schur (@dots{}) +@cindex Schur decomposition +Compute the Schur@tie{}decomposition of @var{A}. + +The Schur@tie{}decomposition is defined as +@tex +$$ + S = U^T A U +$$ +@end tex +@ifnottex + +@example +@code{@var{S} = @var{U}' * @var{A} * @var{U}} +@end example + +@end ifnottex +where @var{U} is a unitary matrix +@tex +($U^T U$ is identity) +@end tex +@ifnottex +(@code{@var{U}'* @var{U}} is identity) +@end ifnottex +and @var{S} is upper triangular. The eigenvalues of @var{A} (and @var{S}) +are the diagonal elements of @var{S}. If the matrix @var{A} is real, then +the real Schur@tie{}decomposition is computed, in which the matrix @var{U} +is orthogonal and @var{S} is block upper triangular with blocks of size at +most +@tex +$2 \times 2$ +@end tex +@ifnottex +@code{2 x 2} +@end ifnottex +along the diagonal. The diagonal elements of @var{S} +(or the eigenvalues of the +@tex +$2 \times 2$ +@end tex +@ifnottex +@code{2 x 2} +@end ifnottex +blocks, when appropriate) are the eigenvalues of @var{A} and @var{S}. + +The default for real matrices is a real Schur@tie{}decomposition. +A complex decomposition may be forced by passing the flag +@qcode{"complex"}. + +The eigenvalues are optionally ordered along the diagonal according to the +value of @var{opt}. @code{@var{opt} = "a"} indicates that all eigenvalues +with negative real parts should be moved to the leading block of @var{S} +(used in @code{are}), @code{@var{opt} = "d"} indicates that all +eigenvalues with magnitude less than one should be moved to the leading +block of @var{S} (used in @code{dare}), and @code{@var{opt} = "u"}, the +default, indicates that no ordering of eigenvalues should occur. The +leading @var{k} columns of @var{U} always span the @var{A}-invariant +subspace corresponding to the @var{k} leading eigenvalues of @var{S}. + +The Schur@tie{}decomposition is used to compute eigenvalues of a square +matrix, and has applications in the solution of algebraic Riccati equations +in control (see @code{are} and @code{dare}). +@seealso{rsf2csf, ordschur, lu, chol, hess, qr, qz, svd} +@end deftypefn */) { int nargin = args.length (); @@ -266,25 +266,25 @@ */ DEFUN (rsf2csf, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{U}, @var{T}] =} rsf2csf (@var{UR}, @var{TR})\n\ -Convert a real, upper quasi-triangular Schur@tie{}form @var{TR} to a\n\ -complex, upper triangular Schur@tie{}form @var{T}.\n\ -\n\ -Note that the following relations hold:\n\ -\n\ -@tex\n\ -$UR \\cdot TR \\cdot {UR}^T = U T U^{\\dagger}$ and\n\ -$U^{\\dagger} U$ is the identity matrix I.\n\ -@end tex\n\ -@ifnottex\n\ -@tcode{@var{UR} * @var{TR} * @var{UR}' = @var{U} * @var{T} * @var{U}'} and\n\ -@code{@var{U}' * @var{U}} is the identity matrix I.\n\ -@end ifnottex\n\ -\n\ -Note also that @var{U} and @var{T} are not unique.\n\ -@seealso{schur}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{U}, @var{T}] =} rsf2csf (@var{UR}, @var{TR}) +Convert a real, upper quasi-triangular Schur@tie{}form @var{TR} to a +complex, upper triangular Schur@tie{}form @var{T}. + +Note that the following relations hold: + +@tex +$UR \cdot TR \cdot {UR}^T = U T U^{\dagger}$ and +$U^{\dagger} U$ is the identity matrix I. +@end tex +@ifnottex +@tcode{@var{UR} * @var{TR} * @var{UR}' = @var{U} * @var{T} * @var{U}'} and +@code{@var{U}' * @var{U}} is the identity matrix I. +@end ifnottex + +Note also that @var{U} and @var{T} are not unique. +@seealso{schur} +@end deftypefn */) { if (args.length () != 2 || nargout > 2) print_usage ();
--- a/libinterp/corefcn/sighandlers.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/sighandlers.cc Tue Jun 21 16:07:51 2016 -0400 @@ -778,10 +778,10 @@ } DEFUN (SIG, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} SIG ()\n\ -Return a structure containing Unix signal names and their defined values.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} SIG () +Return a structure containing Unix signal names and their defined values. +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -799,22 +799,22 @@ */ DEFUN (debug_on_interrupt, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} debug_on_interrupt ()\n\ -@deftypefnx {} {@var{old_val} =} debug_on_interrupt (@var{new_val})\n\ -@deftypefnx {} {} debug_on_interrupt (@var{new_val}, \"local\")\n\ -Query or set the internal variable that controls whether Octave will try\n\ -to enter debugging mode when it receives an interrupt signal (typically\n\ -generated with @kbd{C-c}).\n\ -\n\ -If a second interrupt signal is received before reaching the debugging mode,\n\ -a normal interrupt will occur.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{debug_on_error, debug_on_warning}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} debug_on_interrupt () +@deftypefnx {} {@var{old_val} =} debug_on_interrupt (@var{new_val}) +@deftypefnx {} {} debug_on_interrupt (@var{new_val}, "local") +Query or set the internal variable that controls whether Octave will try +to enter debugging mode when it receives an interrupt signal (typically +generated with @kbd{C-c}). + +If a second interrupt signal is received before reaching the debugging mode, +a normal interrupt will occur. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{debug_on_error, debug_on_warning} +@end deftypefn */) { return SET_INTERNAL_VARIABLE (debug_on_interrupt); } @@ -832,18 +832,18 @@ */ DEFUN (sighup_dumps_octave_core, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} sighup_dumps_octave_core ()\n\ -@deftypefnx {} {@var{old_val} =} sighup_dumps_octave_core (@var{new_val})\n\ -@deftypefnx {} {} sighup_dumps_octave_core (@var{new_val}, \"local\")\n\ -Query or set the internal variable that controls whether Octave tries\n\ -to save all current variables to the file @file{octave-workspace} if it\n\ -receives a hangup signal.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} sighup_dumps_octave_core () +@deftypefnx {} {@var{old_val} =} sighup_dumps_octave_core (@var{new_val}) +@deftypefnx {} {} sighup_dumps_octave_core (@var{new_val}, "local") +Query or set the internal variable that controls whether Octave tries +to save all current variables to the file @file{octave-workspace} if it +receives a hangup signal. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@end deftypefn */) { return SET_INTERNAL_VARIABLE (sighup_dumps_octave_core); } @@ -861,18 +861,18 @@ */ DEFUN (sigterm_dumps_octave_core, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} sigterm_dumps_octave_core ()\n\ -@deftypefnx {} {@var{old_val} =} sigterm_dumps_octave_core (@var{new_val})\n\ -@deftypefnx {} {} sigterm_dumps_octave_core (@var{new_val}, \"local\")\n\ -Query or set the internal variable that controls whether Octave tries\n\ -to save all current variables to the file @file{octave-workspace} if it\n\ -receives a terminate signal.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} sigterm_dumps_octave_core () +@deftypefnx {} {@var{old_val} =} sigterm_dumps_octave_core (@var{new_val}) +@deftypefnx {} {} sigterm_dumps_octave_core (@var{new_val}, "local") +Query or set the internal variable that controls whether Octave tries +to save all current variables to the file @file{octave-workspace} if it +receives a terminate signal. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@end deftypefn */) { return SET_INTERNAL_VARIABLE (sigterm_dumps_octave_core); }
--- a/libinterp/corefcn/sparse.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/sparse.cc Tue Jun 21 16:07:51 2016 -0400 @@ -42,11 +42,11 @@ #include "ov-bool-sparse.h" DEFUN (issparse, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} issparse (@var{x})\n\ -Return true if @var{x} is a sparse matrix.\n\ -@seealso{ismatrix}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} issparse (@var{x}) +Return true if @var{x} is a sparse matrix. +@seealso{ismatrix} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -55,72 +55,72 @@ } DEFUN (sparse, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{s} =} sparse (@var{a})\n\ -@deftypefnx {} {@var{s} =} sparse (@var{i}, @var{j}, @var{sv}, @var{m}, @var{n})\n\ -@deftypefnx {} {@var{s} =} sparse (@var{i}, @var{j}, @var{sv})\n\ -@deftypefnx {} {@var{s} =} sparse (@var{m}, @var{n})\n\ -@deftypefnx {} {@var{s} =} sparse (@var{i}, @var{j}, @var{s}, @var{m}, @var{n}, \"unique\")\n\ -@deftypefnx {} {@var{s} =} sparse (@var{i}, @var{j}, @var{sv}, @var{m}, @var{n}, @var{nzmax})\n\ -Create a sparse matrix from a full matrix, or row, column, value triplets.\n\ -\n\ -If @var{a} is a full matrix, convert it to a sparse matrix representation,\n\ -removing all zero values in the process.\n\ -\n\ -Given the integer index vectors @var{i} and @var{j}, and a 1-by-@code{nnz}\n\ -vector of real or complex values @var{sv}, construct the sparse matrix\n\ -@code{S(@var{i}(@var{k}),@var{j}(@var{k})) = @var{sv}(@var{k})} with overall\n\ -dimensions @var{m} and @var{n}. If any of @var{sv}, @var{i} or @var{j} are\n\ -scalars, they are expanded to have a common size.\n\ -\n\ -If @var{m} or @var{n} are not specified their values are derived from the\n\ -maximum index in the vectors @var{i} and @var{j} as given by\n\ -@code{@var{m} = max (@var{i})}, @code{@var{n} = max (@var{j})}.\n\ -\n\ -@strong{Note}: if multiple values are specified with the same @var{i},\n\ -@var{j} indices, the corresponding value in @var{s} will be the sum of the\n\ -values at the repeated location. See @code{accumarray} for an example of\n\ -how to produce different behavior, such as taking the minimum instead.\n\ -\n\ -If the option @qcode{\"unique\"} is given, and more than one value is\n\ -specified at the same @var{i}, @var{j} indices, then the last specified\n\ -value will be used.\n\ -\n\ -@code{sparse (@var{m}, @var{n})} will create an empty @var{m}x@var{n} sparse\n\ -matrix and is equivalent to @code{sparse ([], [], [], @var{m}, @var{n})}\n\ -\n\ -The argument @code{nzmax} is ignored but accepted for compatibility with\n\ -@sc{matlab}.\n\ -\n\ -Example 1 (sum at repeated indices):\n\ -\n\ -@example\n\ -@group\n\ -@var{i} = [1 1 2]; @var{j} = [1 1 2]; @var{sv} = [3 4 5];\n\ -sparse (@var{i}, @var{j}, @var{sv}, 3, 4)\n\ -@result{}\n\ -Compressed Column Sparse (rows = 3, cols = 4, nnz = 2 [17%])\n\ -\n\ - (1, 1) -> 7\n\ - (2, 2) -> 5\n\ -@end group\n\ -@end example\n\ -\n\ -Example 2 (\"unique\" option):\n\ -\n\ -@example\n\ -@group\n\ -@var{i} = [1 1 2]; @var{j} = [1 1 2]; @var{sv} = [3 4 5];\n\ -sparse (@var{i}, @var{j}, @var{sv}, 3, 4, \"unique\")\n\ -@result{}\n\ -Compressed Column Sparse (rows = 3, cols = 4, nnz = 2 [17%])\n\ -\n\ - (1, 1) -> 4\n\ - (2, 2) -> 5\n\ -@end group\n\ -@end example\n\ -@seealso{full, accumarray, spalloc, spdiags, speye, spones, sprand, sprandn, sprandsym, spconvert, spfun}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{s} =} sparse (@var{a}) +@deftypefnx {} {@var{s} =} sparse (@var{i}, @var{j}, @var{sv}, @var{m}, @var{n}) +@deftypefnx {} {@var{s} =} sparse (@var{i}, @var{j}, @var{sv}) +@deftypefnx {} {@var{s} =} sparse (@var{m}, @var{n}) +@deftypefnx {} {@var{s} =} sparse (@var{i}, @var{j}, @var{s}, @var{m}, @var{n}, "unique") +@deftypefnx {} {@var{s} =} sparse (@var{i}, @var{j}, @var{sv}, @var{m}, @var{n}, @var{nzmax}) +Create a sparse matrix from a full matrix, or row, column, value triplets. + +If @var{a} is a full matrix, convert it to a sparse matrix representation, +removing all zero values in the process. + +Given the integer index vectors @var{i} and @var{j}, and a 1-by-@code{nnz} +vector of real or complex values @var{sv}, construct the sparse matrix +@code{S(@var{i}(@var{k}),@var{j}(@var{k})) = @var{sv}(@var{k})} with overall +dimensions @var{m} and @var{n}. If any of @var{sv}, @var{i} or @var{j} are +scalars, they are expanded to have a common size. + +If @var{m} or @var{n} are not specified their values are derived from the +maximum index in the vectors @var{i} and @var{j} as given by +@code{@var{m} = max (@var{i})}, @code{@var{n} = max (@var{j})}. + +@strong{Note}: if multiple values are specified with the same @var{i}, +@var{j} indices, the corresponding value in @var{s} will be the sum of the +values at the repeated location. See @code{accumarray} for an example of +how to produce different behavior, such as taking the minimum instead. + +If the option @qcode{"unique"} is given, and more than one value is +specified at the same @var{i}, @var{j} indices, then the last specified +value will be used. + +@code{sparse (@var{m}, @var{n})} will create an empty @var{m}x@var{n} sparse +matrix and is equivalent to @code{sparse ([], [], [], @var{m}, @var{n})} + +The argument @code{nzmax} is ignored but accepted for compatibility with +@sc{matlab}. + +Example 1 (sum at repeated indices): + +@example +@group +@var{i} = [1 1 2]; @var{j} = [1 1 2]; @var{sv} = [3 4 5]; +sparse (@var{i}, @var{j}, @var{sv}, 3, 4) +@result{} +Compressed Column Sparse (rows = 3, cols = 4, nnz = 2 [17%]) + + (1, 1) -> 7 + (2, 2) -> 5 +@end group +@end example + +Example 2 ("unique" option): + +@example +@group +@var{i} = [1 1 2]; @var{j} = [1 1 2]; @var{sv} = [3 4 5]; +sparse (@var{i}, @var{j}, @var{sv}, 3, 4, "unique") +@result{} +Compressed Column Sparse (rows = 3, cols = 4, nnz = 2 [17%]) + + (1, 1) -> 4 + (2, 2) -> 5 +@end group +@end example +@seealso{full, accumarray, spalloc, spdiags, speye, spones, sprand, sprandn, sprandsym, spconvert, spfun} +@end deftypefn */) { int nargin = args.length (); @@ -221,42 +221,42 @@ } DEFUN (spalloc, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{s} =} spalloc (@var{m}, @var{n}, @var{nz})\n\ -Create an @var{m}-by-@var{n} sparse matrix with pre-allocated space for at\n\ -most @var{nz} nonzero elements.\n\ -\n\ -This is useful for building a matrix incrementally by a sequence of indexed\n\ -assignments. Subsequent indexed assignments after @code{spalloc} will reuse\n\ -the pre-allocated memory, provided they are of one of the simple forms\n\ -\n\ -@itemize\n\ -@item @code{@var{s}(I:J) = @var{x}}\n\ -\n\ -@item @code{@var{s}(:,I:J) = @var{x}}\n\ -\n\ -@item @code{@var{s}(K:L,I:J) = @var{x}}\n\ -@end itemize\n\ -\n\ -@b{and} that the following conditions are met:\n\ -\n\ -@itemize\n\ -@item the assignment does not decrease nnz (@var{S}).\n\ -\n\ -@item after the assignment, nnz (@var{S}) does not exceed @var{nz}.\n\ -\n\ -@item no index is out of bounds.\n\ -@end itemize\n\ -\n\ -Partial movement of data may still occur, but in general the assignment will\n\ -be more memory and time efficient under these circumstances. In particular,\n\ -it is possible to efficiently build a pre-allocated sparse matrix from a\n\ -contiguous block of columns.\n\ -\n\ -The amount of pre-allocated memory for a given matrix may be queried using\n\ -the function @code{nzmax}.\n\ -@seealso{nzmax, sparse}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{s} =} spalloc (@var{m}, @var{n}, @var{nz}) +Create an @var{m}-by-@var{n} sparse matrix with pre-allocated space for at +most @var{nz} nonzero elements. + +This is useful for building a matrix incrementally by a sequence of indexed +assignments. Subsequent indexed assignments after @code{spalloc} will reuse +the pre-allocated memory, provided they are of one of the simple forms + +@itemize +@item @code{@var{s}(I:J) = @var{x}} + +@item @code{@var{s}(:,I:J) = @var{x}} + +@item @code{@var{s}(K:L,I:J) = @var{x}} +@end itemize + +@b{and} that the following conditions are met: + +@itemize +@item the assignment does not decrease nnz (@var{S}). + +@item after the assignment, nnz (@var{S}) does not exceed @var{nz}. + +@item no index is out of bounds. +@end itemize + +Partial movement of data may still occur, but in general the assignment will +be more memory and time efficient under these circumstances. In particular, +it is possible to efficiently build a pre-allocated sparse matrix from a +contiguous block of columns. + +The amount of pre-allocated memory for a given matrix may be queried using +the function @code{nzmax}. +@seealso{nzmax, sparse} +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/spparms.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/spparms.cc Tue Jun 21 16:07:51 2016 -0400 @@ -34,76 +34,76 @@ #include "oct-spparms.h" DEFUN (spparms, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} { } spparms ()\n\ -@deftypefnx {} {@var{vals} =} spparms ()\n\ -@deftypefnx {} {[@var{keys}, @var{vals}] =} spparms ()\n\ -@deftypefnx {} {@var{val} =} spparms (@var{key})\n\ -@deftypefnx {} { } spparms (@var{vals})\n\ -@deftypefnx {} { } spparms (\"default\")\n\ -@deftypefnx {} { } spparms (\"tight\")\n\ -@deftypefnx {} { } spparms (@var{key}, @var{val})\n\ -Query or set the parameters used by the sparse solvers and factorization\n\ -functions.\n\ -\n\ -The first four calls above get information about the current settings, while\n\ -the others change the current settings. The parameters are stored as pairs\n\ -of keys and values, where the values are all floats and the keys are one of\n\ -the following strings:\n\ -\n\ -@table @samp\n\ -@item spumoni\n\ -Printing level of debugging information of the solvers (default 0)\n\ -\n\ -@item ths_rel\n\ -Included for compatibility. Not used. (default 1)\n\ -\n\ -@item ths_abs\n\ -Included for compatibility. Not used. (default 1)\n\ -\n\ -@item exact_d\n\ -Included for compatibility. Not used. (default 0)\n\ -\n\ -@item supernd\n\ -Included for compatibility. Not used. (default 3)\n\ -\n\ -@item rreduce\n\ -Included for compatibility. Not used. (default 3)\n\ -\n\ -@item wh_frac\n\ -Included for compatibility. Not used. (default 0.5)\n\ -\n\ -@item autommd\n\ -Flag whether the LU/QR and the '\\' and '/' operators will automatically\n\ -use the sparsity preserving mmd functions (default 1)\n\ -\n\ -@item autoamd\n\ -Flag whether the LU and the '\\' and '/' operators will automatically\n\ -use the sparsity preserving amd functions (default 1)\n\ -\n\ -@item piv_tol\n\ -The pivot tolerance of the @sc{umfpack} solvers (default 0.1)\n\ -\n\ -@item sym_tol\n\ -The pivot tolerance of the @sc{umfpack} symmetric solvers (default 0.001)\n\ -\n\ -@item bandden\n\ -The density of nonzero elements in a banded matrix before it is treated\n\ -by the @sc{lapack} banded solvers (default 0.5)\n\ -\n\ -@item umfpack\n\ -Flag whether the @sc{umfpack} or mmd solvers are used for the LU, '\\' and\n\ -'/' operations (default 1)\n\ -@end table\n\ -\n\ -The value of individual keys can be set with\n\ -@code{spparms (@var{key}, @var{val})}.\n\ -The default values can be restored with the special keyword\n\ -@qcode{\"default\"}. The special keyword @qcode{\"tight\"} can be used to\n\ -set the mmd solvers to attempt a sparser solution at the potential cost of\n\ -longer running time.\n\ -@seealso{chol, colamd, lu, qr, symamd}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} { } spparms () +@deftypefnx {} {@var{vals} =} spparms () +@deftypefnx {} {[@var{keys}, @var{vals}] =} spparms () +@deftypefnx {} {@var{val} =} spparms (@var{key}) +@deftypefnx {} { } spparms (@var{vals}) +@deftypefnx {} { } spparms ("default") +@deftypefnx {} { } spparms ("tight") +@deftypefnx {} { } spparms (@var{key}, @var{val}) +Query or set the parameters used by the sparse solvers and factorization +functions. + +The first four calls above get information about the current settings, while +the others change the current settings. The parameters are stored as pairs +of keys and values, where the values are all floats and the keys are one of +the following strings: + +@table @samp +@item spumoni +Printing level of debugging information of the solvers (default 0) + +@item ths_rel +Included for compatibility. Not used. (default 1) + +@item ths_abs +Included for compatibility. Not used. (default 1) + +@item exact_d +Included for compatibility. Not used. (default 0) + +@item supernd +Included for compatibility. Not used. (default 3) + +@item rreduce +Included for compatibility. Not used. (default 3) + +@item wh_frac +Included for compatibility. Not used. (default 0.5) + +@item autommd +Flag whether the LU/QR and the '\' and '/' operators will automatically +use the sparsity preserving mmd functions (default 1) + +@item autoamd +Flag whether the LU and the '\' and '/' operators will automatically +use the sparsity preserving amd functions (default 1) + +@item piv_tol +The pivot tolerance of the @sc{umfpack} solvers (default 0.1) + +@item sym_tol +The pivot tolerance of the @sc{umfpack} symmetric solvers (default 0.001) + +@item bandden +The density of nonzero elements in a banded matrix before it is treated +by the @sc{lapack} banded solvers (default 0.5) + +@item umfpack +Flag whether the @sc{umfpack} or mmd solvers are used for the LU, '\' and +'/' operations (default 1) +@end table + +The value of individual keys can be set with +@code{spparms (@var{key}, @var{val})}. +The default values can be restored with the special keyword +@qcode{"default"}. The special keyword @qcode{"tight"} can be used to +set the mmd solvers to attempt a sparser solution at the potential cost of +longer running time. +@seealso{chol, colamd, lu, qr, symamd} +@end deftypefn */) { octave_value_list retval; int nargin = args.length ();
--- a/libinterp/corefcn/sqrtm.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/sqrtm.cc Tue Jun 21 16:07:51 2016 -0400 @@ -198,16 +198,16 @@ } DEFUN (sqrtm, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{s} =} sqrtm (@var{A})\n\ -@deftypefnx {} {[@var{s}, @var{error_estimate}] =} sqrtm (@var{A})\n\ -Compute the matrix square root of the square matrix @var{A}.\n\ -\n\ -Ref: @nospell{N.J. Higham}. @cite{A New sqrtm for @sc{matlab}}. Numerical\n\ -Analysis Report No. 336, Manchester @nospell{Centre} for Computational\n\ -Mathematics, Manchester, England, January 1999.\n\ -@seealso{expm, logm}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{s} =} sqrtm (@var{A}) +@deftypefnx {} {[@var{s}, @var{error_estimate}] =} sqrtm (@var{A}) +Compute the matrix square root of the square matrix @var{A}. + +Ref: @nospell{N.J. Higham}. @cite{A New sqrtm for @sc{matlab}}. Numerical +Analysis Report No. 336, Manchester @nospell{Centre} for Computational +Mathematics, Manchester, England, January 1999. +@seealso{expm, logm} +@end deftypefn */) { if (args.length () != 1) print_usage ();
--- a/libinterp/corefcn/str2double.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/str2double.cc Tue Jun 21 16:07:51 2016 -0400 @@ -295,51 +295,51 @@ } DEFUN (str2double, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} str2double (@var{s})\n\ -Convert a string to a real or complex number.\n\ -\n\ -The string must be in one of the following formats where a and b are real\n\ -numbers and the complex unit is @qcode{'i'} or @qcode{'j'}:\n\ -\n\ -@itemize\n\ -@item a + bi\n\ -\n\ -@item a + b*i\n\ -\n\ -@item a + i*b\n\ -\n\ -@item bi + a\n\ -\n\ -@item b*i + a\n\ -\n\ -@item i*b + a\n\ -@end itemize\n\ -\n\ -If present, a and/or b are of the form @nospell{[+-]d[,.]d[[eE][+-]d]} where\n\ -the brackets indicate optional arguments and @qcode{'d'} indicates zero or\n\ -more digits. The special input values @code{Inf}, @code{NaN}, and @code{NA}\n\ -are also accepted.\n\ -\n\ -@var{s} may be a character string, character matrix, or cell array. For\n\ -character arrays the conversion is repeated for every row, and a double or\n\ -complex array is returned. Empty rows in @var{s} are deleted and not\n\ -returned in the numeric array. For cell arrays each character string\n\ -element is processed and a double or complex array of the same dimensions as\n\ -@var{s} is returned.\n\ -\n\ -For unconvertible scalar or character string input @code{str2double} returns\n\ -a NaN@. Similarly, for character array input @code{str2double} returns a\n\ -NaN for any row of @var{s} that could not be converted. For a cell array,\n\ -@code{str2double} returns a NaN for any element of @var{s} for which\n\ -conversion fails. Note that numeric elements in a mixed string/numeric\n\ -cell array are not strings and the conversion will fail for these elements\n\ -and return NaN.\n\ -\n\ -@code{str2double} can replace @code{str2num}, and it avoids the security\n\ -risk of using @code{eval} on unknown data.\n\ -@seealso{str2num}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} str2double (@var{s}) +Convert a string to a real or complex number. + +The string must be in one of the following formats where a and b are real +numbers and the complex unit is @qcode{'i'} or @qcode{'j'}: + +@itemize +@item a + bi + +@item a + b*i + +@item a + i*b + +@item bi + a + +@item b*i + a + +@item i*b + a +@end itemize + +If present, a and/or b are of the form @nospell{[+-]d[,.]d[[eE][+-]d]} where +the brackets indicate optional arguments and @qcode{'d'} indicates zero or +more digits. The special input values @code{Inf}, @code{NaN}, and @code{NA} +are also accepted. + +@var{s} may be a character string, character matrix, or cell array. For +character arrays the conversion is repeated for every row, and a double or +complex array is returned. Empty rows in @var{s} are deleted and not +returned in the numeric array. For cell arrays each character string +element is processed and a double or complex array of the same dimensions as +@var{s} is returned. + +For unconvertible scalar or character string input @code{str2double} returns +a NaN@. Similarly, for character array input @code{str2double} returns a +NaN for any row of @var{s} that could not be converted. For a cell array, +@code{str2double} returns a NaN for any element of @var{s} for which +conversion fails. Note that numeric elements in a mixed string/numeric +cell array are not strings and the conversion will fail for these elements +and return NaN. + +@code{str2double} can replace @code{str2num}, and it avoids the security +risk of using @code{eval} on unknown data. +@seealso{str2num} +@end deftypefn */) { if (args.length () != 1) print_usage ();
--- a/libinterp/corefcn/strfind.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/strfind.cc Tue Jun 21 16:07:51 2016 -0400 @@ -149,48 +149,48 @@ } DEFUN (strfind, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{idx} =} strfind (@var{str}, @var{pattern})\n\ -@deftypefnx {} {@var{idx} =} strfind (@var{cellstr}, @var{pattern})\n\ -@deftypefnx {} {@var{idx} =} strfind (@dots{}, \"overlaps\", @var{val})\n\ -Search for @var{pattern} in the string @var{str} and return the starting\n\ -index of every such occurrence in the vector @var{idx}.\n\ -\n\ -If there is no such occurrence, or if @var{pattern} is longer than\n\ -@var{str}, or if @var{pattern} itself is empty, then @var{idx} is the empty\n\ -array @code{[]}.\n\ -\n\ -The optional argument @qcode{\"overlaps\"} determines whether the pattern\n\ -can match at every position in @var{str} (true), or only for unique\n\ -occurrences of the complete pattern (false). The default is true.\n\ -\n\ -If a cell array of strings @var{cellstr} is specified then @var{idx} is a\n\ -cell array of vectors, as specified above.\n\ -\n\ -Examples:\n\ -\n\ -@example\n\ -@group\n\ -strfind (\"abababa\", \"aba\")\n\ - @result{} [1, 3, 5]\n\ -\n\ -strfind (\"abababa\", \"aba\", \"overlaps\", false)\n\ - @result{} [1, 5]\n\ -\n\ -strfind (@{\"abababa\", \"bebebe\", \"ab\"@}, \"aba\")\n\ - @result{}\n\ - @{\n\ - [1,1] =\n\ -\n\ - 1 3 5\n\ -\n\ - [1,2] = [](1x0)\n\ - [1,3] = [](1x0)\n\ - @}\n\ -@end group\n\ -@end example\n\ -@seealso{findstr, strmatch, regexp, regexpi, find}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{idx} =} strfind (@var{str}, @var{pattern}) +@deftypefnx {} {@var{idx} =} strfind (@var{cellstr}, @var{pattern}) +@deftypefnx {} {@var{idx} =} strfind (@dots{}, "overlaps", @var{val}) +Search for @var{pattern} in the string @var{str} and return the starting +index of every such occurrence in the vector @var{idx}. + +If there is no such occurrence, or if @var{pattern} is longer than +@var{str}, or if @var{pattern} itself is empty, then @var{idx} is the empty +array @code{[]}. + +The optional argument @qcode{"overlaps"} determines whether the pattern +can match at every position in @var{str} (true), or only for unique +occurrences of the complete pattern (false). The default is true. + +If a cell array of strings @var{cellstr} is specified then @var{idx} is a +cell array of vectors, as specified above. + +Examples: + +@example +@group +strfind ("abababa", "aba") + @result{} [1, 3, 5] + +strfind ("abababa", "aba", "overlaps", false) + @result{} [1, 5] + +strfind (@{"abababa", "bebebe", "ab"@}, "aba") + @result{} + @{ + [1,1] = + + 1 3 5 + + [1,2] = [](1x0) + [1,3] = [](1x0) + @} +@end group +@end example +@seealso{findstr, strmatch, regexp, regexpi, find} +@end deftypefn */) { int nargin = args.length (); @@ -352,31 +352,31 @@ } DEFUN (strrep, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{newstr} =} strrep (@var{str}, @var{ptn}, @var{rep})\n\ -@deftypefnx {} {@var{newstr} =} strrep (@var{cellstr}, @var{ptn}, @var{rep})\n\ -@deftypefnx {} {@var{newstr} =} strrep (@dots{}, \"overlaps\", @var{val})\n\ -Replace all occurrences of the pattern @var{ptn} in the string @var{str}\n\ -with the string @var{rep} and return the result.\n\ -\n\ -The optional argument @qcode{\"overlaps\"} determines whether the pattern\n\ -can match at every position in @var{str} (true), or only for unique\n\ -occurrences of the complete pattern (false). The default is true.\n\ -\n\ -@var{s} may also be a cell array of strings, in which case the replacement\n\ -is done for each element and a cell array is returned.\n\ -\n\ -Example:\n\ -\n\ -@example\n\ -@group\n\ -strrep (\"This is a test string\", \"is\", \"&%$\")\n\ - @result{} \"Th&%$ &%$ a test string\"\n\ -@end group\n\ -@end example\n\ -\n\ -@seealso{regexprep, strfind, findstr}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{newstr} =} strrep (@var{str}, @var{ptn}, @var{rep}) +@deftypefnx {} {@var{newstr} =} strrep (@var{cellstr}, @var{ptn}, @var{rep}) +@deftypefnx {} {@var{newstr} =} strrep (@dots{}, "overlaps", @var{val}) +Replace all occurrences of the pattern @var{ptn} in the string @var{str} +with the string @var{rep} and return the result. + +The optional argument @qcode{"overlaps"} determines whether the pattern +can match at every position in @var{str} (true), or only for unique +occurrences of the complete pattern (false). The default is true. + +@var{s} may also be a cell array of strings, in which case the replacement +is done for each element and a cell array is returned. + +Example: + +@example +@group +strrep ("This is a test string", "is", "&%$") + @result{} "Th&%$ &%$ a test string" +@end group +@end example + +@seealso{regexprep, strfind, findstr} +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/strfns.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/strfns.cc Tue Jun 21 16:07:51 2016 -0400 @@ -41,40 +41,40 @@ #include "utils.h" DEFUN (char, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} char (@var{x})\n\ -@deftypefnx {} {} char (@var{x}, @dots{})\n\ -@deftypefnx {} {} char (@var{s1}, @var{s2}, @dots{})\n\ -@deftypefnx {} {} char (@var{cell_array})\n\ -Create a string array from one or more numeric matrices, character\n\ -matrices, or cell arrays.\n\ -\n\ -Arguments are concatenated vertically. The returned values are padded with\n\ -blanks as needed to make each row of the string array have the same length.\n\ -Empty input strings are significant and will concatenated in the output.\n\ -\n\ -For numerical input, each element is converted to the corresponding ASCII\n\ -character. A range error results if an input is outside the ASCII range\n\ -(0-255).\n\ -\n\ -For cell arrays, each element is concatenated separately. Cell arrays\n\ -converted through @code{char} can mostly be converted back with\n\ -@code{cellstr}. For example:\n\ -\n\ -@example\n\ -@group\n\ -char ([97, 98, 99], \"\", @{\"98\", \"99\", 100@}, \"str1\", [\"ha\", \"lf\"])\n\ - @result{} [\"abc \"\n\ - \" \"\n\ - \"98 \"\n\ - \"99 \"\n\ - \"d \"\n\ - \"str1 \"\n\ - \"half \"]\n\ -@end group\n\ -@end example\n\ -@seealso{strvcat, cellstr}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} char (@var{x}) +@deftypefnx {} {} char (@var{x}, @dots{}) +@deftypefnx {} {} char (@var{s1}, @var{s2}, @dots{}) +@deftypefnx {} {} char (@var{cell_array}) +Create a string array from one or more numeric matrices, character +matrices, or cell arrays. + +Arguments are concatenated vertically. The returned values are padded with +blanks as needed to make each row of the string array have the same length. +Empty input strings are significant and will concatenated in the output. + +For numerical input, each element is converted to the corresponding ASCII +character. A range error results if an input is outside the ASCII range +(0-255). + +For cell arrays, each element is concatenated separately. Cell arrays +converted through @code{char} can mostly be converted back with +@code{cellstr}. For example: + +@example +@group +char ([97, 98, 99], "", @{"98", "99", 100@}, "str1", ["ha", "lf"]) + @result{} ["abc " + " " + "98 " + "99 " + "d " + "str1 " + "half "] +@end group +@end example +@seealso{strvcat, cellstr} +@end deftypefn */) { octave_value retval; @@ -166,40 +166,40 @@ */ DEFUN (strvcat, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} strvcat (@var{x})\n\ -@deftypefnx {} {} strvcat (@var{x}, @dots{})\n\ -@deftypefnx {} {} strvcat (@var{s1}, @var{s2}, @dots{})\n\ -@deftypefnx {} {} strvcat (@var{cell_array})\n\ -Create a character array from one or more numeric matrices, character\n\ -matrices, or cell arrays.\n\ -\n\ -Arguments are concatenated vertically. The returned values are padded with\n\ -blanks as needed to make each row of the string array have the same length.\n\ -Unlike @code{char}, empty strings are removed and will not appear in the\n\ -output.\n\ -\n\ -For numerical input, each element is converted to the corresponding ASCII\n\ -character. A range error results if an input is outside the ASCII range\n\ -(0-255).\n\ -\n\ -For cell arrays, each element is concatenated separately. Cell arrays\n\ -converted through @code{strvcat} can mostly be converted back with\n\ -@code{cellstr}. For example:\n\ -\n\ -@example\n\ -@group\n\ -strvcat ([97, 98, 99], \"\", @{\"98\", \"99\", 100@}, \"str1\", [\"ha\", \"lf\"])\n\ - @result{} [\"abc \"\n\ - \"98 \"\n\ - \"99 \"\n\ - \"d \"\n\ - \"str1 \"\n\ - \"half \"]\n\ -@end group\n\ -@end example\n\ -@seealso{char, strcat, cstrcat}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} strvcat (@var{x}) +@deftypefnx {} {} strvcat (@var{x}, @dots{}) +@deftypefnx {} {} strvcat (@var{s1}, @var{s2}, @dots{}) +@deftypefnx {} {} strvcat (@var{cell_array}) +Create a character array from one or more numeric matrices, character +matrices, or cell arrays. + +Arguments are concatenated vertically. The returned values are padded with +blanks as needed to make each row of the string array have the same length. +Unlike @code{char}, empty strings are removed and will not appear in the +output. + +For numerical input, each element is converted to the corresponding ASCII +character. A range error results if an input is outside the ASCII range +(0-255). + +For cell arrays, each element is concatenated separately. Cell arrays +converted through @code{strvcat} can mostly be converted back with +@code{cellstr}. For example: + +@example +@group +strvcat ([97, 98, 99], "", @{"98", "99", 100@}, "str1", ["ha", "lf"]) + @result{} ["abc " + "98 " + "99 " + "d " + "str1 " + "half "] +@end group +@end example +@seealso{char, strcat, cstrcat} +@end deftypefn */) { int nargin = args.length (); int n_elts = 0; @@ -280,11 +280,11 @@ DEFUN (ischar, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} ischar (@var{x})\n\ -Return true if @var{x} is a character array.\n\ -@seealso{isfloat, isinteger, islogical, isnumeric, iscellstr, isa}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} ischar (@var{x}) +Return true if @var{x} is a character array. +@seealso{isfloat, isinteger, islogical, isnumeric, iscellstr, isa} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -532,22 +532,22 @@ } DEFUN (strcmp, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} strcmp (@var{s1}, @var{s2})\n\ -Return 1 if the character strings @var{s1} and @var{s2} are the same,\n\ -and 0 otherwise.\n\ -\n\ -If either @var{s1} or @var{s2} is a cell array of strings, then an array\n\ -of the same size is returned, containing the values described above for\n\ -every member of the cell array. The other argument may also be a cell\n\ -array of strings (of the same size or with only one element), char matrix\n\ -or character string.\n\ -\n\ -@strong{Caution:} For compatibility with @sc{matlab}, Octave's strcmp\n\ -function returns 1 if the character strings are equal, and 0 otherwise.\n\ -This is just the opposite of the corresponding C library function.\n\ -@seealso{strcmpi, strncmp, strncmpi}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} strcmp (@var{s1}, @var{s2}) +Return 1 if the character strings @var{s1} and @var{s2} are the same, +and 0 otherwise. + +If either @var{s1} or @var{s2} is a cell array of strings, then an array +of the same size is returned, containing the values described above for +every member of the cell array. The other argument may also be a cell +array of strings (of the same size or with only one element), char matrix +or character string. + +@strong{Caution:} For compatibility with @sc{matlab}, Octave's strcmp +function returns 1 if the character strings are equal, and 0 otherwise. +This is just the opposite of the corresponding C library function. +@seealso{strcmpi, strncmp, strncmpi} +@end deftypefn */) { if (args.length () != 2) print_usage (); @@ -628,36 +628,36 @@ } DEFUN (strncmp, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} strncmp (@var{s1}, @var{s2}, @var{n})\n\ -Return 1 if the first @var{n} characters of strings @var{s1} and @var{s2}\n\ -are the same, and 0 otherwise.\n\ -\n\ -@example\n\ -@group\n\ -strncmp (\"abce\", \"abcd\", 3)\n\ - @result{} 1\n\ -@end group\n\ -@end example\n\ -\n\ -If either @var{s1} or @var{s2} is a cell array of strings, then an array\n\ -of the same size is returned, containing the values described above for\n\ -every member of the cell array. The other argument may also be a cell\n\ -array of strings (of the same size or with only one element), char matrix\n\ -or character string.\n\ -\n\ -@example\n\ -@group\n\ -strncmp (\"abce\", @{\"abcd\", \"bca\", \"abc\"@}, 3)\n\ - @result{} [1, 0, 1]\n\ -@end group\n\ -@end example\n\ -\n\ -@strong{Caution:} For compatibility with @sc{matlab}, Octave's strncmp\n\ -function returns 1 if the character strings are equal, and 0 otherwise.\n\ -This is just the opposite of the corresponding C library function.\n\ -@seealso{strncmpi, strcmp, strcmpi}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} strncmp (@var{s1}, @var{s2}, @var{n}) +Return 1 if the first @var{n} characters of strings @var{s1} and @var{s2} +are the same, and 0 otherwise. + +@example +@group +strncmp ("abce", "abcd", 3) + @result{} 1 +@end group +@end example + +If either @var{s1} or @var{s2} is a cell array of strings, then an array +of the same size is returned, containing the values described above for +every member of the cell array. The other argument may also be a cell +array of strings (of the same size or with only one element), char matrix +or character string. + +@example +@group +strncmp ("abce", @{"abcd", "bca", "abc"@}, 3) + @result{} [1, 0, 1] +@end group +@end example + +@strong{Caution:} For compatibility with @sc{matlab}, Octave's strncmp +function returns 1 if the character strings are equal, and 0 otherwise. +This is just the opposite of the corresponding C library function. +@seealso{strncmpi, strcmp, strcmpi} +@end deftypefn */) { if (args.length () != 3) print_usage (); @@ -713,24 +713,24 @@ } DEFUNX ("strcmpi", Fstrcmpi, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} strcmpi (@var{s1}, @var{s2})\n\ -Return 1 if the character strings @var{s1} and @var{s2} are the same,\n\ -disregarding case of alphabetic characters, and 0 otherwise.\n\ -\n\ -If either @var{s1} or @var{s2} is a cell array of strings, then an array\n\ -of the same size is returned, containing the values described above for\n\ -every member of the cell array. The other argument may also be a cell\n\ -array of strings (of the same size or with only one element), char matrix\n\ -or character string.\n\ -\n\ -@strong{Caution:} For compatibility with @sc{matlab}, Octave's strcmp\n\ -function returns 1 if the character strings are equal, and 0 otherwise.\n\ -This is just the opposite of the corresponding C library function.\n\ -\n\ -@strong{Caution:} National alphabets are not supported.\n\ -@seealso{strcmp, strncmp, strncmpi}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} strcmpi (@var{s1}, @var{s2}) +Return 1 if the character strings @var{s1} and @var{s2} are the same, +disregarding case of alphabetic characters, and 0 otherwise. + +If either @var{s1} or @var{s2} is a cell array of strings, then an array +of the same size is returned, containing the values described above for +every member of the cell array. The other argument may also be a cell +array of strings (of the same size or with only one element), char matrix +or character string. + +@strong{Caution:} For compatibility with @sc{matlab}, Octave's strcmp +function returns 1 if the character strings are equal, and 0 otherwise. +This is just the opposite of the corresponding C library function. + +@strong{Caution:} National alphabets are not supported. +@seealso{strcmp, strncmp, strncmpi} +@end deftypefn */) { if (args.length () != 2) print_usage (); @@ -768,24 +768,24 @@ } DEFUNX ("strncmpi", Fstrncmpi, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} strncmpi (@var{s1}, @var{s2}, @var{n})\n\ -Return 1 if the first @var{n} character of @var{s1} and @var{s2} are the\n\ -same, disregarding case of alphabetic characters, and 0 otherwise.\n\ -\n\ -If either @var{s1} or @var{s2} is a cell array of strings, then an array\n\ -of the same size is returned, containing the values described above for\n\ -every member of the cell array. The other argument may also be a cell\n\ -array of strings (of the same size or with only one element), char matrix\n\ -or character string.\n\ -\n\ -@strong{Caution:} For compatibility with @sc{matlab}, Octave's strncmpi\n\ -function returns 1 if the character strings are equal, and 0 otherwise.\n\ -This is just the opposite of the corresponding C library function.\n\ -\n\ -@strong{Caution:} National alphabets are not supported.\n\ -@seealso{strncmp, strcmp, strcmpi}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} strncmpi (@var{s1}, @var{s2}, @var{n}) +Return 1 if the first @var{n} character of @var{s1} and @var{s2} are the +same, disregarding case of alphabetic characters, and 0 otherwise. + +If either @var{s1} or @var{s2} is a cell array of strings, then an array +of the same size is returned, containing the values described above for +every member of the cell array. The other argument may also be a cell +array of strings (of the same size or with only one element), char matrix +or character string. + +@strong{Caution:} For compatibility with @sc{matlab}, Octave's strncmpi +function returns 1 if the character strings are equal, and 0 otherwise. +This is just the opposite of the corresponding C library function. + +@strong{Caution:} National alphabets are not supported. +@seealso{strncmp, strcmp, strcmpi} +@end deftypefn */) { if (args.length () != 3) print_usage (); @@ -804,40 +804,40 @@ */ DEFUN (list_in_columns, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} list_in_columns (@var{arg}, @var{width}, @var{prefix})\n\ -Return a string containing the elements of @var{arg} listed in columns with\n\ -an overall maximum width of @var{width} and optional prefix @var{prefix}.\n\ -\n\ -The argument @var{arg} must be a cell array of character strings or a\n\ -character array.\n\ -\n\ -If @var{width} is not specified or is an empty matrix, or less than or equal\n\ -to zero, the width of the terminal screen is used. Newline characters are\n\ -used to break the lines in the output string. For example:\n\ -@c Set example in small font to prevent overfull line\n\ -\n\ -@smallexample\n\ -@group\n\ -list_in_columns (@{\"abc\", \"def\", \"ghijkl\", \"mnop\", \"qrs\", \"tuv\"@}, 20)\n\ - @result{} abc mnop\n\ - def qrs\n\ - ghijkl tuv\n\ -\n\ -whos ans\n\ - @result{}\n\ - Variables in the current scope:\n\ -\n\ - Attr Name Size Bytes Class\n\ - ==== ==== ==== ===== =====\n\ - ans 1x37 37 char\n\ -\n\ - Total is 37 elements using 37 bytes\n\ -@end group\n\ -@end smallexample\n\ -\n\ -@seealso{terminal_size}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} list_in_columns (@var{arg}, @var{width}, @var{prefix}) +Return a string containing the elements of @var{arg} listed in columns with +an overall maximum width of @var{width} and optional prefix @var{prefix}. + +The argument @var{arg} must be a cell array of character strings or a +character array. + +If @var{width} is not specified or is an empty matrix, or less than or equal +to zero, the width of the terminal screen is used. Newline characters are +used to break the lines in the output string. For example: +@c Set example in small font to prevent overfull line + +@smallexample +@group +list_in_columns (@{"abc", "def", "ghijkl", "mnop", "qrs", "tuv"@}, 20) + @result{} abc mnop + def qrs + ghijkl tuv + +whos ans + @result{} + Variables in the current scope: + + Attr Name Size Bytes Class + ==== ==== ==== ===== ===== + ans 1x37 37 char + + Total is 37 elements using 37 bytes +@end group +@end smallexample + +@seealso{terminal_size} +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/sub2ind.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/sub2ind.cc Tue Jun 21 16:07:51 2016 -0400 @@ -59,23 +59,23 @@ } DEFUN (sub2ind, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{ind} =} sub2ind (@var{dims}, @var{i}, @var{j})\n\ -@deftypefnx {} {@var{ind} =} sub2ind (@var{dims}, @var{s1}, @var{s2}, @dots{}, @var{sN})\n\ -Convert subscripts to a linear index.\n\ -\n\ -The following example shows how to convert the two-dimensional index\n\ -@code{(2,3)} of a 3-by-3 matrix to a linear index. The matrix is linearly\n\ -indexed moving from one column to next, filling up all rows in each column.\n\ -\n\ -@example\n\ -@group\n\ -linear_index = sub2ind ([3, 3], 2, 3)\n\ -@result{} 8\n\ -@end group\n\ -@end example\n\ -@seealso{ind2sub}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{ind} =} sub2ind (@var{dims}, @var{i}, @var{j}) +@deftypefnx {} {@var{ind} =} sub2ind (@var{dims}, @var{s1}, @var{s2}, @dots{}, @var{sN}) +Convert subscripts to a linear index. + +The following example shows how to convert the two-dimensional index +@code{(2,3)} of a 3-by-3 matrix to a linear index. The matrix is linearly +indexed moving from one column to next, filling up all rows in each column. + +@example +@group +linear_index = sub2ind ([3, 3], 2, 3) +@result{} 8 +@end group +@end example +@seealso{ind2sub} +@end deftypefn */) { int nargin = args.length (); @@ -156,23 +156,23 @@ */ DEFUN (ind2sub, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{s1}, @var{s2}, @dots{}, @var{sN}] =} ind2sub (@var{dims}, @var{ind})\n\ -Convert a linear index to subscripts.\n\ -\n\ -The following example shows how to convert the linear index @code{8}\n\ -in a 3-by-3 matrix into a subscript. The matrix is linearly indexed\n\ -moving from one column to next, filling up all rows in each column.\n\ -\n\ -@example\n\ -@group\n\ -[r, c] = ind2sub ([3, 3], 8)\n\ - @result{} r = 2\n\ - @result{} c = 3\n\ -@end group\n\ -@end example\n\ -@seealso{sub2ind}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{s1}, @var{s2}, @dots{}, @var{sN}] =} ind2sub (@var{dims}, @var{ind}) +Convert a linear index to subscripts. + +The following example shows how to convert the linear index @code{8} +in a 3-by-3 matrix into a subscript. The matrix is linearly indexed +moving from one column to next, filling up all rows in each column. + +@example +@group +[r, c] = ind2sub ([3, 3], 8) + @result{} r = 2 + @result{} c = 3 +@end group +@end example +@seealso{sub2ind} +@end deftypefn */) { if (args.length () != 2) print_usage ();
--- a/libinterp/corefcn/svd.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/svd.cc Tue Jun 21 16:07:51 2016 -0400 @@ -53,89 +53,89 @@ } DEFUN (svd, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{s} =} svd (@var{A})\n\ -@deftypefnx {} {[@var{U}, @var{S}, @var{V}] =} svd (@var{A})\n\ -@deftypefnx {} {[@var{U}, @var{S}, @var{V}] =} svd (@var{A}, @var{econ})\n\ -@cindex singular value decomposition\n\ -Compute the singular value decomposition of @var{A}\n\ -@tex\n\ -$$\n\ - A = U S V^{\\dagger}\n\ -$$\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ -A = U*S*V'\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -\n\ -The function @code{svd} normally returns only the vector of singular values.\n\ -When called with three return values, it computes\n\ -@tex\n\ -$U$, $S$, and $V$.\n\ -@end tex\n\ -@ifnottex\n\ -@var{U}, @var{S}, and @var{V}.\n\ -@end ifnottex\n\ -For example,\n\ -\n\ -@example\n\ -svd (hilb (3))\n\ -@end example\n\ -\n\ -@noindent\n\ -returns\n\ -\n\ -@example\n\ -@group\n\ -ans =\n\ -\n\ - 1.4083189\n\ - 0.1223271\n\ - 0.0026873\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -and\n\ -\n\ -@example\n\ -[u, s, v] = svd (hilb (3))\n\ -@end example\n\ -\n\ -@noindent\n\ -returns\n\ -\n\ -@example\n\ -@group\n\ -u =\n\ -\n\ - -0.82704 0.54745 0.12766\n\ - -0.45986 -0.52829 -0.71375\n\ - -0.32330 -0.64901 0.68867\n\ -\n\ -s =\n\ -\n\ - 1.40832 0.00000 0.00000\n\ - 0.00000 0.12233 0.00000\n\ - 0.00000 0.00000 0.00269\n\ -\n\ -v =\n\ -\n\ - -0.82704 0.54745 0.12766\n\ - -0.45986 -0.52829 -0.71375\n\ - -0.32330 -0.64901 0.68867\n\ -@end group\n\ -@end example\n\ -\n\ -If given a second argument, @code{svd} returns an economy-sized\n\ -decomposition, eliminating the unnecessary rows or columns of @var{U} or\n\ -@var{V}.\n\ -@seealso{svd_driver, svds, eig, lu, chol, hess, qr, qz}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{s} =} svd (@var{A}) +@deftypefnx {} {[@var{U}, @var{S}, @var{V}] =} svd (@var{A}) +@deftypefnx {} {[@var{U}, @var{S}, @var{V}] =} svd (@var{A}, @var{econ}) +@cindex singular value decomposition +Compute the singular value decomposition of @var{A} +@tex +$$ + A = U S V^{\dagger} +$$ +@end tex +@ifnottex + +@example +A = U*S*V' +@end example + +@end ifnottex + +The function @code{svd} normally returns only the vector of singular values. +When called with three return values, it computes +@tex +$U$, $S$, and $V$. +@end tex +@ifnottex +@var{U}, @var{S}, and @var{V}. +@end ifnottex +For example, + +@example +svd (hilb (3)) +@end example + +@noindent +returns + +@example +@group +ans = + + 1.4083189 + 0.1223271 + 0.0026873 +@end group +@end example + +@noindent +and + +@example +[u, s, v] = svd (hilb (3)) +@end example + +@noindent +returns + +@example +@group +u = + + -0.82704 0.54745 0.12766 + -0.45986 -0.52829 -0.71375 + -0.32330 -0.64901 0.68867 + +s = + + 1.40832 0.00000 0.00000 + 0.00000 0.12233 0.00000 + 0.00000 0.00000 0.00269 + +v = + + -0.82704 0.54745 0.12766 + -0.45986 -0.52829 -0.71375 + -0.32330 -0.64901 0.68867 +@end group +@end example + +If given a second argument, @code{svd} returns an economy-sized +decomposition, eliminating the unnecessary rows or columns of @var{U} or +@var{V}. +@seealso{svd_driver, svds, eig, lu, chol, hess, qr, qz} +@end deftypefn */) { int nargin = args.length (); @@ -322,20 +322,20 @@ */ DEFUN (svd_driver, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} svd_driver ()\n\ -@deftypefnx {} {@var{old_val} =} svd_driver (@var{new_val})\n\ -@deftypefnx {} {} svd_driver (@var{new_val}, \"local\")\n\ -Query or set the underlying @sc{lapack} driver used by @code{svd}.\n\ -\n\ -Currently recognized values are @qcode{\"gesvd\"} and @qcode{\"gesdd\"}.\n\ -The default is @qcode{\"gesvd\"}.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{svd}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} svd_driver () +@deftypefnx {} {@var{old_val} =} svd_driver (@var{new_val}) +@deftypefnx {} {} svd_driver (@var{new_val}, "local") +Query or set the underlying @sc{lapack} driver used by @code{svd}. + +Currently recognized values are @qcode{"gesvd"} and @qcode{"gesdd"}. +The default is @qcode{"gesvd"}. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{svd} +@end deftypefn */) { static const char *driver_names[] = { "gesvd", "gesdd", 0 };
--- a/libinterp/corefcn/sylvester.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/sylvester.cc Tue Jun 21 16:07:51 2016 -0400 @@ -33,32 +33,32 @@ #include "utils.h" DEFUN (sylvester, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{X} =} syl (@var{A}, @var{B}, @var{C})\n\ -Solve the Sylvester equation\n\ -@tex\n\ -$$\n\ - A X + X B = C\n\ -$$\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ -A X + X B = C\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -using standard @sc{lapack} subroutines.\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -sylvester ([1, 2; 3, 4], [5, 6; 7, 8], [9, 10; 11, 12])\n\ - @result{} [ 0.50000, 0.66667; 0.66667, 0.50000 ]\n\ -@end group\n\ -@end example\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{X} =} syl (@var{A}, @var{B}, @var{C}) +Solve the Sylvester equation +@tex +$$ + A X + X B = C +$$ +@end tex +@ifnottex + +@example +A X + X B = C +@end example + +@end ifnottex +using standard @sc{lapack} subroutines. + +For example: + +@example +@group +sylvester ([1, 2; 3, 4], [5, 6; 7, 8], [9, 10; 11, 12]) + @result{} [ 0.50000, 0.66667; 0.66667, 0.50000 ] +@end group +@end example +@end deftypefn */) { if (args.length () != 3) print_usage ();
--- a/libinterp/corefcn/symtab.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/symtab.cc Tue Jun 21 16:07:51 2016 -0400 @@ -1687,23 +1687,23 @@ } DEFUN (ignore_function_time_stamp, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} ignore_function_time_stamp ()\n\ -@deftypefnx {} {@var{old_val} =} ignore_function_time_stamp (@var{new_val})\n\ -Query or set the internal variable that controls whether Octave checks\n\ -the time stamp on files each time it looks up functions defined in\n\ -function files.\n\ -\n\ -If the internal variable is set to @qcode{\"system\"}, Octave will not\n\ -automatically recompile function files in subdirectories of\n\ -@file{@var{octave-home}/lib/@var{version}} if they have changed since they were last compiled, but will recompile other function files in the search path if they change.\n\ -\n\ -If set to @qcode{\"all\"}, Octave will not recompile any function files\n\ -unless their definitions are removed with @code{clear}.\n\ -\n\ -If set to @qcode{\"none\"}, Octave will always check time stamps on files to\n\ -determine whether functions defined in function files need to recompiled.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} ignore_function_time_stamp () +@deftypefnx {} {@var{old_val} =} ignore_function_time_stamp (@var{new_val}) +Query or set the internal variable that controls whether Octave checks +the time stamp on files each time it looks up functions defined in +function files. + +If the internal variable is set to @qcode{"system"}, Octave will not +automatically recompile function files in subdirectories of +@file{@var{octave-home}/lib/@var{version}} if they have changed since they were last compiled, but will recompile other function files in the search path if they change. + +If set to @qcode{"all"}, Octave will not recompile any function files +unless their definitions are removed with @code{clear}. + +If set to @qcode{"none"}, Octave will always check time stamps on files to +determine whether functions defined in function files need to recompiled. +@end deftypefn */) { int nargin = args.length (); @@ -1766,24 +1766,24 @@ */ DEFUN (__current_scope__, , , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{scope}, @var{context}]} __current_scope__ ()\n\ -Return the current scope and context as integers.\n\ -@seealso{__dump_symtab_info__}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{scope}, @var{context}]} __current_scope__ () +Return the current scope and context as integers. +@seealso{__dump_symtab_info__} +@end deftypefn */) { return ovl (symbol_table::current_scope (), symbol_table::current_context ()); } DEFUN (__dump_symtab_info__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __dump_symtab_info__ ()\n\ -@deftypefnx {} {} __dump_symtab_info__ (@var{scope})\n\ -@deftypefnx {} {} __dump_symtab_info__ (\"scopes\")\n\ -@deftypefnx {} {} __dump_symtab_info__ (\"functions\")\n\ -Undocumented internal function.\n\ -@seealso{__current_scope__}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __dump_symtab_info__ () +@deftypefnx {} {} __dump_symtab_info__ (@var{scope}) +@deftypefnx {} {} __dump_symtab_info__ ("scopes") +@deftypefnx {} {} __dump_symtab_info__ ("functions") +Undocumented internal function. +@seealso{__current_scope__} +@end deftypefn */) { int nargin = args.length (); @@ -1845,10 +1845,10 @@ } DEFUN (__get_cmdline_fcn_txt__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __get_cmdline_fcn_txt__ (@var{name})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __get_cmdline_fcn_txt__ (@var{name}) +Undocumented internal function. +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1875,41 +1875,37 @@ return retval; } -#if 0 - // FIXME: should we have functions like this in Octave? - -DEFUN (set_variable, args, , "set_variable (NAME, VALUE)") -{ - if (args.length () != 2) - print_usage (); - - std::string name = args(0).xstring_value ("set_variable: variable NAME must be a string"); - - symbol_table::assign (name, args(1)); - - return ovl (); -} - -DEFUN (variable_value, args, , "VALUE = variable_value (NAME)") -{ - if (args.length () != 1) - print_usage (); - - octave_value retval; - - std::string name = args(0).xstring_value ("variable_value: variable NAME must be a string"); - - retval = symbol_table::varval (name); - - if (retval.is_undefined ()) - error ("variable_value: '%s' is not a variable in the current scope", - name.c_str ()); - - return retval; -} -#endif - +// +// DEFUN (set_variable, args, , "set_variable (NAME, VALUE)") +// { +// if (args.length () != 2) +// print_usage (); +// +// std::string name = args(0).xstring_value ("set_variable: variable NAME must be a string"); +// +// symbol_table::assign (name, args(1)); +// +// return ovl (); +// } +// +// DEFUN (variable_value, args, , "VALUE = variable_value (NAME)") +// { +// if (args.length () != 1) +// print_usage (); +// +// octave_value retval; +// +// std::string name = args(0).xstring_value ("variable_value: variable NAME must be a string"); +// +// retval = symbol_table::varval (name); +// +// if (retval.is_undefined ()) +// error ("variable_value: '%s' is not a variable in the current scope", +// name.c_str ()); +// +// return retval; +// } /* bug #34497: 'clear -f' does not work for command line functions
--- a/libinterp/corefcn/syscalls.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/syscalls.cc Tue Jun 21 16:07:51 2016 -0400 @@ -103,15 +103,15 @@ } DEFUNX ("dup2", Fdup2, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{fid}, @var{msg}] =} dup2 (@var{old}, @var{new})\n\ -Duplicate a file descriptor.\n\ -\n\ -If successful, @var{fid} is greater than zero and contains the new file ID@.\n\ -Otherwise, @var{fid} is negative and @var{msg} contains a system-dependent\n\ -error message.\n\ -@seealso{fopen, fclose, fcntl}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{fid}, @var{msg}] =} dup2 (@var{old}, @var{new}) +Duplicate a file descriptor. + +If successful, @var{fid} is greater than zero and contains the new file ID@. +Otherwise, @var{fid} is negative and @var{msg} contains a system-dependent +error message. +@seealso{fopen, fclose, fcntl} +@end deftypefn */) { if (args.length () != 2) print_usage (); @@ -136,25 +136,25 @@ } DEFUNX ("exec", Fexec, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{err}, @var{msg}] =} exec (@var{file}, @var{args})\n\ -Replace current process with a new process.\n\ -\n\ -Calling @code{exec} without first calling @code{fork} will terminate your\n\ -current Octave process and replace it with the program named by @var{file}.\n\ -For example,\n\ -\n\ -@example\n\ -exec (\"ls\", \"-l\")\n\ -@end example\n\ -\n\ -@noindent\n\ -will run @code{ls} and return you to your shell prompt.\n\ -\n\ -If successful, @code{exec} does not return. If @code{exec} does return,\n\ -@var{err} will be nonzero, and @var{msg} will contain a system-dependent\n\ -error message.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{err}, @var{msg}] =} exec (@var{file}, @var{args}) +Replace current process with a new process. + +Calling @code{exec} without first calling @code{fork} will terminate your +current Octave process and replace it with the program named by @var{file}. +For example, + +@example +exec ("ls", "-l") +@end example + +@noindent +will run @code{ls} and return you to your shell prompt. + +If successful, @code{exec} does not return. If @code{exec} does return, +@var{err} will be nonzero, and @var{msg} will contain a system-dependent +error message. +@end deftypefn */) { int nargin = args.length (); @@ -198,51 +198,51 @@ } DEFUNX ("popen2", Fpopen2, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{in}, @var{out}, @var{pid}] =} popen2 (@var{command}, @var{args})\n\ -Start a subprocess with two-way communication.\n\ -\n\ -The name of the process is given by @var{command}, and @var{args} is an\n\ -array of strings containing options for the command.\n\ -\n\ -The file identifiers for the input and output streams of the subprocess are\n\ -returned in @var{in} and @var{out}. If execution of the command is\n\ -successful, @var{pid} contains the process ID of the subprocess. Otherwise,\n\ -@var{pid} is @minus{}1.\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -[in, out, pid] = popen2 (\"sort\", \"-r\");\n\ -fputs (in, \"these\\nare\\nsome\\nstrings\\n\");\n\ -fclose (in);\n\ -EAGAIN = errno (\"EAGAIN\");\n\ -done = false;\n\ -do\n\ - s = fgets (out);\n\ - if (ischar (s))\n\ - fputs (stdout, s);\n\ - elseif (errno () == EAGAIN)\n\ - pause (0.1);\n\ - fclear (out);\n\ - else\n\ - done = true;\n\ - endif\n\ -until (done)\n\ -fclose (out);\n\ -waitpid (pid);\n\ -\n\ - @print{} these\n\ - @print{} strings\n\ - @print{} some\n\ - @print{} are\n\ -@end example\n\ -\n\ -Note that @code{popen2}, unlike @code{popen}, will not @nospell{\"reap\"}\n\ -the child process. If you don't use @code{waitpid} to check the child's\n\ -exit status, it will linger until Octave exits.\n\ -@seealso{popen, waitpid}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{in}, @var{out}, @var{pid}] =} popen2 (@var{command}, @var{args}) +Start a subprocess with two-way communication. + +The name of the process is given by @var{command}, and @var{args} is an +array of strings containing options for the command. + +The file identifiers for the input and output streams of the subprocess are +returned in @var{in} and @var{out}. If execution of the command is +successful, @var{pid} contains the process ID of the subprocess. Otherwise, +@var{pid} is @minus{}1. + +For example: + +@example +[in, out, pid] = popen2 ("sort", "-r"); +fputs (in, "these\nare\nsome\nstrings\n"); +fclose (in); +EAGAIN = errno ("EAGAIN"); +done = false; +do + s = fgets (out); + if (ischar (s)) + fputs (stdout, s); + elseif (errno () == EAGAIN) + pause (0.1); + fclear (out); + else + done = true; + endif +until (done) +fclose (out); +waitpid (pid); + + @print{} these + @print{} strings + @print{} some + @print{} are +@end example + +Note that @code{popen2}, unlike @code{popen}, will not @nospell{"reap"} +the child process. If you don't use @code{waitpid} to check the child's +exit status, it will linger until Octave exits. +@seealso{popen, waitpid} +@end deftypefn */) { int nargin = args.length (); @@ -369,63 +369,63 @@ */ DEFUNX ("fcntl", Ffcntl, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{err}, @var{msg}] =} fcntl (@var{fid}, @var{request}, @var{arg})\n\ -Change the properties of the open file @var{fid}.\n\ -\n\ -The following values may be passed as @var{request}:\n\ -\n\ -@vtable @code\n\ -@item F_DUPFD\n\ -Return a duplicate file descriptor.\n\ -\n\ -@item F_GETFD\n\ -Return the file descriptor flags for @var{fid}.\n\ -\n\ -@item F_SETFD\n\ -Set the file descriptor flags for @var{fid}.\n\ -\n\ -@item F_GETFL\n\ -Return the file status flags for @var{fid}. The following codes may be\n\ -returned (some of the flags may be undefined on some systems).\n\ -\n\ -@vtable @code\n\ -@item O_RDONLY\n\ -Open for reading only.\n\ -\n\ -@item O_WRONLY\n\ -Open for writing only.\n\ -\n\ -@item O_RDWR\n\ -Open for reading and writing.\n\ -\n\ -@item O_APPEND\n\ -Append on each write.\n\ -\n\ -@item O_CREAT\n\ -Create the file if it does not exist.\n\ -\n\ -@item O_NONBLOCK\n\ -Non-blocking mode.\n\ -\n\ -@item O_SYNC\n\ -Wait for writes to complete.\n\ -\n\ -@item O_ASYNC\n\ -Asynchronous I/O.\n\ -@end vtable\n\ -\n\ -@item F_SETFL\n\ -Set the file status flags for @var{fid} to the value specified by @var{arg}.\n\ - The only flags that can be changed are @w{@code{O_APPEND}} and\n\ -@w{@code{O_NONBLOCK}}.\n\ -@end vtable\n\ -\n\ -If successful, @var{err} is 0 and @var{msg} is an empty string. Otherwise,\n\ -@var{err} is nonzero and @var{msg} contains a system-dependent error\n\ -message.\n\ -@seealso{fopen, dup2}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{err}, @var{msg}] =} fcntl (@var{fid}, @var{request}, @var{arg}) +Change the properties of the open file @var{fid}. + +The following values may be passed as @var{request}: + +@vtable @code +@item F_DUPFD +Return a duplicate file descriptor. + +@item F_GETFD +Return the file descriptor flags for @var{fid}. + +@item F_SETFD +Set the file descriptor flags for @var{fid}. + +@item F_GETFL +Return the file status flags for @var{fid}. The following codes may be +returned (some of the flags may be undefined on some systems). + +@vtable @code +@item O_RDONLY +Open for reading only. + +@item O_WRONLY +Open for writing only. + +@item O_RDWR +Open for reading and writing. + +@item O_APPEND +Append on each write. + +@item O_CREAT +Create the file if it does not exist. + +@item O_NONBLOCK +Non-blocking mode. + +@item O_SYNC +Wait for writes to complete. + +@item O_ASYNC +Asynchronous I/O. +@end vtable + +@item F_SETFL +Set the file status flags for @var{fid} to the value specified by @var{arg}. + The only flags that can be changed are @w{@code{O_APPEND}} and +@w{@code{O_NONBLOCK}}. +@end vtable + +If successful, @var{err} is 0 and @var{msg} is an empty string. Otherwise, +@var{err} is nonzero and @var{msg} contains a system-dependent error +message. +@seealso{fopen, dup2} +@end deftypefn */) { if (args.length () != 3) print_usage (); @@ -451,27 +451,27 @@ } DEFUNX ("fork", Ffork, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{pid}, @var{msg}] =} fork ()\n\ -Create a copy of the current process.\n\ -\n\ -Fork can return one of the following values:\n\ -\n\ -@table @asis\n\ -@item > 0\n\ -You are in the parent process. The value returned from @code{fork} is the\n\ -process id of the child process. You should probably arrange to wait for\n\ -any child processes to exit.\n\ -\n\ -@item 0\n\ -You are in the child process. You can call @code{exec} to start another\n\ -process. If that fails, you should probably call @code{exit}.\n\ -\n\ -@item < 0\n\ -The call to @code{fork} failed for some reason. You must take evasive\n\ -action. A system dependent error message will be waiting in @var{msg}.\n\ -@end table\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{pid}, @var{msg}] =} fork () +Create a copy of the current process. + +Fork can return one of the following values: + +@table @asis +@item > 0 +You are in the parent process. The value returned from @code{fork} is the +process id of the child process. You should probably arrange to wait for +any child processes to exit. + +@item 0 +You are in the child process. You can call @code{exec} to start another +process. If that fails, you should probably call @code{exit}. + +@item < 0 +The call to @code{fork} failed for some reason. You must take evasive +action. A system dependent error message will be waiting in @var{msg}. +@end table +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -487,10 +487,10 @@ } DEFUNX ("getpgrp", Fgetpgrp, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {pgid =} getpgrp ()\n\ -Return the process group id of the current process.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {pgid =} getpgrp () +Return the process group id of the current process. +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -503,11 +503,11 @@ } DEFUNX ("getpid", Fgetpid, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {pid =} getpid ()\n\ -Return the process id of the current process.\n\ -@seealso{getppid}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {pid =} getpid () +Return the process id of the current process. +@seealso{getppid} +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -516,11 +516,11 @@ } DEFUNX ("getppid", Fgetppid, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {pid =} getppid ()\n\ -Return the process id of the parent process.\n\ -@seealso{getpid}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {pid =} getppid () +Return the process id of the parent process. +@seealso{getpid} +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -529,11 +529,11 @@ } DEFUNX ("getegid", Fgetegid, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {egid =} getegid ()\n\ -Return the effective group id of the current process.\n\ -@seealso{getgid}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {egid =} getegid () +Return the effective group id of the current process. +@seealso{getgid} +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -542,11 +542,11 @@ } DEFUNX ("getgid", Fgetgid, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {gid =} getgid ()\n\ -Return the real group id of the current process.\n\ -@seealso{getegid}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {gid =} getgid () +Return the real group id of the current process. +@seealso{getegid} +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -555,11 +555,11 @@ } DEFUNX ("geteuid", Fgeteuid, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {euid =} geteuid ()\n\ -Return the effective user id of the current process.\n\ -@seealso{getuid}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {euid =} geteuid () +Return the effective user id of the current process. +@seealso{getuid} +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -568,11 +568,11 @@ } DEFUNX ("getuid", Fgetuid, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {uid =} getuid ()\n\ -Return the real user id of the current process.\n\ -@seealso{geteuid}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {uid =} getuid () +Return the real user id of the current process. +@seealso{geteuid} +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -581,26 +581,26 @@ } DEFUNX ("kill", Fkill, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{err}, @var{msg}] =} kill (@var{pid}, @var{sig})\n\ -Send signal @var{sig} to process @var{pid}.\n\ -\n\ -If @var{pid} is positive, then signal @var{sig} is sent to @var{pid}.\n\ -\n\ -If @var{pid} is 0, then signal @var{sig} is sent to every process\n\ -in the process group of the current process.\n\ -\n\ -If @var{pid} is -1, then signal @var{sig} is sent to every process\n\ -except process 1.\n\ -\n\ -If @var{pid} is less than -1, then signal @var{sig} is sent to every\n\ -process in the process group @var{-pid}.\n\ -\n\ -If @var{sig} is 0, then no signal is sent, but error checking is still\n\ -performed.\n\ -\n\ -Return 0 if successful, otherwise return -1.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{err}, @var{msg}] =} kill (@var{pid}, @var{sig}) +Send signal @var{sig} to process @var{pid}. + +If @var{pid} is positive, then signal @var{sig} is sent to @var{pid}. + +If @var{pid} is 0, then signal @var{sig} is sent to every process +in the process group of the current process. + +If @var{pid} is -1, then signal @var{sig} is sent to every process +except process 1. + +If @var{pid} is less than -1, then signal @var{sig} is sent to every +process in the process group @var{-pid}. + +If @var{sig} is 0, then no signal is sent, but error checking is still +performed. + +Return 0 if successful, otherwise return -1. +@end deftypefn */) { if (args.length () != 2) print_usage (); @@ -617,15 +617,15 @@ } DEFUNX ("lstat", Flstat, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{info} =} lstat (@var{symlink})\n\ -@deftypefnx {} {[@var{info}, @var{err}, @var{msg}] =} lstat (@var{symlink})\n\ -Return a structure @var{info} containing information about the symbolic link\n\ -@var{symlink}.\n\ -\n\ -The function outputs are described in the documentation for @code{stat}.\n\ -@seealso{stat, symlink}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{info} =} lstat (@var{symlink}) +@deftypefnx {} {[@var{info}, @var{err}, @var{msg}] =} lstat (@var{symlink}) +Return a structure @var{info} containing information about the symbolic link +@var{symlink}. + +The function outputs are described in the documentation for @code{stat}. +@seealso{stat, symlink} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -666,19 +666,19 @@ } DEFUNX ("mkfifo", Fmkfifo, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{err} =} mkfifo (@var{name}, @var{mode})\n\ -@deftypefnx {} {[@var{err}, @var{msg}] =} mkfifo (@var{name}, @var{mode})\n\ -Create a FIFO special file named @var{name} with file mode @var{mode}.\n\ -\n\ -@var{mode} is interpreted as an octal number and is subject to umask\n\ -processing. The final calculated mode is @code{@var{mode} - @var{umask}}.\n\ -\n\ -If successful, @var{err} is 0 and @var{msg} is an empty string.\n\ -Otherwise, @var{err} is nonzero and @var{msg} contains a system-dependent\n\ -error message.\n\ -@seealso{pipe, umask}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{err} =} mkfifo (@var{name}, @var{mode}) +@deftypefnx {} {[@var{err}, @var{msg}] =} mkfifo (@var{name}, @var{mode}) +Create a FIFO special file named @var{name} with file mode @var{mode}. + +@var{mode} is interpreted as an octal number and is subject to umask +processing. The final calculated mode is @code{@var{mode} - @var{umask}}. + +If successful, @var{err} is 0 and @var{msg} is an empty string. +Otherwise, @var{err} is nonzero and @var{msg} contains a system-dependent +error message. +@seealso{pipe, umask} +@end deftypefn */) { if (args.length () != 2) print_usage (); @@ -713,16 +713,16 @@ */ DEFUNX ("pipe", Fpipe, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{read_fd}, @var{write_fd}, @var{err}, @var{msg}] =} pipe ()\n\ -Create a pipe and return the reading and writing ends of the pipe into\n\ -@var{read_fd} and @var{write_fd} respectively.\n\ -\n\ -If successful, @var{err} is 0 and @var{msg} is an empty string.\n\ -Otherwise, @var{err} is nonzero and @var{msg} contains a system-dependent\n\ -error message.\n\ -@seealso{mkfifo}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{read_fd}, @var{write_fd}, @var{err}, @var{msg}] =} pipe () +Create a pipe and return the reading and writing ends of the pipe into +@var{read_fd} and @var{write_fd} respectively. + +If successful, @var{err} is 0 and @var{msg} is an empty string. +Otherwise, @var{err} is nonzero and @var{msg} contains a system-dependent +error message. +@seealso{mkfifo} +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -753,100 +753,100 @@ } DEFUNX ("stat", Fstat, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{info}, @var{err}, @var{msg}] =} stat (@var{file})\n\ -@deftypefnx {} {[@var{info}, @var{err}, @var{msg}] =} stat (@var{fid})\n\ -@deftypefnx {} {[@var{info}, @var{err}, @var{msg}] =} lstat (@var{file})\n\ -@deftypefnx {} {[@var{info}, @var{err}, @var{msg}] =} lstat (@var{fid})\n\ -Return a structure @var{info} containing the following information about\n\ -@var{file} or file identifier @var{fid}.\n\ -\n\ -@table @code\n\ -@item dev\n\ -ID of device containing a directory entry for this file.\n\ -\n\ -@item ino\n\ -File number of the file.\n\ -\n\ -@item mode\n\ -File mode, as an integer. Use the functions @w{@code{S_ISREG}},\n\ -@w{@code{S_ISDIR}}, @w{@code{S_ISCHR}}, @w{@code{S_ISBLK}},\n\ -@w{@code{S_ISFIFO}}, @w{@code{S_ISLNK}}, or @w{@code{S_ISSOCK}} to extract\n\ -information from this value.\n\ -\n\ -@item modestr\n\ -File mode, as a string of ten letters or dashes as would be returned by\n\ -@kbd{ls -l}.\n\ -\n\ -@item nlink\n\ -Number of links.\n\ -\n\ -@item uid\n\ -User ID of file's owner.\n\ -\n\ -@item gid\n\ -Group ID of file's group.\n\ -\n\ -@item rdev\n\ -ID of device for block or character special files.\n\ -\n\ -@item size\n\ -Size in bytes.\n\ -\n\ -@item atime\n\ -Time of last access in the same form as time values returned from\n\ -@code{time}. @xref{Timing Utilities}.\n\ -\n\ -@item mtime\n\ -Time of last modification in the same form as time values returned from\n\ -@code{time}. @xref{Timing Utilities}.\n\ -\n\ -@item ctime\n\ -Time of last file status change in the same form as time values\n\ -returned from @code{time}. @xref{Timing Utilities}.\n\ -\n\ -@item blksize\n\ -Size of blocks in the file.\n\ -\n\ -@item blocks\n\ -Number of blocks allocated for file.\n\ -@end table\n\ -\n\ -If the call is successful @var{err} is 0 and @var{msg} is an empty string.\n\ -If the file does not exist, or some other error occurs, @var{info} is an\n\ -empty matrix, @var{err} is @minus{}1, and @var{msg} contains the\n\ -corresponding system error message.\n\ -\n\ -If @var{file} is a symbolic link, @code{stat} will return information about\n\ -the actual file that is referenced by the link. Use @code{lstat} if you\n\ -want information about the symbolic link itself.\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -[info, err, msg] = stat (\"/vmlinuz\")\n\ - @result{} info =\n\ - @{\n\ - atime = 855399756\n\ - rdev = 0\n\ - ctime = 847219094\n\ - uid = 0\n\ - size = 389218\n\ - blksize = 4096\n\ - mtime = 847219094\n\ - gid = 6\n\ - nlink = 1\n\ - blocks = 768\n\ - mode = -rw-r--r--\n\ - modestr = -rw-r--r--\n\ - ino = 9316\n\ - dev = 2049\n\ - @}\n\ - @result{} err = 0\n\ - @result{} msg =\n\ -@end example\n\ -@seealso{lstat, ls, dir}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{info}, @var{err}, @var{msg}] =} stat (@var{file}) +@deftypefnx {} {[@var{info}, @var{err}, @var{msg}] =} stat (@var{fid}) +@deftypefnx {} {[@var{info}, @var{err}, @var{msg}] =} lstat (@var{file}) +@deftypefnx {} {[@var{info}, @var{err}, @var{msg}] =} lstat (@var{fid}) +Return a structure @var{info} containing the following information about +@var{file} or file identifier @var{fid}. + +@table @code +@item dev +ID of device containing a directory entry for this file. + +@item ino +File number of the file. + +@item mode +File mode, as an integer. Use the functions @w{@code{S_ISREG}}, +@w{@code{S_ISDIR}}, @w{@code{S_ISCHR}}, @w{@code{S_ISBLK}}, +@w{@code{S_ISFIFO}}, @w{@code{S_ISLNK}}, or @w{@code{S_ISSOCK}} to extract +information from this value. + +@item modestr +File mode, as a string of ten letters or dashes as would be returned by +@kbd{ls -l}. + +@item nlink +Number of links. + +@item uid +User ID of file's owner. + +@item gid +Group ID of file's group. + +@item rdev +ID of device for block or character special files. + +@item size +Size in bytes. + +@item atime +Time of last access in the same form as time values returned from +@code{time}. @xref{Timing Utilities}. + +@item mtime +Time of last modification in the same form as time values returned from +@code{time}. @xref{Timing Utilities}. + +@item ctime +Time of last file status change in the same form as time values +returned from @code{time}. @xref{Timing Utilities}. + +@item blksize +Size of blocks in the file. + +@item blocks +Number of blocks allocated for file. +@end table + +If the call is successful @var{err} is 0 and @var{msg} is an empty string. +If the file does not exist, or some other error occurs, @var{info} is an +empty matrix, @var{err} is @minus{}1, and @var{msg} contains the +corresponding system error message. + +If @var{file} is a symbolic link, @code{stat} will return information about +the actual file that is referenced by the link. Use @code{lstat} if you +want information about the symbolic link itself. + +For example: + +@example +[info, err, msg] = stat ("/vmlinuz") + @result{} info = + @{ + atime = 855399756 + rdev = 0 + ctime = 847219094 + uid = 0 + size = 389218 + blksize = 4096 + mtime = 847219094 + gid = 6 + nlink = 1 + blocks = 768 + mode = -rw-r--r-- + modestr = -rw-r--r-- + ino = 9316 + dev = 2049 + @} + @result{} err = 0 + @result{} msg = +@end example +@seealso{lstat, ls, dir} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -874,14 +874,14 @@ } DEFUNX ("S_ISREG", FS_ISREG, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} S_ISREG (@var{mode})\n\ -Return true if @var{mode} corresponds to a regular file.\n\ -\n\ -The value of @var{mode} is assumed to be returned from a call to\n\ -@code{stat}.\n\ -@seealso{stat, lstat}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} S_ISREG (@var{mode}) +Return true if @var{mode} corresponds to a regular file. + +The value of @var{mode} is assumed to be returned from a call to +@code{stat}. +@seealso{stat, lstat} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -892,14 +892,14 @@ } DEFUNX ("S_ISDIR", FS_ISDIR, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} S_ISDIR (@var{mode})\n\ -Return true if @var{mode} corresponds to a directory.\n\ -\n\ -The value of @var{mode} is assumed to be returned from a call to\n\ -@code{stat}.\n\ -@seealso{stat, lstat}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} S_ISDIR (@var{mode}) +Return true if @var{mode} corresponds to a directory. + +The value of @var{mode} is assumed to be returned from a call to +@code{stat}. +@seealso{stat, lstat} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -910,14 +910,14 @@ } DEFUNX ("S_ISCHR", FS_ISCHR, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} S_ISCHR (@var{mode})\n\ -Return true if @var{mode} corresponds to a character device.\n\ -\n\ -The value of @var{mode} is assumed to be returned from a call to\n\ -@code{stat}.\n\ -@seealso{stat, lstat}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} S_ISCHR (@var{mode}) +Return true if @var{mode} corresponds to a character device. + +The value of @var{mode} is assumed to be returned from a call to +@code{stat}. +@seealso{stat, lstat} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -928,14 +928,14 @@ } DEFUNX ("S_ISBLK", FS_ISBLK, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} S_ISBLK (@var{mode})\n\ -Return true if @var{mode} corresponds to a block device.\n\ -\n\ -The value of @var{mode} is assumed to be returned from a call to\n\ -@code{stat}.\n\ -@seealso{stat, lstat}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} S_ISBLK (@var{mode}) +Return true if @var{mode} corresponds to a block device. + +The value of @var{mode} is assumed to be returned from a call to +@code{stat}. +@seealso{stat, lstat} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -946,14 +946,14 @@ } DEFUNX ("S_ISFIFO", FS_ISFIFO, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} S_ISFIFO (@var{mode})\n\ -Return true if @var{mode} corresponds to a fifo.\n\ -\n\ -The value of @var{mode} is assumed to be returned from a call to\n\ -@code{stat}.\n\ -@seealso{stat, lstat}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} S_ISFIFO (@var{mode}) +Return true if @var{mode} corresponds to a fifo. + +The value of @var{mode} is assumed to be returned from a call to +@code{stat}. +@seealso{stat, lstat} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -964,14 +964,14 @@ } DEFUNX ("S_ISLNK", FS_ISLNK, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} S_ISLNK (@var{mode})\n\ -Return true if @var{mode} corresponds to a symbolic link.\n\ -\n\ -The value of @var{mode} is assumed to be returned from a call to\n\ -@code{stat}.\n\ -@seealso{stat, lstat}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} S_ISLNK (@var{mode}) +Return true if @var{mode} corresponds to a symbolic link. + +The value of @var{mode} is assumed to be returned from a call to +@code{stat}. +@seealso{stat, lstat} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -982,14 +982,14 @@ } DEFUNX ("S_ISSOCK", FS_ISSOCK, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} S_ISSOCK (@var{mode})\n\ -Return true if @var{mode} corresponds to a socket.\n\ -\n\ -The value of @var{mode} is assumed to be returned from a call to\n\ -@code{stat}.\n\ -@seealso{stat, lstat}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} S_ISSOCK (@var{mode}) +Return true if @var{mode} corresponds to a socket. + +The value of @var{mode} is assumed to be returned from a call to +@code{stat}. +@seealso{stat, lstat} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1000,10 +1000,10 @@ } DEFUN (gethostname, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} gethostname ()\n\ -Return the hostname of the system where Octave is running.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} gethostname () +Return the hostname of the system where Octave is running. +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -1012,29 +1012,29 @@ } DEFUN (uname, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{uts}, @var{err}, @var{msg}] =} uname ()\n\ -Return system information in the structure.\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -uname ()\n\ - @result{} @{\n\ - sysname = x86_64\n\ - nodename = segfault\n\ - release = 2.6.15-1-amd64-k8-smp\n\ - version = Linux\n\ - machine = #2 SMP Thu Feb 23 04:57:49 UTC 2006\n\ - @}\n\ -@end group\n\ -@end example\n\ -\n\ -If successful, @var{err} is 0 and @var{msg} is an empty string.\n\ -Otherwise, @var{err} is nonzero and @var{msg} contains a\n\ -system-dependent error message.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{uts}, @var{err}, @var{msg}] =} uname () +Return system information in the structure. + +For example: + +@example +@group +uname () + @result{} @{ + sysname = x86_64 + nodename = segfault + release = 2.6.15-1-amd64-k8-smp + version = Linux + machine = #2 SMP Thu Feb 23 04:57:49 UTC 2006 + @} +@end group +@end example + +If successful, @var{err} is 0 and @var{msg} is an empty string. +Otherwise, @var{err} is nonzero and @var{msg} contains a +system-dependent error message. +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -1053,15 +1053,15 @@ } DEFUNX ("unlink", Funlink, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{err}, @var{msg}] =} unlink (@var{file})\n\ -Delete the file named @var{file}.\n\ -\n\ -If successful, @var{err} is 0 and @var{msg} is an empty string.\n\ -Otherwise, @var{err} is nonzero and @var{msg} contains a system-dependent\n\ -error message.\n\ -@seealso{delete, rmdir}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{err}, @var{msg}] =} unlink (@var{file}) +Delete the file named @var{file}. + +If successful, @var{err} is 0 and @var{msg} is an empty string. +Otherwise, @var{err} is nonzero and @var{msg} contains a system-dependent +error message. +@seealso{delete, rmdir} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1076,51 +1076,51 @@ } DEFUNX ("waitpid", Fwaitpid, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{pid}, @var{status}, @var{msg}] =} waitpid (@var{pid}, @var{options})\n\ -Wait for process @var{pid} to terminate.\n\ -\n\ -The @var{pid} argument can be:\n\ -\n\ -@table @asis\n\ -@item @minus{}1\n\ -Wait for any child process.\n\ -\n\ -@item 0\n\ -Wait for any child process whose process group ID is equal to that of the\n\ -Octave interpreter process.\n\ -\n\ -@item > 0\n\ -Wait for termination of the child process with ID @var{pid}.\n\ -@end table\n\ -\n\ -The @var{options} argument can be a bitwise OR of zero or more of the\n\ -following constants:\n\ -\n\ -@table @code\n\ -@item 0\n\ -Wait until signal is received or a child process exits (this is the default\n\ -if the @var{options} argument is missing).\n\ -\n\ -@item WNOHANG\n\ -Do not hang if status is not immediately available.\n\ -\n\ -@item WUNTRACED\n\ -Report the status of any child processes that are stopped, and whose status\n\ -has not yet been reported since they stopped.\n\ -\n\ -@item WCONTINUE\n\ -Return if a stopped child has been resumed by delivery of @code{SIGCONT}.\n\ -This value may not be meaningful on all systems.\n\ -@end table\n\ -\n\ -If the returned value of @var{pid} is greater than 0, it is the process ID\n\ -of the child process that exited. If an error occurs, @var{pid} will be\n\ -less than zero and @var{msg} will contain a system-dependent error message.\n\ -The value of @var{status} contains additional system-dependent information\n\ -about the subprocess that exited.\n\ -@seealso{WCONTINUE, WCOREDUMP, WEXITSTATUS, WIFCONTINUED, WIFSIGNALED, WIFSTOPPED, WNOHANG, WSTOPSIG, WTERMSIG, WUNTRACED}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{pid}, @var{status}, @var{msg}] =} waitpid (@var{pid}, @var{options}) +Wait for process @var{pid} to terminate. + +The @var{pid} argument can be: + +@table @asis +@item @minus{}1 +Wait for any child process. + +@item 0 +Wait for any child process whose process group ID is equal to that of the +Octave interpreter process. + +@item > 0 +Wait for termination of the child process with ID @var{pid}. +@end table + +The @var{options} argument can be a bitwise OR of zero or more of the +following constants: + +@table @code +@item 0 +Wait until signal is received or a child process exits (this is the default +if the @var{options} argument is missing). + +@item WNOHANG +Do not hang if status is not immediately available. + +@item WUNTRACED +Report the status of any child processes that are stopped, and whose status +has not yet been reported since they stopped. + +@item WCONTINUE +Return if a stopped child has been resumed by delivery of @code{SIGCONT}. +This value may not be meaningful on all systems. +@end table + +If the returned value of @var{pid} is greater than 0, it is the process ID +of the child process that exited. If an error occurs, @var{pid} will be +less than zero and @var{msg} will contain a system-dependent error message. +The value of @var{status} contains additional system-dependent information +about the subprocess that exited. +@seealso{WCONTINUE, WCOREDUMP, WEXITSTATUS, WIFCONTINUED, WIFSIGNALED, WIFSTOPPED, WNOHANG, WSTOPSIG, WTERMSIG, WUNTRACED} +@end deftypefn */) { int nargin = args.length (); @@ -1143,12 +1143,12 @@ } DEFUNX ("WIFEXITED", FWIFEXITED, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} WIFEXITED (@var{status})\n\ -Given @var{status} from a call to @code{waitpid}, return\n\ -true if the child terminated normally.\n\ -@seealso{waitpid, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WCOREDUMP, WIFSTOPPED, WSTOPSIG, WIFCONTINUED}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} WIFEXITED (@var{status}) +Given @var{status} from a call to @code{waitpid}, return +true if the child terminated normally. +@seealso{waitpid, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WCOREDUMP, WIFSTOPPED, WSTOPSIG, WIFCONTINUED} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1159,14 +1159,14 @@ } DEFUNX ("WEXITSTATUS", FWEXITSTATUS, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} WEXITSTATUS (@var{status})\n\ -Given @var{status} from a call to @code{waitpid}, return\n\ -the exit status of the child.\n\ -\n\ -This function should only be employed if @code{WIFEXITED} returned true.\n\ -@seealso{waitpid, WIFEXITED, WIFSIGNALED, WTERMSIG, WCOREDUMP, WIFSTOPPED, WSTOPSIG, WIFCONTINUED}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} WEXITSTATUS (@var{status}) +Given @var{status} from a call to @code{waitpid}, return +the exit status of the child. + +This function should only be employed if @code{WIFEXITED} returned true. +@seealso{waitpid, WIFEXITED, WIFSIGNALED, WTERMSIG, WCOREDUMP, WIFSTOPPED, WSTOPSIG, WIFCONTINUED} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1177,12 +1177,12 @@ } DEFUNX ("WIFSIGNALED", FWIFSIGNALED, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} WIFSIGNALED (@var{status})\n\ -Given @var{status} from a call to @code{waitpid}, return\n\ -true if the child process was terminated by a signal.\n\ -@seealso{waitpid, WIFEXITED, WEXITSTATUS, WTERMSIG, WCOREDUMP, WIFSTOPPED, WSTOPSIG, WIFCONTINUED}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} WIFSIGNALED (@var{status}) +Given @var{status} from a call to @code{waitpid}, return +true if the child process was terminated by a signal. +@seealso{waitpid, WIFEXITED, WEXITSTATUS, WTERMSIG, WCOREDUMP, WIFSTOPPED, WSTOPSIG, WIFCONTINUED} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1193,14 +1193,14 @@ } DEFUNX ("WTERMSIG", FWTERMSIG, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} WTERMSIG (@var{status})\n\ -Given @var{status} from a call to @code{waitpid}, return\n\ -the number of the signal that caused the child process to terminate.\n\ -\n\ -This function should only be employed if @code{WIFSIGNALED} returned true.\n\ -@seealso{waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WCOREDUMP, WIFSTOPPED, WSTOPSIG, WIFCONTINUED}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} WTERMSIG (@var{status}) +Given @var{status} from a call to @code{waitpid}, return +the number of the signal that caused the child process to terminate. + +This function should only be employed if @code{WIFSIGNALED} returned true. +@seealso{waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WCOREDUMP, WIFSTOPPED, WSTOPSIG, WIFCONTINUED} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1211,16 +1211,16 @@ } DEFUNX ("WCOREDUMP", FWCOREDUMP, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} WCOREDUMP (@var{status})\n\ -Given @var{status} from a call to @code{waitpid}, return\n\ -true if the child produced a core dump.\n\ -\n\ -This function should only be employed if @code{WIFSIGNALED} returned true.\n\ -The macro used to implement this function is not specified in POSIX.1-2001\n\ -and is not available on some Unix implementations (e.g., AIX, SunOS).\n\ -@seealso{waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED, WSTOPSIG, WIFCONTINUED}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} WCOREDUMP (@var{status}) +Given @var{status} from a call to @code{waitpid}, return +true if the child produced a core dump. + +This function should only be employed if @code{WIFSIGNALED} returned true. +The macro used to implement this function is not specified in POSIX.1-2001 +and is not available on some Unix implementations (e.g., AIX, SunOS). +@seealso{waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED, WSTOPSIG, WIFCONTINUED} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1231,15 +1231,15 @@ } DEFUNX ("WIFSTOPPED", FWIFSTOPPED, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} WIFSTOPPED (@var{status})\n\ -Given @var{status} from a call to @code{waitpid}, return\n\ -true if the child process was stopped by delivery of a signal.\n\ -\n\ -This is only possible if the call was done using @code{WUNTRACED} or when\n\ -the child is being traced (see ptrace(2)).\n\ -@seealso{waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WCOREDUMP, WSTOPSIG, WIFCONTINUED}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} WIFSTOPPED (@var{status}) +Given @var{status} from a call to @code{waitpid}, return +true if the child process was stopped by delivery of a signal. + +This is only possible if the call was done using @code{WUNTRACED} or when +the child is being traced (see ptrace(2)). +@seealso{waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WCOREDUMP, WSTOPSIG, WIFCONTINUED} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1250,14 +1250,14 @@ } DEFUNX ("WSTOPSIG", FWSTOPSIG, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} WSTOPSIG (@var{status})\n\ -Given @var{status} from a call to @code{waitpid}, return\n\ -the number of the signal which caused the child to stop.\n\ -\n\ -This function should only be employed if @code{WIFSTOPPED} returned true.\n\ -@seealso{waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WCOREDUMP, WIFSTOPPED, WIFCONTINUED}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} WSTOPSIG (@var{status}) +Given @var{status} from a call to @code{waitpid}, return +the number of the signal which caused the child to stop. + +This function should only be employed if @code{WIFSTOPPED} returned true. +@seealso{waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WCOREDUMP, WIFSTOPPED, WIFCONTINUED} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1268,12 +1268,12 @@ } DEFUNX ("WIFCONTINUED", FWIFCONTINUED, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} WIFCONTINUED (@var{status})\n\ -Given @var{status} from a call to @code{waitpid}, return\n\ -true if the child process was resumed by delivery of @code{SIGCONT}.\n\ -@seealso{waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WCOREDUMP, WIFSTOPPED, WSTOPSIG}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} WIFCONTINUED (@var{status}) +Given @var{status} from a call to @code{waitpid}, return +true if the child process was resumed by delivery of @code{SIGCONT}. +@seealso{waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WCOREDUMP, WIFSTOPPED, WSTOPSIG} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1284,13 +1284,13 @@ } DEFUNX ("canonicalize_file_name", Fcanonicalize_file_name, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{cname}, @var{status}, @var{msg}] =} canonicalize_file_name (@var{fname})\n\ -Return the canonical name of file @var{fname}.\n\ -\n\ -If the file does not exist the empty string (\"\") is returned.\n\ -@seealso{make_absolute_filename, is_absolute_filename, is_rooted_relative_filename}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{cname}, @var{status}, @var{msg}] =} canonicalize_file_name (@var{fname}) +Return the canonical name of file @var{fname}. + +If the file does not exist the empty string ("") is returned. +@seealso{make_absolute_filename, is_absolute_filename, is_rooted_relative_filename} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1314,12 +1314,12 @@ } DEFUNX ("F_DUPFD", FF_DUPFD, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} F_DUPFD ()\n\ -Return the numerical value to pass to @code{fcntl} to return\n\ -a duplicate file descriptor.\n\ -@seealso{fcntl, F_GETFD, F_GETFL, F_SETFD, F_SETFL}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} F_DUPFD () +Return the numerical value to pass to @code{fcntl} to return +a duplicate file descriptor. +@seealso{fcntl, F_GETFD, F_GETFL, F_SETFD, F_SETFL} +@end deftypefn */) { static int val = octave_f_dupfd_wrapper (); @@ -1330,12 +1330,12 @@ } DEFUNX ("F_GETFD", FF_GETFD, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} F_GETFD ()\n\ -Return the numerical value to pass to @code{fcntl} to return\n\ -the file descriptor flags.\n\ -@seealso{fcntl, F_DUPFD, F_GETFL, F_SETFD, F_SETFL}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} F_GETFD () +Return the numerical value to pass to @code{fcntl} to return +the file descriptor flags. +@seealso{fcntl, F_DUPFD, F_GETFL, F_SETFD, F_SETFL} +@end deftypefn */) { static int val = octave_f_getfd_wrapper (); @@ -1346,12 +1346,12 @@ } DEFUNX ("F_GETFL", FF_GETFL, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} F_GETFL ()\n\ -Return the numerical value to pass to @code{fcntl} to return\n\ -the file status flags.\n\ -@seealso{fcntl, F_DUPFD, F_GETFD, F_SETFD, F_SETFL}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} F_GETFL () +Return the numerical value to pass to @code{fcntl} to return +the file status flags. +@seealso{fcntl, F_DUPFD, F_GETFD, F_SETFD, F_SETFL} +@end deftypefn */) { static int val = octave_f_getfl_wrapper (); @@ -1362,12 +1362,12 @@ } DEFUNX ("F_SETFD", FF_SETFD, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} F_SETFD ()\n\ -Return the numerical value to pass to @code{fcntl} to set the file\n\ -descriptor flags.\n\ -@seealso{fcntl, F_DUPFD, F_GETFD, F_GETFL, F_SETFL}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} F_SETFD () +Return the numerical value to pass to @code{fcntl} to set the file +descriptor flags. +@seealso{fcntl, F_DUPFD, F_GETFD, F_GETFL, F_SETFL} +@end deftypefn */) { static int val = octave_f_setfd_wrapper (); @@ -1378,12 +1378,12 @@ } DEFUNX ("F_SETFL", FF_SETFL, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} F_SETFL ()\n\ -Return the numerical value to pass to @code{fcntl} to set the file\n\ -status flags.\n\ -@seealso{fcntl, F_DUPFD, F_GETFD, F_GETFL, F_SETFD}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} F_SETFL () +Return the numerical value to pass to @code{fcntl} to set the file +status flags. +@seealso{fcntl, F_DUPFD, F_GETFD, F_GETFL, F_SETFD} +@end deftypefn */) { static int val = octave_f_setfl_wrapper (); @@ -1394,13 +1394,13 @@ } DEFUNX ("O_APPEND", FO_APPEND, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} O_APPEND ()\n\ -Return the numerical value of the file status flag that may be\n\ -returned by @code{fcntl} to indicate each write operation appends,\n\ -or that may be passed to @code{fcntl} to set the write mode to append.\n\ -@seealso{fcntl, O_ASYNC, O_CREAT, O_EXCL, O_NONBLOCK, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} O_APPEND () +Return the numerical value of the file status flag that may be +returned by @code{fcntl} to indicate each write operation appends, +or that may be passed to @code{fcntl} to set the write mode to append. +@seealso{fcntl, O_ASYNC, O_CREAT, O_EXCL, O_NONBLOCK, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY} +@end deftypefn */) { static int val = octave_o_append_wrapper (); @@ -1411,12 +1411,12 @@ } DEFUNX ("O_ASYNC", FO_ASYNC, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} O_ASYNC ()\n\ -Return the numerical value of the file status flag that may be\n\ -returned by @code{fcntl} to indicate asynchronous I/O.\n\ -@seealso{fcntl, O_APPEND, O_CREAT, O_EXCL, O_NONBLOCK, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} O_ASYNC () +Return the numerical value of the file status flag that may be +returned by @code{fcntl} to indicate asynchronous I/O. +@seealso{fcntl, O_APPEND, O_CREAT, O_EXCL, O_NONBLOCK, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY} +@end deftypefn */) { static int val = octave_o_async_wrapper (); @@ -1427,13 +1427,13 @@ } DEFUNX ("O_CREAT", FO_CREAT, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} O_CREAT ()\n\ -Return the numerical value of the file status flag that may be\n\ -returned by @code{fcntl} to indicate that a file should be created if it\n\ -does not exist.\n\ -@seealso{fcntl, O_APPEND, O_ASYNC, O_EXCL, O_NONBLOCK, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} O_CREAT () +Return the numerical value of the file status flag that may be +returned by @code{fcntl} to indicate that a file should be created if it +does not exist. +@seealso{fcntl, O_APPEND, O_ASYNC, O_EXCL, O_NONBLOCK, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY} +@end deftypefn */) { static int val = octave_o_creat_wrapper (); @@ -1444,12 +1444,12 @@ } DEFUNX ("O_EXCL", FO_EXCL, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} O_EXCL ()\n\ -Return the numerical value of the file status flag that may be\n\ -returned by @code{fcntl} to indicate that file locking is used.\n\ -@seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_NONBLOCK, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} O_EXCL () +Return the numerical value of the file status flag that may be +returned by @code{fcntl} to indicate that file locking is used. +@seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_NONBLOCK, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY} +@end deftypefn */) { static int val = octave_o_excl_wrapper (); @@ -1460,13 +1460,13 @@ } DEFUNX ("O_NONBLOCK", FO_NONBLOCK, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} O_NONBLOCK ()\n\ -Return the numerical value of the file status flag that may be\n\ -returned by @code{fcntl} to indicate that non-blocking I/O is in use,\n\ -or that may be passsed to @code{fcntl} to set non-blocking I/O.\n\ -@seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_EXCL, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} O_NONBLOCK () +Return the numerical value of the file status flag that may be +returned by @code{fcntl} to indicate that non-blocking I/O is in use, +or that may be passsed to @code{fcntl} to set non-blocking I/O. +@seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_EXCL, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY} +@end deftypefn */) { static int val = octave_o_nonblock_wrapper (); @@ -1477,12 +1477,12 @@ } DEFUNX ("O_RDONLY", FO_RDONLY, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} O_RDONLY ()\n\ -Return the numerical value of the file status flag that may be\n\ -returned by @code{fcntl} to indicate that a file is open for reading only.\n\ -@seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_EXCL, O_NONBLOCK, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} O_RDONLY () +Return the numerical value of the file status flag that may be +returned by @code{fcntl} to indicate that a file is open for reading only. +@seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_EXCL, O_NONBLOCK, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY} +@end deftypefn */) { static int val = octave_o_rdonly_wrapper (); @@ -1493,13 +1493,13 @@ } DEFUNX ("O_RDWR", FO_RDWR, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} O_RDWR ()\n\ -Return the numerical value of the file status flag that may be\n\ -returned by @code{fcntl} to indicate that a file is open for both reading\n\ -and writing.\n\ -@seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_EXCL, O_NONBLOCK, O_RDONLY, O_SYNC, O_TRUNC, O_WRONLY}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} O_RDWR () +Return the numerical value of the file status flag that may be +returned by @code{fcntl} to indicate that a file is open for both reading +and writing. +@seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_EXCL, O_NONBLOCK, O_RDONLY, O_SYNC, O_TRUNC, O_WRONLY} +@end deftypefn */) { static int val = octave_o_rdwr_wrapper (); @@ -1510,13 +1510,13 @@ } DEFUNX ("O_SYNC", FO_SYNC, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} O_SYNC ()\n\ -Return the numerical value of the file status flag that may be\n\ -returned by @code{fcntl} to indicate that a file is open for synchronous\n\ -I/O.\n\ -@seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_EXCL, O_NONBLOCK, O_RDONLY, O_RDWR, O_TRUNC, O_WRONLY}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} O_SYNC () +Return the numerical value of the file status flag that may be +returned by @code{fcntl} to indicate that a file is open for synchronous +I/O. +@seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_EXCL, O_NONBLOCK, O_RDONLY, O_RDWR, O_TRUNC, O_WRONLY} +@end deftypefn */) { static int val = octave_o_sync_wrapper (); @@ -1527,13 +1527,13 @@ } DEFUNX ("O_TRUNC", FO_TRUNC, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} O_TRUNC ()\n\ -Return the numerical value of the file status flag that may be\n\ -returned by @code{fcntl} to indicate that if file exists, it should be\n\ -truncated when writing.\n\ -@seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_EXCL, O_NONBLOCK, O_RDONLY, O_RDWR, O_SYNC, O_WRONLY}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} O_TRUNC () +Return the numerical value of the file status flag that may be +returned by @code{fcntl} to indicate that if file exists, it should be +truncated when writing. +@seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_EXCL, O_NONBLOCK, O_RDONLY, O_RDWR, O_SYNC, O_WRONLY} +@end deftypefn */) { static int val = octave_o_trunc_wrapper (); @@ -1544,12 +1544,12 @@ } DEFUNX ("O_WRONLY", FO_WRONLY, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} O_WRONLY ()\n\ -Return the numerical value of the file status flag that may be\n\ -returned by @code{fcntl} to indicate that a file is open for writing only.\n\ -@seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_EXCL, O_NONBLOCK, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} O_WRONLY () +Return the numerical value of the file status flag that may be +returned by @code{fcntl} to indicate that a file is open for writing only. +@seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_EXCL, O_NONBLOCK, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC} +@end deftypefn */) { static int val = octave_o_wronly_wrapper (); @@ -1560,37 +1560,37 @@ } DEFUNX ("WNOHANG", FWNOHANG, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} WNOHANG ()\n\ -Return the numerical value of the option argument that may be\n\ -passed to @code{waitpid} to indicate that it should return its status\n\ -immediately instead of waiting for a process to exit.\n\ -@seealso{waitpid, WUNTRACED, WCONTINUE}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} WNOHANG () +Return the numerical value of the option argument that may be +passed to @code{waitpid} to indicate that it should return its status +immediately instead of waiting for a process to exit. +@seealso{waitpid, WUNTRACED, WCONTINUE} +@end deftypefn */) { return const_value (args, octave::sys::wnohang ()); } DEFUNX ("WUNTRACED", FWUNTRACED, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} WUNTRACED ()\n\ -Return the numerical value of the option argument that may be\n\ -passed to @code{waitpid} to indicate that it should also return if the child\n\ -process has stopped but is not traced via the @code{ptrace} system call\n\ -@seealso{waitpid, WNOHANG, WCONTINUE}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} WUNTRACED () +Return the numerical value of the option argument that may be +passed to @code{waitpid} to indicate that it should also return if the child +process has stopped but is not traced via the @code{ptrace} system call +@seealso{waitpid, WNOHANG, WCONTINUE} +@end deftypefn */) { return const_value (args, octave::sys::wuntraced ()); } DEFUNX ("WCONTINUE", FWCONTINUE, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} WCONTINUE ()\n\ -Return the numerical value of the option argument that may be\n\ -passed to @code{waitpid} to indicate that it should also return if a stopped\n\ -child has been resumed by delivery of a @code{SIGCONT} signal.\n\ -@seealso{waitpid, WNOHANG, WUNTRACED}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} WCONTINUE () +Return the numerical value of the option argument that may be +passed to @code{waitpid} to indicate that it should also return if a stopped +child has been resumed by delivery of a @code{SIGCONT} signal. +@seealso{waitpid, WNOHANG, WUNTRACED} +@end deftypefn */) { return const_value (args, octave::sys::wcontinue ()); }
--- a/libinterp/corefcn/sysdep.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/sysdep.cc Tue Jun 21 16:07:51 2016 -0400 @@ -191,10 +191,10 @@ #endif DEFUN (__open_with_system_app__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __open_with_system_app__ (@var{file})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __open_with_system_app__ (@var{file}) +Undocumented internal function. +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -599,11 +599,11 @@ } DEFUN (clc, , , - "-*- texinfo -*-\n\ -@deftypefn {} {} clc ()\n\ -@deftypefnx {} {} home ()\n\ -Clear the terminal screen and move the cursor to the upper left corner.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} clc () +@deftypefnx {} {} home () +Clear the terminal screen and move the cursor to the upper left corner. +@end deftypefn */) { bool skip_redisplay = true; @@ -615,20 +615,20 @@ DEFALIAS (home, clc); DEFUN (getenv, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} getenv (@var{var})\n\ -Return the value of the environment variable @var{var}.\n\ -\n\ -For example,\n\ -\n\ -@example\n\ -getenv (\"PATH\")\n\ -@end example\n\ -\n\ -@noindent\n\ -returns a string containing the value of your path.\n\ -@seealso{setenv, unsetenv}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} getenv (@var{var}) +Return the value of the environment variable @var{var}. + +For example, + +@example +getenv ("PATH") +@end example + +@noindent +returns a string containing the value of your path. +@seealso{setenv, unsetenv} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -643,16 +643,16 @@ */ DEFUN (setenv, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} setenv (@var{var}, @var{value})\n\ -@deftypefnx {} {} setenv (@var{var})\n\ -@deftypefnx {} {} putenv (@dots{})\n\ -Set the value of the environment variable @var{var} to @var{value}.\n\ -\n\ -If no @var{value} is specified then the variable will be assigned the null\n\ -string.\n\ -@seealso{unsetenv, getenv}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} setenv (@var{var}, @var{value}) +@deftypefnx {} {} setenv (@var{var}) +@deftypefnx {} {} putenv (@dots{}) +Set the value of the environment variable @var{var} to @var{value}. + +If no @var{value} is specified then the variable will be assigned the null +string. +@seealso{unsetenv, getenv} +@end deftypefn */) { int nargin = args.length (); @@ -681,14 +681,14 @@ */ DEFUN (unsetenv, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{status} =} unsetenv (@var{var})\n\ -Delete the environment variable @var{var}.\n\ -\n\ -Return 0 if the variable was deleted, or did not exist, and -1 if an error\n\ -occurred.\n\ -@seealso{setenv, getenv}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{status} =} unsetenv (@var{var}) +Delete the environment variable @var{var}. + +Return 0 if the variable was deleted, or did not exist, and -1 if an error +occurred. +@seealso{setenv, getenv} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -705,32 +705,32 @@ // FIXME: perhaps kbhit should also be able to print a prompt? DEFUN (kbhit, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} kbhit ()\n\ -@deftypefnx {} {} kbhit (1)\n\ -Read a single keystroke from the keyboard.\n\ -\n\ -If called with an argument, don't wait for a keypress.\n\ -\n\ -For example,\n\ -\n\ -@example\n\ -x = kbhit ();\n\ -@end example\n\ -\n\ -@noindent\n\ -will set @var{x} to the next character typed at the keyboard as soon as\n\ -it is typed.\n\ -\n\ -@example\n\ -x = kbhit (1);\n\ -@end example\n\ -\n\ -@noindent\n\ -is identical to the above example, but doesn't wait for a keypress,\n\ -returning the empty string if no key is available.\n\ -@seealso{input, pause}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} kbhit () +@deftypefnx {} {} kbhit (1) +Read a single keystroke from the keyboard. + +If called with an argument, don't wait for a keypress. + +For example, + +@example +x = kbhit (); +@end example + +@noindent +will set @var{x} to the next character typed at the keyboard as soon as +it is typed. + +@example +x = kbhit (1); +@end example + +@noindent +is identical to the above example, but doesn't wait for a keypress, +returning the empty string if no key is available. +@seealso{input, pause} +@end deftypefn */) { octave_value retval; @@ -754,37 +754,37 @@ } DEFUN (pause, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} pause ()\n\ -@deftypefnx {} {} pause (@var{n})\n\ -Suspend the execution of the program for @var{n} seconds.\n\ -\n\ -If invoked without an input arguments then the program is suspended until a\n\ -character is typed.\n\ -\n\ -@var{n} is a positive real value and may be a fraction of a second,\n\ -for example:\n\ -\n\ -@example\n\ -@group\n\ -tic; pause (0.05); toc\n\ - @print{} Elapsed time is 0.05039 seconds.\n\ -@end group\n\ -@end example\n\ -\n\ -The following example prints a message and then waits 5 seconds before\n\ -clearing the screen.\n\ -\n\ -@example\n\ -@group\n\ -disp (\"wait please...\");\n\ -pause (5);\n\ -clc;\n\ -@end group\n\ -@end example\n\ -\n\ -@seealso{kbhit}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} pause () +@deftypefnx {} {} pause (@var{n}) +Suspend the execution of the program for @var{n} seconds. + +If invoked without an input arguments then the program is suspended until a +character is typed. + +@var{n} is a positive real value and may be a fraction of a second, +for example: + +@example +@group +tic; pause (0.05); toc + @print{} Elapsed time is 0.05039 seconds. +@end group +@end example + +The following example prints a message and then waits 5 seconds before +clearing the screen. + +@example +@group +disp ("wait please..."); +pause (5); +clc; +@end group +@end example + +@seealso{kbhit} +@end deftypefn */) { int nargin = args.length (); @@ -831,13 +831,13 @@ // point functions really work. DEFUN (isieee, , , - "-*- texinfo -*-\n\ -@deftypefn {} {} isieee ()\n\ -Return true if your computer @emph{claims} to conform to the IEEE standard\n\ -for floating point calculations.\n\ -\n\ -No actual tests are performed.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isieee () +Return true if your computer @emph{claims} to conform to the IEEE standard +for floating point calculations. + +No actual tests are performed. +@end deftypefn */) { octave::mach_info::float_format flt_fmt = octave::mach_info::native_float_format (); @@ -850,10 +850,10 @@ */ DEFUN (native_float_format, , , - "-*- texinfo -*-\n\ -@deftypefn {} {} native_float_format ()\n\ -Return the native floating point format as a string.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} native_float_format () +Return the native floating point format as a string. +@end deftypefn */) { octave::mach_info::float_format flt_fmt = octave::mach_info::native_float_format (); @@ -865,32 +865,32 @@ */ DEFUN (tilde_expand, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} tilde_expand (@var{string})\n\ -@deftypefnx {} {} tilde_expand (@var{cellstr})\n\ -Perform tilde expansion on @var{string}.\n\ -\n\ -If @var{string} begins with a tilde character, (@samp{~}), all of the\n\ -characters preceding the first slash (or all characters, if there is no\n\ -slash) are treated as a possible user name, and the tilde and the following\n\ -characters up to the slash are replaced by the home directory of the named\n\ -user. If the tilde is followed immediately by a slash, the tilde is\n\ -replaced by the home directory of the user running Octave.\n\ -\n\ -If the input is a cell array of strings @var{cellstr} then tilde expansion\n\ -is performed on each string element.\n\ -\n\ -Examples:\n\ -\n\ -@example\n\ -@group\n\ -tilde_expand (\"~joeuser/bin\")\n\ - @result{} \"/home/joeuser/bin\"\n\ -tilde_expand (\"~/bin\")\n\ - @result{} \"/home/jwe/bin\"\n\ -@end group\n\ -@end example\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} tilde_expand (@var{string}) +@deftypefnx {} {} tilde_expand (@var{cellstr}) +Perform tilde expansion on @var{string}. + +If @var{string} begins with a tilde character, (@samp{~}), all of the +characters preceding the first slash (or all characters, if there is no +slash) are treated as a possible user name, and the tilde and the following +characters up to the slash are replaced by the home directory of the named +user. If the tilde is followed immediately by a slash, the tilde is +replaced by the home directory of the user running Octave. + +If the input is a cell array of strings @var{cellstr} then tilde expansion +is performed on each string element. + +Examples: + +@example +@group +tilde_expand ("~joeuser/bin") + @result{} "/home/joeuser/bin" +tilde_expand ("~/bin") + @result{} "/home/jwe/bin" +@end group +@end example +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -916,16 +916,16 @@ */ DEFUN (get_home_directory, , , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{homedir} =} get_home_directory ()\n\ -Return the current home directory.\n\ -\n\ -On most systems, this is equivalent to @code{getenv (\"HOME\")}. On Windows\n\ -systems, if the environment variable @env{HOME} is not set then it is\n\ -equivalent to\n\ -@code{fullfile (getenv (\"HOMEDRIVE\"), getenv (\"HOMEPATH\"))}\n\ -@seealso{getenv}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{homedir} =} get_home_directory () +Return the current home directory. + +On most systems, this is equivalent to @code{getenv ("HOME")}. On Windows +systems, if the environment variable @env{HOME} is not set then it is +equivalent to +@code{fullfile (getenv ("HOMEDRIVE"), getenv ("HOMEPATH"))} +@seealso{getenv} +@end deftypefn */) { return ovl (octave::sys::env::get_home_directory ()); } @@ -942,12 +942,12 @@ // needed for X11 and Carbon functions. DEFUN (have_window_system, , , - "-*- texinfo -*-\n\ -@deftypefn {} {} have_window_system ()\n\ -Return true if a window system is available (X11, Windows, or Apple OS X)\n\ -and false otherwise.\n\ -@seealso{isguirunning}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} have_window_system () +Return true if a window system is available (X11, Windows, or Apple OS X) +and false otherwise. +@seealso{isguirunning} +@end deftypefn */) { return ovl (display_info::display_available ()); }
--- a/libinterp/corefcn/time.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/time.cc Tue Jun 21 16:07:51 2016 -0400 @@ -104,15 +104,15 @@ } DEFUN (time, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{seconds} =} time ()\n\ -Return the current time as the number of seconds since the epoch.\n\ -\n\ -The epoch is referenced to 00:00:00 CUT (Coordinated Universal Time) 1 Jan\n\ -1970. For example, on Monday February 17, 1997 at 07:15:06 CUT, the value\n\ -returned by @code{time} was 856163706.\n\ -@seealso{strftime, strptime, localtime, gmtime, mktime, now, date, clock, datenum, datestr, datevec, calendar, weekday}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{seconds} =} time () +Return the current time as the number of seconds since the epoch. + +The epoch is referenced to 00:00:00 CUT (Coordinated Universal Time) 1 Jan +1970. For example, on Monday February 17, 1997 at 07:15:06 CUT, the value +returned by @code{time} was 856163706. +@seealso{strftime, strptime, localtime, gmtime, mktime, now, date, clock, datenum, datestr, datevec, calendar, weekday} +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -127,34 +127,34 @@ */ DEFUN (gmtime, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{tm_struct} =} gmtime (@var{t})\n\ -Given a value returned from @code{time}, or any non-negative integer,\n\ -return a time structure corresponding to CUT (Coordinated Universal Time).\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -gmtime (time ())\n\ - @result{} @{\n\ - usec = 0\n\ - sec = 6\n\ - min = 15\n\ - hour = 7\n\ - mday = 17\n\ - mon = 1\n\ - year = 97\n\ - wday = 1\n\ - yday = 47\n\ - isdst = 0\n\ - gmtoff = 0\n\ - zone = GMT\n\ - @}\n\ -@end group\n\ -@end example\n\ -@seealso{strftime, strptime, localtime, mktime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{tm_struct} =} gmtime (@var{t}) +Given a value returned from @code{time}, or any non-negative integer, +return a time structure corresponding to CUT (Coordinated Universal Time). + +For example: + +@example +@group +gmtime (time ()) + @result{} @{ + usec = 0 + sec = 6 + min = 15 + hour = 7 + mday = 17 + mon = 1 + year = 97 + wday = 1 + yday = 47 + isdst = 0 + gmtoff = 0 + zone = GMT + @} +@end group +@end example +@seealso{strftime, strptime, localtime, mktime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -184,32 +184,32 @@ */ DEFUN (localtime, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{tm_struct} =} localtime (@var{t})\n\ -Given a value returned from @code{time}, or any non-negative integer,\n\ -return a time structure corresponding to the local time zone.\n\ -\n\ -@example\n\ -@group\n\ -localtime (time ())\n\ - @result{} @{\n\ - usec = 0\n\ - sec = 6\n\ - min = 15\n\ - hour = 1\n\ - mday = 17\n\ - mon = 1\n\ - year = 97\n\ - wday = 1\n\ - yday = 47\n\ - isdst = 0\n\ - gmtoff = -21600\n\ - zone = CST\n\ - @}\n\ -@end group\n\ -@end example\n\ -@seealso{strftime, strptime, gmtime, mktime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{tm_struct} =} localtime (@var{t}) +Given a value returned from @code{time}, or any non-negative integer, +return a time structure corresponding to the local time zone. + +@example +@group +localtime (time ()) + @result{} @{ + usec = 0 + sec = 6 + min = 15 + hour = 1 + mday = 17 + mon = 1 + year = 97 + wday = 1 + yday = 47 + isdst = 0 + gmtoff = -21600 + zone = CST + @} +@end group +@end example +@seealso{strftime, strptime, gmtime, mktime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -239,21 +239,21 @@ */ DEFUN (mktime, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{seconds} =} mktime (@var{tm_struct})\n\ -Convert a time structure corresponding to the local time to the number of\n\ -seconds since the epoch.\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -mktime (localtime (time ()))\n\ - @result{} 856163706\n\ -@end group\n\ -@end example\n\ -@seealso{strftime, strptime, localtime, gmtime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{seconds} =} mktime (@var{tm_struct}) +Convert a time structure corresponding to the local time to the number of +seconds since the epoch. + +For example: + +@example +@group +mktime (localtime (time ())) + @result{} 856163706 +@end group +@end example +@seealso{strftime, strptime, localtime, gmtime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -283,162 +283,162 @@ */ DEFUN (strftime, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} strftime (@var{fmt}, @var{tm_struct})\n\ -Format the time structure @var{tm_struct} in a flexible way using the format\n\ -string @var{fmt} that contains @samp{%} substitutions similar to those in\n\ -@code{printf}.\n\ -\n\ -Except where noted, substituted fields have a fixed size; numeric fields are\n\ -padded if necessary. Padding is with zeros by default; for fields that\n\ -display a single number, padding can be changed or inhibited by following\n\ -the @samp{%} with one of the modifiers described below. Unknown field\n\ -specifiers are copied as normal characters. All other characters are copied\n\ -to the output without change. For example:\n\ -\n\ -@example\n\ -@group\n\ -strftime (\"%r (%Z) %A %e %B %Y\", localtime (time ()))\n\ - @result{} \"01:15:06 AM (CST) Monday 17 February 1997\"\n\ -@end group\n\ -@end example\n\ -\n\ -Octave's @code{strftime} function supports a superset of the ANSI C field\n\ -specifiers.\n\ -\n\ -@noindent\n\ -Literal character fields:\n\ -\n\ -@table @code\n\ -@item %%\n\ -% character.\n\ -\n\ -@item %n\n\ -Newline character.\n\ -\n\ -@item %t\n\ -Tab character.\n\ -@end table\n\ -\n\ -@noindent\n\ -Numeric modifiers (a nonstandard extension):\n\ -\n\ -@table @code\n\ -@item - (dash)\n\ -Do not pad the field.\n\ -\n\ -@item _ (underscore)\n\ -Pad the field with spaces.\n\ -@end table\n\ -\n\ -@noindent\n\ -Time fields:\n\ -\n\ -@table @code\n\ -@item %H\n\ -Hour (00-23).\n\ -\n\ -@item %I\n\ -Hour (01-12).\n\ -\n\ -@item %k\n\ -Hour (0-23).\n\ -\n\ -@item %l\n\ -Hour (1-12).\n\ -\n\ -@item %M\n\ -Minute (00-59).\n\ -\n\ -@item %p\n\ -Locale's AM or PM.\n\ -\n\ -@item %r\n\ -Time, 12-hour (hh:mm:ss [AP]M).\n\ -\n\ -@item %R\n\ -Time, 24-hour (hh:mm).\n\ -\n\ -@item %s\n\ -Time in seconds since 00:00:00, Jan 1, 1970 (a nonstandard extension).\n\ -\n\ -@item %S\n\ -Second (00-61).\n\ -\n\ -@item %T\n\ -Time, 24-hour (hh:mm:ss).\n\ -\n\ -@item %X\n\ -Locale's time representation (%H:%M:%S).\n\ -\n\ -@item %z\n\ -Offset from UTC (±@nospell{hhmm}), or nothing if no time zone is\n\ -determinable.\n\ -\n\ -@item %Z\n\ -Time zone (EDT), or nothing if no time zone is determinable.\n\ -@end table\n\ -\n\ -@noindent\n\ -Date fields:\n\ -\n\ -@table @code\n\ -@item %a\n\ -Locale's abbreviated weekday name (Sun-Sat).\n\ -\n\ -@item %A\n\ -Locale's full weekday name, variable length (Sunday-Saturday).\n\ -\n\ -@item %b\n\ -Locale's abbreviated month name (Jan-Dec).\n\ -\n\ -@item %B\n\ -Locale's full month name, variable length (January-December).\n\ -\n\ -@item %c\n\ -Locale's date and time (Sat Nov 04 12:02:33 EST 1989).\n\ -\n\ -@item %C\n\ -Century (00-99).\n\ -\n\ -@item %d\n\ -Day of month (01-31).\n\ -\n\ -@item %e\n\ -Day of month ( 1-31).\n\ -\n\ -@item %D\n\ -Date (mm/dd/yy).\n\ -\n\ -@item %h\n\ -Same as %b.\n\ -\n\ -@item %j\n\ -Day of year (001-366).\n\ -\n\ -@item %m\n\ -Month (01-12).\n\ -\n\ -@item %U\n\ -Week number of year with Sunday as first day of week (00-53).\n\ -\n\ -@item %w\n\ -Day of week (0-6).\n\ -\n\ -@item %W\n\ -Week number of year with Monday as first day of week (00-53).\n\ -\n\ -@item %x\n\ -Locale's date representation (mm/dd/yy).\n\ -\n\ -@item %y\n\ -Last two digits of year (00-99).\n\ -\n\ -@item %Y\n\ -Year (1970-).\n\ -@end table\n\ -@seealso{strptime, localtime, gmtime, mktime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} strftime (@var{fmt}, @var{tm_struct}) +Format the time structure @var{tm_struct} in a flexible way using the format +string @var{fmt} that contains @samp{%} substitutions similar to those in +@code{printf}. + +Except where noted, substituted fields have a fixed size; numeric fields are +padded if necessary. Padding is with zeros by default; for fields that +display a single number, padding can be changed or inhibited by following +the @samp{%} with one of the modifiers described below. Unknown field +specifiers are copied as normal characters. All other characters are copied +to the output without change. For example: + +@example +@group +strftime ("%r (%Z) %A %e %B %Y", localtime (time ())) + @result{} "01:15:06 AM (CST) Monday 17 February 1997" +@end group +@end example + +Octave's @code{strftime} function supports a superset of the ANSI C field +specifiers. + +@noindent +Literal character fields: + +@table @code +@item %% +% character. + +@item %n +Newline character. + +@item %t +Tab character. +@end table + +@noindent +Numeric modifiers (a nonstandard extension): + +@table @code +@item - (dash) +Do not pad the field. + +@item _ (underscore) +Pad the field with spaces. +@end table + +@noindent +Time fields: + +@table @code +@item %H +Hour (00-23). + +@item %I +Hour (01-12). + +@item %k +Hour (0-23). + +@item %l +Hour (1-12). + +@item %M +Minute (00-59). + +@item %p +Locale's AM or PM. + +@item %r +Time, 12-hour (hh:mm:ss [AP]M). + +@item %R +Time, 24-hour (hh:mm). + +@item %s +Time in seconds since 00:00:00, Jan 1, 1970 (a nonstandard extension). + +@item %S +Second (00-61). + +@item %T +Time, 24-hour (hh:mm:ss). + +@item %X +Locale's time representation (%H:%M:%S). + +@item %z +Offset from UTC (±@nospell{hhmm}), or nothing if no time zone is +determinable. + +@item %Z +Time zone (EDT), or nothing if no time zone is determinable. +@end table + +@noindent +Date fields: + +@table @code +@item %a +Locale's abbreviated weekday name (Sun-Sat). + +@item %A +Locale's full weekday name, variable length (Sunday-Saturday). + +@item %b +Locale's abbreviated month name (Jan-Dec). + +@item %B +Locale's full month name, variable length (January-December). + +@item %c +Locale's date and time (Sat Nov 04 12:02:33 EST 1989). + +@item %C +Century (00-99). + +@item %d +Day of month (01-31). + +@item %e +Day of month ( 1-31). + +@item %D +Date (mm/dd/yy). + +@item %h +Same as %b. + +@item %j +Day of year (001-366). + +@item %m +Month (01-12). + +@item %U +Week number of year with Sunday as first day of week (00-53). + +@item %w +Day of week (0-6). + +@item %W +Week number of year with Monday as first day of week (00-53). + +@item %x +Locale's date representation (mm/dd/yy). + +@item %y +Last two digits of year (00-99). + +@item %Y +Year (1970-). +@end table +@seealso{strptime, localtime, gmtime, mktime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday} +@end deftypefn */) { if (args.length () != 2) print_usage (); @@ -466,16 +466,16 @@ */ DEFUN (strptime, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{tm_struct}, @var{nchars}] =} strptime (@var{str}, @var{fmt})\n\ -Convert the string @var{str} to the time structure @var{tm_struct} under\n\ -the control of the format string @var{fmt}.\n\ -\n\ -If @var{fmt} fails to match, @var{nchars} is 0; otherwise, it is set to the\n\ -position of last matched character plus 1. Always check for this unless\n\ -you're absolutely sure the date string will be parsed correctly.\n\ -@seealso{strftime, localtime, gmtime, mktime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{tm_struct}, @var{nchars}] =} strptime (@var{str}, @var{fmt}) +Convert the string @var{str} to the time structure @var{tm_struct} under +the control of the format string @var{fmt}. + +If @var{fmt} fails to match, @var{nchars} is 0; otherwise, it is set to the +position of last matched character plus 1. Always check for this unless +you're absolutely sure the date string will be parsed correctly. +@seealso{strftime, localtime, gmtime, mktime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday} +@end deftypefn */) { if (args.length () != 2) print_usage ();
--- a/libinterp/corefcn/toplev.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/toplev.cc Tue Jun 21 16:07:51 2016 -0400 @@ -919,22 +919,22 @@ } DEFUN (quit, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} exit\n\ -@deftypefnx {} {} exit (@var{status})\n\ -@deftypefnx {} {} quit\n\ -@deftypefnx {} {} quit (@var{status})\n\ -Exit the current Octave session.\n\ -\n\ -If the optional integer value @var{status} is supplied, pass that value to\n\ -the operating system as Octave's exit status. The default value is zero.\n\ -\n\ -When exiting, Octave will attempt to run the m-file @file{finish.m} if it\n\ -exists. User commands to save the workspace or clean up temporary files\n\ -may be placed in that file. Alternatively, another m-file may be scheduled\n\ -to run using @code{atexit}.\n\ -@seealso{atexit}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} exit +@deftypefnx {} {} exit (@var{status}) +@deftypefnx {} {} quit +@deftypefnx {} {} quit (@var{status}) +Exit the current Octave session. + +If the optional integer value @var{status} is supplied, pass that value to +the operating system as Octave's exit status. The default value is zero. + +When exiting, Octave will attempt to run the m-file @file{finish.m} if it +exists. User commands to save the workspace or clean up temporary files +may be placed in that file. Alternatively, another m-file may be scheduled +to run using @code{atexit}. +@seealso{atexit} +@end deftypefn */) { // Confirm OK to shutdown. Note: A dynamic function installation similar // to overriding polymorphism for which the GUI can install its own "quit" @@ -970,10 +970,10 @@ DEFALIAS (exit, quit); DEFUN (warranty, , , - "-*- texinfo -*-\n\ -@deftypefn {} {} warranty ()\n\ -Describe the conditions for copying and distributing Octave.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} warranty () +Describe the conditions for copying and distributing Octave. +@end deftypefn */) { octave_stdout << "\n" << octave_name_version_and_copyright () << "\n\ \n\ @@ -1049,56 +1049,56 @@ enum system_exec_type { et_sync, et_async }; DEFUN (system, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} system (\"@var{string}\")\n\ -@deftypefnx {} {} system (\"@var{string}\", @var{return_output})\n\ -@deftypefnx {} {} system (\"@var{string}\", @var{return_output}, @var{type})\n\ -@deftypefnx {} {[@var{status}, @var{output}] =} system (@dots{})\n\ -Execute a shell command specified by @var{string}.\n\ -\n\ -If the optional argument @var{type} is @qcode{\"async\"}, the process is\n\ -started in the background and the process ID of the child process is\n\ -returned immediately. Otherwise, the child process is started and Octave\n\ -waits until it exits. If the @var{type} argument is omitted, it defaults to\n\ -the value @qcode{\"sync\"}.\n\ -\n\ -If @var{system} is called with one or more output arguments, or if the\n\ -optional argument @var{return_output} is true and the subprocess is started\n\ -synchronously, then the output from the command is returned as a variable.\n\ -Otherwise, if the subprocess is executed synchronously, its output is sent\n\ -to the standard output. To send the output of a command executed with\n\ -@code{system} through the pager, use a command like\n\ -\n\ -@example\n\ -@group\n\ -[~, text] = system (\"cmd\");\n\ -disp (text);\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -or\n\ -\n\ -@example\n\ -printf (\"%s\\n\", nthargout (2, \"system\", \"cmd\"));\n\ -@end example\n\ -\n\ -The @code{system} function can return two values. The first is the\n\ -exit status of the command and the second is any output from the\n\ -command that was written to the standard output stream. For example,\n\ -\n\ -@example\n\ -[status, output] = system (\"echo foo; exit 2\");\n\ -@end example\n\ -\n\ -@noindent\n\ -will set the variable @code{output} to the string @samp{foo}, and the\n\ -variable @code{status} to the integer @samp{2}.\n\ -\n\ -For commands run asynchronously, @var{status} is the process id of the\n\ -command shell that is started to run the command.\n\ -@seealso{unix, dos}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} system ("@var{string}") +@deftypefnx {} {} system ("@var{string}", @var{return_output}) +@deftypefnx {} {} system ("@var{string}", @var{return_output}, @var{type}) +@deftypefnx {} {[@var{status}, @var{output}] =} system (@dots{}) +Execute a shell command specified by @var{string}. + +If the optional argument @var{type} is @qcode{"async"}, the process is +started in the background and the process ID of the child process is +returned immediately. Otherwise, the child process is started and Octave +waits until it exits. If the @var{type} argument is omitted, it defaults to +the value @qcode{"sync"}. + +If @var{system} is called with one or more output arguments, or if the +optional argument @var{return_output} is true and the subprocess is started +synchronously, then the output from the command is returned as a variable. +Otherwise, if the subprocess is executed synchronously, its output is sent +to the standard output. To send the output of a command executed with +@code{system} through the pager, use a command like + +@example +@group +[~, text] = system ("cmd"); +disp (text); +@end group +@end example + +@noindent +or + +@example +printf ("%s\n", nthargout (2, "system", "cmd")); +@end example + +The @code{system} function can return two values. The first is the +exit status of the command and the second is any output from the +command that was written to the standard output stream. For example, + +@example +[status, output] = system ("echo foo; exit 2"); +@end example + +@noindent +will set the variable @code{output} to the string @samp{foo}, and the +variable @code{status} to the integer @samp{2}. + +For commands run asynchronously, @var{status} is the process id of the +command shell that is started to run the command. +@seealso{unix, dos} +@end deftypefn */) { int nargin = args.length (); @@ -1243,44 +1243,44 @@ DEFUN (atexit, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} atexit (@var{fcn})\n\ -@deftypefnx {} {} atexit (@var{fcn}, @var{flag})\n\ -Register a function to be called when Octave exits.\n\ -\n\ -For example,\n\ -\n\ -@example\n\ -@group\n\ -function last_words ()\n\ - disp (\"Bye bye\");\n\ -endfunction\n\ -atexit (\"last_words\");\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -will print the message @qcode{\"Bye bye\"} when Octave exits.\n\ -\n\ -The additional argument @var{flag} will register or unregister @var{fcn}\n\ -from the list of functions to be called when Octave exits. If @var{flag} is\n\ -true, the function is registered, and if @var{flag} is false, it is\n\ -unregistered. For example, after registering the function @code{last_words}\n\ -above,\n\ -\n\ -@example\n\ -atexit (\"last_words\", false);\n\ -@end example\n\ -\n\ -@noindent\n\ -will remove the function from the list and Octave will not call\n\ -@code{last_words} when it exits.\n\ -\n\ -Note that @code{atexit} only removes the first occurrence of a function\n\ -from the list, so if a function was placed in the list multiple times with\n\ -@code{atexit}, it must also be removed from the list multiple times.\n\ -@seealso{quit}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} atexit (@var{fcn}) +@deftypefnx {} {} atexit (@var{fcn}, @var{flag}) +Register a function to be called when Octave exits. + +For example, + +@example +@group +function last_words () + disp ("Bye bye"); +endfunction +atexit ("last_words"); +@end group +@end example + +@noindent +will print the message @qcode{"Bye bye"} when Octave exits. + +The additional argument @var{flag} will register or unregister @var{fcn} +from the list of functions to be called when Octave exits. If @var{flag} is +true, the function is registered, and if @var{flag} is false, it is +unregistered. For example, after registering the function @code{last_words} +above, + +@example +atexit ("last_words", false); +@end example + +@noindent +will remove the function from the list and Octave will not call +@code{last_words} when it exits. + +Note that @code{atexit} only removes the first occurrence of a function +from the list, so if a function was placed in the list multiple times with +@code{atexit}, it must also be removed from the list multiple times. +@seealso{quit} +@end deftypefn */) { int nargin = args.length (); @@ -1323,17 +1323,17 @@ } DEFUN (__octave_config_info__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __octave_config_info__ ()\n\ -@deftypefnx {} {} __octave_config_info__ (@var{option})\n\ -Return a structure containing configuration and installation information for\n\ -Octave.\n\ -\n\ -If @var{option} is a string, return the configuration information for the\n\ -specified option.\n\ -\n\ -@seealso{computer}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __octave_config_info__ () +@deftypefnx {} {} __octave_config_info__ (@var{option}) +Return a structure containing configuration and installation information for +Octave. + +If @var{option} is a string, return the configuration information for the +specified option. + +@seealso{computer} +@end deftypefn */) { #if defined (ENABLE_DYNAMIC_LINKING) bool octave_supports_dynamic_linking = true;
--- a/libinterp/corefcn/tril.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/tril.cc Tue Jun 21 16:07:51 2016 -0400 @@ -328,70 +328,70 @@ } DEFUN (tril, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} tril (@var{A})\n\ -@deftypefnx {} {} tril (@var{A}, @var{k})\n\ -@deftypefnx {} {} tril (@var{A}, @var{k}, @var{pack})\n\ -@deftypefnx {} {} triu (@var{A})\n\ -@deftypefnx {} {} triu (@var{A}, @var{k})\n\ -@deftypefnx {} {} triu (@var{A}, @var{k}, @var{pack})\n\ -Return a new matrix formed by extracting the lower (@code{tril})\n\ -or upper (@code{triu}) triangular part of the matrix @var{A}, and\n\ -setting all other elements to zero.\n\ -\n\ -The second argument is optional, and specifies how many diagonals above or\n\ -below the main diagonal should also be set to zero.\n\ -\n\ -The default value of @var{k} is zero, so that @code{triu} and @code{tril}\n\ -normally include the main diagonal as part of the result.\n\ -\n\ -If the value of @var{k} is nonzero integer, the selection of elements starts\n\ -at an offset of @var{k} diagonals above or below the main diagonal; above\n\ -for positive @var{k} and below for negative @var{k}.\n\ -\n\ -The absolute value of @var{k} must not be greater than the number of\n\ -subdiagonals or superdiagonals.\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -tril (ones (3), -1)\n\ - @result{} 0 0 0\n\ - 1 0 0\n\ - 1 1 0\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -and\n\ -\n\ -@example\n\ -@group\n\ -tril (ones (3), 1)\n\ - @result{} 1 1 0\n\ - 1 1 1\n\ - 1 1 1\n\ -@end group\n\ -@end example\n\ -\n\ -If the option @qcode{\"pack\"} is given as third argument, the extracted\n\ -elements are not inserted into a matrix, but rather stacked column-wise one\n\ -above other.\n\ -@seealso{diag}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} tril (@var{A}) +@deftypefnx {} {} tril (@var{A}, @var{k}) +@deftypefnx {} {} tril (@var{A}, @var{k}, @var{pack}) +@deftypefnx {} {} triu (@var{A}) +@deftypefnx {} {} triu (@var{A}, @var{k}) +@deftypefnx {} {} triu (@var{A}, @var{k}, @var{pack}) +Return a new matrix formed by extracting the lower (@code{tril}) +or upper (@code{triu}) triangular part of the matrix @var{A}, and +setting all other elements to zero. + +The second argument is optional, and specifies how many diagonals above or +below the main diagonal should also be set to zero. + +The default value of @var{k} is zero, so that @code{triu} and @code{tril} +normally include the main diagonal as part of the result. + +If the value of @var{k} is nonzero integer, the selection of elements starts +at an offset of @var{k} diagonals above or below the main diagonal; above +for positive @var{k} and below for negative @var{k}. + +The absolute value of @var{k} must not be greater than the number of +subdiagonals or superdiagonals. + +For example: + +@example +@group +tril (ones (3), -1) + @result{} 0 0 0 + 1 0 0 + 1 1 0 +@end group +@end example + +@noindent +and + +@example +@group +tril (ones (3), 1) + @result{} 1 1 0 + 1 1 1 + 1 1 1 +@end group +@end example + +If the option @qcode{"pack"} is given as third argument, the extracted +elements are not inserted into a matrix, but rather stacked column-wise one +above other. +@seealso{diag} +@end deftypefn */) { return do_trilu ("tril", args); } DEFUN (triu, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} triu (@var{A})\n\ -@deftypefnx {} {} triu (@var{A}, @var{k})\n\ -@deftypefnx {} {} triu (@var{A}, @var{k}, @var{pack})\n\ -See the documentation for the @code{tril} function (@pxref{tril}).\n\ -@seealso{tril}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} triu (@var{A}) +@deftypefnx {} {} triu (@var{A}, @var{k}) +@deftypefnx {} {} triu (@var{A}, @var{k}, @var{pack}) +See the documentation for the @code{tril} function (@pxref{tril}). +@seealso{tril} +@end deftypefn */) { return do_trilu ("triu", args); }
--- a/libinterp/corefcn/tsearch.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/tsearch.cc Tue Jun 21 16:07:51 2016 -0400 @@ -60,15 +60,15 @@ // method to traverse it DEFUN (tsearch, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{idx} =} tsearch (@var{x}, @var{y}, @var{t}, @var{xi}, @var{yi})\n\ -Search for the enclosing Delaunay convex hull.\n\ -\n\ -For @code{@var{t} = delaunay (@var{x}, @var{y})}, finds the index in @var{t}\n\ -containing the points @code{(@var{xi}, @var{yi})}. For points outside the\n\ -convex hull, @var{idx} is NaN.\n\ -@seealso{delaunay, delaunayn}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{idx} =} tsearch (@var{x}, @var{y}, @var{t}, @var{xi}, @var{yi}) +Search for the enclosing Delaunay convex hull. + +For @code{@var{t} = delaunay (@var{x}, @var{y})}, finds the index in @var{t} +containing the points @code{(@var{xi}, @var{yi})}. For points outside the +convex hull, @var{idx} is NaN. +@seealso{delaunay, delaunayn} +@end deftypefn */) { if (args.length () != 5) print_usage ();
--- a/libinterp/corefcn/typecast.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/typecast.cc Tue Jun 21 16:07:51 2016 -0400 @@ -84,59 +84,59 @@ DEFUN (typecast, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{y} =} typecast (@var{x}, \"@var{class}\")\n\ -Return a new array @var{y} resulting from interpreting the data of @var{x}\n\ -in memory as data of the numeric class @var{class}.\n\ -\n\ -Both the class of @var{x} and @var{class} must be one of the built-in\n\ -numeric classes:\n\ -\n\ -@example\n\ -@group\n\ -\"logical\"\n\ -\"char\"\n\ -\"int8\"\n\ -\"int16\"\n\ -\"int32\"\n\ -\"int64\"\n\ -\"uint8\"\n\ -\"uint16\"\n\ -\"uint32\"\n\ -\"uint64\"\n\ -\"double\"\n\ -\"single\"\n\ -\"double complex\"\n\ -\"single complex\"\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -the last two are only used with @var{class}; they indicate that a\n\ -complex-valued result is requested. Complex arrays are stored in memory as\n\ -consecutive pairs of real numbers. The sizes of integer types are given by\n\ -their bit counts. Both logical and char are typically one byte wide;\n\ -however, this is not guaranteed by C++. If your system is IEEE conformant,\n\ -single and double will be 4 bytes and 8 bytes wide, respectively.\n\ -@qcode{\"logical\"} is not allowed for @var{class}.\n\ -\n\ -If the input is a row vector, the return value is a row vector, otherwise it\n\ -is a column vector.\n\ -\n\ -If the bit length of @var{x} is not divisible by that of @var{class}, an\n\ -error occurs.\n\ -\n\ -An example of the use of typecast on a little-endian machine is\n\ -\n\ -@example\n\ -@group\n\ -@var{x} = uint16 ([1, 65535]);\n\ -typecast (@var{x}, \"uint8\")\n\ -@result{} [ 1, 0, 255, 255]\n\ -@end group\n\ -@end example\n\ -@seealso{cast, bitpack, bitunpack, swapbytes}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{y} =} typecast (@var{x}, "@var{class}") +Return a new array @var{y} resulting from interpreting the data of @var{x} +in memory as data of the numeric class @var{class}. + +Both the class of @var{x} and @var{class} must be one of the built-in +numeric classes: + +@example +@group +"logical" +"char" +"int8" +"int16" +"int32" +"int64" +"uint8" +"uint16" +"uint32" +"uint64" +"double" +"single" +"double complex" +"single complex" +@end group +@end example + +@noindent +the last two are only used with @var{class}; they indicate that a +complex-valued result is requested. Complex arrays are stored in memory as +consecutive pairs of real numbers. The sizes of integer types are given by +their bit counts. Both logical and char are typically one byte wide; +however, this is not guaranteed by C++. If your system is IEEE conformant, +single and double will be 4 bytes and 8 bytes wide, respectively. +@qcode{"logical"} is not allowed for @var{class}. + +If the input is a row vector, the return value is a row vector, otherwise it +is a column vector. + +If the bit length of @var{x} is not divisible by that of @var{class}, an +error occurs. + +An example of the use of typecast on a little-endian machine is + +@example +@group +@var{x} = uint16 ([1, 65535]); +typecast (@var{x}, "uint8") +@result{} [ 1, 0, 255, 255] +@end group +@end example +@seealso{cast, bitpack, bitunpack, swapbytes} +@end deftypefn */) { if (args.length () != 2) print_usage (); @@ -316,40 +316,40 @@ } DEFUN (bitpack, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{y} =} bitpack (@var{x}, @var{class})\n\ -Return a new array @var{y} resulting from interpreting the logical array\n\ -@var{x} as raw bit patterns for data of the numeric class @var{class}.\n\ -\n\ -@var{class} must be one of the built-in numeric classes:\n\ -\n\ -@example\n\ -@group\n\ -\"double\"\n\ -\"single\"\n\ -\"double complex\"\n\ -\"single complex\"\n\ -\"char\"\n\ -\"int8\"\n\ -\"int16\"\n\ -\"int32\"\n\ -\"int64\"\n\ -\"uint8\"\n\ -\"uint16\"\n\ -\"uint32\"\n\ -\"uint64\"\n\ -@end group\n\ -@end example\n\ -\n\ -The number of elements of @var{x} should be divisible by the bit length of\n\ -@var{class}. If it is not, excess bits are discarded. Bits come in\n\ -increasing order of significance, i.e., @code{x(1)} is bit 0, @code{x(2)} is\n\ -bit 1, etc.\n\ -\n\ -The result is a row vector if @var{x} is a row vector, otherwise it is a\n\ -column vector.\n\ -@seealso{bitunpack, typecast}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{y} =} bitpack (@var{x}, @var{class}) +Return a new array @var{y} resulting from interpreting the logical array +@var{x} as raw bit patterns for data of the numeric class @var{class}. + +@var{class} must be one of the built-in numeric classes: + +@example +@group +"double" +"single" +"double complex" +"single complex" +"char" +"int8" +"int16" +"int32" +"int64" +"uint8" +"uint16" +"uint32" +"uint64" +@end group +@end example + +The number of elements of @var{x} should be divisible by the bit length of +@var{class}. If it is not, excess bits are discarded. Bits come in +increasing order of significance, i.e., @code{x(1)} is bit 0, @code{x(2)} is +bit 1, etc. + +The result is a row vector if @var{x} is a row vector, otherwise it is a +column vector. +@seealso{bitunpack, typecast} +@end deftypefn */) { if (args.length () != 2) print_usage (); @@ -456,33 +456,33 @@ } DEFUN (bitunpack, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{y} =} bitunpack (@var{x})\n\ -Return a logical array @var{y} corresponding to the raw bit patterns of\n\ -@var{x}.\n\ -\n\ -@var{x} must belong to one of the built-in numeric classes:\n\ -\n\ -@example\n\ -@group\n\ -\"double\"\n\ -\"single\"\n\ -\"char\"\n\ -\"int8\"\n\ -\"int16\"\n\ -\"int32\"\n\ -\"int64\"\n\ -\"uint8\"\n\ -\"uint16\"\n\ -\"uint32\"\n\ -\"uint64\"\n\ -@end group\n\ -@end example\n\ -\n\ -The result is a row vector if @var{x} is a row vector; otherwise, it is a\n\ -column vector.\n\ -@seealso{bitpack, typecast}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{y} =} bitunpack (@var{x}) +Return a logical array @var{y} corresponding to the raw bit patterns of +@var{x}. + +@var{x} must belong to one of the built-in numeric classes: + +@example +@group +"double" +"single" +"char" +"int8" +"int16" +"int32" +"int64" +"uint8" +"uint16" +"uint32" +"uint64" +@end group +@end example + +The result is a row vector if @var{x} is a row vector; otherwise, it is a +column vector. +@seealso{bitpack, typecast} +@end deftypefn */) { if (args.length () != 1) print_usage ();
--- a/libinterp/corefcn/urlwrite.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/urlwrite.cc Tue Jun 21 16:07:51 2016 -0400 @@ -278,55 +278,55 @@ ch_manager *ch_manager::instance = 0; DEFUN (urlwrite, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} urlwrite (@var{url}, @var{localfile})\n\ -@deftypefnx {} {@var{f} =} urlwrite (@var{url}, @var{localfile})\n\ -@deftypefnx {} {[@var{f}, @var{success}] =} urlwrite (@var{url}, @var{localfile})\n\ -@deftypefnx {} {[@var{f}, @var{success}, @var{message}] =} urlwrite (@var{url}, @var{localfile})\n\ -Download a remote file specified by its @var{url} and save it as\n\ -@var{localfile}.\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -urlwrite (\"ftp://ftp.octave.org/pub/README\",\n\ - \"README.txt\");\n\ -@end group\n\ -@end example\n\ -\n\ -The full path of the downloaded file is returned in @var{f}.\n\ -\n\ -The variable @var{success} is 1 if the download was successful,\n\ -otherwise it is 0 in which case @var{message} contains an error message.\n\ -\n\ -If no output argument is specified and an error occurs, then the error is\n\ -signaled through Octave's error handling mechanism.\n\ -\n\ -This function uses libcurl. Curl supports, among others, the HTTP, FTP, and\n\ -FILE protocols. Username and password may be specified in the URL, for\n\ -example:\n\ -\n\ -@example\n\ -@group\n\ -urlwrite (\"http://username:password@@example.com/file.txt\",\n\ - \"file.txt\");\n\ -@end group\n\ -@end example\n\ -\n\ -GET and POST requests can be specified by @var{method} and @var{param}.\n\ -The parameter @var{method} is either @samp{get} or @samp{post} and\n\ -@var{param} is a cell array of parameter and value pairs.\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -urlwrite (\"http://www.google.com/search\", \"search.html\",\n\ - \"get\", @{\"query\", \"octave\"@});\n\ -@end group\n\ -@end example\n\ -@seealso{urlread}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} urlwrite (@var{url}, @var{localfile}) +@deftypefnx {} {@var{f} =} urlwrite (@var{url}, @var{localfile}) +@deftypefnx {} {[@var{f}, @var{success}] =} urlwrite (@var{url}, @var{localfile}) +@deftypefnx {} {[@var{f}, @var{success}, @var{message}] =} urlwrite (@var{url}, @var{localfile}) +Download a remote file specified by its @var{url} and save it as +@var{localfile}. + +For example: + +@example +@group +urlwrite ("ftp://ftp.octave.org/pub/README", + "README.txt"); +@end group +@end example + +The full path of the downloaded file is returned in @var{f}. + +The variable @var{success} is 1 if the download was successful, +otherwise it is 0 in which case @var{message} contains an error message. + +If no output argument is specified and an error occurs, then the error is +signaled through Octave's error handling mechanism. + +This function uses libcurl. Curl supports, among others, the HTTP, FTP, and +FILE protocols. Username and password may be specified in the URL, for +example: + +@example +@group +urlwrite ("http://username:password@@example.com/file.txt", + "file.txt"); +@end group +@end example + +GET and POST requests can be specified by @var{method} and @var{param}. +The parameter @var{method} is either @samp{get} or @samp{post} and +@var{param} is a cell array of parameter and value pairs. +For example: + +@example +@group +urlwrite ("http://www.google.com/search", "search.html", + "get", @{"query", "octave"@}); +@end group +@end example +@seealso{urlread} +@end deftypefn */) { int nargin = args.length (); @@ -399,48 +399,48 @@ } DEFUN (urlread, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{s} =} urlread (@var{url})\n\ -@deftypefnx {} {[@var{s}, @var{success}] =} urlread (@var{url})\n\ -@deftypefnx {} {[@var{s}, @var{success}, @var{message}] =} urlread (@var{url})\n\ -@deftypefnx {} {[@dots{}] =} urlread (@var{url}, @var{method}, @var{param})\n\ -Download a remote file specified by its @var{url} and return its content\n\ -in string @var{s}.\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -s = urlread (\"ftp://ftp.octave.org/pub/README\");\n\ -@end example\n\ -\n\ -The variable @var{success} is 1 if the download was successful,\n\ -otherwise it is 0 in which case @var{message} contains an error\n\ -message.\n\ -\n\ -If no output argument is specified and an error occurs, then the error is\n\ -signaled through Octave's error handling mechanism.\n\ -\n\ -This function uses libcurl. Curl supports, among others, the HTTP, FTP, and\n\ -FILE protocols. Username and password may be specified in the URL@. For\n\ -example:\n\ -\n\ -@example\n\ -s = urlread (\"http://user:password@@example.com/file.txt\");\n\ -@end example\n\ -\n\ -GET and POST requests can be specified by @var{method} and @var{param}.\n\ -The parameter @var{method} is either @samp{get} or @samp{post} and\n\ -@var{param} is a cell array of parameter and value pairs.\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -s = urlread (\"http://www.google.com/search\", \"get\",\n\ - @{\"query\", \"octave\"@});\n\ -@end group\n\ -@end example\n\ -@seealso{urlwrite}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{s} =} urlread (@var{url}) +@deftypefnx {} {[@var{s}, @var{success}] =} urlread (@var{url}) +@deftypefnx {} {[@var{s}, @var{success}, @var{message}] =} urlread (@var{url}) +@deftypefnx {} {[@dots{}] =} urlread (@var{url}, @var{method}, @var{param}) +Download a remote file specified by its @var{url} and return its content +in string @var{s}. + +For example: + +@example +s = urlread ("ftp://ftp.octave.org/pub/README"); +@end example + +The variable @var{success} is 1 if the download was successful, +otherwise it is 0 in which case @var{message} contains an error +message. + +If no output argument is specified and an error occurs, then the error is +signaled through Octave's error handling mechanism. + +This function uses libcurl. Curl supports, among others, the HTTP, FTP, and +FILE protocols. Username and password may be specified in the URL@. For +example: + +@example +s = urlread ("http://user:password@@example.com/file.txt"); +@end example + +GET and POST requests can be specified by @var{method} and @var{param}. +The parameter @var{method} is either @samp{get} or @samp{post} and +@var{param} is a cell array of parameter and value pairs. +For example: + +@example +@group +s = urlread ("http://www.google.com/search", "get", + @{"query", "octave"@}); +@end group +@end example +@seealso{urlwrite} +@end deftypefn */) { int nargin = args.length (); @@ -491,11 +491,11 @@ } DEFUN (__ftp__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{handle} =} __ftp__ (@var{host})\n\ -@deftypefnx {} {@var{handle} =} __ftp__ (@var{host}, @var{username}, @var{password})\n\ -Undocumented internal function\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{handle} =} __ftp__ (@var{host}) +@deftypefnx {} {@var{handle} =} __ftp__ (@var{host}, @var{username}, @var{password}) +Undocumented internal function +@end deftypefn */) { int nargin = args.length (); @@ -519,10 +519,10 @@ } DEFUN (__ftp_pwd__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __ftp_pwd__ (@var{handle})\n\ -Undocumented internal function\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __ftp_pwd__ (@var{handle}) +Undocumented internal function +@end deftypefn */) { if (args.length () != 1) error ("__ftp_pwd__: incorrect number of arguments"); @@ -536,10 +536,10 @@ } DEFUN (__ftp_cwd__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __ftp_cwd__ (@var{handle}, @var{path})\n\ -Undocumented internal function\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __ftp_cwd__ (@var{handle}, @var{path}) +Undocumented internal function +@end deftypefn */) { int nargin = args.length (); @@ -561,10 +561,10 @@ } DEFUN (__ftp_dir__, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} __ftp_dir__ (@var{handle})\n\ -Undocumented internal function\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __ftp_dir__ (@var{handle}) +Undocumented internal function +@end deftypefn */) { if (args.length () != 1) error ("__ftp_dir__: incorrect number of arguments"); @@ -633,10 +633,10 @@ } DEFUN (__ftp_ascii__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __ftp_ascii__ (@var{handle})\n\ -Undocumented internal function\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __ftp_ascii__ (@var{handle}) +Undocumented internal function +@end deftypefn */) { if (args.length () != 1) error ("__ftp_ascii__: incorrect number of arguments"); @@ -652,10 +652,10 @@ } DEFUN (__ftp_binary__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __ftp_binary__ (@var{handle})\n\ -Undocumented internal function\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __ftp_binary__ (@var{handle}) +Undocumented internal function +@end deftypefn */) { if (args.length () != 1) error ("__ftp_binary__: incorrect number of arguments"); @@ -671,10 +671,10 @@ } DEFUN (__ftp_close__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __ftp_close__ (@var{handle})\n\ -Undocumented internal function\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __ftp_close__ (@var{handle}) +Undocumented internal function +@end deftypefn */) { if (args.length () != 1) error ("__ftp_close__: incorrect number of arguments"); @@ -690,10 +690,10 @@ } DEFUN (__ftp_mode__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __ftp_mode__ (@var{handle})\n\ -Undocumented internal function\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __ftp_mode__ (@var{handle}) +Undocumented internal function +@end deftypefn */) { if (args.length () != 1) error ("__ftp_mode__: incorrect number of arguments"); @@ -707,10 +707,10 @@ } DEFUN (__ftp_delete__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __ftp_delete__ (@var{handle}, @var{path})\n\ -Undocumented internal function\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __ftp_delete__ (@var{handle}, @var{path}) +Undocumented internal function +@end deftypefn */) { if (args.length () != 2) error ("__ftp_delete__: incorrect number of arguments"); @@ -728,10 +728,10 @@ } DEFUN (__ftp_rmdir__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __ftp_rmdir__ (@var{handle}, @var{path})\n\ -Undocumented internal function\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __ftp_rmdir__ (@var{handle}, @var{path}) +Undocumented internal function +@end deftypefn */) { if (args.length () != 2) error ("__ftp_rmdir__: incorrect number of arguments"); @@ -749,10 +749,10 @@ } DEFUN (__ftp_mkdir__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __ftp_mkdir__ (@var{handle}, @var{path})\n\ -Undocumented internal function\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __ftp_mkdir__ (@var{handle}, @var{path}) +Undocumented internal function +@end deftypefn */) { if (args.length () != 2) error ("__ftp_mkdir__: incorrect number of arguments"); @@ -770,10 +770,10 @@ } DEFUN (__ftp_rename__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __ftp_rename__ (@var{handle}, @var{path})\n\ -Undocumented internal function\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __ftp_rename__ (@var{handle}, @var{path}) +Undocumented internal function +@end deftypefn */) { if (args.length () != 3) error ("__ftp_rename__: incorrect number of arguments"); @@ -792,10 +792,10 @@ } DEFUN (__ftp_mput__, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} __ftp_mput__ (@var{handle}, @var{files})\n\ -Undocumented internal function\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __ftp_mput__ (@var{handle}, @var{files}) +Undocumented internal function +@end deftypefn */) { if (args.length () != 2) error ("__ftp_mput__: incorrect number of arguments"); @@ -854,11 +854,11 @@ } DEFUN (__ftp_mget__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __ftp_mget__ (@var{handle}, @var{pattern})\n\ -@deftypefnx {} {} __ftp_mget__ (@var{handle}, @var{pattern}, @var{target})\n\ -Undocumented internal function\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __ftp_mget__ (@var{handle}, @var{pattern}) +@deftypefnx {} {} __ftp_mget__ (@var{handle}, @var{pattern}, @var{target}) +Undocumented internal function +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/corefcn/utils.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/utils.cc Tue Jun 21 16:07:51 2016 -0400 @@ -90,11 +90,11 @@ } DEFUN (isvarname, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isvarname (@var{name})\n\ -Return true if @var{name} is a valid variable name.\n\ -@seealso{iskeyword, exist, who}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isvarname (@var{name}) +Return true if @var{name} is a valid variable name. +@seealso{iskeyword, exist, who} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -286,24 +286,24 @@ } DEFUN (file_in_loadpath, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} file_in_loadpath (@var{file})\n\ -@deftypefnx {} {} file_in_loadpath (@var{file}, \"all\")\n\ -\n\ -Return the absolute name of @var{file} if it can be found in\n\ -the list of directories specified by @code{path}.\n\ -\n\ -If no file is found, return an empty character string.\n\ -\n\ -If the first argument is a cell array of strings, search each directory of\n\ -the loadpath for element of the cell array and return the first that\n\ -matches.\n\ -\n\ -If the second optional argument @qcode{\"all\"} is supplied, return a cell\n\ -array containing the list of all files that have the same name in the path.\n\ -If no files are found, return an empty cell array.\n\ -@seealso{file_in_path, dir_in_loadpath, path}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} file_in_loadpath (@var{file}) +@deftypefnx {} {} file_in_loadpath (@var{file}, "all") + +Return the absolute name of @var{file} if it can be found in +the list of directories specified by @code{path}. + +If no file is found, return an empty character string. + +If the first argument is a cell array of strings, search each directory of +the loadpath for element of the cell array and return the first that +matches. + +If the second optional argument @qcode{"all"} is supplied, return a cell +array containing the list of all files that have the same name in the path. +If no files are found, return an empty cell array. +@seealso{file_in_path, dir_in_loadpath, path} +@end deftypefn */) { int nargin = args.length (); @@ -349,30 +349,30 @@ */ DEFUN (file_in_path, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} file_in_path (@var{path}, @var{file})\n\ -@deftypefnx {} {} file_in_path (@var{path}, @var{file}, \"all\")\n\ -Return the absolute name of @var{file} if it can be found in @var{path}.\n\ -\n\ -The value of @var{path} should be a colon-separated list of directories in\n\ -the format described for @code{path}. If no file is found, return an empty\n\ -character string. For example:\n\ -\n\ -@example\n\ -@group\n\ -file_in_path (EXEC_PATH, \"sh\")\n\ - @result{} \"/bin/sh\"\n\ -@end group\n\ -@end example\n\ -\n\ -If the second argument is a cell array of strings, search each directory of\n\ -the path for element of the cell array and return the first that matches.\n\ -\n\ -If the third optional argument @qcode{\"all\"} is supplied, return a cell\n\ -array containing the list of all files that have the same name in the path.\n\ -If no files are found, return an empty cell array.\n\ -@seealso{file_in_loadpath, dir_in_loadpath, path}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} file_in_path (@var{path}, @var{file}) +@deftypefnx {} {} file_in_path (@var{path}, @var{file}, "all") +Return the absolute name of @var{file} if it can be found in @var{path}. + +The value of @var{path} should be a colon-separated list of directories in +the format described for @code{path}. If no file is found, return an empty +character string. For example: + +@example +@group +file_in_path (EXEC_PATH, "sh") + @result{} "/bin/sh" +@end group +@end example + +If the second argument is a cell array of strings, search each directory of +the path for element of the cell array and return the first that matches. + +If the third optional argument @qcode{"all"} is supplied, return a cell +array containing the list of all files that have the same name in the path. +If no files are found, return an empty cell array. +@seealso{file_in_loadpath, dir_in_loadpath, path} +@end deftypefn */) { int nargin = args.length (); @@ -714,15 +714,15 @@ } DEFUN (do_string_escapes, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} do_string_escapes (@var{string})\n\ -Convert escape sequences in @var{string} to the characters they represent.\n\ -\n\ -Escape sequences begin with a leading backslash\n\ -(@qcode{'@xbackslashchar{}'}) followed by 1--3 characters\n\ -(.e.g., @qcode{\"@xbackslashchar{}n\"} => newline).\n\ -@seealso{undo_string_escapes}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} do_string_escapes (@var{string}) +Convert escape sequences in @var{string} to the characters they represent. + +Escape sequences begin with a leading backslash +(@qcode{'@xbackslashchar{}'}) followed by 1--3 characters +(.e.g., @qcode{"@xbackslashchar{}n"} => newline). +@seealso{undo_string_escapes} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -829,35 +829,35 @@ } DEFUN (undo_string_escapes, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} undo_string_escapes (@var{s})\n\ -Convert special characters in strings back to their escaped forms.\n\ -\n\ -For example, the expression\n\ -\n\ -@example\n\ -bell = \"\\a\";\n\ -@end example\n\ -\n\ -@noindent\n\ -assigns the value of the alert character (control-g, ASCII code 7) to the\n\ -string variable @code{bell}. If this string is printed, the system will\n\ -ring the terminal bell (if it is possible). This is normally the desired\n\ -outcome. However, sometimes it is useful to be able to print the original\n\ -representation of the string, with the special characters replaced by their\n\ -escape sequences. For example,\n\ -\n\ -@example\n\ -@group\n\ -octave:13> undo_string_escapes (bell)\n\ -ans = \\a\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -replaces the unprintable alert character with its printable representation.\n\ -@seealso{do_string_escapes}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} undo_string_escapes (@var{s}) +Convert special characters in strings back to their escaped forms. + +For example, the expression + +@example +bell = "\a"; +@end example + +@noindent +assigns the value of the alert character (control-g, ASCII code 7) to the +string variable @code{bell}. If this string is printed, the system will +ring the terminal bell (if it is possible). This is normally the desired +outcome. However, sometimes it is useful to be able to print the original +representation of the string, with the special characters replaced by their +escape sequences. For example, + +@example +@group +octave:13> undo_string_escapes (bell) +ans = \a +@end group +@end example + +@noindent +replaces the unprintable alert character with its printable representation. +@seealso{do_string_escapes} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -890,11 +890,11 @@ */ DEFUN (is_absolute_filename, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} is_absolute_filename (@var{file})\n\ -Return true if @var{file} is an absolute filename.\n\ -@seealso{is_rooted_relative_filename, make_absolute_filename, isdir}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} is_absolute_filename (@var{file}) +Return true if @var{file} is an absolute filename. +@seealso{is_rooted_relative_filename, make_absolute_filename, isdir} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -911,11 +911,11 @@ */ DEFUN (is_rooted_relative_filename, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} is_rooted_relative_filename (@var{file})\n\ -Return true if @var{file} is a rooted-relative filename.\n\ -@seealso{is_absolute_filename, make_absolute_filename, isdir}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} is_rooted_relative_filename (@var{file}) +Return true if @var{file} is a rooted-relative filename. +@seealso{is_absolute_filename, make_absolute_filename, isdir} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -932,14 +932,14 @@ */ DEFUN (make_absolute_filename, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} make_absolute_filename (@var{file})\n\ -Return the full name of @var{file} beginning from the root of the file\n\ -system.\n\ -\n\ -No check is done for the existence of @var{file}.\n\ -@seealso{canonicalize_file_name, is_absolute_filename, is_rooted_relative_filename, isdir}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} make_absolute_filename (@var{file}) +Return the full name of @var{file} beginning from the root of the file +system. + +No check is done for the existence of @var{file}. +@seealso{canonicalize_file_name, is_absolute_filename, is_rooted_relative_filename, isdir} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -957,21 +957,21 @@ */ DEFUN (dir_in_loadpath, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} dir_in_loadpath (@var{dir})\n\ -@deftypefnx {} {} dir_in_loadpath (@var{dir}, \"all\")\n\ -Return the full name of the path element matching @var{dir}.\n\ -\n\ -The match is performed at the end of each path element. For example, if\n\ -@var{dir} is @qcode{\"foo/bar\"}, it matches the path element\n\ -@nospell{@qcode{\"/some/dir/foo/bar\"}}, but not\n\ -@nospell{@qcode{\"/some/dir/foo/bar/baz\"}}\n\ -@nospell{@qcode{\"/some/dir/allfoo/bar\"}}.\n\ -\n\ -If the optional second argument is supplied, return a cell array containing\n\ -all name matches rather than just the first.\n\ -@seealso{file_in_path, file_in_loadpath, path}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} dir_in_loadpath (@var{dir}) +@deftypefnx {} {} dir_in_loadpath (@var{dir}, "all") +Return the full name of the path element matching @var{dir}. + +The match is performed at the end of each path element. For example, if +@var{dir} is @qcode{"foo/bar"}, it matches the path element +@nospell{@qcode{"/some/dir/foo/bar"}}, but not +@nospell{@qcode{"/some/dir/foo/bar/baz"}} +@nospell{@qcode{"/some/dir/allfoo/bar"}}. + +If the optional second argument is supplied, return a cell array containing +all name matches rather than just the first. +@seealso{file_in_path, file_in_loadpath, path} +@end deftypefn */) { int nargin = args.length (); @@ -1007,16 +1007,16 @@ */ DEFUNX ("errno", Ferrno, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{err} =} errno ()\n\ -@deftypefnx {} {@var{err} =} errno (@var{val})\n\ -@deftypefnx {} {@var{err} =} errno (@var{name})\n\ -Return the current value of the system-dependent variable errno,\n\ -set its value to @var{val} and return the previous value, or return\n\ -the named error code given @var{name} as a character string, or -1\n\ -if @var{name} is not found.\n\ -@seealso{errno_list}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{err} =} errno () +@deftypefnx {} {@var{err} =} errno (@var{val}) +@deftypefnx {} {@var{err} =} errno (@var{name}) +Return the current value of the system-dependent variable errno, +set its value to @var{val} and return the previous value, or return +the named error code given @var{name} as a character string, or -1 +if @var{name} is not found. +@seealso{errno_list} +@end deftypefn */) { int nargin = args.length (); @@ -1062,11 +1062,11 @@ */ DEFUN (errno_list, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} errno_list ()\n\ -Return a structure containing the system-dependent errno values.\n\ -@seealso{errno}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} errno_list () +Return a structure containing the system-dependent errno values. +@seealso{errno} +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -1335,22 +1335,22 @@ } DEFUN (isindex, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isindex (@var{ind})\n\ -@deftypefnx {} {} isindex (@var{ind}, @var{n})\n\ -Return true if @var{ind} is a valid index.\n\ -\n\ -Valid indices are either positive integers (although possibly of real data\n\ -type), or logical arrays.\n\ -\n\ -If present, @var{n} specifies the maximum extent of the dimension to be\n\ -indexed. When possible the internal result is cached so that subsequent\n\ -indexing using @var{ind} will not perform the check again.\n\ -\n\ -Implementation Note: Strings are first converted to double values before the\n\ -checks for valid indices are made. Unless a string contains the NULL\n\ -character @nospell{\"@xbackslashchar{}0\"}, it will always be a valid index.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isindex (@var{ind}) +@deftypefnx {} {} isindex (@var{ind}, @var{n}) +Return true if @var{ind} is a valid index. + +Valid indices are either positive integers (although possibly of real data +type), or logical arrays. + +If present, @var{n} specifies the maximum extent of the dimension to be +indexed. When possible the internal result is cached so that subsequent +indexing using @var{ind} will not perform the check again. + +Implementation Note: Strings are first converted to double values before the +checks for valid indices are made. Unless a string contains the NULL +character @nospell{"@xbackslashchar{}0"}, it will always be a valid index. +@end deftypefn */) { int nargin = args.length (); @@ -1480,13 +1480,13 @@ } DEFUN (isstudent, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isstudent ()\n\ -Return true if running in the student edition of @sc{matlab}.\n\ -\n\ -@code{isstudent} always returns false in Octave.\n\ -@seealso{false}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isstudent () +Return true if running in the student edition of @sc{matlab}. + +@code{isstudent} always returns false in Octave. +@seealso{false} +@end deftypefn */) { if (args.length () != 0) print_usage ();
--- a/libinterp/corefcn/variables.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/corefcn/variables.cc Tue Jun 21 16:07:51 2016 -0400 @@ -336,21 +336,21 @@ } DEFUN (isglobal, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isglobal (@var{name})\n\ -Return true if @var{name} is a globally visible variable.\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -global x\n\ -isglobal (\"x\")\n\ - @result{} 1\n\ -@end group\n\ -@end example\n\ -@seealso{isvarname, exist}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isglobal (@var{name}) +Return true if @var{name} is a globally visible variable. + +For example: + +@example +@group +global x +isglobal ("x") + @result{} 1 +@end group +@end example +@seealso{isvarname, exist} +@end deftypefn */) { return do_isglobal (args); } @@ -519,77 +519,77 @@ } DEFUN (exist, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{c} =} exist (@var{name})\n\ -@deftypefnx {} {@var{c} =} exist (@var{name}, @var{type})\n\ -Check for the existence of @var{name} as a variable, function, file,\n\ -directory, or class.\n\ -\n\ -The return code @var{c} is one of\n\ -\n\ -@table @asis\n\ -@item 1\n\ -@var{name} is a variable.\n\ -\n\ -@item 2\n\ -@var{name} is an absolute filename, an ordinary file in Octave's\n\ -@code{path}, or (after appending @samp{.m}) a function file in Octave's\n\ -@code{path}.\n\ -\n\ -@item 3\n\ -@var{name} is a @samp{.oct} or @samp{.mex} file in Octave's @code{path}.\n\ -\n\ -@item 5\n\ -@var{name} is a built-in function.\n\ -\n\ -@item 7\n\ -@var{name} is a directory.\n\ -\n\ -@item 103\n\ -@var{name} is a function not associated with a file (entered on the command\n\ -line).\n\ -\n\ -@item 0\n\ -@var{name} does not exist.\n\ -@end table\n\ -\n\ -If the optional argument @var{type} is supplied, check only for symbols of\n\ -the specified type. Valid types are\n\ -\n\ -@table @asis\n\ -@item @qcode{\"var\"}\n\ -Check only for variables.\n\ -\n\ -@item @qcode{\"builtin\"}\n\ -Check only for built-in functions.\n\ -\n\ -@item @qcode{\"dir\"}\n\ -Check only for directories.\n\ -\n\ -@item @qcode{\"file\"}\n\ -Check only for files and directories.\n\ -\n\ -@item @qcode{\"class\"}\n\ -Check only for classes. (Note: This option is accepted, but not currently\n\ -implemented)\n\ -@end table\n\ -\n\ -If no type is given, and there are multiple possible matches for name,\n\ -@code{exist} will return a code according to the following priority list:\n\ -variable, built-in function, oct-file, directory, file, class.\n\ -\n\ -@code{exist} returns 2 if a regular file called @var{name} is present in\n\ -Octave's search path. If you want information about other types of files\n\ -not on the search path you should use some combination of the functions\n\ -@code{file_in_path} and @code{stat} instead.\n\ -\n\ -Programming Note: If @var{name} is implemented by a buggy .oct/.mex file,\n\ -calling @var{exist} may cause Octave to crash. To maintain high\n\ -performance, Octave trusts .oct/.mex files instead of @nospell{sandboxing}\n\ -them.\n\ -\n\ -@seealso{file_in_loadpath, file_in_path, dir_in_loadpath, stat}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{c} =} exist (@var{name}) +@deftypefnx {} {@var{c} =} exist (@var{name}, @var{type}) +Check for the existence of @var{name} as a variable, function, file, +directory, or class. + +The return code @var{c} is one of + +@table @asis +@item 1 +@var{name} is a variable. + +@item 2 +@var{name} is an absolute filename, an ordinary file in Octave's +@code{path}, or (after appending @samp{.m}) a function file in Octave's +@code{path}. + +@item 3 +@var{name} is a @samp{.oct} or @samp{.mex} file in Octave's @code{path}. + +@item 5 +@var{name} is a built-in function. + +@item 7 +@var{name} is a directory. + +@item 103 +@var{name} is a function not associated with a file (entered on the command +line). + +@item 0 +@var{name} does not exist. +@end table + +If the optional argument @var{type} is supplied, check only for symbols of +the specified type. Valid types are + +@table @asis +@item @qcode{"var"} +Check only for variables. + +@item @qcode{"builtin"} +Check only for built-in functions. + +@item @qcode{"dir"} +Check only for directories. + +@item @qcode{"file"} +Check only for files and directories. + +@item @qcode{"class"} +Check only for classes. (Note: This option is accepted, but not currently +implemented) +@end table + +If no type is given, and there are multiple possible matches for name, +@code{exist} will return a code according to the following priority list: +variable, built-in function, oct-file, directory, file, class. + +@code{exist} returns 2 if a regular file called @var{name} is present in +Octave's search path. If you want information about other types of files +not on the search path you should use some combination of the functions +@code{file_in_path} and @code{stat} instead. + +Programming Note: If @var{name} is implemented by a buggy .oct/.mex file, +calling @var{exist} may cause Octave to crash. To maintain high +performance, Octave trusts .oct/.mex files instead of @nospell{sandboxing} +them. + +@seealso{file_in_loadpath, file_in_path, dir_in_loadpath, stat} +@end deftypefn */) { int nargin = args.length (); @@ -1834,39 +1834,39 @@ } DEFUN (who, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} who\n\ -@deftypefnx {} {} who pattern @dots{}\n\ -@deftypefnx {} {} who option pattern @dots{}\n\ -@deftypefnx {} {C =} who (\"pattern\", @dots{})\n\ -List currently defined variables matching the given patterns.\n\ -\n\ -Valid pattern syntax is the same as described for the @code{clear} command.\n\ -If no patterns are supplied, all variables are listed.\n\ -\n\ -By default, only variables visible in the local scope are displayed.\n\ -\n\ -The following are valid options, but may not be combined.\n\ -\n\ -@table @code\n\ -@item global\n\ -List variables in the global scope rather than the current scope.\n\ -\n\ -@item -regexp\n\ -The patterns are considered to be regular expressions when matching the\n\ -variables to display. The same pattern syntax accepted by the @code{regexp}\n\ -function is used.\n\ -\n\ -@item -file\n\ -The next argument is treated as a filename. All variables found within the\n\ -specified file are listed. No patterns are accepted when reading variables\n\ -from a file.\n\ -@end table\n\ -\n\ -If called as a function, return a cell array of defined variable names\n\ -matching the given patterns.\n\ -@seealso{whos, isglobal, isvarname, exist, regexp}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} who +@deftypefnx {} {} who pattern @dots{} +@deftypefnx {} {} who option pattern @dots{} +@deftypefnx {} {C =} who ("pattern", @dots{}) +List currently defined variables matching the given patterns. + +Valid pattern syntax is the same as described for the @code{clear} command. +If no patterns are supplied, all variables are listed. + +By default, only variables visible in the local scope are displayed. + +The following are valid options, but may not be combined. + +@table @code +@item global +List variables in the global scope rather than the current scope. + +@item -regexp +The patterns are considered to be regular expressions when matching the +variables to display. The same pattern syntax accepted by the @code{regexp} +function is used. + +@item -file +The next argument is treated as a filename. All variables found within the +specified file are listed. No patterns are accepted when reading variables +from a file. +@end table + +If called as a function, return a cell array of defined variable names +matching the given patterns. +@seealso{whos, isglobal, isvarname, exist, regexp} +@end deftypefn */) { int argc = args.length () + 1; @@ -1876,68 +1876,68 @@ } DEFUN (whos, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} whos\n\ -@deftypefnx {} {} whos pattern @dots{}\n\ -@deftypefnx {} {} whos option pattern @dots{}\n\ -@deftypefnx {} {S =} whos (\"pattern\", @dots{})\n\ -Provide detailed information on currently defined variables matching the\n\ -given patterns.\n\ -\n\ -Options and pattern syntax are the same as for the @code{who} command.\n\ -\n\ -Extended information about each variable is summarized in a table with the\n\ -following default entries.\n\ -\n\ -@table @asis\n\ -@item Attr\n\ -Attributes of the listed variable. Possible attributes are:\n\ -\n\ -@table @asis\n\ -@item blank\n\ -Variable in local scope\n\ -\n\ -@item @code{a}\n\ -Automatic variable. An automatic variable is one created by the\n\ -interpreter, for example @code{argn}.\n\ -\n\ -@item @code{c}\n\ -Variable of complex type.\n\ -\n\ -@item @code{f}\n\ -Formal parameter (function argument).\n\ -\n\ -@item @code{g}\n\ -Variable with global scope.\n\ -\n\ -@item @code{p}\n\ -Persistent variable.\n\ -@end table\n\ -\n\ -@item Name\n\ -The name of the variable.\n\ -\n\ -@item Size\n\ -The logical size of the variable. A scalar is 1x1, a vector is\n\ -@nospell{1xN} or @nospell{Nx1}, a 2-D matrix is @nospell{MxN}.\n\ -\n\ -@item Bytes\n\ -The amount of memory currently used to store the variable.\n\ -\n\ -@item Class\n\ -The class of the variable. Examples include double, single, char, uint16,\n\ -cell, and struct.\n\ -@end table\n\ -\n\ -The table can be customized to display more or less information through\n\ -the function @code{whos_line_format}.\n\ -\n\ -If @code{whos} is called as a function, return a struct array of defined\n\ -variable names matching the given patterns. Fields in the structure\n\ -describing each variable are: name, size, bytes, class, global, sparse,\n\ -complex, nesting, persistent.\n\ -@seealso{who, whos_line_format}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} whos +@deftypefnx {} {} whos pattern @dots{} +@deftypefnx {} {} whos option pattern @dots{} +@deftypefnx {} {S =} whos ("pattern", @dots{}) +Provide detailed information on currently defined variables matching the +given patterns. + +Options and pattern syntax are the same as for the @code{who} command. + +Extended information about each variable is summarized in a table with the +following default entries. + +@table @asis +@item Attr +Attributes of the listed variable. Possible attributes are: + +@table @asis +@item blank +Variable in local scope + +@item @code{a} +Automatic variable. An automatic variable is one created by the +interpreter, for example @code{argn}. + +@item @code{c} +Variable of complex type. + +@item @code{f} +Formal parameter (function argument). + +@item @code{g} +Variable with global scope. + +@item @code{p} +Persistent variable. +@end table + +@item Name +The name of the variable. + +@item Size +The logical size of the variable. A scalar is 1x1, a vector is +@nospell{1xN} or @nospell{Nx1}, a 2-D matrix is @nospell{MxN}. + +@item Bytes +The amount of memory currently used to store the variable. + +@item Class +The class of the variable. Examples include double, single, char, uint16, +cell, and struct. +@end table + +The table can be customized to display more or less information through +the function @code{whos_line_format}. + +If @code{whos} is called as a function, return a struct array of defined +variable names matching the given patterns. Fields in the structure +describing each variable are: name, size, bytes, class, global, sparse, +complex, nesting, persistent. +@seealso{who, whos_line_format} +@end deftypefn */) { int argc = args.length () + 1; @@ -2026,11 +2026,11 @@ } DEFUN (mlock, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} mlock ()\n\ -Lock the current function into memory so that it can't be cleared.\n\ -@seealso{munlock, mislocked, persistent}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} mlock () +Lock the current function into memory so that it can't be cleared. +@seealso{munlock, mislocked, persistent} +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -2046,14 +2046,14 @@ } DEFUN (munlock, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} munlock ()\n\ -@deftypefnx {} {} munlock (@var{fcn})\n\ -Unlock the named function @var{fcn}.\n\ -\n\ -If no function is named then unlock the current function.\n\ -@seealso{mlock, mislocked, persistent}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} munlock () +@deftypefnx {} {} munlock (@var{fcn}) +Unlock the named function @var{fcn}. + +If no function is named then unlock the current function. +@seealso{mlock, mislocked, persistent} +@end deftypefn */) { int nargin = args.length (); @@ -2081,14 +2081,14 @@ DEFUN (mislocked, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} mislocked ()\n\ -@deftypefnx {} {} mislocked (@var{fcn})\n\ -Return true if the named function @var{fcn} is locked.\n\ -\n\ -If no function is named then return true if the current function is locked.\n\ -@seealso{mlock, munlock, persistent}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} mislocked () +@deftypefnx {} {} mislocked (@var{fcn}) +Return true if the named function @var{fcn} is locked. + +If no function is named then return true if the current function is locked. +@seealso{mlock, munlock, persistent} +@end deftypefn */) { int nargin = args.length (); @@ -2337,78 +2337,78 @@ while (0) DEFUN (clear, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} clear [options] pattern @dots{}\n\ -Delete the names matching the given patterns from the symbol table.\n\ -\n\ -The pattern may contain the following special characters:\n\ -\n\ -@table @code\n\ -@item ?\n\ -Match any single character.\n\ -\n\ -@item *\n\ -Match zero or more characters.\n\ -\n\ -@item [ @var{list} ]\n\ -Match the list of characters specified by @var{list}. If the first\n\ -character is @code{!} or @code{^}, match all characters except those\n\ -specified by @var{list}. For example, the pattern @samp{[a-zA-Z]} will\n\ -match all lowercase and uppercase alphabetic characters.\n\ -@end table\n\ -\n\ -For example, the command\n\ -\n\ -@example\n\ -clear foo b*r\n\ -@end example\n\ -\n\ -@noindent\n\ -clears the name @code{foo} and all names that begin with the letter\n\ -@code{b} and end with the letter @code{r}.\n\ -\n\ -If @code{clear} is called without any arguments, all user-defined\n\ -variables (local and global) are cleared from the symbol table.\n\ -\n\ -If @code{clear} is called with at least one argument, only the visible\n\ -names matching the arguments are cleared. For example, suppose you have\n\ -defined a function @code{foo}, and then hidden it by performing the\n\ -assignment @code{foo = 2}. Executing the command @kbd{clear foo} once\n\ -will clear the variable definition and restore the definition of\n\ -@code{foo} as a function. Executing @kbd{clear foo} a second time will\n\ -clear the function definition.\n\ -\n\ -The following options are available in both long and short form\n\ -\n\ -@table @code\n\ -@item -all, -a\n\ -Clear all local and global user-defined variables and all functions from the\n\ -symbol table.\n\ -\n\ -@item -exclusive, -x\n\ -Clear the variables that don't match the following pattern.\n\ -\n\ -@item -functions, -f\n\ -Clear the function names and the built-in symbols names.\n\ -\n\ -@item -global, -g\n\ -Clear global symbol names.\n\ -\n\ -@item -variables, -v\n\ -Clear local variable names.\n\ -\n\ -@item -classes, -c\n\ -Clears the class structure table and clears all objects.\n\ -\n\ -@item -regexp, -r\n\ -The arguments are treated as regular expressions as any variables that\n\ -match will be cleared.\n\ -@end table\n\ -\n\ -With the exception of @code{exclusive}, all long options can be used\n\ -without the dash as well.\n\ -@seealso{who, whos, exist}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} clear [options] pattern @dots{} +Delete the names matching the given patterns from the symbol table. + +The pattern may contain the following special characters: + +@table @code +@item ? +Match any single character. + +@item * +Match zero or more characters. + +@item [ @var{list} ] +Match the list of characters specified by @var{list}. If the first +character is @code{!} or @code{^}, match all characters except those +specified by @var{list}. For example, the pattern @samp{[a-zA-Z]} will +match all lowercase and uppercase alphabetic characters. +@end table + +For example, the command + +@example +clear foo b*r +@end example + +@noindent +clears the name @code{foo} and all names that begin with the letter +@code{b} and end with the letter @code{r}. + +If @code{clear} is called without any arguments, all user-defined +variables (local and global) are cleared from the symbol table. + +If @code{clear} is called with at least one argument, only the visible +names matching the arguments are cleared. For example, suppose you have +defined a function @code{foo}, and then hidden it by performing the +assignment @code{foo = 2}. Executing the command @kbd{clear foo} once +will clear the variable definition and restore the definition of +@code{foo} as a function. Executing @kbd{clear foo} a second time will +clear the function definition. + +The following options are available in both long and short form + +@table @code +@item -all, -a +Clear all local and global user-defined variables and all functions from the +symbol table. + +@item -exclusive, -x +Clear the variables that don't match the following pattern. + +@item -functions, -f +Clear the function names and the built-in symbols names. + +@item -global, -g +Clear global symbol names. + +@item -variables, -v +Clear local variable names. + +@item -classes, -c +Clears the class structure table and clears all objects. + +@item -regexp, -r +The arguments are treated as regular expressions as any variables that +match will be cleared. +@end table + +With the exception of @code{exclusive}, all long options can be used +without the dash as well. +@seealso{who, whos, exist} +@end deftypefn */) { int argc = args.length () + 1; @@ -2538,78 +2538,78 @@ } DEFUN (whos_line_format, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} whos_line_format ()\n\ -@deftypefnx {} {@var{old_val} =} whos_line_format (@var{new_val})\n\ -@deftypefnx {} {} whos_line_format (@var{new_val}, \"local\")\n\ -Query or set the format string used by the command @code{whos}.\n\ -\n\ -A full format string is:\n\ -@c Set example in small font to prevent overfull line\n\ -\n\ -@smallexample\n\ -%[modifier]<command>[:width[:left-min[:balance]]];\n\ -@end smallexample\n\ -\n\ -The following command sequences are available:\n\ -\n\ -@table @code\n\ -@item %a\n\ -Prints attributes of variables (g=global, p=persistent, f=formal parameter,\n\ -a=automatic variable).\n\ -\n\ -@item %b\n\ -Prints number of bytes occupied by variables.\n\ -\n\ -@item %c\n\ -Prints class names of variables.\n\ -\n\ -@item %e\n\ -Prints elements held by variables.\n\ -\n\ -@item %n\n\ -Prints variable names.\n\ -\n\ -@item %s\n\ -Prints dimensions of variables.\n\ -\n\ -@item %t\n\ -Prints type names of variables.\n\ -@end table\n\ -\n\ -Every command may also have an alignment modifier:\n\ -\n\ -@table @code\n\ -@item l\n\ -Left alignment.\n\ -\n\ -@item r\n\ -Right alignment (default).\n\ -\n\ -@item c\n\ -Column-aligned (only applicable to command %s).\n\ -@end table\n\ -\n\ -The @code{width} parameter is a positive integer specifying the minimum\n\ -number of columns used for printing. No maximum is needed as the field will\n\ -auto-expand as required.\n\ -\n\ -The parameters @code{left-min} and @code{balance} are only available when\n\ -the column-aligned modifier is used with the command @samp{%s}.\n\ -@code{balance} specifies the column number within the field width which\n\ -will be aligned between entries. Numbering starts from 0 which indicates\n\ -the leftmost column. @code{left-min} specifies the minimum field width to\n\ -the left of the specified balance column.\n\ -\n\ -The default format is:\n\ -\n\ -@qcode{\" %a:4; %ln:6; %cs:16:6:1; %rb:12; %lc:-1;@xbackslashchar{}n\"}\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{whos}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} whos_line_format () +@deftypefnx {} {@var{old_val} =} whos_line_format (@var{new_val}) +@deftypefnx {} {} whos_line_format (@var{new_val}, "local") +Query or set the format string used by the command @code{whos}. + +A full format string is: +@c Set example in small font to prevent overfull line + +@smallexample +%[modifier]<command>[:width[:left-min[:balance]]]; +@end smallexample + +The following command sequences are available: + +@table @code +@item %a +Prints attributes of variables (g=global, p=persistent, f=formal parameter, +a=automatic variable). + +@item %b +Prints number of bytes occupied by variables. + +@item %c +Prints class names of variables. + +@item %e +Prints elements held by variables. + +@item %n +Prints variable names. + +@item %s +Prints dimensions of variables. + +@item %t +Prints type names of variables. +@end table + +Every command may also have an alignment modifier: + +@table @code +@item l +Left alignment. + +@item r +Right alignment (default). + +@item c +Column-aligned (only applicable to command %s). +@end table + +The @code{width} parameter is a positive integer specifying the minimum +number of columns used for printing. No maximum is needed as the field will +auto-expand as required. + +The parameters @code{left-min} and @code{balance} are only available when +the column-aligned modifier is used with the command @samp{%s}. +@code{balance} specifies the column number within the field width which +will be aligned between entries. Numbering starts from 0 which indicates +the leftmost column. @code{left-min} specifies the minimum field width to +the left of the specified balance column. + +The default format is: + +@qcode{" %a:4; %ln:6; %cs:16:6:1; %rb:12; %lc:-1;@xbackslashchar{}n"} + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{whos} +@end deftypefn */) { return SET_INTERNAL_VARIABLE (whos_line_format); } @@ -2617,18 +2617,18 @@ static std::string Vmissing_function_hook = "__unimplemented__"; DEFUN (missing_function_hook, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} missing_function_hook ()\n\ -@deftypefnx {} {@var{old_val} =} missing_function_hook (@var{new_val})\n\ -@deftypefnx {} {} missing_function_hook (@var{new_val}, \"local\")\n\ -Query or set the internal variable that specifies the function to call when\n\ -an unknown identifier is requested.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{missing_component_hook}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} missing_function_hook () +@deftypefnx {} {@var{old_val} =} missing_function_hook (@var{new_val}) +@deftypefnx {} {} missing_function_hook (@var{new_val}, "local") +Query or set the internal variable that specifies the function to call when +an unknown identifier is requested. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{missing_component_hook} +@end deftypefn */) { return SET_INTERNAL_VARIABLE (missing_function_hook); } @@ -2657,10 +2657,10 @@ } DEFUN (__varval__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __varval__ (@var{name})\n\ -Return the value of the variable @var{name} directly from the symbol table.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __varval__ (@var{name}) +Return the value of the variable @var{name} directly from the symbol table. +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -2673,32 +2673,32 @@ static std::string Vmissing_component_hook; DEFUN (missing_component_hook, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} missing_component_hook ()\n\ -@deftypefnx {} {@var{old_val} =} missing_component_hook (@var{new_val})\n\ -@deftypefnx {} {} missing_component_hook (@var{new_val}, \"local\")\n\ -Query or set the internal variable that specifies the function to call when\n\ -a component of Octave is missing.\n\ -\n\ -This can be useful for packagers that may split the Octave installation into\n\ -multiple sub-packages, for example, to provide a hint to users for how to\n\ -install the missing components.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -\n\ -The hook function is expected to be of the form\n\ -\n\ -@example\n\ -@var{fcn} (@var{component})\n\ -@end example\n\ -\n\ -Octave will call @var{fcn} with the name of the function that requires the\n\ -component and a string describing the missing component. The hook function\n\ -should return an error message to be displayed.\n\ -@seealso{missing_function_hook}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} missing_component_hook () +@deftypefnx {} {@var{old_val} =} missing_component_hook (@var{new_val}) +@deftypefnx {} {} missing_component_hook (@var{new_val}, "local") +Query or set the internal variable that specifies the function to call when +a component of Octave is missing. + +This can be useful for packagers that may split the Octave installation into +multiple sub-packages, for example, to provide a hint to users for how to +install the missing components. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. + +The hook function is expected to be of the form + +@example +@var{fcn} (@var{component}) +@end example + +Octave will call @var{fcn} with the name of the function that requires the +component and a string describing the missing component. The hook function +should return an error message to be displayed. +@seealso{missing_function_hook} +@end deftypefn */) { return SET_INTERNAL_VARIABLE (missing_component_hook); }
--- a/libinterp/dldfcn/__delaunayn__.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/dldfcn/__delaunayn__.cc Tue Jun 21 16:07:51 2016 -0400 @@ -85,11 +85,11 @@ #endif DEFUN_DLD (__delaunayn__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{T} =} __delaunayn__ (@var{pts})\n\ -@deftypefnx {} {@var{T} =} __delaunayn__ (@var{pts}, @var{options})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{T} =} __delaunayn__ (@var{pts}) +@deftypefnx {} {@var{T} =} __delaunayn__ (@var{pts}, @var{options}) +Undocumented internal function. +@end deftypefn */) { #if defined (HAVE_QHULL)
--- a/libinterp/dldfcn/__eigs__.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/dldfcn/__eigs__.cc Tue Jun 21 16:07:51 2016 -0400 @@ -125,29 +125,29 @@ #endif DEFUN_DLD (__eigs__, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{d} =} __eigs__ (@var{A})\n\ -@deftypefnx {} {@var{d} =} __eigs__ (@var{A}, @var{k})\n\ -@deftypefnx {} {@var{d} =} __eigs__ (@var{A}, @var{k}, @var{sigma})\n\ -@deftypefnx {} {@var{d} =} __eigs__ (@var{A}, @var{k}, @var{sigma}, @var{opts})\n\ -@deftypefnx {} {@var{d} =} __eigs__ (@var{A}, @var{B})\n\ -@deftypefnx {} {@var{d} =} __eigs__ (@var{A}, @var{B}, @var{k})\n\ -@deftypefnx {} {@var{d} =} __eigs__ (@var{A}, @var{B}, @var{k}, @var{sigma})\n\ -@deftypefnx {} {@var{d} =} __eigs__ (@var{A}, @var{B}, @var{k}, @var{sigma}, @var{opts})\n\ -@deftypefnx {} {@var{d} =} __eigs__ (@var{af}, @var{n})\n\ -@deftypefnx {} {@var{d} =} __eigs__ (@var{af}, @var{n}, @var{B})\n\ -@deftypefnx {} {@var{d} =} __eigs__ (@var{af}, @var{n}, @var{k})\n\ -@deftypefnx {} {@var{d} =} __eigs__ (@var{af}, @var{n}, @var{B}, @var{k})\n\ -@deftypefnx {} {@var{d} =} __eigs__ (@var{af}, @var{n}, @var{k}, @var{sigma})\n\ -@deftypefnx {} {@var{d} =} __eigs__ (@var{af}, @var{n}, @var{B}, @var{k}, @var{sigma})\n\ -@deftypefnx {} {@var{d} =} __eigs__ (@var{af}, @var{n}, @var{k}, @var{sigma}, @var{opts})\n\ -@deftypefnx {} {@var{d} =} __eigs__ (@var{af}, @var{n}, @var{B}, @var{k}, @var{sigma}, @var{opts})\n\ -@deftypefnx {} {[@var{V}, @var{d}] =} __eigs__ (@var{A}, @dots{})\n\ -@deftypefnx {} {[@var{V}, @var{d}] =} __eigs__ (@var{af}, @var{n}, @dots{})\n\ -@deftypefnx {} {[@var{V}, @var{d}, @var{flag}] =} __eigs__ (@var{A}, @dots{})\n\ -@deftypefnx {} {[@var{V}, @var{d}, @var{flag}] =} __eigs__ (@var{af}, @var{n}, @dots{})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{d} =} __eigs__ (@var{A}) +@deftypefnx {} {@var{d} =} __eigs__ (@var{A}, @var{k}) +@deftypefnx {} {@var{d} =} __eigs__ (@var{A}, @var{k}, @var{sigma}) +@deftypefnx {} {@var{d} =} __eigs__ (@var{A}, @var{k}, @var{sigma}, @var{opts}) +@deftypefnx {} {@var{d} =} __eigs__ (@var{A}, @var{B}) +@deftypefnx {} {@var{d} =} __eigs__ (@var{A}, @var{B}, @var{k}) +@deftypefnx {} {@var{d} =} __eigs__ (@var{A}, @var{B}, @var{k}, @var{sigma}) +@deftypefnx {} {@var{d} =} __eigs__ (@var{A}, @var{B}, @var{k}, @var{sigma}, @var{opts}) +@deftypefnx {} {@var{d} =} __eigs__ (@var{af}, @var{n}) +@deftypefnx {} {@var{d} =} __eigs__ (@var{af}, @var{n}, @var{B}) +@deftypefnx {} {@var{d} =} __eigs__ (@var{af}, @var{n}, @var{k}) +@deftypefnx {} {@var{d} =} __eigs__ (@var{af}, @var{n}, @var{B}, @var{k}) +@deftypefnx {} {@var{d} =} __eigs__ (@var{af}, @var{n}, @var{k}, @var{sigma}) +@deftypefnx {} {@var{d} =} __eigs__ (@var{af}, @var{n}, @var{B}, @var{k}, @var{sigma}) +@deftypefnx {} {@var{d} =} __eigs__ (@var{af}, @var{n}, @var{k}, @var{sigma}, @var{opts}) +@deftypefnx {} {@var{d} =} __eigs__ (@var{af}, @var{n}, @var{B}, @var{k}, @var{sigma}, @var{opts}) +@deftypefnx {} {[@var{V}, @var{d}] =} __eigs__ (@var{A}, @dots{}) +@deftypefnx {} {[@var{V}, @var{d}] =} __eigs__ (@var{af}, @var{n}, @dots{}) +@deftypefnx {} {[@var{V}, @var{d}, @var{flag}] =} __eigs__ (@var{A}, @dots{}) +@deftypefnx {} {[@var{V}, @var{d}, @var{flag}] =} __eigs__ (@var{af}, @var{n}, @dots{}) +Undocumented internal function. +@end deftypefn */) { #if defined (HAVE_ARPACK)
--- a/libinterp/dldfcn/__fltk_uigetfile__.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/dldfcn/__fltk_uigetfile__.cc Tue Jun 21 16:07:51 2016 -0400 @@ -46,10 +46,10 @@ #include "file-ops.h" DEFUN_DLD (__fltk_uigetfile__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __fltk_uigetfile__ (@dots{})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __fltk_uigetfile__ (@dots{}) +Undocumented internal function. +@end deftypefn */) { #if defined (HAVE_FLTK)
--- a/libinterp/dldfcn/__glpk__.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/dldfcn/__glpk__.cc Tue Jun 21 16:07:51 2016 -0400 @@ -327,10 +327,10 @@ while (0) DEFUN_DLD (__glpk__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{values}] =} __glpk__ (@var{args})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{values}] =} __glpk__ (@var{args}) +Undocumented internal function. +@end deftypefn */) { #if defined (HAVE_GLPK)
--- a/libinterp/dldfcn/__init_fltk__.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/dldfcn/__init_fltk__.cc Tue Jun 21 16:07:51 2016 -0400 @@ -2391,10 +2391,10 @@ #endif DEFUN_DLD (__fltk_check__, , , - "-*- texinfo -*-\n\ -@deftypefn {} {} __fltk_check__ ()\n\ -Undocumented internal function. Calls Fl::check ()\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __fltk_check__ () +Undocumented internal function. Calls Fl::check () +@end deftypefn */) { #if defined (HAVE_FLTK) Fl::check (); @@ -2411,10 +2411,10 @@ // Initialize the fltk graphics toolkit. DEFUN_DLD (__init_fltk__, , , - "-*- texinfo -*-\n\ -@deftypefn {} {} __init_fltk__ ()\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __init_fltk__ () +Undocumented internal function. +@end deftypefn */) { #if defined (HAVE_FLTK) if (! display_info::display_available ())
--- a/libinterp/dldfcn/__init_gnuplot__.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/dldfcn/__init_gnuplot__.cc Tue Jun 21 16:07:51 2016 -0400 @@ -207,7 +207,11 @@ // Initialize the gnuplot graphics toolkit. -DEFUN_DLD (__init_gnuplot__, , , "") +DEFUN_DLD (__init_gnuplot__, , , + doc: /* -*- texinfo -*- +@deftypefn {} {} __init_gnuplot__ () +Undocumented internal function. +@end deftypefn */) { octave_value retval; @@ -227,10 +231,10 @@ } DEFUN_DLD (__have_gnuplot__, , , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{gnuplot_available} =} __have_gnuplot__ ()\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{gnuplot_available} =} __have_gnuplot__ () +Undocumented internal function. +@end deftypefn */) { octave_value retval;
--- a/libinterp/dldfcn/__osmesa_print__.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/dldfcn/__osmesa_print__.cc Tue Jun 21 16:07:51 2016 -0400 @@ -54,36 +54,36 @@ #endif DEFUN_DLD(__osmesa_print__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __osmesa_print__ (@var{h}, @var{file}, @var{term})\n\ -@deftypefnx {} {@var{img} =} __osmesa_print__ (@var{h})\n\ -Print figure @var{h} using OSMesa and gl2ps for vector formats.\n\ -\n\ -This is a private internal function.\n\ -\n\ -The first method calls gl2ps with the appropriate @var{term} and writes\n\ -the output of gl2ps to @var{file}. If the first character of @var{file}\n\ -is @qcode{|}, then a process is started and the output of gl2ps is piped\n\ -to it.\n\ -\n\ -Valid options for @var{term}, which can be concatenated in one string, are:\n\ -\n\ -@table @asis\n\ -@item @qcode{eps}, @qcode{pdf}, @qcode{ps}, @qcode{svg}, @qcode{pgf}, @qcode{tex}\n\ -Select output format.\n\ -\n\ -@item @qcode{is2D}\n\ -Use GL2PS_SIMPLE_SORT instead of GL2PS_BSP_SORT as Z-depth sorting\n\ -algorithm.\n\ -\n\ -@item @qcode{notext}\n\ -Don't render text.\n\ -@end table\n\ -\n\ -The second method doesn't use gl2ps and returns a RGB image in @var{img}\n\ -instead.\n\ -\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __osmesa_print__ (@var{h}, @var{file}, @var{term}) +@deftypefnx {} {@var{img} =} __osmesa_print__ (@var{h}) +Print figure @var{h} using OSMesa and gl2ps for vector formats. + +This is a private internal function. + +The first method calls gl2ps with the appropriate @var{term} and writes +the output of gl2ps to @var{file}. If the first character of @var{file} +is @qcode{|}, then a process is started and the output of gl2ps is piped +to it. + +Valid options for @var{term}, which can be concatenated in one string, are: + +@table @asis +@item @qcode{eps}, @qcode{pdf}, @qcode{ps}, @qcode{svg}, @qcode{pgf}, @qcode{tex} +Select output format. + +@item @qcode{is2D} +Use GL2PS_SIMPLE_SORT instead of GL2PS_BSP_SORT as Z-depth sorting +algorithm. + +@item @qcode{notext} +Don't render text. +@end table + +The second method doesn't use gl2ps and returns a RGB image in @var{img} +instead. + +@end deftypefn */) { #if defined (HAVE_OSMESA)
--- a/libinterp/dldfcn/__voronoi__.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/dldfcn/__voronoi__.cc Tue Jun 21 16:07:51 2016 -0400 @@ -79,12 +79,12 @@ #endif DEFUN_DLD (__voronoi__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{C}, @var{F} =} __voronoi__ (@var{caller}, @var{pts})\n\ -@deftypefnx {} {@var{C}, @var{F} =} __voronoi__ (@var{caller}, @var{pts}, @var{options})\n\ -@deftypefnx {} {@var{C}, @var{F}, @var{Inf_Pts} =} __voronoi__ (@dots{})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{C}, @var{F} =} __voronoi__ (@var{caller}, @var{pts}) +@deftypefnx {} {@var{C}, @var{F} =} __voronoi__ (@var{caller}, @var{pts}, @var{options}) +@deftypefnx {} {@var{C}, @var{F}, @var{Inf_Pts} =} __voronoi__ (@dots{}) +Undocumented internal function. +@end deftypefn */) { #if defined (HAVE_QHULL)
--- a/libinterp/dldfcn/amd.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/dldfcn/amd.cc Tue Jun 21 16:07:51 2016 -0400 @@ -52,38 +52,38 @@ #endif DEFUN_DLD (amd, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{p} =} amd (@var{S})\n\ -@deftypefnx {} {@var{p} =} amd (@var{S}, @var{opts})\n\ -\n\ -Return the approximate minimum degree permutation of a matrix.\n\ -\n\ -This is a permutation such that the Cholesky@tie{}factorization of\n\ -@code{@var{S} (@var{p}, @var{p})} tends to be sparser than the\n\ -Cholesky@tie{}factorization of @var{S} itself. @code{amd} is typically\n\ -faster than @code{symamd} but serves a similar purpose.\n\ -\n\ -The optional parameter @var{opts} is a structure that controls the behavior\n\ -of @code{amd}. The fields of the structure are\n\ -\n\ -@table @asis\n\ -@item @var{opts}.dense\n\ -Determines what @code{amd} considers to be a dense row or column of the\n\ -input matrix. Rows or columns with more than @code{max (16, (dense *\n\ -sqrt (@var{n})))} entries, where @var{n} is the order of the matrix @var{S},\n\ -are ignored by @code{amd} during the calculation of the permutation.\n\ -The value of dense must be a positive scalar and the default value is 10.0\n\ -\n\ -@item @var{opts}.aggressive\n\ -If this value is a nonzero scalar, then @code{amd} performs aggressive\n\ -absorption. The default is not to perform aggressive absorption.\n\ -@end table\n\ -\n\ -The author of the code itself is Timothy A. Davis\n\ -@email{davis@@cise.ufl.edu}, University of Florida\n\ -(see @url{http://www.cise.ufl.edu/research/sparse/amd}).\n\ -@seealso{symamd, colamd}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{p} =} amd (@var{S}) +@deftypefnx {} {@var{p} =} amd (@var{S}, @var{opts}) + +Return the approximate minimum degree permutation of a matrix. + +This is a permutation such that the Cholesky@tie{}factorization of +@code{@var{S} (@var{p}, @var{p})} tends to be sparser than the +Cholesky@tie{}factorization of @var{S} itself. @code{amd} is typically +faster than @code{symamd} but serves a similar purpose. + +The optional parameter @var{opts} is a structure that controls the behavior +of @code{amd}. The fields of the structure are + +@table @asis +@item @var{opts}.dense +Determines what @code{amd} considers to be a dense row or column of the +input matrix. Rows or columns with more than @code{max (16, (dense * +sqrt (@var{n})))} entries, where @var{n} is the order of the matrix @var{S}, +are ignored by @code{amd} during the calculation of the permutation. +The value of dense must be a positive scalar and the default value is 10.0 + +@item @var{opts}.aggressive +If this value is a nonzero scalar, then @code{amd} performs aggressive +absorption. The default is not to perform aggressive absorption. +@end table + +The author of the code itself is Timothy A. Davis +@email{davis@@cise.ufl.edu}, University of Florida +(see @url{http://www.cise.ufl.edu/research/sparse/amd}). +@seealso{symamd, colamd} +@end deftypefn */) { #if defined (HAVE_AMD)
--- a/libinterp/dldfcn/audiodevinfo.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/dldfcn/audiodevinfo.cc Tue Jun 21 16:07:51 2016 -0400 @@ -66,39 +66,39 @@ #endif DEFUN_DLD (audiodevinfo, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{devinfo} =} audiodevinfo ()\n\ -\n\ -@deftypefnx {} {@var{devs} =} audiodevinfo (@var{io})\n\ -@deftypefnx {} {@var{name} =} audiodevinfo (@var{io}, @var{id})\n\ -@deftypefnx {} {@var{id} =} audiodevinfo (@var{io}, @var{name})\n\ -@deftypefnx {} {@var{id} =} audiodevinfo (@var{io}, @var{rate}, @var{bits}, @var{chans})\n\ -\n\ -@deftypefnx {} {@var{supports} =} audiodevinfo (@var{io}, @var{id}, @var{rate}, @var{bits}, @var{chans})\n\ -\n\ -Return a structure describing the available audio input and output devices.\n\ -\n\ -The @var{devinfo} structure has two fields @qcode{\"input\"} and\n\ -@qcode{\"output\"}. The value of each field is a structure array with\n\ -fields @qcode{\"Name\"}, @nospell{\"DriverVersion\"} and @qcode{\"ID\"}\n\ -describing an audio device.\n\ -\n\ -If the optional argument @var{io} is 1, return information about input\n\ -devices only. If it is 0, return information about output devices only.\n\ -\n\ -If the optional argument @var{id} is provided, return information about\n\ -the corresponding device.\n\ -\n\ -If the optional argument @var{name} is provided, return the id of the\n\ -named device.\n\ -\n\ -Given a sampling rate, bits per sample, and number of channels for an input\n\ -or output device, return the ID of the first device that supports playback\n\ -or recording using the specified parameters.\n\ -\n\ -If also given a device ID, return true if the device supports playback or\n\ -recording using those parameters.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{devinfo} =} audiodevinfo () + +@deftypefnx {} {@var{devs} =} audiodevinfo (@var{io}) +@deftypefnx {} {@var{name} =} audiodevinfo (@var{io}, @var{id}) +@deftypefnx {} {@var{id} =} audiodevinfo (@var{io}, @var{name}) +@deftypefnx {} {@var{id} =} audiodevinfo (@var{io}, @var{rate}, @var{bits}, @var{chans}) + +@deftypefnx {} {@var{supports} =} audiodevinfo (@var{io}, @var{id}, @var{rate}, @var{bits}, @var{chans}) + +Return a structure describing the available audio input and output devices. + +The @var{devinfo} structure has two fields @qcode{"input"} and +@qcode{"output"}. The value of each field is a structure array with +fields @qcode{"Name"}, @nospell{"DriverVersion"} and @qcode{"ID"} +describing an audio device. + +If the optional argument @var{io} is 1, return information about input +devices only. If it is 0, return information about output devices only. + +If the optional argument @var{id} is provided, return information about +the corresponding device. + +If the optional argument @var{name} is provided, return the id of the +named device. + +Given a sampling rate, bits per sample, and number of channels for an input +or output device, return the ID of the first device that supports playback +or recording using the specified parameters. + +If also given a device ID, return true if the device supports playback or +recording using those parameters. +@end deftypefn */) { #if defined (HAVE_PORTAUDIO) @@ -1802,12 +1802,12 @@ #endif DEFUN_DLD (__recorder_audiorecorder__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{recorder} =} __recorder_audiorecorder__ (@var{fs}, @var{nbits}, @var{channels})\n\ -@deftypefnx {} {@var{recorder} =} __recorder_audiorecorder__ (@var{fs}, @var{nbits}, @var{channels}, @var{id})\n\ -@deftypefnx {} {@var{recorder} =} __recorder_audiorecorder__ (@var{fcn}, @dots{})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{recorder} =} __recorder_audiorecorder__ (@var{fs}, @var{nbits}, @var{channels}) +@deftypefnx {} {@var{recorder} =} __recorder_audiorecorder__ (@var{fs}, @var{nbits}, @var{channels}, @var{id}) +@deftypefnx {} {@var{recorder} =} __recorder_audiorecorder__ (@var{fcn}, @dots{}) +Undocumented internal function. +@end deftypefn */) { octave_value retval; @@ -1870,10 +1870,10 @@ #endif DEFUN_DLD (__recorder_getaudiodata__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{data}} __recorder_getaudiodata__ (@var{recorder})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{data}} __recorder_getaudiodata__ (@var{recorder}) +Undocumented internal function. +@end deftypefn */) { octave_value retval; #if ! defined (HAVE_PORTAUDIO) @@ -1888,10 +1888,10 @@ } DEFUN_DLD (__recorder_get_channels__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{n} =} __recorder_get_channels__ (@var{recorder})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{n} =} __recorder_get_channels__ (@var{recorder}) +Undocumented internal function. +@end deftypefn */) { octave_value retval; #if ! defined (HAVE_PORTAUDIO) @@ -1906,10 +1906,10 @@ } DEFUN_DLD (__recorder_get_fs__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{fs} =} __recorder_get_fs__ (@var{recorder})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{fs} =} __recorder_get_fs__ (@var{recorder}) +Undocumented internal function. +@end deftypefn */) { octave_value retval; #if ! defined (HAVE_PORTAUDIO) @@ -1924,10 +1924,10 @@ } DEFUN_DLD (__recorder_get_id__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{id} =} __recorder_get_id__ (@var{recorder})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{id} =} __recorder_get_id__ (@var{recorder}) +Undocumented internal function. +@end deftypefn */) { octave_value retval; #if ! defined (HAVE_PORTAUDIO) @@ -1942,10 +1942,10 @@ } DEFUN_DLD (__recorder_get_nbits__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{nbits} =} __recorder_get_nbits__ (@var{recorder})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{nbits} =} __recorder_get_nbits__ (@var{recorder}) +Undocumented internal function. +@end deftypefn */) { octave_value retval; #if ! defined (HAVE_PORTAUDIO) @@ -1960,10 +1960,10 @@ } DEFUN_DLD (__recorder_get_sample_number__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{n} =} __recorder_get_sample_number__ (@var{recorder})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{n} =} __recorder_get_sample_number__ (@var{recorder}) +Undocumented internal function. +@end deftypefn */) { octave_value retval; #if ! defined (HAVE_PORTAUDIO) @@ -1978,10 +1978,10 @@ } DEFUN_DLD (__recorder_get_tag__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{tag} =} __recorder_get_tag__ (@var{recorder})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{tag} =} __recorder_get_tag__ (@var{recorder}) +Undocumented internal function. +@end deftypefn */) { octave_value retval; #if ! defined (HAVE_PORTAUDIO) @@ -1996,10 +1996,10 @@ } DEFUN_DLD (__recorder_get_total_samples__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{n} =} __recorder_get_total_samples__ (@var{recorder})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{n} =} __recorder_get_total_samples__ (@var{recorder}) +Undocumented internal function. +@end deftypefn */) { octave_value retval; #if ! defined (HAVE_PORTAUDIO) @@ -2014,10 +2014,10 @@ } DEFUN_DLD (__recorder_get_userdata__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{data} =} __recorder_get_userdata__ (@var{recorder})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{data} =} __recorder_get_userdata__ (@var{recorder}) +Undocumented internal function. +@end deftypefn */) { octave_value retval; #if ! defined (HAVE_PORTAUDIO) @@ -2032,10 +2032,10 @@ } DEFUN_DLD (__recorder_isrecording__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __recorder_isrecording__ (@var{recorder})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __recorder_isrecording__ (@var{recorder}) +Undocumented internal function. +@end deftypefn */) { octave_value retval; #if ! defined (HAVE_PORTAUDIO) @@ -2050,10 +2050,10 @@ } DEFUN_DLD (__recorder_pause__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __recorder_pause__ (@var{recorder})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __recorder_pause__ (@var{recorder}) +Undocumented internal function. +@end deftypefn */) { #if ! defined (HAVE_PORTAUDIO) octave_unused_parameter (args); @@ -2067,10 +2067,10 @@ } DEFUN_DLD (__recorder_recordblocking__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __recorder_recordblocking__ (@var{recorder}, @var{seconds})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __recorder_recordblocking__ (@var{recorder}, @var{seconds}) +Undocumented internal function. +@end deftypefn */) { #if ! defined (HAVE_PORTAUDIO) octave_unused_parameter (args); @@ -2085,11 +2085,11 @@ } DEFUN_DLD (__recorder_record__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __recorder_record__ (@var{recorder})\n\ -@deftypefnx {} {} __recorder_record__ (@var{recorder}, @var{seconds})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __recorder_record__ (@var{recorder}) +@deftypefnx {} {} __recorder_record__ (@var{recorder}, @var{seconds}) +Undocumented internal function. +@end deftypefn */) { #if ! defined (HAVE_PORTAUDIO) octave_unused_parameter (args); @@ -2108,10 +2108,10 @@ } DEFUN_DLD (__recorder_resume__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __recorder_resume__ (@var{recorder})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __recorder_resume__ (@var{recorder}) +Undocumented internal function. +@end deftypefn */) { #if ! defined (HAVE_PORTAUDIO) octave_unused_parameter (args); @@ -2126,10 +2126,10 @@ } DEFUN_DLD (__recorder_set_fs__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __recorder_set_fs__ (@var{recorder}, @var{fs})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __recorder_set_fs__ (@var{recorder}, @var{fs}) +Undocumented internal function. +@end deftypefn */) { #if ! defined (HAVE_PORTAUDIO) octave_unused_parameter (args); @@ -2144,10 +2144,10 @@ } DEFUN_DLD (__recorder_set_tag__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __recorder_set_tag__ (@var{recorder}, @var{tag})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __recorder_set_tag__ (@var{recorder}, @var{tag}) +Undocumented internal function. +@end deftypefn */) { #if ! defined (HAVE_PORTAUDIO) octave_unused_parameter (args); @@ -2162,10 +2162,10 @@ } DEFUN_DLD (__recorder_set_userdata__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __recorder_set_userdata__ (@var{recorder}, @var{data})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __recorder_set_userdata__ (@var{recorder}, @var{data}) +Undocumented internal function. +@end deftypefn */) { #if ! defined (HAVE_PORTAUDIO) octave_unused_parameter (args); @@ -2180,10 +2180,10 @@ } DEFUN_DLD (__recorder_stop__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __recorder_stop__ (@var{recorder})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __recorder_stop__ (@var{recorder}) +Undocumented internal function. +@end deftypefn */) { #if ! defined (HAVE_PORTAUDIO) octave_unused_parameter (args); @@ -2198,12 +2198,12 @@ } DEFUN_DLD (__player_audioplayer__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{player} =} __player_audioplayer__ (@var{y}, @var{fs})\n\ -@deftypefnx {} {@var{player} =} __player_audioplayer__ (@var{y}, @var{fs}, @var{nbits})\n\ -@deftypefnx {} {@var{player} =} __player_audioplayer__ (@var{y}, @var{fs}, @var{nbits}, @var{id})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{player} =} __player_audioplayer__ (@var{y}, @var{fs}) +@deftypefnx {} {@var{player} =} __player_audioplayer__ (@var{y}, @var{fs}, @var{nbits}) +@deftypefnx {} {@var{player} =} __player_audioplayer__ (@var{y}, @var{fs}, @var{nbits}, @var{id}) +Undocumented internal function. +@end deftypefn */) { octave_value retval; #if ! defined (HAVE_PORTAUDIO) @@ -2270,10 +2270,10 @@ #endif DEFUN_DLD (__player_get_channels__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{n} =} __player_get_channels__ (@var{player})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{n} =} __player_get_channels__ (@var{player}) +Undocumented internal function. +@end deftypefn */) { octave_value retval; #if ! defined (HAVE_PORTAUDIO) @@ -2289,10 +2289,10 @@ } DEFUN_DLD (__player_get_fs__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{fs} =} __player_get_fs__ (@var{player})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{fs} =} __player_get_fs__ (@var{player}) +Undocumented internal function. +@end deftypefn */) { octave_value retval; #if ! defined (HAVE_PORTAUDIO) @@ -2308,10 +2308,10 @@ } DEFUN_DLD (__player_get_id__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{id} =} __player_get_id__ (@var{player})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{id} =} __player_get_id__ (@var{player}) +Undocumented internal function. +@end deftypefn */) { octave_value retval; #if ! defined (HAVE_PORTAUDIO) @@ -2327,10 +2327,10 @@ } DEFUN_DLD (__player_get_nbits__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{nbits} =} __player_get_nbits__ (@var{player})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{nbits} =} __player_get_nbits__ (@var{player}) +Undocumented internal function. +@end deftypefn */) { octave_value retval; #if ! defined (HAVE_PORTAUDIO) @@ -2346,10 +2346,10 @@ } DEFUN_DLD (__player_get_sample_number__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{n} =} __player_get_sample_number__ (@var{player})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{n} =} __player_get_sample_number__ (@var{player}) +Undocumented internal function. +@end deftypefn */) { octave_value retval; #if ! defined (HAVE_PORTAUDIO) @@ -2365,10 +2365,10 @@ } DEFUN_DLD (__player_get_tag__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{tag} =} __player_get_tag__ (@var{player})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{tag} =} __player_get_tag__ (@var{player}) +Undocumented internal function. +@end deftypefn */) { octave_value retval; #if ! defined (HAVE_PORTAUDIO) @@ -2384,10 +2384,10 @@ } DEFUN_DLD (__player_get_total_samples__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{n} =} __player_get_total_samples__ (@var{player})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{n} =} __player_get_total_samples__ (@var{player}) +Undocumented internal function. +@end deftypefn */) { octave_value retval; #if ! defined (HAVE_PORTAUDIO) @@ -2403,10 +2403,10 @@ } DEFUN_DLD (__player_get_userdata__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{data} =} __player_get_userdata__ (@var{player})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{data} =} __player_get_userdata__ (@var{player}) +Undocumented internal function. +@end deftypefn */) { octave_value retval; #if ! defined (HAVE_PORTAUDIO) @@ -2422,10 +2422,10 @@ } DEFUN_DLD (__player_isplaying__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __player_isplaying__ (@var{player})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __player_isplaying__ (@var{player}) +Undocumented internal function. +@end deftypefn */) { octave_value retval; #if ! defined (HAVE_PORTAUDIO) @@ -2441,10 +2441,10 @@ } DEFUN_DLD (__player_pause__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __player_pause__ (@var{player})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __player_pause__ (@var{player}) +Undocumented internal function. +@end deftypefn */) { #if ! defined (HAVE_PORTAUDIO) octave_unused_parameter (args); @@ -2459,12 +2459,12 @@ } DEFUN_DLD (__player_playblocking__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __player_playblocking__ (@var{player})\n\ -@deftypefnx {} {} __player_playblocking__ (@var{player}, @var{start})\n\ -@deftypefnx {} {} __player_playblocking__ (@var{player}, [@var{start}, @var{end}])\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __player_playblocking__ (@var{player}) +@deftypefnx {} {} __player_playblocking__ (@var{player}, @var{start}) +@deftypefnx {} {} __player_playblocking__ (@var{player}, [@var{start}, @var{end}]) +Undocumented internal function. +@end deftypefn */) { #if ! defined (HAVE_PORTAUDIO) octave_unused_parameter (args); @@ -2513,12 +2513,12 @@ } DEFUN_DLD (__player_play__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __player_play__ (@var{player})\n\ -@deftypefnx {} {} __player_play__ (@var{player}, @var{start})\n\ -@deftypefnx {} {} __player_play__ (@var{player}, [@var{start}, @var{end}])\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __player_play__ (@var{player}) +@deftypefnx {} {} __player_play__ (@var{player}, @var{start}) +@deftypefnx {} {} __player_play__ (@var{player}, [@var{start}, @var{end}]) +Undocumented internal function. +@end deftypefn */) { #if ! defined (HAVE_PORTAUDIO) octave_unused_parameter (args); @@ -2567,10 +2567,10 @@ } DEFUN_DLD (__player_resume__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __player_resume__ (@var{player})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __player_resume__ (@var{player}) +Undocumented internal function. +@end deftypefn */) { #if ! defined (HAVE_PORTAUDIO) octave_unused_parameter (args); @@ -2585,10 +2585,10 @@ } DEFUN_DLD (__player_set_fs__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __player_set_fs__ (@var{player}, @var{fs})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __player_set_fs__ (@var{player}, @var{fs}) +Undocumented internal function. +@end deftypefn */) { #if ! defined (HAVE_PORTAUDIO) octave_unused_parameter (args); @@ -2603,10 +2603,10 @@ } DEFUN_DLD (__player_set_tag__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __player_set_tag__ (@var{player}, @var{tag})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __player_set_tag__ (@var{player}, @var{tag}) +Undocumented internal function. +@end deftypefn */) { #if ! defined (HAVE_PORTAUDIO) octave_unused_parameter (args); @@ -2621,10 +2621,10 @@ } DEFUN_DLD (__player_set_userdata__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __player_set_userdata__ (@var{player}, @var{data})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __player_set_userdata__ (@var{player}, @var{data}) +Undocumented internal function. +@end deftypefn */) { #if ! defined (HAVE_PORTAUDIO) octave_unused_parameter (args); @@ -2639,10 +2639,10 @@ } DEFUN_DLD (__player_stop__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __player_stop__ (@var{player})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __player_stop__ (@var{player}) +Undocumented internal function. +@end deftypefn */) { #if ! defined (HAVE_PORTAUDIO) octave_unused_parameter (args);
--- a/libinterp/dldfcn/audioread.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/dldfcn/audioread.cc Tue Jun 21 16:07:51 2016 -0400 @@ -55,25 +55,25 @@ #endif DEFUN_DLD (audioread, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{y}, @var{fs}] =} audioread (@var{filename})\n\ -@deftypefnx {} {[@var{y}, @var{fs}] =} audioread (@var{filename}, @var{samples})\n\ -\n\ -@deftypefnx {} {[@var{y}, @var{fs}] =} audioread (@var{filename}, @var{datatype})\n\ -@deftypefnx {} {[@var{y}, @var{fs}] =} audioread (@var{filename}, @var{samples}, @var{datatype})\n\ -Read the audio file @var{filename} and return the audio data @var{y} and\n\ -sampling rate @var{fs}.\n\ -\n\ -The audio data is stored as matrix with rows corresponding to audio frames\n\ -and columns corresponding to channels.\n\ -\n\ -The optional two-element vector argument @var{samples} specifies starting\n\ -and ending frames.\n\ -\n\ -The optional argument @var{datatype} specifies the datatype to return.\n\ -If it is @qcode{\"native\"}, then the type of data depends on how the data\n\ -is stored in the audio file.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{y}, @var{fs}] =} audioread (@var{filename}) +@deftypefnx {} {[@var{y}, @var{fs}] =} audioread (@var{filename}, @var{samples}) + +@deftypefnx {} {[@var{y}, @var{fs}] =} audioread (@var{filename}, @var{datatype}) +@deftypefnx {} {[@var{y}, @var{fs}] =} audioread (@var{filename}, @var{samples}, @var{datatype}) +Read the audio file @var{filename} and return the audio data @var{y} and +sampling rate @var{fs}. + +The audio data is stored as matrix with rows corresponding to audio frames +and columns corresponding to channels. + +The optional two-element vector argument @var{samples} specifies starting +and ending frames. + +The optional argument @var{datatype} specifies the datatype to return. +If it is @qcode{"native"}, then the type of data depends on how the data +is stored in the audio file. +@end deftypefn */) { #if defined (HAVE_SNDFILE) @@ -234,38 +234,38 @@ #endif DEFUN_DLD (audiowrite, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} audiowrite (@var{filename}, @var{y}, @var{fs})\n\ -@deftypefnx {} {} audiowrite (@var{filename}, @var{y}, @var{fs}, @var{name}, @var{value}, @dots{})\n\ -\n\ -Write audio data from the matrix @var{y} to @var{filename} at sampling rate\n\ -@var{fs} with the file format determined by the file extension.\n\ -\n\ -Additional name/value argument pairs may be used to specify the\n\ -following options:\n\ -\n\ -@table @samp\n\ -@item BitsPerSample\n\ -Number of bits per sample. Valid values are 8, 16, 24, and 32. Default is\n\ -16.\n\ -\n\ -@item BitRate\n\ -Valid argument name, but ignored. Left for compatibility with @sc{matlab}.\n\ -\n\ -@item Quality\n\ -Quality setting for the Ogg Vorbis compressor. Values can range between 0\n\ -and 100 with 100 being the highest quality setting. Default is 75.\n\ -\n\ -@item Title\n\ -Title for the audio file.\n\ -\n\ -@item Artist\n\ -Artist name.\n\ -\n\ -@item Comment\n\ -Comment.\n\ -@end table\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} audiowrite (@var{filename}, @var{y}, @var{fs}) +@deftypefnx {} {} audiowrite (@var{filename}, @var{y}, @var{fs}, @var{name}, @var{value}, @dots{}) + +Write audio data from the matrix @var{y} to @var{filename} at sampling rate +@var{fs} with the file format determined by the file extension. + +Additional name/value argument pairs may be used to specify the +following options: + +@table @samp +@item BitsPerSample +Number of bits per sample. Valid values are 8, 16, 24, and 32. Default is +16. + +@item BitRate +Valid argument name, but ignored. Left for compatibility with @sc{matlab}. + +@item Quality +Quality setting for the Ogg Vorbis compressor. Values can range between 0 +and 100 with 100 being the highest quality setting. Default is 75. + +@item Title +Title for the audio file. + +@item Artist +Artist name. + +@item Comment +Comment. +@end table +@end deftypefn */) { #if defined (HAVE_SNDFILE) @@ -443,10 +443,10 @@ } DEFUN_DLD (audioinfo, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{info} =} audioinfo (@var{filename})\n\ -Return information about an audio file specified by @var{filename}.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{info} =} audioinfo (@var{filename}) +Return information about an audio file specified by @var{filename}. +@end deftypefn */) { #if defined (HAVE_SNDFILE) @@ -546,14 +546,14 @@ #endif DEFUN_DLD (audioformats, args, , -"-*- texinfo -*-\n\ -@deftypefn {} {} audioformats ()\n\ -@deftypefnx {} {} audioformats (@var{format})\n\ -Display information about all supported audio formats.\n\ -\n\ -If the optional argument @var{format} is given, then display only formats\n\ -with names that start with @var{format}.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} audioformats () +@deftypefnx {} {} audioformats (@var{format}) +Display information about all supported audio formats. + +If the optional argument @var{format} is given, then display only formats +with names that start with @var{format}. +@end deftypefn */) { #if defined (HAVE_SNDFILE)
--- a/libinterp/dldfcn/ccolamd.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/dldfcn/ccolamd.cc Tue Jun 21 16:07:51 2016 -0400 @@ -53,96 +53,96 @@ #endif DEFUN_DLD (ccolamd, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{p} =} ccolamd (@var{S})\n\ -@deftypefnx {} {@var{p} =} ccolamd (@var{S}, @var{knobs})\n\ -@deftypefnx {} {@var{p} =} ccolamd (@var{S}, @var{knobs}, @var{cmember})\n\ -@deftypefnx {} {[@var{p}, @var{stats}] =} ccolamd (@dots{})\n\ -\n\ -Constrained column approximate minimum degree permutation.\n\ -\n\ -@code{@var{p} = ccolamd (@var{S})} returns the column approximate minimum\n\ -degree permutation vector for the sparse matrix @var{S}. For a\n\ -non-symmetric matrix @var{S}, @code{@var{S}(:, @var{p})} tends to have\n\ -sparser LU@tie{}factors than @var{S}.\n\ -@code{chol (@var{S}(:, @var{p})' * @var{S}(:, @var{p}))} also tends to be\n\ -sparser than @code{chol (@var{S}' * @var{S})}.\n\ -@code{@var{p} = ccolamd (@var{S}, 1)} optimizes the ordering for\n\ -@code{lu (@var{S}(:, @var{p}))}. The ordering is followed by a column\n\ -elimination tree post-ordering.\n\ -\n\ -@var{knobs} is an optional 1-element to 5-element input vector, with a\n\ -default value of @code{[0 10 10 1 0]} if not present or empty. Entries not\n\ -present are set to their defaults.\n\ -\n\ -@table @code\n\ -@item @var{knobs}(1)\n\ -if nonzero, the ordering is optimized for @code{lu (S(:, p))}. It will be a\n\ -poor ordering for @code{chol (@var{S}(:, @var{p})' * @var{S}(:, @var{p}))}.\n\ -This is the most important knob for ccolamd.\n\ -\n\ -@item @var{knobs}(2)\n\ -if @var{S} is m-by-n, rows with more than\n\ -@code{max (16, @var{knobs}(2) * sqrt (n))} entries are ignored.\n\ -\n\ -@item @var{knobs}(3)\n\ -columns with more than\n\ -@code{max (16, @var{knobs}(3) * sqrt (min (@var{m}, @var{n})))} entries are\n\ -ignored and ordered last in the output permutation\n\ -(subject to the cmember constraints).\n\ -\n\ -@item @var{knobs}(4)\n\ -if nonzero, aggressive absorption is performed.\n\ -\n\ -@item @var{knobs}(5)\n\ -if nonzero, statistics and knobs are printed.\n\ -\n\ -@end table\n\ -\n\ -@var{cmember} is an optional vector of length @math{n}. It defines the\n\ -constraints on the column ordering. If @code{@var{cmember}(j) = @var{c}},\n\ -then column @var{j} is in constraint set @var{c} (@var{c} must be in the\n\ -range 1 to n). In the output permutation @var{p}, all columns in set 1\n\ -appear first, followed by all columns in set 2, and so on.\n\ -@code{@var{cmember} = ones (1,n)} if not present or empty.\n\ -@code{ccolamd (@var{S}, [], 1 : n)} returns @code{1 : n}\n\ -\n\ -@code{@var{p} = ccolamd (@var{S})} is about the same as\n\ -@code{@var{p} = colamd (@var{S})}. @var{knobs} and its default values\n\ -differ. @code{colamd} always does aggressive absorption, and it finds an\n\ -ordering suitable for both @code{lu (@var{S}(:, @var{p}))} and @code{chol\n\ -(@var{S}(:, @var{p})' * @var{S}(:, @var{p}))}; it cannot optimize its\n\ -ordering for @code{lu (@var{S}(:, @var{p}))} to the extent that\n\ -@code{ccolamd (@var{S}, 1)} can.\n\ -\n\ -@var{stats} is an optional 20-element output vector that provides data\n\ -about the ordering and the validity of the input matrix @var{S}. Ordering\n\ -statistics are in @code{@var{stats}(1 : 3)}. @code{@var{stats}(1)} and\n\ -@code{@var{stats}(2)} are the number of dense or empty rows and columns\n\ -ignored by @sc{ccolamd} and @code{@var{stats}(3)} is the number of garbage\n\ -collections performed on the internal data structure used by @sc{ccolamd}\n\ -(roughly of size @code{2.2 * nnz (@var{S}) + 4 * @var{m} + 7 * @var{n}}\n\ -integers).\n\ -\n\ -@code{@var{stats}(4 : 7)} provide information if CCOLAMD was able to\n\ -continue. The matrix is OK if @code{@var{stats}(4)} is zero, or 1 if\n\ -invalid. @code{@var{stats}(5)} is the rightmost column index that is\n\ -unsorted or contains duplicate entries, or zero if no such column exists.\n\ -@code{@var{stats}(6)} is the last seen duplicate or out-of-order row\n\ -index in the column index given by @code{@var{stats}(5)}, or zero if no\n\ -such row index exists. @code{@var{stats}(7)} is the number of duplicate\n\ -or out-of-order row indices. @code{@var{stats}(8 : 20)} is always zero in\n\ -the current version of @sc{ccolamd} (reserved for future use).\n\ -\n\ -The authors of the code itself are @nospell{S. Larimore, T. Davis}\n\ -(Univ. of Florida) and @nospell{S. Rajamanickam} in collaboration with\n\ -@nospell{J. Bilbert and E. Ng}. Supported by the National Science Foundation\n\ -@nospell{(DMS-9504974, DMS-9803599, CCR-0203270)}, and a grant from\n\ -@nospell{Sandia} National Lab.\n\ -See @url{http://www.cise.ufl.edu/research/sparse} for\n\ -ccolamd, csymamd, amd, colamd, symamd, and other related orderings.\n\ -@seealso{colamd, csymamd}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{p} =} ccolamd (@var{S}) +@deftypefnx {} {@var{p} =} ccolamd (@var{S}, @var{knobs}) +@deftypefnx {} {@var{p} =} ccolamd (@var{S}, @var{knobs}, @var{cmember}) +@deftypefnx {} {[@var{p}, @var{stats}] =} ccolamd (@dots{}) + +Constrained column approximate minimum degree permutation. + +@code{@var{p} = ccolamd (@var{S})} returns the column approximate minimum +degree permutation vector for the sparse matrix @var{S}. For a +non-symmetric matrix @var{S}, @code{@var{S}(:, @var{p})} tends to have +sparser LU@tie{}factors than @var{S}. +@code{chol (@var{S}(:, @var{p})' * @var{S}(:, @var{p}))} also tends to be +sparser than @code{chol (@var{S}' * @var{S})}. +@code{@var{p} = ccolamd (@var{S}, 1)} optimizes the ordering for +@code{lu (@var{S}(:, @var{p}))}. The ordering is followed by a column +elimination tree post-ordering. + +@var{knobs} is an optional 1-element to 5-element input vector, with a +default value of @code{[0 10 10 1 0]} if not present or empty. Entries not +present are set to their defaults. + +@table @code +@item @var{knobs}(1) +if nonzero, the ordering is optimized for @code{lu (S(:, p))}. It will be a +poor ordering for @code{chol (@var{S}(:, @var{p})' * @var{S}(:, @var{p}))}. +This is the most important knob for ccolamd. + +@item @var{knobs}(2) +if @var{S} is m-by-n, rows with more than +@code{max (16, @var{knobs}(2) * sqrt (n))} entries are ignored. + +@item @var{knobs}(3) +columns with more than +@code{max (16, @var{knobs}(3) * sqrt (min (@var{m}, @var{n})))} entries are +ignored and ordered last in the output permutation +(subject to the cmember constraints). + +@item @var{knobs}(4) +if nonzero, aggressive absorption is performed. + +@item @var{knobs}(5) +if nonzero, statistics and knobs are printed. + +@end table + +@var{cmember} is an optional vector of length @math{n}. It defines the +constraints on the column ordering. If @code{@var{cmember}(j) = @var{c}}, +then column @var{j} is in constraint set @var{c} (@var{c} must be in the +range 1 to n). In the output permutation @var{p}, all columns in set 1 +appear first, followed by all columns in set 2, and so on. +@code{@var{cmember} = ones (1,n)} if not present or empty. +@code{ccolamd (@var{S}, [], 1 : n)} returns @code{1 : n} + +@code{@var{p} = ccolamd (@var{S})} is about the same as +@code{@var{p} = colamd (@var{S})}. @var{knobs} and its default values +differ. @code{colamd} always does aggressive absorption, and it finds an +ordering suitable for both @code{lu (@var{S}(:, @var{p}))} and @code{chol +(@var{S}(:, @var{p})' * @var{S}(:, @var{p}))}; it cannot optimize its +ordering for @code{lu (@var{S}(:, @var{p}))} to the extent that +@code{ccolamd (@var{S}, 1)} can. + +@var{stats} is an optional 20-element output vector that provides data +about the ordering and the validity of the input matrix @var{S}. Ordering +statistics are in @code{@var{stats}(1 : 3)}. @code{@var{stats}(1)} and +@code{@var{stats}(2)} are the number of dense or empty rows and columns +ignored by @sc{ccolamd} and @code{@var{stats}(3)} is the number of garbage +collections performed on the internal data structure used by @sc{ccolamd} +(roughly of size @code{2.2 * nnz (@var{S}) + 4 * @var{m} + 7 * @var{n}} +integers). + +@code{@var{stats}(4 : 7)} provide information if CCOLAMD was able to +continue. The matrix is OK if @code{@var{stats}(4)} is zero, or 1 if +invalid. @code{@var{stats}(5)} is the rightmost column index that is +unsorted or contains duplicate entries, or zero if no such column exists. +@code{@var{stats}(6)} is the last seen duplicate or out-of-order row +index in the column index given by @code{@var{stats}(5)}, or zero if no +such row index exists. @code{@var{stats}(7)} is the number of duplicate +or out-of-order row indices. @code{@var{stats}(8 : 20)} is always zero in +the current version of @sc{ccolamd} (reserved for future use). + +The authors of the code itself are @nospell{S. Larimore, T. Davis} +(Univ. of Florida) and @nospell{S. Rajamanickam} in collaboration with +@nospell{J. Bilbert and E. Ng}. Supported by the National Science Foundation +@nospell{(DMS-9504974, DMS-9803599, CCR-0203270)}, and a grant from +@nospell{Sandia} National Lab. +See @url{http://www.cise.ufl.edu/research/sparse} for +ccolamd, csymamd, amd, colamd, symamd, and other related orderings. +@seealso{colamd, csymamd} +@end deftypefn */) { #if defined (HAVE_CCOLAMD) @@ -340,70 +340,70 @@ } DEFUN_DLD (csymamd, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{p} =} csymamd (@var{S})\n\ -@deftypefnx {} {@var{p} =} csymamd (@var{S}, @var{knobs})\n\ -@deftypefnx {} {@var{p} =} csymamd (@var{S}, @var{knobs}, @var{cmember})\n\ -@deftypefnx {} {[@var{p}, @var{stats}] =} csymamd (@dots{})\n\ -\n\ -For a symmetric positive definite matrix @var{S}, return the permutation\n\ -vector @var{p} such that @code{@var{S}(@var{p},@var{p})} tends to have a\n\ -sparser Cholesky@tie{}factor than @var{S}.\n\ -\n\ -Sometimes @code{csymamd} works well for symmetric indefinite matrices too.\n\ -The matrix @var{S} is assumed to be symmetric; only the strictly lower\n\ -triangular part is referenced. @var{S} must be square. The ordering is\n\ -followed by an elimination tree post-ordering.\n\ -\n\ -@var{knobs} is an optional 1-element to 3-element input vector, with a\n\ -default value of @code{[10 1 0]}. Entries not present are set to their\n\ -defaults.\n\ -\n\ -@table @code\n\ -@item @var{knobs}(1)\n\ -If @var{S} is n-by-n, then rows and columns with more than\n\ -@code{max(16,@var{knobs}(1)*sqrt(n))} entries are ignored, and ordered\n\ -last in the output permutation (subject to the cmember constraints).\n\ -\n\ -@item @var{knobs}(2)\n\ -If nonzero, aggressive absorption is performed.\n\ -\n\ -@item @var{knobs}(3)\n\ -If nonzero, statistics and knobs are printed.\n\ -\n\ -@end table\n\ -\n\ -@var{cmember} is an optional vector of length n. It defines the constraints\n\ -on the ordering. If @code{@var{cmember}(j) = @var{S}}, then row/column j is\n\ -in constraint set @var{c} (@var{c} must be in the range 1 to n). In the\n\ -output permutation @var{p}, rows/columns in set 1 appear first, followed\n\ -by all rows/columns in set 2, and so on. @code{@var{cmember} = ones (1,n)}\n\ -if not present or empty. @code{csymamd (@var{S},[],1:n)} returns\n\ -@code{1:n}.\n\ -\n\ -@code{@var{p} = csymamd (@var{S})} is about the same as\n\ -@code{@var{p} = symamd (@var{S})}. @var{knobs} and its default values\n\ -differ.\n\ -\n\ -@code{@var{stats}(4:7)} provide information if CCOLAMD was able to\n\ -continue. The matrix is OK if @code{@var{stats}(4)} is zero, or 1 if\n\ -invalid. @code{@var{stats}(5)} is the rightmost column index that is\n\ -unsorted or contains duplicate entries, or zero if no such column exists.\n\ -@code{@var{stats}(6)} is the last seen duplicate or out-of-order row\n\ -index in the column index given by @code{@var{stats}(5)}, or zero if no\n\ -such row index exists. @code{@var{stats}(7)} is the number of duplicate\n\ -or out-of-order row indices. @code{@var{stats}(8:20)} is always zero in\n\ -the current version of @sc{ccolamd} (reserved for future use).\n\ -\n\ -The authors of the code itself are @nospell{S. Larimore, T. Davis}\n\ -(Univ. of Florida) and @nospell{S. Rajamanickam} in collaboration with\n\ -@nospell{J. Bilbert and E. Ng}. Supported by the National Science Foundation\n\ -@nospell{(DMS-9504974, DMS-9803599, CCR-0203270)}, and a grant from\n\ -@nospell{Sandia} National Lab.\n\ -See @url{http://www.cise.ufl.edu/research/sparse} for\n\ -ccolamd, csymamd, amd, colamd, symamd, and other related orderings.\n\ -@seealso{symamd, ccolamd}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{p} =} csymamd (@var{S}) +@deftypefnx {} {@var{p} =} csymamd (@var{S}, @var{knobs}) +@deftypefnx {} {@var{p} =} csymamd (@var{S}, @var{knobs}, @var{cmember}) +@deftypefnx {} {[@var{p}, @var{stats}] =} csymamd (@dots{}) + +For a symmetric positive definite matrix @var{S}, return the permutation +vector @var{p} such that @code{@var{S}(@var{p},@var{p})} tends to have a +sparser Cholesky@tie{}factor than @var{S}. + +Sometimes @code{csymamd} works well for symmetric indefinite matrices too. +The matrix @var{S} is assumed to be symmetric; only the strictly lower +triangular part is referenced. @var{S} must be square. The ordering is +followed by an elimination tree post-ordering. + +@var{knobs} is an optional 1-element to 3-element input vector, with a +default value of @code{[10 1 0]}. Entries not present are set to their +defaults. + +@table @code +@item @var{knobs}(1) +If @var{S} is n-by-n, then rows and columns with more than +@code{max(16,@var{knobs}(1)*sqrt(n))} entries are ignored, and ordered +last in the output permutation (subject to the cmember constraints). + +@item @var{knobs}(2) +If nonzero, aggressive absorption is performed. + +@item @var{knobs}(3) +If nonzero, statistics and knobs are printed. + +@end table + +@var{cmember} is an optional vector of length n. It defines the constraints +on the ordering. If @code{@var{cmember}(j) = @var{S}}, then row/column j is +in constraint set @var{c} (@var{c} must be in the range 1 to n). In the +output permutation @var{p}, rows/columns in set 1 appear first, followed +by all rows/columns in set 2, and so on. @code{@var{cmember} = ones (1,n)} +if not present or empty. @code{csymamd (@var{S},[],1:n)} returns +@code{1:n}. + +@code{@var{p} = csymamd (@var{S})} is about the same as +@code{@var{p} = symamd (@var{S})}. @var{knobs} and its default values +differ. + +@code{@var{stats}(4:7)} provide information if CCOLAMD was able to +continue. The matrix is OK if @code{@var{stats}(4)} is zero, or 1 if +invalid. @code{@var{stats}(5)} is the rightmost column index that is +unsorted or contains duplicate entries, or zero if no such column exists. +@code{@var{stats}(6)} is the last seen duplicate or out-of-order row +index in the column index given by @code{@var{stats}(5)}, or zero if no +such row index exists. @code{@var{stats}(7)} is the number of duplicate +or out-of-order row indices. @code{@var{stats}(8:20)} is always zero in +the current version of @sc{ccolamd} (reserved for future use). + +The authors of the code itself are @nospell{S. Larimore, T. Davis} +(Univ. of Florida) and @nospell{S. Rajamanickam} in collaboration with +@nospell{J. Bilbert and E. Ng}. Supported by the National Science Foundation +@nospell{(DMS-9504974, DMS-9803599, CCR-0203270)}, and a grant from +@nospell{Sandia} National Lab. +See @url{http://www.cise.ufl.edu/research/sparse} for +ccolamd, csymamd, amd, colamd, symamd, and other related orderings. +@seealso{symamd, ccolamd} +@end deftypefn */) { #if defined (HAVE_CCOLAMD)
--- a/libinterp/dldfcn/chol.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/dldfcn/chol.cc Tue Jun 21 16:07:51 2016 -0400 @@ -64,89 +64,89 @@ } DEFUN_DLD (chol, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{R} =} chol (@var{A})\n\ -@deftypefnx {} {[@var{R}, @var{p}] =} chol (@var{A})\n\ -@deftypefnx {} {[@var{R}, @var{p}, @var{Q}] =} chol (@var{A})\n\ -@deftypefnx {} {[@var{R}, @var{p}, @var{Q}] =} chol (@var{A}, \"vector\")\n\ -@deftypefnx {} {[@var{L}, @dots{}] =} chol (@dots{}, \"lower\")\n\ -@deftypefnx {} {[@var{R}, @dots{}] =} chol (@dots{}, \"upper\")\n\ -@cindex Cholesky factorization\n\ -Compute the upper Cholesky@tie{}factor, @var{R}, of the real symmetric\n\ -or complex Hermitian positive definite matrix @var{A}.\n\ -\n\ -The upper Cholesky@tie{}factor @var{R} is computed by using the upper\n\ -triangular part of matrix @var{A} and is defined by\n\ -@tex\n\ -$ R^T R = A $.\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ -@var{R}' * @var{R} = @var{A}.\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -\n\ -Calling @code{chol} using the optional @qcode{\"upper\"} flag has the\n\ -same behavior. In contrast, using the optional @qcode{\"lower\"} flag,\n\ -@code{chol} returns the lower triangular factorization, computed by using\n\ -the lower triangular part of matrix @var{A}, such that\n\ -@tex\n\ -$ L L^T = A $.\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ -@var{L} * @var{L}' = @var{A}.\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -\n\ -Called with one output argument @code{chol} fails if matrix @var{A} is\n\ -not positive definite. Note that if matrix @var{A} is not real symmetric\n\ -or complex Hermitian then the lower triangular part is considered to be\n\ -the (complex conjugate) transpose of the upper triangular part, or vice\n\ -versa, given the @qcode{\"lower\"} flag.\n\ -\n\ -Called with two or more output arguments @var{p} flags whether the matrix\n\ -@var{A} was positive definite and @code{chol} does not fail. A zero value\n\ -of @var{p} indicates that matrix @var{A} is positive definite and @var{R}\n\ -gives the factorization. Otherwise, @var{p} will have a positive value.\n\ -\n\ -If called with three output arguments matrix @var{A} must be sparse and\n\ -a sparsity preserving row/column permutation is applied to matrix @var{A}\n\ -prior to the factorization. That is @var{R} is the factorization of\n\ -@code{@var{A}(@var{Q},@var{Q})} such that\n\ -@tex\n\ -$ R^T R = Q^T A Q$.\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ -@var{R}' * @var{R} = @var{Q}' * @var{A} * @var{Q}.\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -\n\ -The sparsity preserving permutation is generally returned as a matrix.\n\ -However, given the optional flag @qcode{\"vector\"}, @var{Q} will be\n\ -returned as a vector such that\n\ -@tex\n\ -$ R^T R = A (Q, Q)$.\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ -@var{R}' * @var{R} = @var{A}(@var{Q}, @var{Q}).\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -\n\ -In general the lower triangular factorization is significantly faster for\n\ -sparse matrices.\n\ -@seealso{hess, lu, qr, qz, schur, svd, ichol, cholinv, chol2inv, cholupdate, cholinsert, choldelete, cholshift}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{R} =} chol (@var{A}) +@deftypefnx {} {[@var{R}, @var{p}] =} chol (@var{A}) +@deftypefnx {} {[@var{R}, @var{p}, @var{Q}] =} chol (@var{A}) +@deftypefnx {} {[@var{R}, @var{p}, @var{Q}] =} chol (@var{A}, "vector") +@deftypefnx {} {[@var{L}, @dots{}] =} chol (@dots{}, "lower") +@deftypefnx {} {[@var{R}, @dots{}] =} chol (@dots{}, "upper") +@cindex Cholesky factorization +Compute the upper Cholesky@tie{}factor, @var{R}, of the real symmetric +or complex Hermitian positive definite matrix @var{A}. + +The upper Cholesky@tie{}factor @var{R} is computed by using the upper +triangular part of matrix @var{A} and is defined by +@tex +$ R^T R = A $. +@end tex +@ifnottex + +@example +@var{R}' * @var{R} = @var{A}. +@end example + +@end ifnottex + +Calling @code{chol} using the optional @qcode{"upper"} flag has the +same behavior. In contrast, using the optional @qcode{"lower"} flag, +@code{chol} returns the lower triangular factorization, computed by using +the lower triangular part of matrix @var{A}, such that +@tex +$ L L^T = A $. +@end tex +@ifnottex + +@example +@var{L} * @var{L}' = @var{A}. +@end example + +@end ifnottex + +Called with one output argument @code{chol} fails if matrix @var{A} is +not positive definite. Note that if matrix @var{A} is not real symmetric +or complex Hermitian then the lower triangular part is considered to be +the (complex conjugate) transpose of the upper triangular part, or vice +versa, given the @qcode{"lower"} flag. + +Called with two or more output arguments @var{p} flags whether the matrix +@var{A} was positive definite and @code{chol} does not fail. A zero value +of @var{p} indicates that matrix @var{A} is positive definite and @var{R} +gives the factorization. Otherwise, @var{p} will have a positive value. + +If called with three output arguments matrix @var{A} must be sparse and +a sparsity preserving row/column permutation is applied to matrix @var{A} +prior to the factorization. That is @var{R} is the factorization of +@code{@var{A}(@var{Q},@var{Q})} such that +@tex +$ R^T R = Q^T A Q$. +@end tex +@ifnottex + +@example +@var{R}' * @var{R} = @var{Q}' * @var{A} * @var{Q}. +@end example + +@end ifnottex + +The sparsity preserving permutation is generally returned as a matrix. +However, given the optional flag @qcode{"vector"}, @var{Q} will be +returned as a vector such that +@tex +$ R^T R = A (Q, Q)$. +@end tex +@ifnottex + +@example +@var{R}' * @var{R} = @var{A}(@var{Q}, @var{Q}). +@end example + +@end ifnottex + +In general the lower triangular factorization is significantly faster for +sparse matrices. +@seealso{hess, lu, qr, qz, schur, svd, ichol, cholinv, chol2inv, cholupdate, cholinsert, choldelete, cholshift} +@end deftypefn */) { int nargin = args.length (); @@ -329,12 +329,12 @@ */ DEFUN_DLD (cholinv, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} cholinv (@var{A})\n\ -Compute the inverse of the symmetric positive definite matrix @var{A} using\n\ -the Cholesky@tie{}factorization.\n\ -@seealso{chol, chol2inv, inv}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} cholinv (@var{A}) +Compute the inverse of the symmetric positive definite matrix @var{A} using +the Cholesky@tie{}factorization. +@seealso{chol, chol2inv, inv} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -453,16 +453,16 @@ */ DEFUN_DLD (chol2inv, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} chol2inv (@var{U})\n\ -Invert a symmetric, positive definite square matrix from its Cholesky\n\ -decomposition, @var{U}.\n\ -\n\ -Note that @var{U} should be an upper-triangular matrix with positive\n\ -diagonal elements. @code{chol2inv (@var{U})} provides\n\ -@code{inv (@var{U}'*@var{U})} but it is much faster than using @code{inv}.\n\ -@seealso{chol, cholinv, inv}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} chol2inv (@var{U}) +Invert a symmetric, positive definite square matrix from its Cholesky +decomposition, @var{U}. + +Note that @var{U} should be an upper-triangular matrix with positive +diagonal elements. @code{chol2inv (@var{U})} provides +@code{inv (@var{U}'*@var{U})} but it is much faster than using @code{inv}. +@seealso{chol, cholinv, inv} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -536,36 +536,36 @@ } DEFUN_DLD (cholupdate, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{R1}, @var{info}] =} cholupdate (@var{R}, @var{u}, @var{op})\n\ -Update or downdate a Cholesky@tie{}factorization.\n\ -\n\ -Given an upper triangular matrix @var{R} and a column vector @var{u},\n\ -attempt to determine another upper triangular matrix @var{R1} such that\n\ -\n\ -@itemize @bullet\n\ -@item\n\ -@var{R1}'*@var{R1} = @var{R}'*@var{R} + @var{u}*@var{u}'\n\ -if @var{op} is @qcode{\"+\"}\n\ -\n\ -@item\n\ -@var{R1}'*@var{R1} = @var{R}'*@var{R} - @var{u}*@var{u}'\n\ -if @var{op} is @qcode{\"-\"}\n\ -@end itemize\n\ -\n\ -If @var{op} is @qcode{\"-\"}, @var{info} is set to\n\ -\n\ -@itemize\n\ -@item 0 if the downdate was successful,\n\ -\n\ -@item 1 if @var{R}'*@var{R} - @var{u}*@var{u}' is not positive definite,\n\ -\n\ -@item 2 if @var{R} is singular.\n\ -@end itemize\n\ -\n\ -If @var{info} is not present, an error message is printed in cases 1 and 2.\n\ -@seealso{chol, cholinsert, choldelete, cholshift}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{R1}, @var{info}] =} cholupdate (@var{R}, @var{u}, @var{op}) +Update or downdate a Cholesky@tie{}factorization. + +Given an upper triangular matrix @var{R} and a column vector @var{u}, +attempt to determine another upper triangular matrix @var{R1} such that + +@itemize @bullet +@item +@var{R1}'*@var{R1} = @var{R}'*@var{R} + @var{u}*@var{u}' +if @var{op} is @qcode{"+"} + +@item +@var{R1}'*@var{R1} = @var{R}'*@var{R} - @var{u}*@var{u}' +if @var{op} is @qcode{"-"} +@end itemize + +If @var{op} is @qcode{"-"}, @var{info} is set to + +@itemize +@item 0 if the downdate was successful, + +@item 1 if @var{R}'*@var{R} - @var{u}*@var{u}' is not positive definite, + +@item 2 if @var{R} is singular. +@end itemize + +If @var{info} is not present, an error message is printed in cases 1 and 2. +@seealso{chol, cholinsert, choldelete, cholshift} +@end deftypefn */) { int nargin = args.length (); @@ -739,28 +739,28 @@ */ DEFUN_DLD (cholinsert, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{R1} =} cholinsert (@var{R}, @var{j}, @var{u})\n\ -@deftypefnx {} {[@var{R1}, @var{info}] =} cholinsert (@var{R}, @var{j}, @var{u})\n\ -Given a Cholesky@tie{}factorization of a real symmetric or complex Hermitian\n\ -positive definite matrix @w{@var{A} = @var{R}'*@var{R}}, @var{R}@tie{}upper\n\ -triangular, return the Cholesky@tie{}factorization of\n\ -@var{A1}, where @w{A1(p,p) = A}, @w{A1(:,j) = A1(j,:)' = u} and\n\ -@w{p = [1:j-1,j+1:n+1]}. @w{u(j)} should be positive.\n\ -\n\ -On return, @var{info} is set to\n\ -\n\ -@itemize\n\ -@item 0 if the insertion was successful,\n\ -\n\ -@item 1 if @var{A1} is not positive definite,\n\ -\n\ -@item 2 if @var{R} is singular.\n\ -@end itemize\n\ -\n\ -If @var{info} is not present, an error message is printed in cases 1 and 2.\n\ -@seealso{chol, cholupdate, choldelete, cholshift}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{R1} =} cholinsert (@var{R}, @var{j}, @var{u}) +@deftypefnx {} {[@var{R1}, @var{info}] =} cholinsert (@var{R}, @var{j}, @var{u}) +Given a Cholesky@tie{}factorization of a real symmetric or complex Hermitian +positive definite matrix @w{@var{A} = @var{R}'*@var{R}}, @var{R}@tie{}upper +triangular, return the Cholesky@tie{}factorization of +@var{A1}, where @w{A1(p,p) = A}, @w{A1(:,j) = A1(j,:)' = u} and +@w{p = [1:j-1,j+1:n+1]}. @w{u(j)} should be positive. + +On return, @var{info} is set to + +@itemize +@item 0 if the insertion was successful, + +@item 1 if @var{A1} is not positive definite, + +@item 2 if @var{R} is singular. +@end itemize + +If @var{info} is not present, an error message is printed in cases 1 and 2. +@seealso{chol, cholupdate, choldelete, cholshift} +@end deftypefn */) { if (args.length () != 3) print_usage (); @@ -992,14 +992,14 @@ */ DEFUN_DLD (choldelete, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{R1} =} choldelete (@var{R}, @var{j})\n\ -Given a Cholesky@tie{}factorization of a real symmetric or complex Hermitian\n\ -positive definite matrix @w{@var{A} = @var{R}'*@var{R}}, @var{R}@tie{}upper\n\ -triangular, return the Cholesky@tie{}factorization of @w{A(p,p)}, where\n\ -@w{p = [1:j-1,j+1:n+1]}.\n\ -@seealso{chol, cholupdate, cholinsert, cholshift}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{R1} =} choldelete (@var{R}, @var{j}) +Given a Cholesky@tie{}factorization of a real symmetric or complex Hermitian +positive definite matrix @w{@var{A} = @var{R}'*@var{R}}, @var{R}@tie{}upper +triangular, return the Cholesky@tie{}factorization of @w{A(p,p)}, where +@w{p = [1:j-1,j+1:n+1]}. +@seealso{chol, cholupdate, cholinsert, cholshift} +@end deftypefn */) { if (args.length () != 2) print_usage (); @@ -1114,18 +1114,18 @@ */ DEFUN_DLD (cholshift, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{R1} =} cholshift (@var{R}, @var{i}, @var{j})\n\ -Given a Cholesky@tie{}factorization of a real symmetric or complex Hermitian\n\ -positive definite matrix @w{@var{A} = @var{R}'*@var{R}}, @var{R}@tie{}upper\n\ -triangular, return the Cholesky@tie{}factorization of\n\ -@w{@var{A}(p,p)}, where @w{p} is the permutation @*\n\ -@code{p = [1:i-1, shift(i:j, 1), j+1:n]} if @w{@var{i} < @var{j}} @*\n\ - or @*\n\ -@code{p = [1:j-1, shift(j:i,-1), i+1:n]} if @w{@var{j} < @var{i}}. @*\n\ -\n\ -@seealso{chol, cholupdate, cholinsert, choldelete}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{R1} =} cholshift (@var{R}, @var{i}, @var{j}) +Given a Cholesky@tie{}factorization of a real symmetric or complex Hermitian +positive definite matrix @w{@var{A} = @var{R}'*@var{R}}, @var{R}@tie{}upper +triangular, return the Cholesky@tie{}factorization of +@w{@var{A}(p,p)}, where @w{p} is the permutation @* +@code{p = [1:i-1, shift(i:j, 1), j+1:n]} if @w{@var{i} < @var{j}} @* + or @* +@code{p = [1:j-1, shift(j:i,-1), i+1:n]} if @w{@var{j} < @var{i}}. @* + +@seealso{chol, cholupdate, cholinsert, choldelete} +@end deftypefn */) { if (args.length () != 3) print_usage ();
--- a/libinterp/dldfcn/colamd.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/dldfcn/colamd.cc Tue Jun 21 16:07:51 2016 -0400 @@ -209,74 +209,74 @@ } DEFUN_DLD (colamd, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{p} =} colamd (@var{S})\n\ -@deftypefnx {} {@var{p} =} colamd (@var{S}, @var{knobs})\n\ -@deftypefnx {} {[@var{p}, @var{stats}] =} colamd (@var{S})\n\ -@deftypefnx {} {[@var{p}, @var{stats}] =} colamd (@var{S}, @var{knobs})\n\ -\n\ -Compute the column approximate minimum degree permutation.\n\ -\n\ -@code{@var{p} = colamd (@var{S})} returns the column approximate minimum\n\ -degree permutation vector for the sparse matrix @var{S}. For a\n\ -non-symmetric matrix @var{S}, @code{@var{S}(:,@var{p})} tends to have\n\ -sparser LU@tie{}factors than @var{S}. The Cholesky@tie{}factorization of\n\ -@code{@var{S}(:,@var{p})' * @var{S}(:,@var{p})} also tends to be sparser\n\ -than that of @code{@var{S}' * @var{S}}.\n\ -\n\ -@var{knobs} is an optional one- to three-element input vector. If @var{S}\n\ -is m-by-n, then rows with more than @code{max(16,@var{knobs}(1)*sqrt(n))}\n\ -entries are ignored. Columns with more than\n\ -@code{max (16,@var{knobs}(2)*sqrt(min(m,n)))} entries are removed prior to\n\ -ordering, and ordered last in the output permutation @var{p}. Only\n\ -completely dense rows or columns are removed if @code{@var{knobs}(1)} and\n\ -@code{@var{knobs}(2)} are < 0, respectively. If @code{@var{knobs}(3)} is\n\ -nonzero, @var{stats} and @var{knobs} are printed. The default is\n\ -@code{@var{knobs} = [10 10 0]}. Note that @var{knobs} differs from earlier\n\ -versions of colamd.\n\ -\n\ -@var{stats} is an optional 20-element output vector that provides data\n\ -about the ordering and the validity of the input matrix @var{S}. Ordering\n\ -statistics are in @code{@var{stats}(1:3)}. @code{@var{stats}(1)} and\n\ -@code{@var{stats}(2)} are the number of dense or empty rows and columns\n\ -ignored by @sc{colamd} and @code{@var{stats}(3)} is the number of garbage\n\ -collections performed on the internal data structure used by @sc{colamd}\n\ -(roughly of size @code{2.2 * nnz(@var{S}) + 4 * @var{m} + 7 * @var{n}}\n\ -integers).\n\ -\n\ -Octave built-in functions are intended to generate valid sparse matrices,\n\ -with no duplicate entries, with ascending row indices of the nonzeros\n\ -in each column, with a non-negative number of entries in each column (!)\n\ -and so on. If a matrix is invalid, then @sc{colamd} may or may not be able\n\ -to continue. If there are duplicate entries (a row index appears two or\n\ -more times in the same column) or if the row indices in a column are out\n\ -of order, then @sc{colamd} can correct these errors by ignoring the\n\ -duplicate entries and sorting each column of its internal copy of the\n\ -matrix @var{S} (the input matrix @var{S} is not repaired, however). If a\n\ -matrix is invalid in other ways then @sc{colamd} cannot continue, an error\n\ -message is printed, and no output arguments (@var{p} or @var{stats}) are\n\ -returned.\n\ -@sc{colamd} is thus a simple way to check a sparse matrix to see if it's\n\ -valid.\n\ -\n\ -@code{@var{stats}(4:7)} provide information if @sc{colamd} was able to\n\ -continue. The matrix is OK if @code{@var{stats}(4)} is zero, or 1 if\n\ -invalid. @code{@var{stats}(5)} is the rightmost column index that is\n\ -unsorted or contains duplicate entries, or zero if no such column exists.\n\ -@code{@var{stats}(6)} is the last seen duplicate or out-of-order row\n\ -index in the column index given by @code{@var{stats}(5)}, or zero if no\n\ -such row index exists. @code{@var{stats}(7)} is the number of duplicate\n\ -or out-of-order row indices. @code{@var{stats}(8:20)} is always zero in\n\ -the current version of @sc{colamd} (reserved for future use).\n\ -\n\ -The ordering is followed by a column elimination tree post-ordering.\n\ -\n\ -The authors of the code itself are @nospell{Stefan I. Larimore} and\n\ -@nospell{Timothy A. Davis @email{davis@@cise.ufl.edu}}, University of Florida. The algorithm was developed in collaboration with @nospell{John Gilbert},\n\ -Xerox PARC, and @nospell{Esmond Ng}, Oak Ridge National Laboratory. (see\n\ -@url{http://www.cise.ufl.edu/research/sparse/colamd})\n\ -@seealso{colperm, symamd, ccolamd}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{p} =} colamd (@var{S}) +@deftypefnx {} {@var{p} =} colamd (@var{S}, @var{knobs}) +@deftypefnx {} {[@var{p}, @var{stats}] =} colamd (@var{S}) +@deftypefnx {} {[@var{p}, @var{stats}] =} colamd (@var{S}, @var{knobs}) + +Compute the column approximate minimum degree permutation. + +@code{@var{p} = colamd (@var{S})} returns the column approximate minimum +degree permutation vector for the sparse matrix @var{S}. For a +non-symmetric matrix @var{S}, @code{@var{S}(:,@var{p})} tends to have +sparser LU@tie{}factors than @var{S}. The Cholesky@tie{}factorization of +@code{@var{S}(:,@var{p})' * @var{S}(:,@var{p})} also tends to be sparser +than that of @code{@var{S}' * @var{S}}. + +@var{knobs} is an optional one- to three-element input vector. If @var{S} +is m-by-n, then rows with more than @code{max(16,@var{knobs}(1)*sqrt(n))} +entries are ignored. Columns with more than +@code{max (16,@var{knobs}(2)*sqrt(min(m,n)))} entries are removed prior to +ordering, and ordered last in the output permutation @var{p}. Only +completely dense rows or columns are removed if @code{@var{knobs}(1)} and +@code{@var{knobs}(2)} are < 0, respectively. If @code{@var{knobs}(3)} is +nonzero, @var{stats} and @var{knobs} are printed. The default is +@code{@var{knobs} = [10 10 0]}. Note that @var{knobs} differs from earlier +versions of colamd. + +@var{stats} is an optional 20-element output vector that provides data +about the ordering and the validity of the input matrix @var{S}. Ordering +statistics are in @code{@var{stats}(1:3)}. @code{@var{stats}(1)} and +@code{@var{stats}(2)} are the number of dense or empty rows and columns +ignored by @sc{colamd} and @code{@var{stats}(3)} is the number of garbage +collections performed on the internal data structure used by @sc{colamd} +(roughly of size @code{2.2 * nnz(@var{S}) + 4 * @var{m} + 7 * @var{n}} +integers). + +Octave built-in functions are intended to generate valid sparse matrices, +with no duplicate entries, with ascending row indices of the nonzeros +in each column, with a non-negative number of entries in each column (!) +and so on. If a matrix is invalid, then @sc{colamd} may or may not be able +to continue. If there are duplicate entries (a row index appears two or +more times in the same column) or if the row indices in a column are out +of order, then @sc{colamd} can correct these errors by ignoring the +duplicate entries and sorting each column of its internal copy of the +matrix @var{S} (the input matrix @var{S} is not repaired, however). If a +matrix is invalid in other ways then @sc{colamd} cannot continue, an error +message is printed, and no output arguments (@var{p} or @var{stats}) are +returned. +@sc{colamd} is thus a simple way to check a sparse matrix to see if it's +valid. + +@code{@var{stats}(4:7)} provide information if @sc{colamd} was able to +continue. The matrix is OK if @code{@var{stats}(4)} is zero, or 1 if +invalid. @code{@var{stats}(5)} is the rightmost column index that is +unsorted or contains duplicate entries, or zero if no such column exists. +@code{@var{stats}(6)} is the last seen duplicate or out-of-order row +index in the column index given by @code{@var{stats}(5)}, or zero if no +such row index exists. @code{@var{stats}(7)} is the number of duplicate +or out-of-order row indices. @code{@var{stats}(8:20)} is always zero in +the current version of @sc{colamd} (reserved for future use). + +The ordering is followed by a column elimination tree post-ordering. + +The authors of the code itself are @nospell{Stefan I. Larimore} and +@nospell{Timothy A. Davis @email{davis@@cise.ufl.edu}}, University of Florida. The algorithm was developed in collaboration with @nospell{John Gilbert}, +Xerox PARC, and @nospell{Esmond Ng}, Oak Ridge National Laboratory. (see +@url{http://www.cise.ufl.edu/research/sparse/colamd}) +@seealso{colperm, symamd, ccolamd} +@end deftypefn */) { #if defined (HAVE_COLAMD) @@ -452,69 +452,69 @@ } DEFUN_DLD (symamd, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{p} =} symamd (@var{S})\n\ -@deftypefnx {} {@var{p} =} symamd (@var{S}, @var{knobs})\n\ -@deftypefnx {} {[@var{p}, @var{stats}] =} symamd (@var{S})\n\ -@deftypefnx {} {[@var{p}, @var{stats}] =} symamd (@var{S}, @var{knobs})\n\ -\n\ -For a symmetric positive definite matrix @var{S}, returns the permutation\n\ -vector p such that @code{@var{S}(@var{p}, @var{p})} tends to have a\n\ -sparser Cholesky@tie{}factor than @var{S}.\n\ -\n\ -Sometimes @code{symamd} works well for symmetric indefinite matrices too.\n\ -The matrix @var{S} is assumed to be symmetric; only the strictly lower\n\ -triangular part is referenced. @var{S} must be square.\n\ -\n\ -@var{knobs} is an optional one- to two-element input vector. If @var{S} is\n\ -n-by-n, then rows and columns with more than\n\ -@code{max (16,@var{knobs}(1)*sqrt(n))} entries are removed prior to\n\ -ordering, and ordered last in the output permutation @var{p}. No\n\ -rows/columns are removed if @code{@var{knobs}(1) < 0}. If\n\ -@code{@var{knobs} (2)} is nonzero, @code{stats} and @var{knobs} are\n\ -printed. The default is @code{@var{knobs} = [10 0]}. Note that\n\ -@var{knobs} differs from earlier versions of @code{symamd}.\n\ -\n\ -@var{stats} is an optional 20-element output vector that provides data\n\ -about the ordering and the validity of the input matrix @var{S}. Ordering\n\ -statistics are in @code{@var{stats}(1:3)}.\n\ -@code{@var{stats}(1) = @var{stats}(2)} is the number of dense or empty rows\n\ -and columns ignored by SYMAMD and @code{@var{stats}(3)} is the number of\n\ -garbage collections performed on the internal data structure used by SYMAMD\n\ -(roughly of size @code{8.4 * nnz (tril (@var{S}, -1)) + 9 * @var{n}}\n\ -integers).\n\ -\n\ -Octave built-in functions are intended to generate valid sparse matrices,\n\ -with no duplicate entries, with ascending row indices of the nonzeros\n\ -in each column, with a non-negative number of entries in each column (!)\n\ -and so on. If a matrix is invalid, then SYMAMD may or may not be able\n\ -to continue. If there are duplicate entries (a row index appears two or\n\ -more times in the same column) or if the row indices in a column are out\n\ -of order, then SYMAMD can correct these errors by ignoring the duplicate\n\ -entries and sorting each column of its internal copy of the matrix S (the\n\ -input matrix S is not repaired, however). If a matrix is invalid in\n\ -other ways then SYMAMD cannot continue, an error message is printed, and\n\ -no output arguments (@var{p} or @var{stats}) are returned. SYMAMD is\n\ -thus a simple way to check a sparse matrix to see if it's valid.\n\ -\n\ -@code{@var{stats}(4:7)} provide information if SYMAMD was able to\n\ -continue. The matrix is OK if @code{@var{stats} (4)} is zero, or 1\n\ -if invalid. @code{@var{stats}(5)} is the rightmost column index that\n\ -is unsorted or contains duplicate entries, or zero if no such column\n\ -exists. @code{@var{stats}(6)} is the last seen duplicate or out-of-order\n\ -row index in the column index given by @code{@var{stats}(5)}, or zero\n\ -if no such row index exists. @code{@var{stats}(7)} is the number of\n\ -duplicate or out-of-order row indices. @code{@var{stats}(8:20)} is\n\ -always zero in the current version of SYMAMD (reserved for future use).\n\ -\n\ -The ordering is followed by a column elimination tree post-ordering.\n\ -\n\ -The authors of the code itself are @nospell{Stefan I. Larimore} and\n\ -@nospell{Timothy A. Davis @email{davis@@cise.ufl.edu}}, University of Florida. The algorithm was developed in collaboration with @nospell{John Gilbert},\n\ -Xerox PARC, and @nospell{Esmond Ng}, Oak Ridge National Laboratory. (see\n\ -@url{http://www.cise.ufl.edu/research/sparse/colamd})\n\ -@seealso{colperm, colamd}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{p} =} symamd (@var{S}) +@deftypefnx {} {@var{p} =} symamd (@var{S}, @var{knobs}) +@deftypefnx {} {[@var{p}, @var{stats}] =} symamd (@var{S}) +@deftypefnx {} {[@var{p}, @var{stats}] =} symamd (@var{S}, @var{knobs}) + +For a symmetric positive definite matrix @var{S}, returns the permutation +vector p such that @code{@var{S}(@var{p}, @var{p})} tends to have a +sparser Cholesky@tie{}factor than @var{S}. + +Sometimes @code{symamd} works well for symmetric indefinite matrices too. +The matrix @var{S} is assumed to be symmetric; only the strictly lower +triangular part is referenced. @var{S} must be square. + +@var{knobs} is an optional one- to two-element input vector. If @var{S} is +n-by-n, then rows and columns with more than +@code{max (16,@var{knobs}(1)*sqrt(n))} entries are removed prior to +ordering, and ordered last in the output permutation @var{p}. No +rows/columns are removed if @code{@var{knobs}(1) < 0}. If +@code{@var{knobs} (2)} is nonzero, @code{stats} and @var{knobs} are +printed. The default is @code{@var{knobs} = [10 0]}. Note that +@var{knobs} differs from earlier versions of @code{symamd}. + +@var{stats} is an optional 20-element output vector that provides data +about the ordering and the validity of the input matrix @var{S}. Ordering +statistics are in @code{@var{stats}(1:3)}. +@code{@var{stats}(1) = @var{stats}(2)} is the number of dense or empty rows +and columns ignored by SYMAMD and @code{@var{stats}(3)} is the number of +garbage collections performed on the internal data structure used by SYMAMD +(roughly of size @code{8.4 * nnz (tril (@var{S}, -1)) + 9 * @var{n}} +integers). + +Octave built-in functions are intended to generate valid sparse matrices, +with no duplicate entries, with ascending row indices of the nonzeros +in each column, with a non-negative number of entries in each column (!) +and so on. If a matrix is invalid, then SYMAMD may or may not be able +to continue. If there are duplicate entries (a row index appears two or +more times in the same column) or if the row indices in a column are out +of order, then SYMAMD can correct these errors by ignoring the duplicate +entries and sorting each column of its internal copy of the matrix S (the +input matrix S is not repaired, however). If a matrix is invalid in +other ways then SYMAMD cannot continue, an error message is printed, and +no output arguments (@var{p} or @var{stats}) are returned. SYMAMD is +thus a simple way to check a sparse matrix to see if it's valid. + +@code{@var{stats}(4:7)} provide information if SYMAMD was able to +continue. The matrix is OK if @code{@var{stats} (4)} is zero, or 1 +if invalid. @code{@var{stats}(5)} is the rightmost column index that +is unsorted or contains duplicate entries, or zero if no such column +exists. @code{@var{stats}(6)} is the last seen duplicate or out-of-order +row index in the column index given by @code{@var{stats}(5)}, or zero +if no such row index exists. @code{@var{stats}(7)} is the number of +duplicate or out-of-order row indices. @code{@var{stats}(8:20)} is +always zero in the current version of SYMAMD (reserved for future use). + +The ordering is followed by a column elimination tree post-ordering. + +The authors of the code itself are @nospell{Stefan I. Larimore} and +@nospell{Timothy A. Davis @email{davis@@cise.ufl.edu}}, University of Florida. The algorithm was developed in collaboration with @nospell{John Gilbert}, +Xerox PARC, and @nospell{Esmond Ng}, Oak Ridge National Laboratory. (see +@url{http://www.cise.ufl.edu/research/sparse/colamd}) +@seealso{colperm, colamd} +@end deftypefn */) { #if defined (HAVE_COLAMD) @@ -645,22 +645,22 @@ } DEFUN_DLD (etree, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{p} =} etree (@var{S})\n\ -@deftypefnx {} {@var{p} =} etree (@var{S}, @var{typ})\n\ -@deftypefnx {} {[@var{p}, @var{q}] =} etree (@var{S}, @var{typ})\n\ -\n\ -Return the elimination tree for the matrix @var{S}.\n\ -\n\ -By default @var{S} is assumed to be symmetric and the symmetric elimination\n\ -tree is returned. The argument @var{typ} controls whether a symmetric or\n\ -column elimination tree is returned. Valid values of @var{typ} are\n\ -@qcode{\"sym\"} or @qcode{\"col\"}, for symmetric or column elimination tree\n\ -respectively.\n\ -\n\ -Called with a second argument, @code{etree} also returns the postorder\n\ -permutations on the tree.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{p} =} etree (@var{S}) +@deftypefnx {} {@var{p} =} etree (@var{S}, @var{typ}) +@deftypefnx {} {[@var{p}, @var{q}] =} etree (@var{S}, @var{typ}) + +Return the elimination tree for the matrix @var{S}. + +By default @var{S} is assumed to be symmetric and the symmetric elimination +tree is returned. The argument @var{typ} controls whether a symmetric or +column elimination tree is returned. Valid values of @var{typ} are +@qcode{"sym"} or @qcode{"col"}, for symmetric or column elimination tree +respectively. + +Called with a second argument, @code{etree} also returns the postorder +permutations on the tree. +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/dldfcn/convhulln.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/dldfcn/convhulln.cc Tue Jun 21 16:07:51 2016 -0400 @@ -74,39 +74,39 @@ #endif DEFUN_DLD (convhulln, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{h} =} convhulln (@var{pts})\n\ -@deftypefnx {} {@var{h} =} convhulln (@var{pts}, @var{options})\n\ -@deftypefnx {} {[@var{h}, @var{v}] =} convhulln (@dots{})\n\ -Compute the convex hull of the set of points @var{pts}.\n\ -\n\ -@var{pts} is a matrix of size [n, dim] containing n points in a space of\n\ -dimension dim.\n\ -\n\ -The hull @var{h} is an index vector into the set of points and specifies\n\ -which points form the enclosing hull.\n\ -\n\ -An optional second argument, which must be a string or cell array of\n\ -strings, contains options passed to the underlying qhull command. See the\n\ -documentation for the Qhull library for details\n\ -@url{http://www.qhull.org/html/qh-quick.htm#options}.\n\ -The default options depend on the dimension of the input:\n\ -\n\ -@itemize\n\ -@item 2D, 3D, 4D: @var{options} = @code{@{\"Qt\"@}}\n\ -\n\ -@item 5D and higher: @var{options} = @code{@{\"Qt\", \"Qx\"@}}\n\ -@end itemize\n\ -\n\ -If @var{options} is not present or @code{[]} then the default arguments are\n\ -used. Otherwise, @var{options} replaces the default argument list.\n\ -To append user options to the defaults it is necessary to repeat the\n\ -default arguments in @var{options}. Use a null string to pass no arguments.\n\ -\n\ -If the second output @var{v} is requested the volume of the enclosing\n\ -convex hull is calculated.\n\n\ -@seealso{convhull, delaunayn, voronoin}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{h} =} convhulln (@var{pts}) +@deftypefnx {} {@var{h} =} convhulln (@var{pts}, @var{options}) +@deftypefnx {} {[@var{h}, @var{v}] =} convhulln (@dots{}) +Compute the convex hull of the set of points @var{pts}. + +@var{pts} is a matrix of size [n, dim] containing n points in a space of +dimension dim. + +The hull @var{h} is an index vector into the set of points and specifies +which points form the enclosing hull. + +An optional second argument, which must be a string or cell array of +strings, contains options passed to the underlying qhull command. See the +documentation for the Qhull library for details +@url{http://www.qhull.org/html/qh-quick.htm#options}. +The default options depend on the dimension of the input: + +@itemize +@item 2D, 3D, 4D: @var{options} = @code{@{"Qt"@}} + +@item 5D and higher: @var{options} = @code{@{"Qt", "Qx"@}} +@end itemize + +If @var{options} is not present or @code{[]} then the default arguments are +used. Otherwise, @var{options} replaces the default argument list. +To append user options to the defaults it is necessary to repeat the +default arguments in @var{options}. Use a null string to pass no arguments. + +If the second output @var{v} is requested the volume of the enclosing +convex hull is calculated.\n +@seealso{convhull, delaunayn, voronoin} +@end deftypefn */) { #if defined (HAVE_QHULL)
--- a/libinterp/dldfcn/dmperm.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/dldfcn/dmperm.cc Tue Jun 21 16:07:51 2016 -0400 @@ -115,28 +115,28 @@ #endif DEFUN_DLD (dmperm, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{p} =} dmperm (@var{S})\n\ -@deftypefnx {} {[@var{p}, @var{q}, @var{r}, @var{S}] =} dmperm (@var{S})\n\ -\n\ -@cindex @nospell{Dulmage-Mendelsohn} decomposition\n\ -Perform a @nospell{Dulmage-Mendelsohn} permutation of the sparse matrix\n\ -@var{S}.\n\ -\n\ -With a single output argument @code{dmperm} performs the row permutations\n\ -@var{p} such that @code{@var{S}(@var{p},:)} has no zero elements on the\n\ -diagonal.\n\ -\n\ -Called with two or more output arguments, returns the row and column\n\ -permutations, such that @code{@var{S}(@var{p}, @var{q})} is in block\n\ -triangular form. The values of @var{r} and @var{S} define the boundaries\n\ -of the blocks. If @var{S} is square then @code{@var{r} == @var{S}}.\n\ -\n\ -The method used is described in: @nospell{A. Pothen & C.-J. Fan.}\n\ -@cite{Computing the Block Triangular Form of a Sparse Matrix}.\n\ -ACM Trans. Math. Software, 16(4):303-324, 1990.\n\ -@seealso{colamd, ccolamd}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{p} =} dmperm (@var{S}) +@deftypefnx {} {[@var{p}, @var{q}, @var{r}, @var{S}] =} dmperm (@var{S}) + +@cindex @nospell{Dulmage-Mendelsohn} decomposition +Perform a @nospell{Dulmage-Mendelsohn} permutation of the sparse matrix +@var{S}. + +With a single output argument @code{dmperm} performs the row permutations +@var{p} such that @code{@var{S}(@var{p},:)} has no zero elements on the +diagonal. + +Called with two or more output arguments, returns the row and column +permutations, such that @code{@var{S}(@var{p}, @var{q})} is in block +triangular form. The values of @var{r} and @var{S} define the boundaries +of the blocks. If @var{S} is square then @code{@var{r} == @var{S}}. + +The method used is described in: @nospell{A. Pothen & C.-J. Fan.} +@cite{Computing the Block Triangular Form of a Sparse Matrix}. +ACM Trans. Math. Software, 16(4):303-324, 1990. +@seealso{colamd, ccolamd} +@end deftypefn */) { #if defined (HAVE_CXSPARSE) @@ -172,19 +172,19 @@ */ DEFUN_DLD (sprank, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{p} =} sprank (@var{S})\n\ -@cindex structural rank\n\ -\n\ -Calculate the structural rank of the sparse matrix @var{S}.\n\ -\n\ -Note that only the structure of the matrix is used in this calculation based\n\ -on a @nospell{Dulmage-Mendelsohn} permutation to block triangular form. As\n\ -such the numerical rank of the matrix @var{S} is bounded by\n\ -@code{sprank (@var{S}) >= rank (@var{S})}. Ignoring floating point errors\n\ -@code{sprank (@var{S}) == rank (@var{S})}.\n\ -@seealso{dmperm}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{p} =} sprank (@var{S}) +@cindex structural rank + +Calculate the structural rank of the sparse matrix @var{S}. + +Note that only the structure of the matrix is used in this calculation based +on a @nospell{Dulmage-Mendelsohn} permutation to block triangular form. As +such the numerical rank of the matrix @var{S} is bounded by +@code{sprank (@var{S}) >= rank (@var{S})}. Ignoring floating point errors +@code{sprank (@var{S}) == rank (@var{S})}. +@seealso{dmperm} +@end deftypefn */) { #if defined (HAVE_CXSPARSE)
--- a/libinterp/dldfcn/fftw.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/dldfcn/fftw.cc Tue Jun 21 16:07:51 2016 -0400 @@ -39,102 +39,102 @@ #include "errwarn.h" DEFUN_DLD (fftw, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{method} =} fftw (\"planner\")\n\ -@deftypefnx {} {} fftw (\"planner\", @var{method})\n\ -@deftypefnx {} {@var{wisdom} =} fftw (\"dwisdom\")\n\ -@deftypefnx {} {} fftw (\"dwisdom\", @var{wisdom})\n\ -@deftypefnx {} {} fftw (\"threads\", @var{nthreads})\n\ -@deftypefnx {} {@var{nthreads} =} fftw (\"threads\")\n\ -\n\ -Manage @sc{fftw} wisdom data.\n\ -\n\ -Wisdom data can be used to significantly accelerate the calculation of the\n\ -FFTs, but implies an initial cost in its calculation. When the @sc{fftw}\n\ -libraries are initialized, they read a system wide wisdom file (typically in\n\ -@file{/etc/fftw/wisdom}), allowing wisdom to be shared between applications\n\ -other than Octave. Alternatively, the @code{fftw} function can be used to\n\ -import wisdom. For example,\n\ -\n\ -@example\n\ -@var{wisdom} = fftw (\"dwisdom\")\n\ -@end example\n\ -\n\ -@noindent\n\ -will save the existing wisdom used by Octave to the string @var{wisdom}.\n\ -This string can then be saved to a file and restored using the @code{save}\n\ -and @code{load} commands respectively. This existing wisdom can be\n\ -re-imported as follows\n\ -\n\ -@example\n\ -fftw (\"dwisdom\", @var{wisdom})\n\ -@end example\n\ -\n\ -If @var{wisdom} is an empty string, then the wisdom used is cleared.\n\ -\n\ -During the calculation of Fourier transforms further wisdom is generated.\n\ -The fashion in which this wisdom is generated is also controlled by\n\ -the @code{fftw} function. There are five different manners in which the\n\ -wisdom can be treated:\n\ -\n\ -@table @asis\n\ -@item @qcode{\"estimate\"}\n\ -Specifies that no run-time measurement of the optimal means of\n\ -calculating a particular is performed, and a simple heuristic is used\n\ -to pick a (probably sub-optimal) plan. The advantage of this method is\n\ -that there is little or no overhead in the generation of the plan, which\n\ -is appropriate for a Fourier transform that will be calculated once.\n\ -\n\ -@item @qcode{\"measure\"}\n\ -In this case a range of algorithms to perform the transform is considered\n\ -and the best is selected based on their execution time.\n\ -\n\ -@item @qcode{\"patient\"}\n\ -Similar to @qcode{\"measure\"}, but a wider range of algorithms is\n\ -considered.\n\ -\n\ -@item @qcode{\"exhaustive\"}\n\ -Like @qcode{\"measure\"}, but all possible algorithms that may be used to\n\ -treat the transform are considered.\n\ -\n\ -@item @qcode{\"hybrid\"}\n\ -As run-time measurement of the algorithm can be expensive, this is a\n\ -compromise where @qcode{\"measure\"} is used for transforms up to the size\n\ -of 8192 and beyond that the @qcode{\"estimate\"} method is used.\n\ -@end table\n\ -\n\ -The default method is @qcode{\"estimate\"}. The current method can\n\ -be queried with\n\ -\n\ -@example\n\ -@var{method} = fftw (\"planner\")\n\ -@end example\n\ -\n\ -@noindent\n\ -or set by using\n\ -\n\ -@example\n\ -fftw (\"planner\", @var{method})\n\ -@end example\n\ -\n\ -Note that calculated wisdom will be lost when restarting Octave. However,\n\ -the wisdom data can be reloaded if it is saved to a file as described\n\ -above. Saved wisdom files should not be used on different platforms since\n\ -they will not be efficient and the point of calculating the wisdom is lost.\n\ -\n\ -The number of threads used for computing the plans and executing the\n\ -transforms can be set with\n\ -\n\ -@example\n\ -fftw (\"threads\", @var{NTHREADS})\n\ -@end example\n\ -\n\ -Note that octave must be compiled with multi-threaded @sc{fftw} support for\n\ -this feature. The number of processors available to the current process is\n\ -used per default.\n\ -\n\ -@seealso{fft, ifft, fft2, ifft2, fftn, ifftn}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{method} =} fftw ("planner") +@deftypefnx {} {} fftw ("planner", @var{method}) +@deftypefnx {} {@var{wisdom} =} fftw ("dwisdom") +@deftypefnx {} {} fftw ("dwisdom", @var{wisdom}) +@deftypefnx {} {} fftw ("threads", @var{nthreads}) +@deftypefnx {} {@var{nthreads} =} fftw ("threads") + +Manage @sc{fftw} wisdom data. + +Wisdom data can be used to significantly accelerate the calculation of the +FFTs, but implies an initial cost in its calculation. When the @sc{fftw} +libraries are initialized, they read a system wide wisdom file (typically in +@file{/etc/fftw/wisdom}), allowing wisdom to be shared between applications +other than Octave. Alternatively, the @code{fftw} function can be used to +import wisdom. For example, + +@example +@var{wisdom} = fftw ("dwisdom") +@end example + +@noindent +will save the existing wisdom used by Octave to the string @var{wisdom}. +This string can then be saved to a file and restored using the @code{save} +and @code{load} commands respectively. This existing wisdom can be +re-imported as follows + +@example +fftw ("dwisdom", @var{wisdom}) +@end example + +If @var{wisdom} is an empty string, then the wisdom used is cleared. + +During the calculation of Fourier transforms further wisdom is generated. +The fashion in which this wisdom is generated is also controlled by +the @code{fftw} function. There are five different manners in which the +wisdom can be treated: + +@table @asis +@item @qcode{"estimate"} +Specifies that no run-time measurement of the optimal means of +calculating a particular is performed, and a simple heuristic is used +to pick a (probably sub-optimal) plan. The advantage of this method is +that there is little or no overhead in the generation of the plan, which +is appropriate for a Fourier transform that will be calculated once. + +@item @qcode{"measure"} +In this case a range of algorithms to perform the transform is considered +and the best is selected based on their execution time. + +@item @qcode{"patient"} +Similar to @qcode{"measure"}, but a wider range of algorithms is +considered. + +@item @qcode{"exhaustive"} +Like @qcode{"measure"}, but all possible algorithms that may be used to +treat the transform are considered. + +@item @qcode{"hybrid"} +As run-time measurement of the algorithm can be expensive, this is a +compromise where @qcode{"measure"} is used for transforms up to the size +of 8192 and beyond that the @qcode{"estimate"} method is used. +@end table + +The default method is @qcode{"estimate"}. The current method can +be queried with + +@example +@var{method} = fftw ("planner") +@end example + +@noindent +or set by using + +@example +fftw ("planner", @var{method}) +@end example + +Note that calculated wisdom will be lost when restarting Octave. However, +the wisdom data can be reloaded if it is saved to a file as described +above. Saved wisdom files should not be used on different platforms since +they will not be efficient and the point of calculating the wisdom is lost. + +The number of threads used for computing the plans and executing the +transforms can be set with + +@example +fftw ("threads", @var{NTHREADS}) +@end example + +Note that octave must be compiled with multi-threaded @sc{fftw} support for +this feature. The number of processors available to the current process is +used per default. + +@seealso{fft, ifft, fft2, ifft2, fftn, ifftn} +@end deftypefn */) { #if defined (HAVE_FFTW)
--- a/libinterp/dldfcn/qr.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/dldfcn/qr.cc Tue Jun 21 16:07:51 2016 -0400 @@ -75,131 +75,131 @@ // that R = triu (qr (X)) DEFUN_DLD (qr, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{Q}, @var{R}, @var{P}] =} qr (@var{A})\n\ -@deftypefnx {} {[@var{Q}, @var{R}, @var{P}] =} qr (@var{A}, '0')\n\ -@deftypefnx {} {[@var{C}, @var{R}] =} qr (@var{A}, @var{B})\n\ -@deftypefnx {} {[@var{C}, @var{R}] =} qr (@var{A}, @var{B}, '0')\n\ -@cindex QR factorization\n\ -Compute the QR@tie{}factorization of @var{A}, using standard @sc{lapack}\n\ -subroutines.\n\ -\n\ -For example, given the matrix @code{@var{A} = [1, 2; 3, 4]},\n\ -\n\ -@example\n\ -[@var{Q}, @var{R}] = qr (@var{A})\n\ -@end example\n\ -\n\ -@noindent\n\ -returns\n\ -\n\ -@example\n\ -@group\n\ -@var{Q} =\n\ -\n\ - -0.31623 -0.94868\n\ - -0.94868 0.31623\n\ -\n\ -@var{R} =\n\ -\n\ - -3.16228 -4.42719\n\ - 0.00000 -0.63246\n\ -@end group\n\ -@end example\n\ -\n\ -The @code{qr} factorization has applications in the solution of least\n\ -squares problems\n\ -@tex\n\ -$$\n\ -\\min_x \\left\\Vert A x - b \\right\\Vert_2\n\ -$$\n\ -@end tex\n\ -@ifnottex\n\ -\n\ -@example\n\ -min norm(A x - b)\n\ -@end example\n\ -\n\ -@end ifnottex\n\ -for overdetermined systems of equations (i.e.,\n\ -@tex\n\ -$A$\n\ -@end tex\n\ -@ifnottex\n\ -@var{A}\n\ -@end ifnottex\n\ -is a tall, thin matrix). The QR@tie{}factorization is\n\ -@tex\n\ -$QR = A$ where $Q$ is an orthogonal matrix and $R$ is upper triangular.\n\ -@end tex\n\ -@ifnottex\n\ -@code{@var{Q} * @var{R} = @var{A}} where @var{Q} is an orthogonal matrix and\n\ -@var{R} is upper triangular.\n\ -@end ifnottex\n\ -\n\ -If given a second argument of @qcode{'0'}, @code{qr} returns an\n\ -economy-sized QR@tie{}factorization, omitting zero rows of @var{R} and the\n\ -corresponding columns of @var{Q}.\n\ -\n\ -If the matrix @var{A} is full, the permuted QR@tie{}factorization\n\ -@code{[@var{Q}, @var{R}, @var{P}] = qr (@var{A})} forms the\n\ -QR@tie{}factorization such that the diagonal entries of @var{R} are\n\ -decreasing in magnitude order. For example, given the matrix\n\ -@code{a = [1, 2; 3, 4]},\n\ -\n\ -@example\n\ -[@var{Q}, @var{R}, @var{P}] = qr (@var{A})\n\ -@end example\n\ -\n\ -@noindent\n\ -returns\n\ -\n\ -@example\n\ -@group\n\ -@var{Q} =\n\ -\n\ - -0.44721 -0.89443\n\ - -0.89443 0.44721\n\ -\n\ -@var{R} =\n\ -\n\ - -4.47214 -3.13050\n\ - 0.00000 0.44721\n\ -\n\ -@var{P} =\n\ -\n\ - 0 1\n\ - 1 0\n\ -@end group\n\ -@end example\n\ -\n\ -The permuted @code{qr} factorization\n\ -@code{[@var{Q}, @var{R}, @var{P}] = qr (@var{A})} factorization allows the\n\ -construction of an orthogonal basis of @code{span (A)}.\n\ -\n\ -If the matrix @var{A} is sparse, then compute the sparse\n\ -QR@tie{}factorization of @var{A}, using @sc{CSparse}. As the matrix @var{Q}\n\ -is in general a full matrix, this function returns the @var{Q}-less\n\ -factorization @var{R} of @var{A}, such that\n\ -@code{@var{R} = chol (@var{A}' * @var{A})}.\n\ -\n\ -If the final argument is the scalar @code{0} and the number of rows is\n\ -larger than the number of columns, then an economy factorization is\n\ -returned. That is @var{R} will have only @code{size (@var{A},1)} rows.\n\ -\n\ -If an additional matrix @var{B} is supplied, then @code{qr} returns\n\ -@var{C}, where @code{@var{C} = @var{Q}' * @var{B}}. This allows the\n\ -least squares approximation of @code{@var{A} \\ @var{B}} to be calculated\n\ -as\n\ -\n\ -@example\n\ -@group\n\ -[@var{C}, @var{R}] = qr (@var{A}, @var{B})\n\ -x = @var{R} \\ @var{C}\n\ -@end group\n\ -@end example\n\ -@seealso{chol, hess, lu, qz, schur, svd, qrupdate, qrinsert, qrdelete, qrshift}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{Q}, @var{R}, @var{P}] =} qr (@var{A}) +@deftypefnx {} {[@var{Q}, @var{R}, @var{P}] =} qr (@var{A}, '0') +@deftypefnx {} {[@var{C}, @var{R}] =} qr (@var{A}, @var{B}) +@deftypefnx {} {[@var{C}, @var{R}] =} qr (@var{A}, @var{B}, '0') +@cindex QR factorization +Compute the QR@tie{}factorization of @var{A}, using standard @sc{lapack} +subroutines. + +For example, given the matrix @code{@var{A} = [1, 2; 3, 4]}, + +@example +[@var{Q}, @var{R}] = qr (@var{A}) +@end example + +@noindent +returns + +@example +@group +@var{Q} = + + -0.31623 -0.94868 + -0.94868 0.31623 + +@var{R} = + + -3.16228 -4.42719 + 0.00000 -0.63246 +@end group +@end example + +The @code{qr} factorization has applications in the solution of least +squares problems +@tex +$$ +\min_x \left\Vert A x - b \right\Vert_2 +$$ +@end tex +@ifnottex + +@example +min norm(A x - b) +@end example + +@end ifnottex +for overdetermined systems of equations (i.e., +@tex +$A$ +@end tex +@ifnottex +@var{A} +@end ifnottex +is a tall, thin matrix). The QR@tie{}factorization is +@tex +$QR = A$ where $Q$ is an orthogonal matrix and $R$ is upper triangular. +@end tex +@ifnottex +@code{@var{Q} * @var{R} = @var{A}} where @var{Q} is an orthogonal matrix and +@var{R} is upper triangular. +@end ifnottex + +If given a second argument of @qcode{'0'}, @code{qr} returns an +economy-sized QR@tie{}factorization, omitting zero rows of @var{R} and the +corresponding columns of @var{Q}. + +If the matrix @var{A} is full, the permuted QR@tie{}factorization +@code{[@var{Q}, @var{R}, @var{P}] = qr (@var{A})} forms the +QR@tie{}factorization such that the diagonal entries of @var{R} are +decreasing in magnitude order. For example, given the matrix +@code{a = [1, 2; 3, 4]}, + +@example +[@var{Q}, @var{R}, @var{P}] = qr (@var{A}) +@end example + +@noindent +returns + +@example +@group +@var{Q} = + + -0.44721 -0.89443 + -0.89443 0.44721 + +@var{R} = + + -4.47214 -3.13050 + 0.00000 0.44721 + +@var{P} = + + 0 1 + 1 0 +@end group +@end example + +The permuted @code{qr} factorization +@code{[@var{Q}, @var{R}, @var{P}] = qr (@var{A})} factorization allows the +construction of an orthogonal basis of @code{span (A)}. + +If the matrix @var{A} is sparse, then compute the sparse +QR@tie{}factorization of @var{A}, using @sc{CSparse}. As the matrix @var{Q} +is in general a full matrix, this function returns the @var{Q}-less +factorization @var{R} of @var{A}, such that +@code{@var{R} = chol (@var{A}' * @var{A})}. + +If the final argument is the scalar @code{0} and the number of rows is +larger than the number of columns, then an economy factorization is +returned. That is @var{R} will have only @code{size (@var{A},1)} rows. + +If an additional matrix @var{B} is supplied, then @code{qr} returns +@var{C}, where @code{@var{C} = @var{Q}' * @var{B}}. This allows the +least squares approximation of @code{@var{A} \ @var{B}} to be calculated +as + +@example +@group +[@var{C}, @var{R}] = qr (@var{A}, @var{B}) +x = @var{R} \ @var{C} +@end group +@end example +@seealso{chol, hess, lu, qz, schur, svd, qrupdate, qrinsert, qrdelete, qrshift} +@end deftypefn */) { int nargin = args.length (); @@ -727,22 +727,22 @@ } DEFUN_DLD (qrupdate, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{Q1}, @var{R1}] =} qrupdate (@var{Q}, @var{R}, @var{u}, @var{v})\n\ -Given a QR@tie{}factorization of a real or complex matrix\n\ -@w{@var{A} = @var{Q}*@var{R}}, @var{Q}@tie{}unitary and\n\ -@var{R}@tie{}upper trapezoidal, return the QR@tie{}factorization of\n\ -@w{@var{A} + @var{u}*@var{v}'}, where @var{u} and @var{v} are column vectors\n\ -(rank-1 update) or matrices with equal number of columns\n\ -(rank-k update). Notice that the latter case is done as a sequence of\n\ -rank-1 updates; thus, for k large enough, it will be both faster and more\n\ -accurate to recompute the factorization from scratch.\n\ -\n\ -The QR@tie{}factorization supplied may be either full (Q is square) or\n\ -economized (R is square).\n\ -\n\ -@seealso{qr, qrinsert, qrdelete, qrshift}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{Q1}, @var{R1}] =} qrupdate (@var{Q}, @var{R}, @var{u}, @var{v}) +Given a QR@tie{}factorization of a real or complex matrix +@w{@var{A} = @var{Q}*@var{R}}, @var{Q}@tie{}unitary and +@var{R}@tie{}upper trapezoidal, return the QR@tie{}factorization of +@w{@var{A} + @var{u}*@var{v}'}, where @var{u} and @var{v} are column vectors +(rank-1 update) or matrices with equal number of columns +(rank-k update). Notice that the latter case is done as a sequence of +rank-1 updates; thus, for k large enough, it will be both faster and more +accurate to recompute the factorization from scratch. + +The QR@tie{}factorization supplied may be either full (Q is square) or +economized (R is square). + +@seealso{qr, qrinsert, qrdelete, qrshift} +@end deftypefn */) { octave_value_list retval; @@ -889,30 +889,30 @@ */ DEFUN_DLD (qrinsert, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{Q1}, @var{R1}] =} qrinsert (@var{Q}, @var{R}, @var{j}, @var{x}, @var{orient})\n\ -Given a QR@tie{}factorization of a real or complex matrix\n\ -@w{@var{A} = @var{Q}*@var{R}}, @var{Q}@tie{}unitary and\n\ -@var{R}@tie{}upper trapezoidal, return the QR@tie{}factorization of\n\ -@w{[A(:,1:j-1) x A(:,j:n)]}, where @var{u} is a column vector to be inserted\n\ -into @var{A} (if @var{orient} is @qcode{\"col\"}), or the\n\ -QR@tie{}factorization of @w{[A(1:j-1,:);x;A(:,j:n)]}, where @var{x} is a row\n\ -vector to be inserted into @var{A} (if @var{orient} is @qcode{\"row\"}).\n\ -\n\ -The default value of @var{orient} is @qcode{\"col\"}. If @var{orient} is\n\ -@qcode{\"col\"}, @var{u} may be a matrix and @var{j} an index vector\n\ -resulting in the QR@tie{}factorization of a matrix @var{B} such that\n\ -@w{B(:,@var{j})} gives @var{u} and @w{B(:,@var{j}) = []} gives @var{A}.\n\ -Notice that the latter case is done as a sequence of k insertions;\n\ -thus, for k large enough, it will be both faster and more accurate to\n\ -recompute the factorization from scratch.\n\ -\n\ -If @var{orient} is @qcode{\"col\"}, the QR@tie{}factorization supplied may\n\ -be either full (Q is square) or economized (R is square).\n\ -\n\ -If @var{orient} is @qcode{\"row\"}, full factorization is needed.\n\ -@seealso{qr, qrupdate, qrdelete, qrshift}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{Q1}, @var{R1}] =} qrinsert (@var{Q}, @var{R}, @var{j}, @var{x}, @var{orient}) +Given a QR@tie{}factorization of a real or complex matrix +@w{@var{A} = @var{Q}*@var{R}}, @var{Q}@tie{}unitary and +@var{R}@tie{}upper trapezoidal, return the QR@tie{}factorization of +@w{[A(:,1:j-1) x A(:,j:n)]}, where @var{u} is a column vector to be inserted +into @var{A} (if @var{orient} is @qcode{"col"}), or the +QR@tie{}factorization of @w{[A(1:j-1,:);x;A(:,j:n)]}, where @var{x} is a row +vector to be inserted into @var{A} (if @var{orient} is @qcode{"row"}). + +The default value of @var{orient} is @qcode{"col"}. If @var{orient} is +@qcode{"col"}, @var{u} may be a matrix and @var{j} an index vector +resulting in the QR@tie{}factorization of a matrix @var{B} such that +@w{B(:,@var{j})} gives @var{u} and @w{B(:,@var{j}) = []} gives @var{A}. +Notice that the latter case is done as a sequence of k insertions; +thus, for k large enough, it will be both faster and more accurate to +recompute the factorization from scratch. + +If @var{orient} is @qcode{"col"}, the QR@tie{}factorization supplied may +be either full (Q is square) or economized (R is square). + +If @var{orient} is @qcode{"row"}, full factorization is needed. +@seealso{qr, qrupdate, qrdelete, qrshift} +@end deftypefn */) { int nargin = args.length (); @@ -1085,30 +1085,30 @@ */ DEFUN_DLD (qrdelete, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{Q1}, @var{R1}] =} qrdelete (@var{Q}, @var{R}, @var{j}, @var{orient})\n\ -Given a QR@tie{}factorization of a real or complex matrix\n\ -@w{@var{A} = @var{Q}*@var{R}}, @var{Q}@tie{}unitary and\n\ -@var{R}@tie{}upper trapezoidal, return the QR@tie{}factorization of\n\ -@w{[A(:,1:j-1) A(:,j+1:n)]}, i.e., @var{A} with one column deleted\n\ -(if @var{orient} is @qcode{\"col\"}), or the QR@tie{}factorization of\n\ -@w{[A(1:j-1,:);A(j+1:n,:)]}, i.e., @var{A} with one row deleted (if\n\ -@var{orient} is @qcode{\"row\"}).\n\ -\n\ -The default value of @var{orient} is @qcode{\"col\"}.\n\ -\n\ -If @var{orient} is @qcode{\"col\"}, @var{j} may be an index vector\n\ -resulting in the QR@tie{}factorization of a matrix @var{B} such that\n\ -@w{A(:,@var{j}) = []} gives @var{B}. Notice that the latter case is done as\n\ -a sequence of k deletions; thus, for k large enough, it will be both faster\n\ -and more accurate to recompute the factorization from scratch.\n\ -\n\ -If @var{orient} is @qcode{\"col\"}, the QR@tie{}factorization supplied may\n\ -be either full (Q is square) or economized (R is square).\n\ -\n\ -If @var{orient} is @qcode{\"row\"}, full factorization is needed.\n\ -@seealso{qr, qrupdate, qrinsert, qrshift}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{Q1}, @var{R1}] =} qrdelete (@var{Q}, @var{R}, @var{j}, @var{orient}) +Given a QR@tie{}factorization of a real or complex matrix +@w{@var{A} = @var{Q}*@var{R}}, @var{Q}@tie{}unitary and +@var{R}@tie{}upper trapezoidal, return the QR@tie{}factorization of +@w{[A(:,1:j-1) A(:,j+1:n)]}, i.e., @var{A} with one column deleted +(if @var{orient} is @qcode{"col"}), or the QR@tie{}factorization of +@w{[A(1:j-1,:);A(j+1:n,:)]}, i.e., @var{A} with one row deleted (if +@var{orient} is @qcode{"row"}). + +The default value of @var{orient} is @qcode{"col"}. + +If @var{orient} is @qcode{"col"}, @var{j} may be an index vector +resulting in the QR@tie{}factorization of a matrix @var{B} such that +@w{A(:,@var{j}) = []} gives @var{B}. Notice that the latter case is done as +a sequence of k deletions; thus, for k large enough, it will be both faster +and more accurate to recompute the factorization from scratch. + +If @var{orient} is @qcode{"col"}, the QR@tie{}factorization supplied may +be either full (Q is square) or economized (R is square). + +If @var{orient} is @qcode{"row"}, full factorization is needed. +@seealso{qr, qrupdate, qrinsert, qrshift} +@end deftypefn */) { int nargin = args.length (); @@ -1330,18 +1330,18 @@ */ DEFUN_DLD (qrshift, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{Q1}, @var{R1}] =} qrshift (@var{Q}, @var{R}, @var{i}, @var{j})\n\ -Given a QR@tie{}factorization of a real or complex matrix\n\ -@w{@var{A} = @var{Q}*@var{R}}, @var{Q}@tie{}unitary and\n\ -@var{R}@tie{}upper trapezoidal, return the QR@tie{}factorization\n\ -of @w{@var{A}(:,p)}, where @w{p} is the permutation @*\n\ -@code{p = [1:i-1, shift(i:j, 1), j+1:n]} if @w{@var{i} < @var{j}} @*\n\ - or @*\n\ -@code{p = [1:j-1, shift(j:i,-1), i+1:n]} if @w{@var{j} < @var{i}}. @*\n\ -\n\ -@seealso{qr, qrupdate, qrinsert, qrdelete}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{Q1}, @var{R1}] =} qrshift (@var{Q}, @var{R}, @var{i}, @var{j}) +Given a QR@tie{}factorization of a real or complex matrix +@w{@var{A} = @var{Q}*@var{R}}, @var{Q}@tie{}unitary and +@var{R}@tie{}upper trapezoidal, return the QR@tie{}factorization +of @w{@var{A}(:,p)}, where @w{p} is the permutation @* +@code{p = [1:i-1, shift(i:j, 1), j+1:n]} if @w{@var{i} < @var{j}} @* + or @* +@code{p = [1:j-1, shift(j:i,-1), i+1:n]} if @w{@var{j} < @var{i}}. @* + +@seealso{qr, qrupdate, qrinsert, qrdelete} +@end deftypefn */) { if (args.length () != 4) print_usage ();
--- a/libinterp/dldfcn/symbfact.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/dldfcn/symbfact.cc Tue Jun 21 16:07:51 2016 -0400 @@ -40,67 +40,67 @@ #include "utils.h" DEFUN_DLD (symbfact, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {[@var{count}, @var{h}, @var{parent}, @var{post}, @var{R}] =} symbfact (@var{S})\n\ -@deftypefnx {} {[@dots{}] =} symbfact (@var{S}, @var{typ})\n\ -@deftypefnx {} {[@dots{}] =} symbfact (@var{S}, @var{typ}, @var{mode})\n\ -\n\ -Perform a symbolic factorization analysis of the sparse matrix @var{S}.\n\ -\n\ -The input variables are\n\ -\n\ -@table @var\n\ -@item S\n\ -@var{S} is a real or complex sparse matrix.\n\ -\n\ -@item typ\n\ -Is the type of the factorization and can be one of\n\ -\n\ -@table @asis\n\ -@item @qcode{\"sym\"} (default)\n\ -Factorize @var{S}. Assumes @var{S} is symmetric and uses the upper\n\ -triangular portion of the matrix.\n\ -\n\ -@item @qcode{\"col\"}\n\ -Factorize @tcode{@var{S}' * @var{S}}.\n\ -\n\ -@item @qcode{\"row\"}\n\ -Factorize @tcode{@var{S} * @var{S}'}.\n\ -\n\ -@item @qcode{\"lo\"}\n\ -Factorize @tcode{@var{S}'}. Assumes @var{S} is symmetric and uses the lower\n\ -triangular portion of the matrix.\n\ -@end table\n\ -\n\ -@item mode\n\ -When @var{mode} is unspecified return the Cholesky@tie{}factorization for\n\ -@var{R}. If @var{mode} is @qcode{\"lower\"} or @qcode{\"L\"} then return\n\ -the conjugate transpose @tcode{@var{R}'} which is a lower triangular factor.\n\ -The conjugate transpose version is faster and uses less memory, but still\n\ -returns the same values for all other outputs: @var{count}, @var{h},\n\ -@var{parent}, and @var{post}.\n\ -@end table\n\ -\n\ -The output variables are:\n\ -\n\ -@table @var\n\ -@item count\n\ -The row counts of the Cholesky@tie{}factorization as determined by\n\ -@var{typ}. The computational difficulty of performing the true\n\ -factorization using @code{chol} is @code{sum (@var{count} .^ 2)}.\n\ -\n\ -@item h\n\ -The height of the elimination tree.\n\ -\n\ -@item parent\n\ -The elimination tree itself.\n\ -\n\ -@item post\n\ -A sparse boolean matrix whose structure is that of the\n\ -Cholesky@tie{}factorization as determined by @var{typ}.\n\ -@end table\n\ -@seealso{chol, etree, treelayout}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@var{count}, @var{h}, @var{parent}, @var{post}, @var{R}] =} symbfact (@var{S}) +@deftypefnx {} {[@dots{}] =} symbfact (@var{S}, @var{typ}) +@deftypefnx {} {[@dots{}] =} symbfact (@var{S}, @var{typ}, @var{mode}) + +Perform a symbolic factorization analysis of the sparse matrix @var{S}. + +The input variables are + +@table @var +@item S +@var{S} is a real or complex sparse matrix. + +@item typ +Is the type of the factorization and can be one of + +@table @asis +@item @qcode{"sym"} (default) +Factorize @var{S}. Assumes @var{S} is symmetric and uses the upper +triangular portion of the matrix. + +@item @qcode{"col"} +Factorize @tcode{@var{S}' * @var{S}}. + +@item @qcode{"row"} +Factorize @tcode{@var{S} * @var{S}'}. + +@item @qcode{"lo"} +Factorize @tcode{@var{S}'}. Assumes @var{S} is symmetric and uses the lower +triangular portion of the matrix. +@end table + +@item mode +When @var{mode} is unspecified return the Cholesky@tie{}factorization for +@var{R}. If @var{mode} is @qcode{"lower"} or @qcode{"L"} then return +the conjugate transpose @tcode{@var{R}'} which is a lower triangular factor. +The conjugate transpose version is faster and uses less memory, but still +returns the same values for all other outputs: @var{count}, @var{h}, +@var{parent}, and @var{post}. +@end table + +The output variables are: + +@table @var +@item count +The row counts of the Cholesky@tie{}factorization as determined by +@var{typ}. The computational difficulty of performing the true +factorization using @code{chol} is @code{sum (@var{count} .^ 2)}. + +@item h +The height of the elimination tree. + +@item parent +The elimination tree itself. + +@item post +A sparse boolean matrix whose structure is that of the +Cholesky@tie{}factorization as determined by @var{typ}. +@end table +@seealso{chol, etree, treelayout} +@end deftypefn */) { #if defined (HAVE_CHOLMOD)
--- a/libinterp/dldfcn/symrcm.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/dldfcn/symrcm.cc Tue Jun 21 16:07:51 2016 -0400 @@ -412,30 +412,30 @@ // An implementation of the Cuthill-McKee algorithm. DEFUN_DLD (symrcm, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{p} =} symrcm (@var{S})\n\ -Return the symmetric reverse @nospell{Cuthill-McKee} permutation of @var{S}.\n\ -\n\ -@var{p} is a permutation vector such that\n\ -@code{@var{S}(@var{p}, @var{p})} tends to have its diagonal elements closer\n\ -to the diagonal than @var{S}. This is a good preordering for LU or\n\ -Cholesky@tie{}factorization of matrices that come from ``long, skinny''\n\ -problems. It works for both symmetric and asymmetric @var{S}.\n\ -\n\ -The algorithm represents a heuristic approach to the NP-complete bandwidth\n\ -minimization problem. The implementation is based in the descriptions found\n\ -in\n\ -\n\ -@nospell{E. Cuthill, J. McKee}. @cite{Reducing the Bandwidth of Sparse\n\ -Symmetric Matrices}. Proceedings of the 24th ACM National Conference,\n\ -157--172 1969, Brandon Press, New Jersey.\n\ -\n\ -@nospell{A. George, J.W.H. Liu}. @cite{Computer Solution of Large Sparse\n\ -Positive Definite Systems}, Prentice Hall Series in Computational\n\ -Mathematics, ISBN 0-13-165274-5, 1981.\n\ -\n\ -@seealso{colperm, colamd, symamd}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{p} =} symrcm (@var{S}) +Return the symmetric reverse @nospell{Cuthill-McKee} permutation of @var{S}. + +@var{p} is a permutation vector such that +@code{@var{S}(@var{p}, @var{p})} tends to have its diagonal elements closer +to the diagonal than @var{S}. This is a good preordering for LU or +Cholesky@tie{}factorization of matrices that come from ``long, skinny'' +problems. It works for both symmetric and asymmetric @var{S}. + +The algorithm represents a heuristic approach to the NP-complete bandwidth +minimization problem. The implementation is based in the descriptions found +in + +@nospell{E. Cuthill, J. McKee}. @cite{Reducing the Bandwidth of Sparse +Symmetric Matrices}. Proceedings of the 24th ACM National Conference, +157--172 1969, Brandon Press, New Jersey. + +@nospell{A. George, J.W.H. Liu}. @cite{Computer Solution of Large Sparse +Positive Definite Systems}, Prentice Hall Series in Computational +Mathematics, ISBN 0-13-165274-5, 1981. + +@seealso{colperm, colamd, symamd} +@end deftypefn */) { if (args.length () != 1) print_usage ();
--- a/libinterp/find-defun-files.sh Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/find-defun-files.sh Tue Jun 21 16:07:51 2016 -0400 @@ -9,7 +9,7 @@ # so we have to repeat ourselves because some stupid egreps don't like # empty elements in alternation patterns. -DEFUN_PATTERN="^[ \t]*DEF(CONSTFUN|CMD|UN|UN_DLD|UNX_DLD|UN_TEXT)[ \t]*\\(" +DEFUN_PATTERN="^[ \t]*DEF(CONSTFUN|UN|UN_DLD|UNX|UNX_DLD)[ \t]*\\(" srcdir="$1" if [ "$1" ]; then @@ -25,7 +25,7 @@ fi if [ -f "$file" ]; then if [ "`$EGREP -l "$DEFUN_PATTERN" $file`" ]; then - echo "$file" | $SED "s,\\$srcdir/,," | $SED 's/\.cc$/.df/; s/\.ll$/.df/; s/\.in.yy$/.df/' + echo "$file" | $SED "s,\\$srcdir/,," fi fi done
--- a/libinterp/gendoc.pl Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/gendoc.pl Tue Jun 21 16:07:51 2016 -0400 @@ -18,7 +18,10 @@ # along with Octave; see the file COPYING. If not, see # <http://www.gnu.org/licenses/>. -unless (@ARGV > 1) { die "Usage: $0 df-file1 ..." } +unless (@ARGV > 1) { die "Usage: $0 SRCDIR src-file1 ..." } + +$srcdir = $ARGV[0]; +shift; print <<__END_OF_MSG__; ### DO NOT EDIT! @@ -28,44 +31,63 @@ __END_OF_MSG__ -DFFILE: foreach $df_fname (@ARGV) +FILE: foreach $fname (@ARGV) { - open (DF_FH, $df_fname) or die "Unable to open $df_fname"; + if (-f "$fname") + { + $src_fname = "$fname"; + } + else + { + $src_fname = "$srcdir/$fname"; + } - $src_fname = ""; + open (SRC_FH, $src_fname) or die "Unable to open $src_fname"; + @func_list = (); @docstr = (); - LINE: while (<DF_FH>) + LINE: while (<SRC_FH>) { - if (/XDEFUN_FILE_NAME \("([^"]+)"/) - { - $src_fname = $1; - next LINE; - } - if (/XDEF/ and ! /XDEFALIAS/) + if (/^\s*DEF(CONSTFUN|UN|UN_DLD|UNX|UNX_DLD)\s*\(/) { - ## Decode 4 or 5 part macro definition. - ($func, $str) = /\("?(\w+)"?,[^,]+,[^,]+,(?:[^,]+,)?\s*"(.*)"\)\s*$/ ; - - unless ($func) { die "Unable to parse $df_fname at line $.\n" } - + ($func) = /\("?(\w+)"?,/; + unless ($func) { die "Unable to parse $src_fname at line $.\n" } push (@func_list, $func); - ## Do escape sequence expansion - $str =~ s/(?<!\\)\\n/\n/g; - $str =~ s/\\([^\\])/$1/g; - $str =~ s/\\\\/\\/g; - push (@docstr, $str); + + if (<SRC_FH> =~ /\s*doc:\s+\/\*\s+-\*- texinfo -\*-\s*$/) + { + $str = "-*- texinfo -*-\n"; + $reading_docstring = 1; + } + else + { + print STDERR "gendoc.pl: undocumented function $func from $fname\n"; + push (@docstr, "Undocumented."); + } + } + elsif ($reading_docstring) + { + if (/^.*\s+\*\/\s*\)\s*$/) + { + s/\s+\*\/\s*\)\s*$//; + push (@docstr, $str . $_); + $reading_docstring = 0; + } + else + { + $str .= $_; + } } } - close (DF_FH); + close (SRC_FH); ## Print results in DOCSTRING format foreach $i (0 .. $#func_list) { $func = $func_list[$i]; print "\x{1d}$func\n"; - print "\@c $func $src_fname\n"; + print "\@c $func $fname\n"; print $docstr[$i],"\n"; }
--- a/libinterp/mk-pkg-add Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/mk-pkg-add Tue Jun 21 16:07:51 2016 -0400 @@ -22,14 +22,20 @@ SED=${SED:-sed} -for f in "$@"; do - if [ -f $f ]; then +srcdir="$1" +shift + +for arg +do + src_file="$srcdir/$arg" + + if [ -f "$src_file" ]; then ## Compute and print the autoloads. - base=`basename $f | $SED 's/\.df$//'` - fcns=`$SED -n -e 's/^ *XDEFUN_DLD_INTERNAL *( *\([^, ]*\)[, ].*$/\1/p' \ - -e 's/^ *XDEFUNX_DLD_INTERNAL *( *"\([^"]*\)".*$/\1/p' $f | \ + base=`basename "$src_file" | $SED 's/\.cc$//'` + fcns=`$SED -n -e 's/^ *DEFUN_DLD *( *\([^, ]*\) *,.*$/\1/p' \ + -e 's/^ *DEFUNX_DLD *( *"\([^"]*\)".*$/\1/p' "$src_file" | \ LC_COLLATE=C sort -u` if [ -n "$fcns" ]; then for n in $fcns; do @@ -45,7 +51,7 @@ ## necessary functions can be found before they are used. $SED -n -e 's,^//* *PKG_ADD: *,,p' \ - -e 's,^/\* *PKG_ADD: *\(.*\) *\*/ *$,\1,p' $f + -e 's,^/\* *PKG_ADD: *\(.*\) *\*/ *$,\1,p' "$src_file" fi done
--- a/libinterp/mkbuiltins Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/mkbuiltins Tue Jun 21 16:07:51 2016 -0400 @@ -19,12 +19,15 @@ # <http://www.gnu.org/licenses/>. if test $# -lt 2; then - echo "usage: mkbuiltins --header|--source f1 f2 ..." 1>&2 + echo "usage: mkbuiltins SRCDIR --header|--source f1 f2 ..." 1>&2 exit 1 fi SED=${SED:-sed} +srcdir="$1" +shift + make_header=false make_source=false case "$1" in @@ -54,17 +57,33 @@ #include "ovl.h" -#define DEFUN_DECL(name) \ +#define XDEFUN_DECL(name) \ extern OCTINTERP_API octave_value_list \ name (const octave_value_list& = octave_value_list (), int = 0); +#if defined (ENABLE_DYNAMIC_LINKING) +# define XDEFUN_DLD_DECL(name) +#else +# define XDEFUN_DLD_DECL(name) XDEFUN_DECL (name) +#endif + EOF - $SED -n -e 's/ *\(XDEFUN\|XDEFCONSTFUN\)_INTERNAL *( *\([_A-Za-z][_A-Za-z0-9]*\) *,.*$/DEFUN_DECL (F\2);/p; s/^ *XDEFUNX_INTERNAL *( *"\([_A-Za-z][_A-Za-z0-9]*\)" *,.*$/DEFUN_DECL (F\1);/p' "$@" + for arg + do + if [ -f $arg ]; then + file="$arg"; + else + file="$srcdir/$arg"; + fi + + $SED -n -e 's/^[ \t]*DEF\(CONSTFUN\|UN\)[ \t]*( *\([_A-Za-z][_A-Za-z0-9]*\) *,.*$/XDEFUN_DECL (F\2)/p; s/^[ \t]*DEFUNX[ \t]*( *"\([_A-Za-z][_A-Za-z0-9]*\)" *,.*$/XDEFUN_DECL (F\1)/p; s/^[ \t]*DEFUN_DLD[ \t]*( *\([_A-Za-z][_A-Za-z0-9]*\) *,.*$/XDEFUN_DLD_DECL (F\1)/p; s/^[ \t]*DEFUNX_DLD[ \t]*( *"\([_A-Za-z][_A-Za-z0-9]*\)" *,.*$/XDEFUN_DLD_DECL (F\1)/p' "$file" + done cat << \EOF -#undef DEFUN_DECL +#undef XDEFUN_DECL +#undef XDEFUN_DLD_DECL #endif @@ -83,6 +102,7 @@ #include "help.h" #include "ovl.h" #include "variables.h" +#include "builtin-defun-decls.h" #include "builtins.h" #if defined (quad) @@ -91,49 +111,54 @@ #if defined (ENABLE_DYNAMIC_LINKING) -# define XDEFUN_DLD_INTERNAL(name, args_name, nargout_name, doc) +# define XDEFUN_DLD_INTERNAL(name) -# define XDEFUNX_DLD_INTERNAL(name, fname, args_name, nargout_name, doc) +# define XDEFUNX_DLD_INTERNAL(name, fname) #else -# define XDEFUN_DLD_INTERNAL(name, args_name, nargout_name, doc) \ - XDEFUN_INTERNAL(name, args_name, nargout_name, doc) +# define XDEFUN_DLD_INTERNAL(name) \ + XDEFUN_INTERNAL(name) -# define XDEFUNX_DLD_INTERNAL(name, fname, args_name, nargout_name, doc) \ - XDEFUNX_INTERNAL(name, fname, args_name, nargout_name, doc) +# define XDEFUNX_DLD_INTERNAL(name, fname) \ + XDEFUNX_INTERNAL(name, fname) #endif -#define XDEFUN_FILE_NAME(name) \ - std::string file = name; - -#define XDEFUN_INTERNAL(name, args_name, nargout_name, doc) \ - extern DECLARE_FUN (name, args_name, nargout_name); \ - install_builtin_function (F ## name, #name, file, doc); \ +#define XDEFUN_INTERNAL(name) \ + install_builtin_function (F ## name, #name, file, "external-doc"); \ -#define XDEFCONSTFUN_INTERNAL(name, args_name, nargout_name, doc) \ - extern DECLARE_FUN (name, args_name, nargout_name); \ - install_builtin_function (F ## name, #name, file, doc, false); \ +#define XDEFCONSTFUN_INTERNAL(name) \ + install_builtin_function (F ## name, #name, file, "external-doc", false); \ -#define XDEFUNX_INTERNAL(name, fname, args_name, nargout_name, doc) \ - extern DECLARE_FUNX (fname, args_name, nargout_name); \ - install_builtin_function (fname, name, file, doc); \ +#define XDEFUNX_INTERNAL(name, fname) \ + install_builtin_function (fname, name, file, "external-doc"); \ #define XDEFALIAS_INTERNAL(alias, name) \ alias_builtin (#alias, #name); -#define XDEFCONST_INTERNAL(name, defn, doc) - EOF for arg do - fcn=`echo "$arg" | $SED 's,.*/,,; s/\.df//; s/-/_/g;'` + if [ -f $arg ]; then + file="$arg"; + else + file="$srcdir/$arg"; + fi + + fcn=`echo "$arg" | $SED 's,.*/,,; s/\.\(cc\|cpp\|in\.yy\|ll\)$//; s/-/_/g;'` echo "static void" echo "install_${fcn}_fcns (void)" echo "{" - cat "$arg" + echo " std::string file = \"$arg\";" + echo "" + $SED -n \ + -e 's/^ *\(DEFUN\(_DLD\|\)\) *( *\([^ ,]*\) *,.*$/ X\1_INTERNAL (\3);/p' \ + -e 's/^ *\(DEFUNX\(_DLD\|\)\) *( *\("[^"]*"\) *, *\([^ ,]*\) *,.*$/ X\1_INTERNAL (\3, \4);/p' \ + -e 's/^ *\(DEFCONSTFUN\) *( *\([^ ,]*\) *,.*$/ X\1_INTERNAL (\2);/p' \ + -e 's/^ *\(DEFALIAS\) *( *\([^ ,]*\) *, *\([^ )]*\) *).*$/ X\1_INTERNAL (\2, \3);/p' \ + "$file" echo "}" echo "" done @@ -147,7 +172,7 @@ for arg do - fcn=`echo "$arg" | $SED 's,.*/,,; s/\.df//; s/-/_/g;'` + fcn=`echo "$arg" | $SED 's,.*/,,; s/\.\(cc\|cpp\|in\.yy\|ll\)$//; s/-/_/g;'` echo " install_${fcn}_fcns ();" done
--- a/libinterp/mkdefs Tue Jun 21 13:08:25 2016 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,54 +0,0 @@ -#! /bin/sh -# -# Copyright (C) 1996-2015 John W. Eaton -# -# 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 -# <http://www.gnu.org/licenses/>. - -SED=${SED:-sed} - -if [ $# -ne 2 ]; then - echo "usage: mkdefs srcdir file < preprocessed-file-contents" 1>&2 - exit 1 -fi - -srcdir="$1" -file="$2" - -echo "// DO NOT EDIT! Generated automatically by mkdefs." -case "$file" in - $srcdir/*) - xsrcdir=`echo "$file" | sed "s,^$srcdir,libinterp,"` - ;; - *) - xsrcdir="$file" - ;; -esac -echo " XDEFUN_FILE_NAME (\"$xsrcdir\")" -egrep '^(///*|/\*) *PKG_ADD:' $file - -$SED -n -e '/^ *BEGIN_INSTALL_BUILTIN/{ - : loop - s/BEGIN_INSTALL_BUILTIN// - s/^#[ \t][ \t]*[0-9][0-9]*.*$// - /END_INSTALL_BUILTIN/b done - p - n - b loop - : done - s/END_INSTALL_BUILTIN// - p -}'
--- a/libinterp/module.mk Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/module.mk Tue Jun 21 16:07:51 2016 -0400 @@ -29,10 +29,8 @@ octlib_LTLIBRARIES += libinterp/liboctinterp.la -## This is the subset of $(BUILT_SOURCES) that may be included by source -## files that are preprocessed to make $(DEF_FILES). This ensures that -## files in $(BUILT_SOURCES) are built in the right dependency order. -GENERATED_MAKE_BUILTINS_INCS = \ +BUILT_SOURCES += \ + libinterp/builtin-defun-decls.h \ libinterp/corefcn/defaults.h \ libinterp/corefcn/graphics-props.cc \ libinterp/corefcn/graphics.h \ @@ -41,20 +39,6 @@ libinterp/parse-tree/oct-parse.h \ libinterp/version.h -BUILT_SOURCES += \ - $(GENERATED_MAKE_BUILTINS_INCS) \ - libinterp/build-env.cc \ - libinterp/builtin-defun-decls.h \ - libinterp/builtins.cc \ - libinterp/liboctinterp-build-info.cc \ - libinterp/corefcn/oct-errno.cc \ - libinterp/corefcn/oct-tex-lexer.cc \ - libinterp/corefcn/oct-tex-parser.cc \ - libinterp/corefcn/oct-tex-symbols.cc \ - libinterp/operators/ops.cc \ - libinterp/parse-tree/lex.cc \ - libinterp/parse-tree/oct-parse.cc - ULT_PARSER_SRC := \ libinterp/corefcn/oct-tex-lexer.in.ll \ libinterp/corefcn/oct-tex-parser.in.yy \ @@ -66,8 +50,12 @@ libinterp/corefcn/oct-tex-parser.yy \ libinterp/parse-tree/oct-parse.yy +## These generated files are included in the source distribution to +## avoid needing certain tools to build from a distribution tarball. + LIBINTERP_BUILT_DISTFILES = \ $(GENERATED_PARSER_FILES) \ + $(OPT_HANDLERS) \ libinterp/corefcn/oct-tex-parser.h \ libinterp/corefcn/oct-tex-symbols.cc \ libinterp/parse-tree/oct-gperf.h \ @@ -86,8 +74,6 @@ libinterp/builtin-defun-decls.h \ libinterp/operators/ops.cc \ libinterp/version.h \ - $(OPT_HANDLERS) \ - $(ALL_DEF_FILES) \ libinterp/builtins.cc libinterp_EXTRA_DIST += \ @@ -101,7 +87,6 @@ libinterp/mk-errno-list \ libinterp/mk-pkg-add \ libinterp/mkbuiltins \ - libinterp/mkdefs \ libinterp/mkops \ libinterp/version.in.h \ $(LIBINTERP_BUILT_DISTFILES) @@ -193,47 +178,29 @@ $(LIBOCTINTERP_LINK_OPTS) \ $(WARN_LDFLAGS) -## Section for defining and creating DEF_FILES - ULT_DIST_SRC := \ $(filter-out $(GENERATED_PARSER_FILES), $(DIST_SRC)) $(ULT_PARSER_SRC) -SRC_DEF_FILES := $(shell $(SHELL) $(srcdir)/libinterp/find-defun-files.sh "$(srcdir)" $(ULT_DIST_SRC)) +FOUND_DEFUN_FILES := \ + $(shell $(SHELL) $(srcdir)/libinterp/find-defun-files.sh "$(srcdir)" $(ULT_DIST_SRC)) -DLDFCN_DEF_FILES = $(DLDFCN_SRC:.cc=.df) +SRC_DEFUN_FILES = $(OPT_HANDLERS) $(FOUND_DEFUN_FILES) -## builtins.cc depends on $(DEF_FILES), so DEF_FILES should only include -## .df files that correspond to sources included in liboctave. +DLDFCN_DEFUN_FILES = $(DLDFCN_SRC) + if AMCOND_ENABLE_DYNAMIC_LINKING - DEF_FILES = $(SRC_DEF_FILES) + DEFUN_FILES = $(SRC_DEFUN_FILES) else - DEF_FILES = $(SRC_DEF_FILES) $(DLDFCN_DEF_FILES) + DEFUN_FILES = $(SRC_DEFUN_FILES) $(DLDFCN_DEFUN_FILES) endif -ALL_DEF_FILES = $(SRC_DEF_FILES) $(DLDFCN_DEF_FILES) - -$(SRC_DEF_FILES): libinterp/mkdefs - -$(DEF_FILES): $(OPT_HANDLERS) $(LIBOCTAVE_OPT_INC) +ALL_DEFUN_FILES = $(SRC_DEFUN_FILES) $(DLDFCN_DEFUN_FILES) ## FIXME: The following two variables are deprecated and should be removed ## in Octave version 3.12. DLL_CDEFS = @OCTINTERP_DLL_DEFS@ DLL_CXXDEFS = @OCTINTERP_DLL_DEFS@ -## Rule to build a DEF file from a .cc file -## See also module.mk files for overrides when speciall CPPFLAGS are needed. -## FIXME: Shouldn't the build stop if CPP fails here? Yes (10/31/2013) -%.df: %.cc $(GENERATED_MAKE_BUILTINS_INCS) octave-config.h - $(AM_V_GEN)rm -f $@-t $@-t1 $@ && \ - $(CXXCPP) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) \ - $(libinterp_liboctinterp_la_CPPFLAGS) $(LLVM_CPPFLAGS) $(CPPFLAGS) \ - $(libinterp_liboctinterp_la_CXXFLAGS) $(CXXFLAGS) \ - -DMAKE_BUILTINS $< > $@-t1 && \ - $(SHELL) $(srcdir)/libinterp/mkdefs $(srcdir)/libinterp $< < $@-t1 > $@-t && \ - rm -f $@-t1 && \ - mv $@-t $@ - ## Rules to build test files LIBINTERP_TST_FILES_SRC := $(shell $(SHELL) $(srcdir)/build-aux/find-files-with-tests.sh "$(srcdir)" $(ULT_DIST_SRC) $(DLDFCN_SRC)) @@ -259,7 +226,7 @@ libinterp/build-env-features.cc: config.h libinterp/build-env-features.sh | libinterp/$(octave-dirstamp) $(AM_V_GEN)rm -f $@-t && \ $(SHELL) $(srcdir)/libinterp/build-env-features.sh $< > $@-t && \ - $(simple_move_if_change_rule) + mv $@-t $@ libinterp/version.h: libinterp/version.in.h build-aux/mk-version-h.sh | libinterp/$(octave-dirstamp) $(AM_V_GEN)$(call simple-filter-rule,build-aux/mk-version-h.sh) @@ -271,33 +238,33 @@ -e "s|%OCTAVE_HG_ID%|`cat $(builddir)/HG-ID`|" $< > $@-t && \ $(simple_move_if_change_rule) -libinterp/builtins.cc: $(DEF_FILES) libinterp/mkbuiltins | libinterp/$(octave-dirstamp) +libinterp/builtins.cc: $(ALL_DEFUN_FILES) libinterp/mkbuiltins | libinterp/$(octave-dirstamp) $(AM_V_GEN)rm -f $@-t && \ - $(SHELL) $(srcdir)/libinterp/mkbuiltins --source $(DEF_FILES) > $@-t && \ - $(simple_move_if_change_rule) + $(SHELL) $(srcdir)/libinterp/mkbuiltins "$(srcdir)" --source $(ALL_DEFUN_FILES) > $@-t && \ + mv $@-t $@ -libinterp/builtin-defun-decls.h: $(SRC_DEF_FILES) libinterp/mkbuiltins | libinterp/$(octave-dirstamp) +libinterp/builtin-defun-decls.h: $(ALL_DEFUN_FILES) libinterp/mkbuiltins | libinterp/$(octave-dirstamp) $(AM_V_GEN)rm -f $@-t && \ - $(SHELL) $(srcdir)/libinterp/mkbuiltins --header $(SRC_DEF_FILES) > $@-t && \ + $(SHELL) $(srcdir)/libinterp/mkbuiltins "$(srcdir)" --header $(ALL_DEFUN_FILES) > $@-t && \ $(simple_move_if_change_rule) if AMCOND_ENABLE_DYNAMIC_LINKING DLDFCN_PKG_ADD_FILE = libinterp/dldfcn/PKG_ADD -libinterp/dldfcn/PKG_ADD: $(DLDFCN_DEF_FILES) libinterp/mk-pkg-add | libinterp/$(octave-dirstamp) +libinterp/dldfcn/PKG_ADD: $(DLDFCN_DEFUN_FILES) libinterp/mk-pkg-add | libinterp/$(octave-dirstamp) $(AM_V_GEN)rm -f $@-t && \ - $(SHELL) $(srcdir)/libinterp/mk-pkg-add $(DLDFCN_DEF_FILES) > $@-t && \ - $(simple_move_if_change_rule) + $(SHELL) $(srcdir)/libinterp/mk-pkg-add "$(srcdir)" $(DLDFCN_DEFUN_FILES) > $@-t && \ + mv $@-t $@ endif if AMCOND_BUILD_DOCS DOCSTRING_FILES += $(srcdir)/libinterp/DOCSTRINGS -$(srcdir)/libinterp/DOCSTRINGS: $(ALL_DEF_FILES) | libinterp/$(octave-dirstamp) +$(srcdir)/libinterp/DOCSTRINGS: $(ALL_DEFUN_FILES) | libinterp/$(octave-dirstamp) $(AM_V_GEN)rm -f libinterp/DOCSTRINGS-t && \ - $(PERL) $(srcdir)/libinterp/gendoc.pl $(ALL_DEF_FILES) > libinterp/DOCSTRINGS-t && \ - $(SHELL) $(srcdir)/build-aux/move-if-change libinterp/DOCSTRINGS-t $@ + $(PERL) $(srcdir)/libinterp/gendoc.pl "$(srcdir)" $(ALL_DEFUN_FILES) > libinterp/DOCSTRINGS-t && \ + mv libinterp/DOCSTRINGS-t $@ endif
--- a/libinterp/octave-value/ov-base.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/octave-value/ov-base.cc Tue Jun 21 16:07:51 2016 -0400 @@ -1485,33 +1485,33 @@ } DEFUN (sparse_auto_mutate, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} sparse_auto_mutate ()\n\ -@deftypefnx {} {@var{old_val} =} sparse_auto_mutate (@var{new_val})\n\ -@deftypefnx {} {} sparse_auto_mutate (@var{new_val}, \"local\")\n\ -Query or set the internal variable that controls whether Octave will\n\ -automatically mutate sparse matrices to full matrices to save memory.\n\ -\n\ -For example:\n\ -\n\ -@example\n\ -@group\n\ -s = speye (3);\n\ -sparse_auto_mutate (false);\n\ -s(:, 1) = 1;\n\ -typeinfo (s)\n\ -@result{} sparse matrix\n\ -sparse_auto_mutate (true);\n\ -s(1, :) = 1;\n\ -typeinfo (s)\n\ -@result{} matrix\n\ -@end group\n\ -@end example\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} sparse_auto_mutate () +@deftypefnx {} {@var{old_val} =} sparse_auto_mutate (@var{new_val}) +@deftypefnx {} {} sparse_auto_mutate (@var{new_val}, "local") +Query or set the internal variable that controls whether Octave will +automatically mutate sparse matrices to full matrices to save memory. + +For example: + +@example +@group +s = speye (3); +sparse_auto_mutate (false); +s(:, 1) = 1; +typeinfo (s) +@result{} sparse matrix +sparse_auto_mutate (true); +s(1, :) = 1; +typeinfo (s) +@result{} matrix +@end group +@end example + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@end deftypefn */) { return SET_INTERNAL_VARIABLE (sparse_auto_mutate); }
--- a/libinterp/octave-value/ov-bool-mat.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/octave-value/ov-bool-mat.cc Tue Jun 21 16:07:51 2016 -0400 @@ -523,18 +523,18 @@ } DEFUN (logical, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} logical (@var{x})\n\ -Convert the numeric object @var{x} to logical type.\n\ -\n\ -Any nonzero values will be converted to true (1) while zero values will be\n\ -converted to false (0). The non-numeric value NaN cannot be converted and\n\ -will produce an error.\n\ -\n\ -Compatibility Note: Octave accepts complex values as input, whereas\n\ -@sc{matlab} issues an error.\n\ -@seealso{double, single, char}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} logical (@var{x}) +Convert the numeric object @var{x} to logical type. + +Any nonzero values will be converted to true (1) while zero values will be +converted to false (0). The non-numeric value NaN cannot be converted and +will produce an error. + +Compatibility Note: Octave accepts complex values as input, whereas +@sc{matlab} issues an error. +@seealso{double, single, char} +@end deftypefn */) { if (args.length () != 1) print_usage ();
--- a/libinterp/octave-value/ov-cell.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/octave-value/ov-cell.cc Tue Jun 21 16:07:51 2016 -0400 @@ -1180,11 +1180,11 @@ } DEFUN (iscell, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} iscell (@var{x})\n\ -Return true if @var{x} is a cell array object.\n\ -@seealso{ismatrix, isstruct, iscellstr, isa}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} iscell (@var{x}) +Return true if @var{x} is a cell array object. +@seealso{ismatrix, isstruct, iscellstr, isa} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1193,19 +1193,19 @@ } DEFUN (cell, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} cell (@var{n})\n\ -@deftypefnx {} {} cell (@var{m}, @var{n})\n\ -@deftypefnx {} {} cell (@var{m}, @var{n}, @var{k}, @dots{})\n\ -@deftypefnx {} {} cell ([@var{m} @var{n} @dots{}])\n\ -Create a new cell array object.\n\ -\n\ -If invoked with a single scalar integer argument, return a square\n\ -@nospell{NxN} cell array. If invoked with two or more scalar integer\n\ -arguments, or a vector of integer values, return an array with the given\n\ -dimensions.\n\ -@seealso{cellstr, mat2cell, num2cell, struct2cell}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} cell (@var{n}) +@deftypefnx {} {} cell (@var{m}, @var{n}) +@deftypefnx {} {} cell (@var{m}, @var{n}, @var{k}, @dots{}) +@deftypefnx {} {} cell ([@var{m} @var{n} @dots{}]) +Create a new cell array object. + +If invoked with a single scalar integer argument, return a square +@nospell{NxN} cell array. If invoked with two or more scalar integer +arguments, or a vector of integer values, return an array with the given +dimensions. +@seealso{cellstr, mat2cell, num2cell, struct2cell} +@end deftypefn */) { int nargin = args.length (); @@ -1240,12 +1240,12 @@ } DEFUN (iscellstr, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} iscellstr (@var{cell})\n\ -Return true if every element of the cell array @var{cell} is a character\n\ -string.\n\ -@seealso{ischar}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} iscellstr (@var{cell}) +Return true if every element of the cell array @var{cell} is a character +string. +@seealso{ischar} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1259,17 +1259,17 @@ // declaration) and so we don't have to use feval to call it. DEFUN (cellstr, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{cstr} =} cellstr (@var{strmat})\n\ -Create a new cell array object from the elements of the string array\n\ -@var{strmat}.\n\ -\n\ -Each row of @var{strmat} becomes an element of @var{cstr}. Any trailing\n\ -spaces in a row are deleted before conversion.\n\ -\n\ -To convert back from a cellstr to a character array use @code{char}.\n\ -@seealso{cell, char}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{cstr} =} cellstr (@var{strmat}) +Create a new cell array object from the elements of the string array +@var{strmat}. + +Each row of @var{strmat} becomes an element of @var{cstr}. Any trailing +spaces in a row are deleted before conversion. + +To convert back from a cellstr to a character array use @code{char}. +@seealso{cell, char} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1288,39 +1288,39 @@ } DEFUN (struct2cell, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{c} =} struct2cell (@var{s})\n\ -Create a new cell array from the objects stored in the struct object.\n\ -\n\ -If @var{f} is the number of fields in the structure, the resulting cell\n\ -array will have a dimension vector corresponding to\n\ -@code{[@var{f} size(@var{s})]}. For example:\n\ -\n\ -@example\n\ -@group\n\ -s = struct (\"name\", @{\"Peter\", \"Hannah\", \"Robert\"@},\n\ - \"age\", @{23, 16, 3@});\n\ -c = struct2cell (s)\n\ - @result{} c = @{2x1x3 Cell Array@}\n\ -c(1,1,:)(:)\n\ - @result{}\n\ - @{\n\ - [1,1] = Peter\n\ - [2,1] = Hannah\n\ - [3,1] = Robert\n\ - @}\n\ -c(2,1,:)(:)\n\ - @result{}\n\ - @{\n\ - [1,1] = 23\n\ - [2,1] = 16\n\ - [3,1] = 3\n\ - @}\n\ -@end group\n\ -@end example\n\ -\n\ -@seealso{cell2struct, fieldnames}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{c} =} struct2cell (@var{s}) +Create a new cell array from the objects stored in the struct object. + +If @var{f} is the number of fields in the structure, the resulting cell +array will have a dimension vector corresponding to +@code{[@var{f} size(@var{s})]}. For example: + +@example +@group +s = struct ("name", @{"Peter", "Hannah", "Robert"@}, + "age", @{23, 16, 3@}); +c = struct2cell (s) + @result{} c = @{2x1x3 Cell Array@} +c(1,1,:)(:) + @result{} + @{ + [1,1] = Peter + [2,1] = Hannah + [3,1] = Robert + @} +c(2,1,:)(:) + @result{} + @{ + [1,1] = 23 + [2,1] = 16 + [3,1] = 3 + @} +@end group +@end example + +@seealso{cell2struct, fieldnames} +@end deftypefn */) { if (args.length () != 1) print_usage ();
--- a/libinterp/octave-value/ov-class.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/octave-value/ov-class.cc Tue Jun 21 16:07:51 2016 -0400 @@ -1710,17 +1710,17 @@ } DEFUN (class, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{classname} =} class (@var{obj})\n\ -@deftypefnx {} {} class (@var{s}, @var{id})\n\ -@deftypefnx {} {} class (@var{s}, @var{id}, @var{p}, @dots{})\n\ -Return the class of the object @var{obj}, or create a class with\n\ -fields from structure @var{s} and name (string) @var{id}.\n\ -\n\ -Additional arguments name a list of parent classes from which the new class\n\ -is derived.\n\ -@seealso{typeinfo, isa}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{classname} =} class (@var{obj}) +@deftypefnx {} {} class (@var{s}, @var{id}) +@deftypefnx {} {} class (@var{s}, @var{id}, @var{p}, @dots{}) +Return the class of the object @var{obj}, or create a class with +fields from structure @var{s} and name (string) @var{id}. + +Additional arguments name a list of parent classes from which the new class +is derived. +@seealso{typeinfo, isa} +@end deftypefn */) { int nargin = args.length (); @@ -1784,30 +1784,30 @@ */ DEFUN (isa, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isa (@var{obj}, @var{classname})\n\ -Return true if @var{obj} is an object from the class @var{classname}.\n\ -\n\ -@var{classname} may also be one of the following class categories:\n\ -\n\ -@table @asis\n\ -@item @qcode{\"float\"}\n\ -Floating point value comprising classes @qcode{\"double\"} and\n\ -@qcode{\"single\"}.\n\ -\n\ -@item @qcode{\"integer\"}\n\ -Integer value comprising classes (u)int8, (u)int16, (u)int32, (u)int64.\n\ -\n\ -@item @qcode{\"numeric\"}\n\ -Numeric value comprising either a floating point or integer value.\n\ -@end table\n\ -\n\ -If @var{classname} is a cell array of string, a logical array of the same\n\ -size is returned, containing true for each class to which @var{obj}\n\ -belongs to.\n\ -\n\ -@seealso{class, typeinfo}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isa (@var{obj}, @var{classname}) +Return true if @var{obj} is an object from the class @var{classname}. + +@var{classname} may also be one of the following class categories: + +@table @asis +@item @qcode{"float"} +Floating point value comprising classes @qcode{"double"} and +@qcode{"single"}. + +@item @qcode{"integer"} +Integer value comprising classes (u)int8, (u)int16, (u)int32, (u)int64. + +@item @qcode{"numeric"} +Numeric value comprising either a floating point or integer value. +@end table + +If @var{classname} is a cell array of string, a logical array of the same +size is returned, containing true for each class to which @var{obj} +belongs to. + +@seealso{class, typeinfo} +@end deftypefn */) { if (args.length () != 2) print_usage (); @@ -1893,10 +1893,10 @@ */ DEFUN (__parent_classes__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __parent_classes__ (@var{x})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __parent_classes__ (@var{x}) +Undocumented internal function. +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1910,11 +1910,11 @@ } DEFUN (isobject, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isobject (@var{x})\n\ -Return true if @var{x} is a class object.\n\ -@seealso{class, typeinfo, isa, ismethod, isprop}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isobject (@var{x}) +Return true if @var{x} is a class object. +@seealso{class, typeinfo, isa, ismethod, isprop} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1923,13 +1923,13 @@ } DEFUN (ismethod, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} ismethod (@var{obj}, @var{method})\n\ -@deftypefnx {} {} ismethod (@var{clsname}, @var{method})\n\ -Return true if the string @var{method} is a valid method of the object\n\ -@var{obj} or of the class @var{clsname}.\n\ -@seealso{isprop, isobject}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} ismethod (@var{obj}, @var{method}) +@deftypefnx {} {} ismethod (@var{clsname}, @var{method}) +Return true if the string @var{method} is a valid method of the object +@var{obj} or of the class @var{clsname}. +@seealso{isprop, isobject} +@end deftypefn */) { if (args.length () != 2) print_usage (); @@ -1954,14 +1954,14 @@ } DEFUN (__methods__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __methods__ (@var{x})\n\ -@deftypefnx {} {} __methods__ (\"classname\")\n\ -Internal function.\n\ -\n\ -Implements @code{methods} for Octave class objects and classnames.\n\ -@seealso{methods}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __methods__ (@var{x}) +@deftypefnx {} {} __methods__ ("classname") +Internal function. + +Implements @code{methods} for Octave class objects and classnames. +@seealso{methods} +@end deftypefn */) { // Input validation has already been done in methods.m. octave_value arg = args(0); @@ -2006,15 +2006,15 @@ } DEFUN (superiorto, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} superiorto (@var{class_name}, @dots{})\n\ -When called from a class constructor, mark the object currently constructed\n\ -as having a higher precedence than @var{class_name}.\n\ -\n\ -More that one such class can be specified in a single call. This function\n\ -may @emph{only} be called from a class constructor.\n\ -@seealso{inferiorto}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} superiorto (@var{class_name}, @dots{}) +When called from a class constructor, mark the object currently constructed +as having a higher precedence than @var{class_name}. + +More that one such class can be specified in a single call. This function +may @emph{only} be called from a class constructor. +@seealso{inferiorto} +@end deftypefn */) { octave_function *fcn = octave_call_stack::caller (); if (! fcn || ! fcn->is_class_constructor ()) @@ -2039,15 +2039,15 @@ } DEFUN (inferiorto, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} inferiorto (@var{class_name}, @dots{})\n\ -When called from a class constructor, mark the object currently constructed\n\ -as having a lower precedence than @var{class_name}.\n\ -\n\ -More that one such class can be specified in a single call. This function\n\ -may @emph{only} be called from a class constructor.\n\ -@seealso{superiorto}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} inferiorto (@var{class_name}, @dots{}) +When called from a class constructor, mark the object currently constructed +as having a lower precedence than @var{class_name}. + +More that one such class can be specified in a single call. This function +may @emph{only} be called from a class constructor. +@seealso{superiorto} +@end deftypefn */) { octave_function *fcn = octave_call_stack::caller (); if (! fcn || ! fcn->is_class_constructor ())
--- a/libinterp/octave-value/ov-classdef.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/octave-value/ov-classdef.cc Tue Jun 21 16:07:51 2016 -0400 @@ -3712,7 +3712,11 @@ //---------------------------------------------------------------------------- -DEFUN (__meta_get_package__, args, , "") +DEFUN (__meta_get_package__, args, , + doc: /* -*- texinfo -*- +@deftypefn {} {} __meta_get_package__ () +Undocumented internal function. +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -3723,19 +3727,19 @@ } DEFUN (__superclass_reference__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __superclass_reference__ ()\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __superclass_reference__ () +Undocumented internal function. +@end deftypefn */) { return ovl (new octave_classdef_superclass_ref (args)); } DEFUN (__meta_class_query__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __meta_class_query__ ()\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __meta_class_query__ () +Undocumented internal function. +@end deftypefn */) { #if DEBUG_TRACE std::cerr << "__meta_class_query__ (" @@ -3752,10 +3756,10 @@ } DEFUN (metaclass, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} metaclass (obj)\n\ -Returns the meta.class object corresponding to the class of @var{obj}.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} metaclass (obj) +Returns the meta.class object corresponding to the class of @var{obj}. +@end deftypefn */) { if (args.length () != 1) print_usage ();
--- a/libinterp/octave-value/ov-fcn-handle.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/octave-value/ov-fcn-handle.cc Tue Jun 21 16:07:51 2016 -0400 @@ -1650,51 +1650,51 @@ */ DEFUN (functions, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{s} =} functions (@var{fcn_handle})\n\ -Return a structure containing information about the function handle\n\ -@var{fcn_handle}.\n\ -\n\ -The structure @var{s} always contains these three fields:\n\ -\n\ -@table @asis\n\ -@item function\n\ -The function name. For an anonymous function (no name) this will be the\n\ -actual function definition.\n\ -\n\ -@item type\n\ -Type of the function.\n\ -\n\ -@table @asis\n\ -@item anonymous\n\ -The function is anonymous.\n\ -\n\ -@item private\n\ -The function is private.\n\ -\n\ -@item overloaded\n\ -The function overloads an existing function.\n\ -\n\ -@item simple\n\ -The function is a built-in or m-file function.\n\ -\n\ -@item subfunction\n\ -The function is a subfunction within an m-file.\n\ -@end table\n\ -\n\ -@item file\n\ -The m-file that will be called to perform the function. This field is empty\n\ -for anonymous and built-in functions.\n\ -@end table\n\ -\n\ -In addition, some function types may return more information in additional\n\ -fields.\n\ -\n\ -@strong{Warning:} @code{functions} is provided for debugging purposes only.\n\ -It's behavior may change in the future and programs should not depend on a\n\ -particular output.\n\ -\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{s} =} functions (@var{fcn_handle}) +Return a structure containing information about the function handle +@var{fcn_handle}. + +The structure @var{s} always contains these three fields: + +@table @asis +@item function +The function name. For an anonymous function (no name) this will be the +actual function definition. + +@item type +Type of the function. + +@table @asis +@item anonymous +The function is anonymous. + +@item private +The function is private. + +@item overloaded +The function overloads an existing function. + +@item simple +The function is a built-in or m-file function. + +@item subfunction +The function is a subfunction within an m-file. +@end table + +@item file +The m-file that will be called to perform the function. This field is empty +for anonymous and built-in functions. +@end table + +In addition, some function types may return more information in additional +fields. + +@strong{Warning:} @code{functions} is provided for debugging purposes only. +It's behavior may change in the future and programs should not depend on a +particular output. + +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1775,12 +1775,12 @@ } DEFUN (func2str, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} func2str (@var{fcn_handle})\n\ -Return a string containing the name of the function referenced by the\n\ -function handle @var{fcn_handle}.\n\ -@seealso{str2func, functions}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} func2str (@var{fcn_handle}) +Return a string containing the name of the function referenced by the +function handle @var{fcn_handle}. +@seealso{str2func, functions} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1809,15 +1809,15 @@ } DEFUN (str2func, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} str2func (@var{fcn_name})\n\ -@deftypefnx {} {} str2func (@var{fcn_name}, \"global\")\n\ -Return a function handle constructed from the string @var{fcn_name}.\n\ -\n\ -If the optional @qcode{\"global\"} argument is passed, locally visible\n\ -functions are ignored in the lookup.\n\ -@seealso{func2str, inline}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} str2func (@var{fcn_name}) +@deftypefnx {} {} str2func (@var{fcn_name}, "global") +Return a function handle constructed from the string @var{fcn_name}. + +If the optional @qcode{"global"} argument is passed, locally visible +functions are ignored in the lookup. +@seealso{func2str, inline} +@end deftypefn */) { int nargin = args.length (); @@ -1876,11 +1876,11 @@ */ DEFUN (is_function_handle, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} is_function_handle (@var{x})\n\ -Return true if @var{x} is a function handle.\n\ -@seealso{isa, typeinfo, class, functions}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} is_function_handle (@var{x}) +Return true if @var{x} is a function handle. +@seealso{isa, typeinfo, class, functions} +@end deftypefn */) { if (args.length () != 1) print_usage ();
--- a/libinterp/octave-value/ov-fcn-inline.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/octave-value/ov-fcn-inline.cc Tue Jun 21 16:07:51 2016 -0400 @@ -655,32 +655,32 @@ } DEFUNX ("inline", Finline, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} inline (@var{str})\n\ -@deftypefnx {} {} inline (@var{str}, @var{arg1}, @dots{})\n\ -@deftypefnx {} {} inline (@var{str}, @var{n})\n\ -Create an inline function from the character string @var{str}.\n\ -\n\ -If called with a single argument, the arguments of the generated function\n\ -are extracted from the function itself. The generated function arguments\n\ -will then be in alphabetical order. It should be noted that i and j are\n\ -ignored as arguments due to the ambiguity between their use as a variable or\n\ -their use as an built-in constant. All arguments followed by a parenthesis\n\ -are considered to be functions. If no arguments are found, a function\n\ -taking a single argument named @code{x} will be created.\n\ -\n\ -If the second and subsequent arguments are character strings, they are the\n\ -names of the arguments of the function.\n\ -\n\ -If the second argument is an integer @var{n}, the arguments are\n\ -@qcode{\"x\"}, @qcode{\"P1\"}, @dots{}, @qcode{\"P@var{N}\"}.\n\ -\n\ -Programming Note: The use of @code{inline} is discouraged and it may be\n\ -removed from a future version of Octave. The preferred way to create\n\ -functions from strings is through the use of anonymous functions\n\ -(@pxref{Anonymous Functions}) or @code{str2func}.\n\ -@seealso{argnames, formula, vectorize, str2func}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} inline (@var{str}) +@deftypefnx {} {} inline (@var{str}, @var{arg1}, @dots{}) +@deftypefnx {} {} inline (@var{str}, @var{n}) +Create an inline function from the character string @var{str}. + +If called with a single argument, the arguments of the generated function +are extracted from the function itself. The generated function arguments +will then be in alphabetical order. It should be noted that i and j are +ignored as arguments due to the ambiguity between their use as a variable or +their use as an built-in constant. All arguments followed by a parenthesis +are considered to be functions. If no arguments are found, a function +taking a single argument named @code{x} will be created. + +If the second and subsequent arguments are character strings, they are the +names of the arguments of the function. + +If the second argument is an integer @var{n}, the arguments are +@qcode{"x"}, @qcode{"P1"}, @dots{}, @qcode{"P@var{N}"}. + +Programming Note: The use of @code{inline} is discouraged and it may be +removed from a future version of Octave. The preferred way to create +functions from strings is through the use of anonymous functions +(@pxref{Anonymous Functions}) or @code{str2func}. +@seealso{argnames, formula, vectorize, str2func} +@end deftypefn */) { int nargin = args.length (); @@ -834,14 +834,14 @@ */ DEFUN (formula, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} formula (@var{fun})\n\ -Return a character string representing the inline function @var{fun}.\n\ -\n\ -Note that @code{char (@var{fun})} is equivalent to\n\ -@code{formula (@var{fun})}.\n\ -@seealso{char, argnames, inline, vectorize}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} formula (@var{fun}) +Return a character string representing the inline function @var{fun}. + +Note that @code{char (@var{fun})} is equivalent to +@code{formula (@var{fun})}. +@seealso{char, argnames, inline, vectorize} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -865,12 +865,12 @@ */ DEFUN (argnames, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} argnames (@var{fun})\n\ -Return a cell array of character strings containing the names of the\n\ -arguments of the inline function @var{fun}.\n\ -@seealso{inline, formula, vectorize}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} argnames (@var{fun}) +Return a cell array of character strings containing the names of the +arguments of the inline function @var{fun}. +@seealso{inline, formula, vectorize} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -902,24 +902,24 @@ */ DEFUN (vectorize, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} vectorize (@var{fun})\n\ -Create a vectorized version of the inline function @var{fun} by replacing\n\ -all occurrences of @code{*}, @code{/}, etc., with @code{.*}, @code{./}, etc.\n\ -\n\ -This may be useful, for example, when using inline functions with numerical\n\ -integration or optimization where a vector-valued function is expected.\n\ -\n\ -@example\n\ -@group\n\ -fcn = vectorize (inline (\"x^2 - 1\"))\n\ - @result{} fcn = f(x) = x.^2 - 1\n\ -quadv (fcn, 0, 3)\n\ - @result{} 6\n\ -@end group\n\ -@end example\n\ -@seealso{inline, formula, argnames}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} vectorize (@var{fun}) +Create a vectorized version of the inline function @var{fun} by replacing +all occurrences of @code{*}, @code{/}, etc., with @code{.*}, @code{./}, etc. + +This may be useful, for example, when using inline functions with numerical +integration or optimization where a vector-valued function is expected. + +@example +@group +fcn = vectorize (inline ("x^2 - 1")) + @result{} fcn = f(x) = x.^2 - 1 +quadv (fcn, 0, 3) + @result{} 6 +@end group +@end example +@seealso{inline, formula, argnames} +@end deftypefn */) { if (args.length () != 1) print_usage ();
--- a/libinterp/octave-value/ov-flt-re-mat.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/octave-value/ov-flt-re-mat.cc Tue Jun 21 16:07:51 2016 -0400 @@ -812,11 +812,11 @@ } DEFUN (single, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} single (@var{x})\n\ -Convert @var{x} to single precision type.\n\ -@seealso{double}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} single (@var{x}) +Convert @var{x} to single precision type. +@seealso{double} +@end deftypefn */) { // The OCTAVE_TYPE_CONV_BODY3 macro declares retval, so they go // inside their own scopes, and we don't declare retval here to
--- a/libinterp/octave-value/ov-int16.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/octave-value/ov-int16.cc Tue Jun 21 16:07:51 2016 -0400 @@ -79,11 +79,11 @@ "int16 scalar", "int16"); DEFUN (int16, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} int16 (@var{x})\n\ -Convert @var{x} to 16-bit integer type.\n\ -@seealso{int8, uint8, uint16, int32, uint32, int64, uint64}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} int16 (@var{x}) +Convert @var{x} to 16-bit integer type. +@seealso{int8, uint8, uint16, int32, uint32, int64, uint64} +@end deftypefn */) { OCTAVE_TYPE_CONV_BODY (int16); }
--- a/libinterp/octave-value/ov-int32.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/octave-value/ov-int32.cc Tue Jun 21 16:07:51 2016 -0400 @@ -79,11 +79,11 @@ "int32 scalar", "int32"); DEFUN (int32, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} int32 (@var{x})\n\ -Convert @var{x} to 32-bit integer type.\n\ -@seealso{int8, uint8, int16, uint16, uint32, int64, uint64}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} int32 (@var{x}) +Convert @var{x} to 32-bit integer type. +@seealso{int8, uint8, int16, uint16, uint32, int64, uint64} +@end deftypefn */) { OCTAVE_TYPE_CONV_BODY (int32); }
--- a/libinterp/octave-value/ov-int64.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/octave-value/ov-int64.cc Tue Jun 21 16:07:51 2016 -0400 @@ -79,11 +79,11 @@ "int64 scalar", "int64"); DEFUN (int64, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} int64 (@var{x})\n\ -Convert @var{x} to 64-bit integer type.\n\ -@seealso{int8, uint8, int16, uint16, int32, uint32, uint64}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} int64 (@var{x}) +Convert @var{x} to 64-bit integer type. +@seealso{int8, uint8, int16, uint16, int32, uint32, uint64} +@end deftypefn */) { OCTAVE_TYPE_CONV_BODY (int64); }
--- a/libinterp/octave-value/ov-int8.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/octave-value/ov-int8.cc Tue Jun 21 16:07:51 2016 -0400 @@ -79,11 +79,11 @@ "int8 scalar", "int8"); DEFUN (int8, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} int8 (@var{x})\n\ -Convert @var{x} to 8-bit integer type.\n\ -@seealso{uint8, int16, uint16, int32, uint32, int64, uint64}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} int8 (@var{x}) +Convert @var{x} to 8-bit integer type. +@seealso{uint8, int16, uint16, int32, uint32, int64, uint64} +@end deftypefn */) { OCTAVE_TYPE_CONV_BODY (int8); }
--- a/libinterp/octave-value/ov-java.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/octave-value/ov-java.cc Tue Jun 21 16:07:51 2016 -0400 @@ -2651,12 +2651,12 @@ // documentation strings are always available, even when functions are not. DEFUN (__java_init__, , , - "-*- texinfo -*-\n\ -@deftypefn {} {} __java_init__ ()\n\ -Internal function used @strong{only} when debugging Java interface.\n\ -\n\ -Function will directly call initialize_java to create an instance of a JVM.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __java_init__ () +Internal function used @strong{only} when debugging Java interface. + +Function will directly call initialize_java to create an instance of a JVM. +@end deftypefn */) { #if defined (HAVE_JAVA) @@ -2678,13 +2678,13 @@ } DEFUN (__java_exit__, , , - "-*- texinfo -*-\n\ -@deftypefn {} {} __java_exit__ ()\n\ -Internal function used @strong{only} when debugging Java interface.\n\ -\n\ -Function will directly call terminate_jvm to destroy the current JVM\n\ -instance.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __java_exit__ () +Internal function used @strong{only} when debugging Java interface. + +Function will directly call terminate_jvm to destroy the current JVM +instance. +@end deftypefn */) { #if defined (HAVE_JAVA) @@ -2700,24 +2700,24 @@ } DEFUN (javaObject, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{jobj} =} javaObject (@var{classname})\n\ -@deftypefnx {} {@var{jobj} =} javaObject (@var{classname}, @var{arg1}, @dots{})\n\ -Create a Java object of class @var{classsname}, by calling the class\n\ -constructor with the arguments @var{arg1}, @dots{}\n\ -\n\ -The first example below creates an uninitialized object, while the second\n\ -example supplies an initial argument to the constructor.\n\ -\n\ -@example\n\ -@group\n\ -x = javaObject (\"java.lang.StringBuffer\")\n\ -x = javaObject (\"java.lang.StringBuffer\", \"Initial string\")\n\ -@end group\n\ -@end example\n\ -\n\ -@seealso{javaMethod, javaArray}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{jobj} =} javaObject (@var{classname}) +@deftypefnx {} {@var{jobj} =} javaObject (@var{classname}, @var{arg1}, @dots{}) +Create a Java object of class @var{classsname}, by calling the class +constructor with the arguments @var{arg1}, @dots{} + +The first example below creates an uninitialized object, while the second +example supplies an initial argument to the constructor. + +@example +@group +x = javaObject ("java.lang.StringBuffer") +x = javaObject ("java.lang.StringBuffer", "Initial string") +@end group +@end example + +@seealso{javaMethod, javaArray} +@end deftypefn */) { #if defined (HAVE_JAVA) @@ -2755,30 +2755,30 @@ */ DEFUN (javaMethod, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{ret} =} javaMethod (@var{methodname}, @var{obj})\n\ -@deftypefnx {} {@var{ret} =} javaMethod (@var{methodname}, @var{obj}, @var{arg1}, @dots{})\n\ -Invoke the method @var{methodname} on the Java object @var{obj} with the\n\ -arguments @var{arg1}, @dots{}.\n\ -\n\ -For static methods, @var{obj} can be a string representing the fully\n\ -qualified name of the corresponding class.\n\ -\n\ -When @var{obj} is a regular Java object, structure-like indexing can be\n\ -used as a shortcut syntax. For instance, the two following statements are\n\ -equivalent\n\ -\n\ -@example\n\ -@group\n\ - ret = javaMethod (\"method1\", x, 1.0, \"a string\")\n\ - ret = x.method1 (1.0, \"a string\")\n\ -@end group\n\ -@end example\n\ -\n\ -@code{javaMethod} returns the result of the method invocation.\n\ -\n\ -@seealso{methods, javaObject}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{ret} =} javaMethod (@var{methodname}, @var{obj}) +@deftypefnx {} {@var{ret} =} javaMethod (@var{methodname}, @var{obj}, @var{arg1}, @dots{}) +Invoke the method @var{methodname} on the Java object @var{obj} with the +arguments @var{arg1}, @dots{}. + +For static methods, @var{obj} can be a string representing the fully +qualified name of the corresponding class. + +When @var{obj} is a regular Java object, structure-like indexing can be +used as a shortcut syntax. For instance, the two following statements are +equivalent + +@example +@group + ret = javaMethod ("method1", x, 1.0, "a string") + ret = x.method1 (1.0, "a string") +@end group +@end example + +@code{javaMethod} returns the result of the method invocation. + +@seealso{methods, javaObject} +@end deftypefn */) { #if defined (HAVE_JAVA) @@ -2829,26 +2829,26 @@ */ DEFUN (__java_get__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} __java_get__ (@var{obj}, @var{name})\n\ -Get the value of the field @var{name} of the Java object @var{obj}.\n\ -\n\ -For static fields, @var{obj} can be a string representing the fully\n\ -qualified name of the corresponding class.\n\ -\n\ -When @var{obj} is a regular Java object, structure-like indexing can be used\n\ -as a shortcut syntax. For instance, the two following statements are\n\ -equivalent\n\ -\n\ -@example\n\ -@group\n\ - __java_get__ (x, \"field1\")\n\ - x.field1\n\ -@end group\n\ -@end example\n\ -\n\ -@seealso{__java_set__, javaMethod, javaObject}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} __java_get__ (@var{obj}, @var{name}) +Get the value of the field @var{name} of the Java object @var{obj}. + +For static fields, @var{obj} can be a string representing the fully +qualified name of the corresponding class. + +When @var{obj} is a regular Java object, structure-like indexing can be used +as a shortcut syntax. For instance, the two following statements are +equivalent + +@example +@group + __java_get__ (x, "field1") + x.field1 +@end group +@end example + +@seealso{__java_set__, javaMethod, javaObject} +@end deftypefn */) { #if defined (HAVE_JAVA) @@ -2888,27 +2888,27 @@ } DEFUN (__java_set__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{obj} =} __java_set__ (@var{obj}, @var{name}, @var{val})\n\ -Set the value of the field @var{name} of the Java object @var{obj} to\n\ -@var{val}.\n\ -\n\ -For static fields, @var{obj} can be a string representing the fully\n\ -qualified named of the corresponding Java class.\n\ -\n\ -When @var{obj} is a regular Java object, structure-like indexing can be\n\ -used as a shortcut syntax. For instance, the two following statements are\n\ -equivalent\n\ -\n\ -@example\n\ -@group\n\ - __java_set__ (x, \"field1\", val)\n\ - x.field1 = val\n\ -@end group\n\ -@end example\n\ -\n\ -@seealso{__java_get__, javaMethod, javaObject}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{obj} =} __java_set__ (@var{obj}, @var{name}, @var{val}) +Set the value of the field @var{name} of the Java object @var{obj} to +@var{val}. + +For static fields, @var{obj} can be a string representing the fully +qualified named of the corresponding Java class. + +When @var{obj} is a regular Java object, structure-like indexing can be +used as a shortcut syntax. For instance, the two following statements are +equivalent + +@example +@group + __java_set__ (x, "field1", val) + x.field1 = val +@end group +@end example + +@seealso{__java_get__, javaMethod, javaObject} +@end deftypefn */) { #if defined (HAVE_JAVA) @@ -2948,10 +2948,10 @@ } DEFUN (java2mat, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} java2mat (@var{javaobj})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} java2mat (@var{javaobj}) +Undocumented internal function. +@end deftypefn */) { #if defined (HAVE_JAVA) @@ -2984,20 +2984,20 @@ } DEFUN (java_matrix_autoconversion, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} java_matrix_autoconversion ()\n\ -@deftypefnx {} {@var{old_val} =} java_matrix_autoconversion (@var{new_val})\n\ -@deftypefnx {} {} java_matrix_autoconversion (@var{new_val}, \"local\")\n\ -Query or set the internal variable that controls whether Java arrays are\n\ -automatically converted to Octave matrices.\n\ -\n\ -The default value is false.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{java_unsigned_autoconversion, debug_java}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} java_matrix_autoconversion () +@deftypefnx {} {@var{old_val} =} java_matrix_autoconversion (@var{new_val}) +@deftypefnx {} {} java_matrix_autoconversion (@var{new_val}, "local") +Query or set the internal variable that controls whether Java arrays are +automatically converted to Octave matrices. + +The default value is false. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{java_unsigned_autoconversion, debug_java} +@end deftypefn */) { #if defined (HAVE_JAVA) @@ -3014,21 +3014,21 @@ } DEFUN (java_unsigned_autoconversion, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} java_unsigned_autoconversion ()\n\ -@deftypefnx {} {@var{old_val} =} java_unsigned_autoconversion (@var{new_val})\n\ -@deftypefnx {} {} java_unsigned_autoconversion (@var{new_val}, \"local\")\n\ -Query or set the internal variable that controls how integer classes are\n\ -converted when @code{java_matrix_autoconversion} is enabled.\n\ -\n\ -When enabled, Java arrays of class Byte or Integer are converted to matrices\n\ -of class uint8 or uint32 respectively. The default value is true.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{java_matrix_autoconversion, debug_java}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} java_unsigned_autoconversion () +@deftypefnx {} {@var{old_val} =} java_unsigned_autoconversion (@var{new_val}) +@deftypefnx {} {} java_unsigned_autoconversion (@var{new_val}, "local") +Query or set the internal variable that controls how integer classes are +converted when @code{java_matrix_autoconversion} is enabled. + +When enabled, Java arrays of class Byte or Integer are converted to matrices +of class uint8 or uint32 respectively. The default value is true. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{java_matrix_autoconversion, debug_java} +@end deftypefn */) { #if defined (HAVE_JAVA) @@ -3045,19 +3045,19 @@ } DEFUN (debug_java, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} debug_java ()\n\ -@deftypefnx {} {@var{old_val} =} debug_java (@var{new_val})\n\ -@deftypefnx {} {} debug_java (@var{new_val}, \"local\")\n\ -Query or set the internal variable that determines whether extra debugging\n\ -information regarding the initialization of the JVM and any Java exceptions\n\ -is printed.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{java_matrix_autoconversion, java_unsigned_autoconversion}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} debug_java () +@deftypefnx {} {@var{old_val} =} debug_java (@var{new_val}) +@deftypefnx {} {} debug_java (@var{new_val}, "local") +Query or set the internal variable that determines whether extra debugging +information regarding the initialization of the JVM and any Java exceptions +is printed. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{java_matrix_autoconversion, java_unsigned_autoconversion} +@end deftypefn */) { #if defined (HAVE_JAVA) @@ -3078,11 +3078,11 @@ // installed. DEFUN (isjava, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isjava (@var{x})\n\ -Return true if @var{x} is a Java object.\n\ -@seealso{class, typeinfo, isa, javaObject}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isjava (@var{x}) +Return true if @var{x} is a Java object. +@seealso{class, typeinfo, isa, javaObject} +@end deftypefn */) { if (args.length () != 1) print_usage ();
--- a/libinterp/octave-value/ov-null-mat.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/octave-value/ov-null-mat.cc Tue Jun 21 16:07:51 2016 -0400 @@ -94,25 +94,25 @@ } DEFUN (isnull, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isnull (@var{x})\n\ -Return true if @var{x} is a special null matrix, string, or single quoted\n\ -string.\n\ -\n\ -Indexed assignment with such a value on the right-hand side should delete\n\ -array elements. This function should be used when overloading indexed\n\ -assignment for user-defined classes instead of @code{isempty}, to\n\ -distinguish the cases:\n\ -\n\ -@table @asis\n\ -@item @code{A(I) = []}\n\ -This should delete elements if @code{I} is nonempty.\n\ -\n\ -@item @code{X = []; A(I) = X}\n\ -This should give an error if @code{I} is nonempty.\n\ -@end table\n\ -@seealso{isempty, isindex}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isnull (@var{x}) +Return true if @var{x} is a special null matrix, string, or single quoted +string. + +Indexed assignment with such a value on the right-hand side should delete +array elements. This function should be used when overloading indexed +assignment for user-defined classes instead of @code{isempty}, to +distinguish the cases: + +@table @asis +@item @code{A(I) = []} +This should delete elements if @code{I} is nonempty. + +@item @code{X = []; A(I) = X} +This should give an error if @code{I} is nonempty. +@end table +@seealso{isempty, isindex} +@end deftypefn */) { if (args.length () != 1) print_usage ();
--- a/libinterp/octave-value/ov-oncleanup.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/octave-value/ov-oncleanup.cc Tue Jun 21 16:07:51 2016 -0400 @@ -173,16 +173,16 @@ } DEFUN (onCleanup, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{obj} =} onCleanup (@var{function})\n\ -Create a special object that executes a given function upon destruction.\n\ -\n\ -If the object is copied to multiple variables (or cell or struct array\n\ -elements) or returned from a function, @var{function} will be executed after\n\ -clearing the last copy of the object. Note that if multiple local onCleanup\n\ -variables are created, the order in which they are called is unspecified.\n\ -For similar functionality @xref{The unwind_protect Statement}.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{obj} =} onCleanup (@var{function}) +Create a special object that executes a given function upon destruction. + +If the object is copied to multiple variables (or cell or struct array +elements) or returned from a function, @var{function} will be executed after +clearing the last copy of the object. Note that if multiple local onCleanup +variables are created, the order in which they are called is unspecified. +For similar functionality @xref{The unwind_protect Statement}. +@end deftypefn */) { if (args.length () != 1) print_usage ();
--- a/libinterp/octave-value/ov-range.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/octave-value/ov-range.cc Tue Jun 21 16:07:51 2016 -0400 @@ -701,21 +701,21 @@ } DEFUN (allow_noninteger_range_as_index, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} allow_noninteger_range_as_index ()\n\ -@deftypefnx {} {@var{old_val} =} allow_noninteger_range_as_index (@var{new_val})\n\ -@deftypefnx {} {} allow_noninteger_range_as_index (@var{new_val}, \"local\")\n\ -Query or set the internal variable that controls whether non-integer\n\ -ranges are allowed as indices.\n\ -\n\ -This might be useful for @sc{matlab} compatibility; however, it is still not\n\ -entirely compatible because @sc{matlab} treats the range expression\n\ -differently in different contexts.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} allow_noninteger_range_as_index () +@deftypefnx {} {@var{old_val} =} allow_noninteger_range_as_index (@var{new_val}) +@deftypefnx {} {} allow_noninteger_range_as_index (@var{new_val}, "local") +Query or set the internal variable that controls whether non-integer +ranges are allowed as indices. + +This might be useful for @sc{matlab} compatibility; however, it is still not +entirely compatible because @sc{matlab} treats the range expression +differently in different contexts. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@end deftypefn */) { static bool warned = false; if (! warned)
--- a/libinterp/octave-value/ov-re-mat.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/octave-value/ov-re-mat.cc Tue Jun 21 16:07:51 2016 -0400 @@ -937,11 +937,11 @@ } DEFUN (double, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} double (@var{x})\n\ -Convert @var{x} to double precision type.\n\ -@seealso{single}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} double (@var{x}) +Convert @var{x} to double precision type. +@seealso{single} +@end deftypefn */) { // The OCTAVE_TYPE_CONV_BODY3 macro declares retval, so they go // inside their own scopes, and we don't declare retval here to
--- a/libinterp/octave-value/ov-struct.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/octave-value/ov-struct.cc Tue Jun 21 16:07:51 2016 -0400 @@ -1631,61 +1631,61 @@ } DEFUN (struct, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{s} =} struct ()\n\ -@deftypefnx {} {@var{s} =} struct (@var{field1}, @var{value1}, @var{field2}, @var{value2}, @dots{})\n\ -@deftypefnx {} {@var{s} =} struct (@var{obj})\n\ -\n\ -Create a scalar or array structure and initialize its values.\n\ -\n\ -The @var{field1}, @var{field2}, @dots{} variables are strings specifying the\n\ -names of the fields and the @var{value1}, @var{value2}, @dots{} variables\n\ -can be of any type.\n\ -\n\ -If the values are cell arrays, create a structure array and initialize its\n\ -values. The dimensions of each cell array of values must match. Singleton\n\ -cells and non-cell values are repeated so that they fill the entire array.\n\ -If the cells are empty, create an empty structure array with the specified\n\ -field names.\n\ -\n\ -If the argument is an object, return the underlying struct.\n\ -\n\ -Observe that the syntax is optimized for struct @strong{arrays}. Consider\n\ -the following examples:\n\ -\n\ -@example\n\ -@group\n\ -struct (\"foo\", 1)\n\ - @result{} scalar structure containing the fields:\n\ - foo = 1\n\ -\n\ -struct (\"foo\", @{@})\n\ - @result{} 0x0 struct array containing the fields:\n\ - foo\n\ -\n\ -struct (\"foo\", @{ @{@} @})\n\ - @result{} scalar structure containing the fields:\n\ - foo = @{@}(0x0)\n\ -\n\ -struct (\"foo\", @{1, 2, 3@})\n\ - @result{} 1x3 struct array containing the fields:\n\ - foo\n\ -\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -The first case is an ordinary scalar struct---one field, one value. The\n\ -second produces an empty struct array with one field and no values, since\n\ -being passed an empty cell array of struct array values. When the value is\n\ -a cell array containing a single entry, this becomes a scalar struct with\n\ -that single entry as the value of the field. That single entry happens\n\ -to be an empty cell array.\n\ -\n\ -Finally, if the value is a non-scalar cell array, then @code{struct}\n\ -produces a struct @strong{array}.\n\ -@seealso{cell2struct, fieldnames, getfield, setfield, rmfield, isfield, orderfields, isstruct, structfun}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{s} =} struct () +@deftypefnx {} {@var{s} =} struct (@var{field1}, @var{value1}, @var{field2}, @var{value2}, @dots{}) +@deftypefnx {} {@var{s} =} struct (@var{obj}) + +Create a scalar or array structure and initialize its values. + +The @var{field1}, @var{field2}, @dots{} variables are strings specifying the +names of the fields and the @var{value1}, @var{value2}, @dots{} variables +can be of any type. + +If the values are cell arrays, create a structure array and initialize its +values. The dimensions of each cell array of values must match. Singleton +cells and non-cell values are repeated so that they fill the entire array. +If the cells are empty, create an empty structure array with the specified +field names. + +If the argument is an object, return the underlying struct. + +Observe that the syntax is optimized for struct @strong{arrays}. Consider +the following examples: + +@example +@group +struct ("foo", 1) + @result{} scalar structure containing the fields: + foo = 1 + +struct ("foo", @{@}) + @result{} 0x0 struct array containing the fields: + foo + +struct ("foo", @{ @{@} @}) + @result{} scalar structure containing the fields: + foo = @{@}(0x0) + +struct ("foo", @{1, 2, 3@}) + @result{} 1x3 struct array containing the fields: + foo + +@end group +@end example + +@noindent +The first case is an ordinary scalar struct---one field, one value. The +second produces an empty struct array with one field and no values, since +being passed an empty cell array of struct array values. When the value is +a cell array containing a single entry, this becomes a scalar struct with +that single entry as the value of the field. That single entry happens +to be an empty cell array. + +Finally, if the value is a non-scalar cell array, then @code{struct} +produces a struct @strong{array}. +@seealso{cell2struct, fieldnames, getfield, setfield, rmfield, isfield, orderfields, isstruct, structfun} +@end deftypefn */) { int nargin = args.length (); @@ -1808,11 +1808,11 @@ */ DEFUN (isstruct, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isstruct (@var{x})\n\ -Return true if @var{x} is a structure or a structure array.\n\ -@seealso{ismatrix, iscell, isa}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isstruct (@var{x}) +Return true if @var{x} is a structure or a structure array. +@seealso{ismatrix, iscell, isa} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1821,14 +1821,14 @@ } DEFUN (__fieldnames__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __fieldnames__ (@var{struct})\n\ -@deftypefnx {} {} __fieldnames__ (@var{obj})\n\ -Internal function.\n\ -\n\ -Implements @code{fieldnames()} for structures and Octave objects.\n\ -@seealso{fieldnames}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __fieldnames__ (@var{struct}) +@deftypefnx {} {} __fieldnames__ (@var{obj}) +Internal function. + +Implements @code{fieldnames()} for structures and Octave objects. +@seealso{fieldnames} +@end deftypefn */) { octave_value retval; @@ -1848,16 +1848,16 @@ } DEFUN (isfield, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isfield (@var{x}, \"@var{name}\")\n\ -@deftypefnx {} {} isfield (@var{x}, @var{name})\n\ -Return true if the @var{x} is a structure and it includes an element named\n\ -@var{name}.\n\ -\n\ -If @var{name} is a cell array of strings then a logical array of equal\n\ -dimension is returned.\n\ -@seealso{fieldnames}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isfield (@var{x}, "@var{name}") +@deftypefnx {} {} isfield (@var{x}, @var{name}) +Return true if the @var{x} is a structure and it includes an element named +@var{name}. + +If @var{name} is a cell array of strings then a logical array of equal +dimension is returned. +@seealso{fieldnames} +@end deftypefn */) { if (args.length () != 2) print_usage (); @@ -1902,11 +1902,11 @@ } DEFUN (numfields, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} numfields (@var{s})\n\ -Return the number of fields of the structure @var{s}.\n\ -@seealso{fieldnames}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} numfields (@var{s}) +Return the number of fields of the structure @var{s}. +@seealso{fieldnames} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -1930,32 +1930,32 @@ */ DEFUN (cell2struct, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} cell2struct (@var{cell}, @var{fields})\n\ -@deftypefnx {} {} cell2struct (@var{cell}, @var{fields}, @var{dim})\n\ -Convert @var{cell} to a structure.\n\ -\n\ -The number of fields in @var{fields} must match the number of elements in\n\ -@var{cell} along dimension @var{dim}, that is\n\ -@code{numel (@var{fields}) == size (@var{cell}, @var{dim})}. If @var{dim}\n\ -is omitted, a value of 1 is assumed.\n\ -\n\ -@example\n\ -@group\n\ -A = cell2struct (@{\"Peter\", \"Hannah\", \"Robert\";\n\ - 185, 170, 168@},\n\ - @{\"Name\",\"Height\"@}, 1);\n\ -A(1)\n\ - @result{}\n\ - @{\n\ - Name = Peter\n\ - Height = 185\n\ - @}\n\ -\n\ -@end group\n\ -@end example\n\ -@seealso{struct2cell, cell2mat, struct}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} cell2struct (@var{cell}, @var{fields}) +@deftypefnx {} {} cell2struct (@var{cell}, @var{fields}, @var{dim}) +Convert @var{cell} to a structure. + +The number of fields in @var{fields} must match the number of elements in +@var{cell} along dimension @var{dim}, that is +@code{numel (@var{fields}) == size (@var{cell}, @var{dim})}. If @var{dim} +is omitted, a value of 1 is assumed. + +@example +@group +A = cell2struct (@{"Peter", "Hannah", "Robert"; + 185, 170, 168@}, + @{"Name","Height"@}, 1); +A(1) + @result{} + @{ + Name = Peter + Height = 185 + @} + +@end group +@end example +@seealso{struct2cell, cell2mat, struct} +@end deftypefn */) { int nargin = args.length (); @@ -2041,16 +2041,16 @@ Fcellstr (const octave_value_list& = octave_value_list (), int = 0); DEFUN (rmfield, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{sout} =} rmfield (@var{s}, \"@var{f}\")\n\ -@deftypefnx {} {@var{sout} =} rmfield (@var{s}, @var{f})\n\ -Return a @emph{copy} of the structure (array) @var{s} with the field @var{f}\n\ -removed.\n\ -\n\ -If @var{f} is a cell array of strings or a character array, remove each of\n\ -the named fields.\n\ -@seealso{orderfields, fieldnames, isfield}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{sout} =} rmfield (@var{s}, "@var{f}") +@deftypefnx {} {@var{sout} =} rmfield (@var{s}, @var{f}) +Return a @emph{copy} of the structure (array) @var{s} with the field @var{f} +removed. + +If @var{f} is a cell array of strings or a character array, remove each of +the named fields. +@seealso{orderfields, fieldnames, isfield} +@end deftypefn */) { if (args.length () != 2) print_usage (); @@ -2090,41 +2090,41 @@ */ DEFUN (struct_levels_to_print, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} struct_levels_to_print ()\n\ -@deftypefnx {} {@var{old_val} =} struct_levels_to_print (@var{new_val})\n\ -@deftypefnx {} {} struct_levels_to_print (@var{new_val}, \"local\")\n\ -Query or set the internal variable that specifies the number of\n\ -structure levels to display.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{print_struct_array_contents}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} struct_levels_to_print () +@deftypefnx {} {@var{old_val} =} struct_levels_to_print (@var{new_val}) +@deftypefnx {} {} struct_levels_to_print (@var{new_val}, "local") +Query or set the internal variable that specifies the number of +structure levels to display. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{print_struct_array_contents} +@end deftypefn */) { return SET_INTERNAL_VARIABLE_WITH_LIMITS (struct_levels_to_print, -1, std::numeric_limits<int>::max ()); } DEFUN (print_struct_array_contents, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} print_struct_array_contents ()\n\ -@deftypefnx {} {@var{old_val} =} print_struct_array_contents (@var{new_val})\n\ -@deftypefnx {} {} print_struct_array_contents (@var{new_val}, \"local\")\n\ -Query or set the internal variable that specifies whether to print struct\n\ -array contents.\n\ -\n\ -If true, values of struct array elements are printed. This variable does\n\ -not affect scalar structures whose elements are always printed. In both\n\ -cases, however, printing will be limited to the number of levels specified\n\ -by @var{struct_levels_to_print}.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{struct_levels_to_print}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} print_struct_array_contents () +@deftypefnx {} {@var{old_val} =} print_struct_array_contents (@var{new_val}) +@deftypefnx {} {} print_struct_array_contents (@var{new_val}, "local") +Query or set the internal variable that specifies whether to print struct +array contents. + +If true, values of struct array elements are printed. This variable does +not affect scalar structures whose elements are always printed. In both +cases, however, printing will be limited to the number of levels specified +by @var{struct_levels_to_print}. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{struct_levels_to_print} +@end deftypefn */) { return SET_INTERNAL_VARIABLE (print_struct_array_contents); }
--- a/libinterp/octave-value/ov-typeinfo.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/octave-value/ov-typeinfo.cc Tue Jun 21 16:07:51 2016 -0400 @@ -606,16 +606,16 @@ } DEFUN (typeinfo, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} typeinfo ()\n\ -@deftypefnx {} {} typeinfo (@var{expr})\n\ -\n\ -Return the type of the expression @var{expr}, as a string.\n\ -\n\ -If @var{expr} is omitted, return a cell array of strings containing all the\n\ -currently installed data types.\n\ -@seealso{class, isa}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} typeinfo () +@deftypefnx {} {} typeinfo (@var{expr}) + +Return the type of the expression @var{expr}, as a string. + +If @var{expr} is omitted, return a cell array of strings containing all the +currently installed data types. +@seealso{class, isa} +@end deftypefn */) { int nargin = args.length ();
--- a/libinterp/octave-value/ov-uint16.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/octave-value/ov-uint16.cc Tue Jun 21 16:07:51 2016 -0400 @@ -79,11 +79,11 @@ "uint16 scalar", "uint16"); DEFUN (uint16, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} uint16 (@var{x})\n\ -Convert @var{x} to unsigned 16-bit integer type.\n\ -@seealso{int8, uint8, int16, int32, uint32, int64, uint64}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} uint16 (@var{x}) +Convert @var{x} to unsigned 16-bit integer type. +@seealso{int8, uint8, int16, int32, uint32, int64, uint64} +@end deftypefn */) { OCTAVE_TYPE_CONV_BODY (uint16); }
--- a/libinterp/octave-value/ov-uint32.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/octave-value/ov-uint32.cc Tue Jun 21 16:07:51 2016 -0400 @@ -79,11 +79,11 @@ "uint32 scalar", "uint32"); DEFUN (uint32, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} uint32 (@var{x})\n\ -Convert @var{x} to unsigned 32-bit integer type.\n\ -@seealso{int8, uint8, int16, uint16, int32, int64, uint64}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} uint32 (@var{x}) +Convert @var{x} to unsigned 32-bit integer type. +@seealso{int8, uint8, int16, uint16, int32, int64, uint64} +@end deftypefn */) { OCTAVE_TYPE_CONV_BODY (uint32); }
--- a/libinterp/octave-value/ov-uint64.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/octave-value/ov-uint64.cc Tue Jun 21 16:07:51 2016 -0400 @@ -79,11 +79,11 @@ "uint64 scalar", "uint64"); DEFUN (uint64, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} uint64 (@var{x})\n\ -Convert @var{x} to unsigned 64-bit integer type.\n\ -@seealso{int8, uint8, int16, uint16, int32, uint32, int64}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} uint64 (@var{x}) +Convert @var{x} to unsigned 64-bit integer type. +@seealso{int8, uint8, int16, uint16, int32, uint32, int64} +@end deftypefn */) { OCTAVE_TYPE_CONV_BODY (uint64); }
--- a/libinterp/octave-value/ov-uint8.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/octave-value/ov-uint8.cc Tue Jun 21 16:07:51 2016 -0400 @@ -79,11 +79,11 @@ "uint8 scalar", "uint8"); DEFUN (uint8, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} uint8 (@var{x})\n\ -Convert @var{x} to unsigned 8-bit integer type.\n\ -@seealso{int8, int16, uint16, int32, uint32, int64, uint64}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} uint8 (@var{x}) +Convert @var{x} to unsigned 8-bit integer type. +@seealso{int8, int16, uint16, int32, uint32, int64, uint64} +@end deftypefn */) { OCTAVE_TYPE_CONV_BODY (uint8); }
--- a/libinterp/octave-value/ov-usr-fcn.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/octave-value/ov-usr-fcn.cc Tue Jun 21 16:07:51 2016 -0400 @@ -781,37 +781,37 @@ } DEFUN (nargin, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} nargin ()\n\ -@deftypefnx {} {} nargin (@var{fcn})\n\ -Report the number of input arguments to a function.\n\ -\n\ -Called from within a function, return the number of arguments passed to the\n\ -function. At the top level, return the number of command line arguments\n\ -passed to Octave.\n\ -\n\ -If called with the optional argument @var{fcn}---a function name or\n\ -handle---return the declared number of arguments that the function can\n\ -accept.\n\ -\n\ -If the last argument to @var{fcn} is @var{varargin} the returned value is\n\ -negative. For example, the function @code{union} for sets is declared as\n\ -\n\ -@example\n\ -@group\n\ -function [y, ia, ib] = union (a, b, varargin)\n\ -\n\ -and\n\ -\n\ -nargin (\"union\")\n\ -@result{} -3\n\ -@end group\n\ -@end example\n\ -\n\ -Programming Note: @code{nargin} does not work on compiled functions\n\ -(@file{.oct} files) such as built-in or dynamically loaded functions.\n\ -@seealso{nargout, narginchk, varargin, inputname}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} nargin () +@deftypefnx {} {} nargin (@var{fcn}) +Report the number of input arguments to a function. + +Called from within a function, return the number of arguments passed to the +function. At the top level, return the number of command line arguments +passed to Octave. + +If called with the optional argument @var{fcn}---a function name or +handle---return the declared number of arguments that the function can +accept. + +If the last argument to @var{fcn} is @var{varargin} the returned value is +negative. For example, the function @code{union} for sets is declared as + +@example +@group +function [y, ia, ib] = union (a, b, varargin) + +and + +nargin ("union") +@result{} -3 +@end group +@end example + +Programming Note: @code{nargin} does not work on compiled functions +(@file{.oct} files) such as built-in or dynamically loaded functions. +@seealso{nargout, narginchk, varargin, inputname} +@end deftypefn */) { int nargin = args.length (); @@ -866,59 +866,59 @@ } DEFUN (nargout, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} nargout ()\n\ -@deftypefnx {} {} nargout (@var{fcn})\n\ -Report the number of output arguments from a function.\n\ -\n\ -Called from within a function, return the number of values the caller\n\ -expects to receive. At the top level, @code{nargout} with no argument is\n\ -undefined and will produce an error.\n\ -\n\ -If called with the optional argument @var{fcn}---a function name or\n\ -handle---return the number of declared output values that the function can\n\ -produce.\n\ -\n\ -If the final output argument is @var{varargout} the returned value is\n\ -negative.\n\ -\n\ -For example,\n\ -\n\ -@example\n\ -f ()\n\ -@end example\n\ -\n\ -@noindent\n\ -will cause @code{nargout} to return 0 inside the function @code{f} and\n\ -\n\ -@example\n\ -[s, t] = f ()\n\ -@end example\n\ -\n\ -@noindent\n\ -will cause @code{nargout} to return 2 inside the function @code{f}.\n\ -\n\ -In the second usage,\n\ -\n\ -@example\n\ -nargout (@@histc) \% or nargout (\"histc\")\n\ -@end example\n\ -\n\ -@noindent\n\ -will return 2, because @code{histc} has two outputs, whereas\n\ -\n\ -@example\n\ -nargout (@@imread)\n\ -@end example\n\ -\n\ -@noindent\n\ -will return -2, because @code{imread} has two outputs and the second is\n\ -@var{varargout}.\n\ -\n\ -Programming Note. @code{nargout} does not work for built-in functions and\n\ -returns -1 for all anonymous functions.\n\ -@seealso{nargin, varargout, isargout, nthargout}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} nargout () +@deftypefnx {} {} nargout (@var{fcn}) +Report the number of output arguments from a function. + +Called from within a function, return the number of values the caller +expects to receive. At the top level, @code{nargout} with no argument is +undefined and will produce an error. + +If called with the optional argument @var{fcn}---a function name or +handle---return the number of declared output values that the function can +produce. + +If the final output argument is @var{varargout} the returned value is +negative. + +For example, + +@example +f () +@end example + +@noindent +will cause @code{nargout} to return 0 inside the function @code{f} and + +@example +[s, t] = f () +@end example + +@noindent +will cause @code{nargout} to return 2 inside the function @code{f}. + +In the second usage, + +@example +nargout (@@histc) \% or nargout ("histc") +@end example + +@noindent +will return 2, because @code{histc} has two outputs, whereas + +@example +nargout (@@imread) +@end example + +@noindent +will return -2, because @code{imread} has two outputs and the second is +@var{varargout}. + +Programming Note. @code{nargout} does not work for built-in functions and +returns -1 for all anonymous functions. +@seealso{nargin, varargout, isargout, nthargout} +@end deftypefn */) { int nargin = args.length (); @@ -989,21 +989,21 @@ } DEFUN (optimize_subsasgn_calls, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} optimize_subsasgn_calls ()\n\ -@deftypefnx {} {@var{old_val} =} optimize_subsasgn_calls (@var{new_val})\n\ -@deftypefnx {} {} optimize_subsasgn_calls (@var{new_val}, \"local\")\n\ -Query or set the internal flag for @code{subsasgn} method call\n\ -optimizations.\n\ -\n\ -If true, Octave will attempt to eliminate the redundant copying when calling\n\ -the @code{subsasgn} method of a user-defined class.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{subsasgn}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} optimize_subsasgn_calls () +@deftypefnx {} {@var{old_val} =} optimize_subsasgn_calls (@var{new_val}) +@deftypefnx {} {} optimize_subsasgn_calls (@var{new_val}, "local") +Query or set the internal flag for @code{subsasgn} method call +optimizations. + +If true, Octave will attempt to eliminate the redundant copying when calling +the @code{subsasgn} method of a user-defined class. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{subsasgn} +@end deftypefn */) { return SET_INTERNAL_VARIABLE (optimize_subsasgn_calls); } @@ -1026,22 +1026,22 @@ } DEFUN (isargout, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isargout (@var{k})\n\ -Within a function, return a logical value indicating whether the argument\n\ -@var{k} will be assigned to a variable on output.\n\ -\n\ -If the result is false, the argument has been ignored during the function\n\ -call through the use of the tilde (~) special output argument. Functions\n\ -can use @code{isargout} to avoid performing unnecessary calculations for\n\ -outputs which are unwanted.\n\ -\n\ -If @var{k} is outside the range @code{1:max (nargout)}, the function returns\n\ -false. @var{k} can also be an array, in which case the function works\n\ -element-by-element and a logical array is returned. At the top level,\n\ -@code{isargout} returns an error.\n\ -@seealso{nargout, varargout, nthargout}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isargout (@var{k}) +Within a function, return a logical value indicating whether the argument +@var{k} will be assigned to a variable on output. + +If the result is false, the argument has been ignored during the function +call through the use of the tilde (~) special output argument. Functions +can use @code{isargout} to avoid performing unnecessary calculations for +outputs which are unwanted. + +If @var{k} is outside the range @code{1:max (nargout)}, the function returns +false. @var{k} can also be an array, in which case the function works +element-by-element and a logical array is returned. At the top level, +@code{isargout} returns an error. +@seealso{nargout, varargout, nthargout} +@end deftypefn */) { if (args.length () != 1) print_usage ();
--- a/libinterp/octave-value/ov.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/octave-value/ov.cc Tue Jun 21 16:07:51 2016 -0400 @@ -2713,11 +2713,11 @@ } DEFUN (sizeof, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} sizeof (@var{val})\n\ -Return the size of @var{val} in bytes.\n\ -@seealso{whos}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} sizeof (@var{val}) +Return the size of @var{val} in bytes. +@seealso{whos} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -2791,40 +2791,40 @@ } DEFUN (subsref, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} subsref (@var{val}, @var{idx})\n\ -Perform the subscripted element selection operation on @var{val} according\n\ -to the subscript specified by @var{idx}.\n\ -\n\ -The subscript @var{idx} must be a structure array with fields @samp{type}\n\ -and @samp{subs}. Valid values for @samp{type} are @qcode{\"()\"},\n\ -@qcode{\"@{@}\"}, and @qcode{\".\"}. The @samp{subs} field may be either\n\ -@qcode{\":\"} or a cell array of index values.\n\ -\n\ -The following example shows how to extract the first two columns of a matrix\n\ -\n\ -@example\n\ -@group\n\ -val = magic (3)\n\ - @result{} val = [ 8 1 6\n\ - 3 5 7\n\ - 4 9 2 ]\n\ -idx.type = \"()\";\n\ -idx.subs = @{\":\", 1:2@};\n\ -subsref (val, idx)\n\ - @result{} [ 8 1\n\ - 3 5\n\ - 4 9 ]\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -Note that this is the same as writing @code{val(:, 1:2)}.\n\ -\n\ -If @var{idx} is an empty structure array with fields @samp{type} and\n\ -@samp{subs}, return @var{val}.\n\ -@seealso{subsasgn, substruct}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} subsref (@var{val}, @var{idx}) +Perform the subscripted element selection operation on @var{val} according +to the subscript specified by @var{idx}. + +The subscript @var{idx} must be a structure array with fields @samp{type} +and @samp{subs}. Valid values for @samp{type} are @qcode{"()"}, +@qcode{"@{@}"}, and @qcode{"."}. The @samp{subs} field may be either +@qcode{":"} or a cell array of index values. + +The following example shows how to extract the first two columns of a matrix + +@example +@group +val = magic (3) + @result{} val = [ 8 1 6 + 3 5 7 + 4 9 2 ] +idx.type = "()"; +idx.subs = @{":", 1:2@}; +subsref (val, idx) + @result{} [ 8 1 + 3 5 + 4 9 ] +@end group +@end example + +@noindent +Note that this is the same as writing @code{val(:, 1:2)}. + +If @var{idx} is an empty structure array with fields @samp{type} and +@samp{subs}, return @var{val}. +@seealso{subsasgn, substruct} +@end deftypefn */) { if (args.length () != 2) print_usage (); @@ -2843,37 +2843,37 @@ } DEFUN (subsasgn, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} subsasgn (@var{val}, @var{idx}, @var{rhs})\n\ -Perform the subscripted assignment operation according to the subscript\n\ -specified by @var{idx}.\n\ -\n\ -The subscript @var{idx} must be a structure array with fields @samp{type}\n\ -and @samp{subs}. Valid values for @samp{type} are @qcode{\"()\"},\n\ -@qcode{\"@{@}\"}, and @qcode{\".\"}. The @samp{subs} field may be either\n\ -@qcode{\":\"} or a cell array of index values.\n\ -\n\ -The following example shows how to set the two first columns of a 3-by-3\n\ -matrix to zero.\n\ -\n\ -@example\n\ -@group\n\ -val = magic (3);\n\ -idx.type = \"()\";\n\ -idx.subs = @{\":\", 1:2@};\n\ -subsasgn (val, idx, 0)\n\ - @result{} [ 0 0 6\n\ - 0 0 7\n\ - 0 0 2 ]\n\ -@end group\n\ -@end example\n\ -\n\ -Note that this is the same as writing @code{val(:, 1:2) = 0}.\n\ -\n\ -If @var{idx} is an empty structure array with fields @samp{type} and\n\ -@samp{subs}, return @var{rhs}.\n\ -@seealso{subsref, substruct, optimize_subsasgn_calls}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} subsasgn (@var{val}, @var{idx}, @var{rhs}) +Perform the subscripted assignment operation according to the subscript +specified by @var{idx}. + +The subscript @var{idx} must be a structure array with fields @samp{type} +and @samp{subs}. Valid values for @samp{type} are @qcode{"()"}, +@qcode{"@{@}"}, and @qcode{"."}. The @samp{subs} field may be either +@qcode{":"} or a cell array of index values. + +The following example shows how to set the two first columns of a 3-by-3 +matrix to zero. + +@example +@group +val = magic (3); +idx.type = "()"; +idx.subs = @{":", 1:2@}; +subsasgn (val, idx, 0) + @result{} [ 0 0 6 + 0 0 7 + 0 0 2 ] +@end group +@end example + +Note that this is the same as writing @code{val(:, 1:2) = 0}. + +If @var{idx} is an empty structure array with fields @samp{type} and +@samp{subs}, return @var{rhs}. +@seealso{subsref, substruct, optimize_subsasgn_calls} +@end deftypefn */) { if (args.length () != 3) print_usage (); @@ -2966,11 +2966,11 @@ */ DEFUN (is_sq_string, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} is_sq_string (@var{x})\n\ -Return true if @var{x} is a single-quoted character string.\n\ -@seealso{is_dq_string, ischar}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} is_sq_string (@var{x}) +Return true if @var{x} is a single-quoted character string. +@seealso{is_dq_string, ischar} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -2989,11 +2989,11 @@ */ DEFUN (is_dq_string, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} is_dq_string (@var{x})\n\ -Return true if @var{x} is a double-quoted character string.\n\ -@seealso{is_sq_string, ischar}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} is_dq_string (@var{x}) +Return true if @var{x} is a double-quoted character string. +@seealso{is_sq_string, ischar} +@end deftypefn */) { if (args.length () != 1) print_usage (); @@ -3012,21 +3012,21 @@ */ DEFUN (disable_permutation_matrix, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} disable_permutation_matrix ()\n\ -@deftypefnx {} {@var{old_val} =} disable_permutation_matrix (@var{new_val})\n\ -@deftypefnx {} {} disable_permutation_matrix (@var{new_val}, \"local\")\n\ -Query or set the internal variable that controls whether permutation\n\ -matrices are stored in a special space-efficient format.\n\ -\n\ -The default value is true. If this option is disabled Octave will store\n\ -permutation matrices as full matrices.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{disable_range, disable_diagonal_matrix}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} disable_permutation_matrix () +@deftypefnx {} {@var{old_val} =} disable_permutation_matrix (@var{new_val}) +@deftypefnx {} {} disable_permutation_matrix (@var{new_val}, "local") +Query or set the internal variable that controls whether permutation +matrices are stored in a special space-efficient format. + +The default value is true. If this option is disabled Octave will store +permutation matrices as full matrices. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{disable_range, disable_diagonal_matrix} +@end deftypefn */) { return SET_INTERNAL_VARIABLE (disable_permutation_matrix); } @@ -3042,21 +3042,21 @@ */ DEFUN (disable_diagonal_matrix, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} disable_diagonal_matrix ()\n\ -@deftypefnx {} {@var{old_val} =} disable_diagonal_matrix (@var{new_val})\n\ -@deftypefnx {} {} disable_diagonal_matrix (@var{new_val}, \"local\")\n\ -Query or set the internal variable that controls whether diagonal\n\ -matrices are stored in a special space-efficient format.\n\ -\n\ -The default value is true. If this option is disabled Octave will store\n\ -diagonal matrices as full matrices.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{disable_range, disable_permutation_matrix}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} disable_diagonal_matrix () +@deftypefnx {} {@var{old_val} =} disable_diagonal_matrix (@var{new_val}) +@deftypefnx {} {} disable_diagonal_matrix (@var{new_val}, "local") +Query or set the internal variable that controls whether diagonal +matrices are stored in a special space-efficient format. + +The default value is true. If this option is disabled Octave will store +diagonal matrices as full matrices. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{disable_range, disable_permutation_matrix} +@end deftypefn */) { return SET_INTERNAL_VARIABLE (disable_diagonal_matrix); } @@ -3086,21 +3086,21 @@ */ DEFUN (disable_range, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} disable_range ()\n\ -@deftypefnx {} {@var{old_val} =} disable_range (@var{new_val})\n\ -@deftypefnx {} {} disable_range (@var{new_val}, \"local\")\n\ -Query or set the internal variable that controls whether ranges are stored\n\ -in a special space-efficient format.\n\ -\n\ -The default value is true. If this option is disabled Octave will store\n\ -ranges as full matrices.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@seealso{disable_diagonal_matrix, disable_permutation_matrix}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} disable_range () +@deftypefnx {} {@var{old_val} =} disable_range (@var{new_val}) +@deftypefnx {} {} disable_range (@var{new_val}, "local") +Query or set the internal variable that controls whether ranges are stored +in a special space-efficient format. + +The default value is true. If this option is disabled Octave will store +ranges as full matrices. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@seealso{disable_diagonal_matrix, disable_permutation_matrix} +@end deftypefn */) { return SET_INTERNAL_VARIABLE (disable_range); }
--- a/libinterp/octave.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/octave.cc Tue Jun 21 16:07:51 2016 -0400 @@ -249,10 +249,10 @@ } DEFUN (__version_info__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {retval =} __version_info__ (@var{name}, @var{version}, @var{release}, @var{date})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {retval =} __version_info__ (@var{name}, @var{version}, @var{release}, @var{date}) +Undocumented internal function. +@end deftypefn */) { static octave_map vinfo; @@ -1061,11 +1061,11 @@ } DEFUN (isguirunning, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} isguirunning ()\n\ -Return true if Octave is running in GUI mode and false otherwise.\n\ -@seealso{have_window_system}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} isguirunning () +Return true if Octave is running in GUI mode and false otherwise. +@seealso{have_window_system} +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -1079,24 +1079,24 @@ */ DEFUN (argv, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} argv ()\n\ -Return the command line arguments passed to Octave.\n\ -\n\ -For example, if you invoked Octave using the command\n\ -\n\ -@example\n\ -octave --no-line-editing --silent\n\ -@end example\n\ -\n\ -@noindent\n\ -@code{argv} would return a cell array of strings with the elements\n\ -@option{--no-line-editing} and @option{--silent}.\n\ -\n\ -If you write an executable Octave script, @code{argv} will return the list\n\ -of arguments passed to the script. @xref{Executable Octave Programs}, for\n\ -an example of how to create an executable Octave script.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} argv () +Return the command line arguments passed to Octave. + +For example, if you invoked Octave using the command + +@example +octave --no-line-editing --silent +@end example + +@noindent +@code{argv} would return a cell array of strings with the elements +@option{--no-line-editing} and @option{--silent}. + +If you write an executable Octave script, @code{argv} will return the list +of arguments passed to the script. @xref{Executable Octave Programs}, for +an example of how to create an executable Octave script. +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -1110,16 +1110,16 @@ */ DEFUN (program_invocation_name, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} program_invocation_name ()\n\ -Return the name that was typed at the shell prompt to run Octave.\n\ -\n\ -If executing a script from the command line (e.g., @code{octave foo.m})\n\ -or using an executable Octave script, the program name is set to the\n\ -name of the script. @xref{Executable Octave Programs}, for an example of\n\ -how to create an executable Octave script.\n\ -@seealso{program_name}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} program_invocation_name () +Return the name that was typed at the shell prompt to run Octave. + +If executing a script from the command line (e.g., @code{octave foo.m}) +or using an executable Octave script, the program name is set to the +name of the script. @xref{Executable Octave Programs}, for an example of +how to create an executable Octave script. +@seealso{program_name} +@end deftypefn */) { if (args.length () != 0) print_usage (); @@ -1133,12 +1133,12 @@ */ DEFUN (program_name, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} program_name ()\n\ -Return the last component of the value returned by\n\ -@code{program_invocation_name}.\n\ -@seealso{program_invocation_name}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} program_name () +Return the last component of the value returned by +@code{program_invocation_name}. +@seealso{program_invocation_name} +@end deftypefn */) { if (args.length () != 0) print_usage ();
--- a/libinterp/parse-tree/lex.ll Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/parse-tree/lex.ll Tue Jun 21 16:07:51 2016 -0400 @@ -1975,14 +1975,14 @@ } DEFUN (iskeyword, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} iskeyword ()\n\ -@deftypefnx {} {} iskeyword (@var{name})\n\ -Return true if @var{name} is an Octave keyword.\n\ -\n\ -If @var{name} is omitted, return a list of keywords.\n\ -@seealso{isvarname, exist}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} iskeyword () +@deftypefnx {} {} iskeyword (@var{name}) +Return true if @var{name} is an Octave keyword. + +If @var{name} is omitted, return a list of keywords. +@seealso{isvarname, exist} +@end deftypefn */) { octave_value retval; @@ -2035,34 +2035,34 @@ */ DEFUN (__display_tokens__, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} __display_tokens__ ()\n\ -Query or set the internal variable that determines whether Octave's\n\ -lexer displays tokens as they are read.\n\ -@seealso{__lexer_debug_flag__, __token_count__}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __display_tokens__ () +Query or set the internal variable that determines whether Octave's +lexer displays tokens as they are read. +@seealso{__lexer_debug_flag__, __token_count__} +@end deftypefn */) { return SET_INTERNAL_VARIABLE (display_tokens); } DEFUN (__token_count__, , , - "-*- texinfo -*-\n\ -@deftypefn {} {} __token_count__ ()\n\ -Return the number of language tokens processed since Octave startup.\n\ -@seealso{__lexer_debug_flag__, __display_tokens__}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __token_count__ () +Return the number of language tokens processed since Octave startup. +@seealso{__lexer_debug_flag__, __display_tokens__} +@end deftypefn */) { return octave_value (Vtoken_count); } DEFUN (__lexer_debug_flag__, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} __lexer_debug_flag__ ()\n\ -@deftypefnx {} {@var{old_val} =} __lexer_debug_flag__ (@var{new_val})\n\ -Query or set the internal flag that determines whether Octave's lexer prints\n\ -debug information as it processes an expression.\n\ -@seealso{__display_tokens__, __token_count__, __parse_debug_flag__}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} __lexer_debug_flag__ () +@deftypefnx {} {@var{old_val} =} __lexer_debug_flag__ (@var{new_val}) +Query or set the internal flag that determines whether Octave's lexer prints +debug information as it processes an expression. +@seealso{__display_tokens__, __token_count__, __parse_debug_flag__} +@end deftypefn */) { octave_value retval;
--- a/libinterp/parse-tree/oct-parse.in.yy Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/parse-tree/oct-parse.in.yy Tue Jun 21 16:07:51 2016 -0400 @@ -4401,44 +4401,44 @@ } DEFUN (autoload, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {@var{autoload_map} =} autoload ()\n\ -@deftypefnx {} {} autoload (@var{function}, @var{file})\n\ -@deftypefnx {} {} autoload (@dots{}, \"remove\")\n\ -Define @var{function} to autoload from @var{file}.\n\ -\n\ -The second argument, @var{file}, should be an absolute filename or a file\n\ -name in the same directory as the function or script from which the autoload\n\ -command was run. @var{file} @emph{should not} depend on the Octave load\n\ -path.\n\ -\n\ -Normally, calls to @code{autoload} appear in PKG_ADD script files that are\n\ -evaluated when a directory is added to Octave's load path. To avoid having\n\ -to hardcode directory names in @var{file}, if @var{file} is in the same\n\ -directory as the PKG_ADD script then\n\ -\n\ -@example\n\ -autoload (\"foo\", \"bar.oct\");\n\ -@end example\n\ -\n\ -@noindent\n\ -will load the function @code{foo} from the file @code{bar.oct}. The above\n\ -usage when @code{bar.oct} is not in the same directory, or usages such as\n\ -\n\ -@example\n\ -autoload (\"foo\", file_in_loadpath (\"bar.oct\"))\n\ -@end example\n\ -\n\ -@noindent\n\ -are strongly discouraged, as their behavior may be unpredictable.\n\ -\n\ -With no arguments, return a structure containing the current autoload map.\n\ -\n\ -If a third argument @qcode{\"remove\"} is given, the function is cleared and\n\ -not loaded anymore during the current Octave session.\n\ -\n\ -@seealso{PKG_ADD}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{autoload_map} =} autoload () +@deftypefnx {} {} autoload (@var{function}, @var{file}) +@deftypefnx {} {} autoload (@dots{}, "remove") +Define @var{function} to autoload from @var{file}. + +The second argument, @var{file}, should be an absolute filename or a file +name in the same directory as the function or script from which the autoload +command was run. @var{file} @emph{should not} depend on the Octave load +path. + +Normally, calls to @code{autoload} appear in PKG_ADD script files that are +evaluated when a directory is added to Octave's load path. To avoid having +to hardcode directory names in @var{file}, if @var{file} is in the same +directory as the PKG_ADD script then + +@example +autoload ("foo", "bar.oct"); +@end example + +@noindent +will load the function @code{foo} from the file @code{bar.oct}. The above +usage when @code{bar.oct} is not in the same directory, or usages such as + +@example +autoload ("foo", file_in_loadpath ("bar.oct")) +@end example + +@noindent +are strongly discouraged, as their behavior may be unpredictable. + +With no arguments, return a structure containing the current autoload map. + +If a third argument @qcode{"remove"} is given, the function is cleared and +not loaded anymore during the current Octave session. + +@seealso{PKG_ADD} +@end deftypefn */) { octave_value retval; @@ -4666,20 +4666,20 @@ } DEFUN (mfilename, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} mfilename ()\n\ -@deftypefnx {} {} mfilename (\"fullpath\")\n\ -@deftypefnx {} {} mfilename (\"fullpathext\")\n\ -Return the name of the currently executing file.\n\ -\n\ -When called from outside an m-file return the empty string.\n\ -\n\ -Given the argument @qcode{\"fullpath\"}, include the directory part of the\n\ -filename, but not the extension.\n\ -\n\ -Given the argument @qcode{\"fullpathext\"}, include the directory part of\n\ -the filename and the extension.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} mfilename () +@deftypefnx {} {} mfilename ("fullpath") +@deftypefnx {} {} mfilename ("fullpathext") +Return the name of the currently executing file. + +When called from outside an m-file return the empty string. + +Given the argument @qcode{"fullpath"}, include the directory part of the +filename, but not the extension. + +Given the argument @qcode{"fullpathext"}, include the directory part of +the filename and the extension. +@end deftypefn */) { octave_value retval; @@ -4727,20 +4727,20 @@ } DEFUN (source, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} source (@var{file})\n\ -@deftypefnx {} {} source (@var{file}, @var{context})\n\ -Parse and execute the contents of @var{file}.\n\ -\n\ -Without specifying @var{context}, this is equivalent to executing commands\n\ -from a script file, but without requiring the file to be named\n\ -@file{@var{file}.m} or to be on the execution path.\n\ -\n\ -Instead of the current context, the script may be executed in either the\n\ -context of the function that called the present function\n\ -(@qcode{\"caller\"}), or the top-level context (@qcode{\"base\"}).\n\ -@seealso{run}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} source (@var{file}) +@deftypefnx {} {} source (@var{file}, @var{context}) +Parse and execute the contents of @var{file}. + +Without specifying @var{context}, this is equivalent to executing commands +from a script file, but without requiring the file to be named +@file{@var{file}.m} or to be on the execution path. + +Instead of the current context, the script may be executed in either the +context of the function that called the present function +(@qcode{"caller"}), or the top-level context (@qcode{"base"}). +@seealso{run} +@end deftypefn */) { octave_value_list retval; @@ -4847,44 +4847,44 @@ } DEFUN (feval, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} feval (@var{name}, @dots{})\n\ -Evaluate the function named @var{name}.\n\ -\n\ -Any arguments after the first are passed as inputs to the named function.\n\ -For example,\n\ -\n\ -@example\n\ -@group\n\ -feval (\"acos\", -1)\n\ - @result{} 3.1416\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -calls the function @code{acos} with the argument @samp{-1}.\n\ -\n\ -The function @code{feval} can also be used with function handles of any sort\n\ -(@pxref{Function Handles}). Historically, @code{feval} was the only way to\n\ -call user-supplied functions in strings, but function handles are now\n\ -preferred due to the cleaner syntax they offer. For example,\n\ -\n\ -@example\n\ -@group\n\ -@var{f} = @@exp;\n\ -feval (@var{f}, 1)\n\ - @result{} 2.7183\n\ -@var{f} (1)\n\ - @result{} 2.7183\n\ -@end group\n\ -@end example\n\ -\n\ -@noindent\n\ -are equivalent ways to call the function referred to by @var{f}. If it\n\ -cannot be predicted beforehand whether @var{f} is a function handle,\n\ -function name in a string, or inline function then @code{feval} can be used\n\ -instead.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} feval (@var{name}, @dots{}) +Evaluate the function named @var{name}. + +Any arguments after the first are passed as inputs to the named function. +For example, + +@example +@group +feval ("acos", -1) + @result{} 3.1416 +@end group +@end example + +@noindent +calls the function @code{acos} with the argument @samp{-1}. + +The function @code{feval} can also be used with function handles of any sort +(@pxref{Function Handles}). Historically, @code{feval} was the only way to +call user-supplied functions in strings, but function handles are now +preferred due to the cleaner syntax they offer. For example, + +@example +@group +@var{f} = @@exp; +feval (@var{f}, 1) + @result{} 2.7183 +@var{f} (1) + @result{} 2.7183 +@end group +@end example + +@noindent +are equivalent ways to call the function referred to by @var{f}. If it +cannot be predicted beforehand whether @var{f} is a function handle, +function name in a string, or inline function then @code{feval} can be used +instead. +@end deftypefn */) { if (args.length () == 0) print_usage (); @@ -4893,30 +4893,30 @@ } DEFUN (builtin, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {[@dots{}] =} builtin (@var{f}, @dots{})\n\ -Call the base function @var{f} even if @var{f} is overloaded to another\n\ -function for the given type signature.\n\ -\n\ -This is normally useful when doing object-oriented programming and there is\n\ -a requirement to call one of Octave's base functions rather than the\n\ -overloaded one of a new class.\n\ -\n\ -A trivial example which redefines the @code{sin} function to be the\n\ -@code{cos} function shows how @code{builtin} works.\n\ -\n\ -@example\n\ -@group\n\ -sin (0)\n\ - @result{} 0\n\ -function y = sin (x), y = cos (x); endfunction\n\ -sin (0)\n\ - @result{} 1\n\ -builtin (\"sin\", 0)\n\ - @result{} 0\n\ -@end group\n\ -@end example\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {[@dots{}] =} builtin (@var{f}, @dots{}) +Call the base function @var{f} even if @var{f} is overloaded to another +function for the given type signature. + +This is normally useful when doing object-oriented programming and there is +a requirement to call one of Octave's base functions rather than the +overloaded one of a new class. + +A trivial example which redefines the @code{sin} function to be the +@code{cos} function shows how @code{builtin} works. + +@example +@group +sin (0) + @result{} 0 +function y = sin (x), y = cos (x); endfunction +sin (0) + @result{} 1 +builtin ("sin", 0) + @result{} 0 +@end group +@end example +@end deftypefn */) { octave_value_list retval; @@ -5036,44 +5036,44 @@ } DEFUN (eval, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} eval (@var{try})\n\ -@deftypefnx {} {} eval (@var{try}, @var{catch})\n\ -Parse the string @var{try} and evaluate it as if it were an Octave\n\ -program.\n\ -\n\ -If execution fails, evaluate the optional string @var{catch}.\n\ -\n\ -The string @var{try} is evaluated in the current context, so any results\n\ -remain available after @code{eval} returns.\n\ -\n\ -The following example creates the variable @var{A} with the approximate\n\ -value of 3.1416 in the current workspace.\n\ -\n\ -@example\n\ -eval (\"A = acos(-1);\");\n\ -@end example\n\ -\n\ -If an error occurs during the evaluation of @var{try} then the @var{catch}\n\ -string is evaluated, as the following example shows:\n\ -\n\ -@example\n\ -@group\n\ -eval ('error (\"This is a bad example\");',\n\ - 'printf (\"This error occurred:\\n%s\\n\", lasterr ());');\n\ - @print{} This error occurred:\n\ - This is a bad example\n\ -@end group\n\ -@end example\n\ -\n\ -Programming Note: if you are only using @code{eval} as an error-capturing\n\ -mechanism, rather than for the execution of arbitrary code strings,\n\ -Consider using try/catch blocks or unwind_protect/unwind_protect_cleanup\n\ -blocks instead. These techniques have higher performance and don't\n\ -introduce the security considerations that the evaluation of arbitrary code\n\ -does.\n\ -@seealso{evalin, evalc, assignin, feval}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} eval (@var{try}) +@deftypefnx {} {} eval (@var{try}, @var{catch}) +Parse the string @var{try} and evaluate it as if it were an Octave +program. + +If execution fails, evaluate the optional string @var{catch}. + +The string @var{try} is evaluated in the current context, so any results +remain available after @code{eval} returns. + +The following example creates the variable @var{A} with the approximate +value of 3.1416 in the current workspace. + +@example +eval ("A = acos(-1);"); +@end example + +If an error occurs during the evaluation of @var{try} then the @var{catch} +string is evaluated, as the following example shows: + +@example +@group +eval ('error ("This is a bad example");', + 'printf ("This error occurred:\n%s\n", lasterr ());'); + @print{} This error occurred: + This is a bad example +@end group +@end example + +Programming Note: if you are only using @code{eval} as an error-capturing +mechanism, rather than for the execution of arbitrary code strings, +Consider using try/catch blocks or unwind_protect/unwind_protect_cleanup +blocks instead. These techniques have higher performance and don't +introduce the security considerations that the evaluation of arbitrary code +does. +@seealso{evalin, evalc, assignin, feval} +@end deftypefn */) { octave_value_list retval; @@ -5174,12 +5174,12 @@ */ DEFUN (assignin, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} assignin (@var{context}, @var{varname}, @var{value})\n\ -Assign @var{value} to @var{varname} in context @var{context}, which\n\ -may be either @qcode{\"base\"} or @qcode{\"caller\"}.\n\ -@seealso{evalin}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} assignin (@var{context}, @var{varname}, @var{value}) +Assign @var{value} to @var{varname} in context @var{context}, which +may be either @qcode{"base"} or @qcode{"caller"}. +@seealso{evalin} +@end deftypefn */) { octave_value_list retval; @@ -5225,13 +5225,13 @@ */ DEFUN (evalin, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {} evalin (@var{context}, @var{try})\n\ -@deftypefnx {} {} evalin (@var{context}, @var{try}, @var{catch})\n\ -Like @code{eval}, except that the expressions are evaluated in the context\n\ -@var{context}, which may be either @qcode{\"caller\"} or @qcode{\"base\"}.\n\ -@seealso{eval, assignin}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} evalin (@var{context}, @var{try}) +@deftypefnx {} {} evalin (@var{context}, @var{try}, @var{catch}) +Like @code{eval}, except that the expressions are evaluated in the context +@var{context}, which may be either @qcode{"caller"} or @qcode{"base"}. +@seealso{eval, assignin} +@end deftypefn */) { octave_value_list retval; @@ -5305,33 +5305,33 @@ } DEFUN (evalc, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{s} =} evalc (@var{try})\n\ -@deftypefnx {} {@var{s} =} evalc (@var{try}, @var{catch})\n\ -Parse and evaluate the string @var{try} as if it were an Octave program,\n\ -while capturing the output into the return variable @var{s}.\n\ -\n\ -If execution fails, evaluate the optional string @var{catch}.\n\ -\n\ -This function behaves like @code{eval}, but any output or warning messages\n\ -which would normally be written to the console are captured and returned in\n\ -the string @var{s}.\n\ -\n\ -The @code{diary} is disabled during the execution of this function. When\n\ -@code{system} is used, any output produced by external programs is\n\ -@emph{not} captured, unless their output is captured by the @code{system}\n\ -function itself.\n\ -\n\ -@example\n\ -@group\n\ -s = evalc (\"t = 42\"), t\n\ - @result{} s = t = 42\n\ -\n\ - @result{} t = 42\n\ -@end group\n\ -@end example\n\ -@seealso{eval, diary}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{s} =} evalc (@var{try}) +@deftypefnx {} {@var{s} =} evalc (@var{try}, @var{catch}) +Parse and evaluate the string @var{try} as if it were an Octave program, +while capturing the output into the return variable @var{s}. + +If execution fails, evaluate the optional string @var{catch}. + +This function behaves like @code{eval}, but any output or warning messages +which would normally be written to the console are captured and returned in +the string @var{s}. + +The @code{diary} is disabled during the execution of this function. When +@code{system} is used, any output produced by external programs is +@emph{not} captured, unless their output is captured by the @code{system} +function itself. + +@example +@group +s = evalc ("t = 42"), t + @result{} s = t = 42 + + @result{} t = 42 +@end group +@end example +@seealso{eval, diary} +@end deftypefn */) { int nargin = args.length (); @@ -5445,13 +5445,13 @@ */ DEFUN (__parser_debug_flag__, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} __parser_debug_flag__ ()\n\ -@deftypefnx {} {@var{old_val} =} __parser_debug_flag__ (@var{new_val})\n\ -Query or set the internal flag that determines whether Octave's parser\n\ -prints debug information as it processes an expression.\n\ -@seealso{__lexer_debug_flag__}\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} __parser_debug_flag__ () +@deftypefnx {} {@var{old_val} =} __parser_debug_flag__ (@var{new_val}) +Query or set the internal flag that determines whether Octave's parser +prints debug information as it processes an expression. +@seealso{__lexer_debug_flag__} +@end deftypefn */) { octave_value retval; @@ -5466,10 +5466,10 @@ } DEFUN (__parse_file__, args, , - "-*- texinfo -*-\n\ -@deftypefn {} {} __parse_file__ (@var{file}, @var{verbose})\n\ -Undocumented internal function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} __parse_file__ (@var{file}, @var{verbose}) +Undocumented internal function. +@end deftypefn */) { octave_value retval;
--- a/libinterp/parse-tree/pt-arg-list.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/parse-tree/pt-arg-list.cc Tue Jun 21 16:07:51 2016 -0400 @@ -127,26 +127,26 @@ static int num_indices = 0; DEFCONSTFUN (end, , , - "-*- texinfo -*-\n\ -@deftypefn {} {} end\n\ -The magic index @qcode{\"end\"} refers to the last valid entry in an\n\ -indexing operation.\n\ -\n\ -Example:\n\ -\n\ -@example\n\ -@group\n\ -@var{x} = [ 1 2 3\n\ - 4 5 6 ];\n\ -@var{x}(1,end)\n\ - @result{} 3\n\ -@var{x}(end,1)\n\ - @result{} 4\n\ -@var{x}(end,end)\n\ - @result{} 6\n\ -@end group\n\ -@end example\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {} end +The magic index @qcode{"end"} refers to the last valid entry in an +indexing operation. + +Example: + +@example +@group +@var{x} = [ 1 2 3 + 4 5 6 ]; +@var{x}(1,end) + @result{} 3 +@var{x}(end,1) + @result{} 4 +@var{x}(end,end) + @result{} 6 +@end group +@end example +@end deftypefn */) { octave_value retval;
--- a/libinterp/parse-tree/pt-binop.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/parse-tree/pt-binop.cc Tue Jun 21 16:07:51 2016 -0400 @@ -260,24 +260,24 @@ } DEFUN (do_braindead_shortcircuit_evaluation, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} do_braindead_shortcircuit_evaluation ()\n\ -@deftypefnx {} {@var{old_val} =} do_braindead_shortcircuit_evaluation (@var{new_val})\n\ -@deftypefnx {} {} do_braindead_shortcircuit_evaluation (@var{new_val}, \"local\")\n\ -Query or set the internal variable that controls whether Octave will\n\ -do short-circuit evaluation of @samp{|} and @samp{&} operators inside the\n\ -conditions of if or while statements.\n\ -\n\ -This feature is only provided for compatibility with @sc{matlab} and should\n\ -not be used unless you are porting old code that relies on this feature.\n\ -\n\ -To obtain short-circuit behavior for logical expressions in new programs,\n\ -you should always use the @samp{&&} and @samp{||} operators.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} do_braindead_shortcircuit_evaluation () +@deftypefnx {} {@var{old_val} =} do_braindead_shortcircuit_evaluation (@var{new_val}) +@deftypefnx {} {} do_braindead_shortcircuit_evaluation (@var{new_val}, "local") +Query or set the internal variable that controls whether Octave will +do short-circuit evaluation of @samp{|} and @samp{&} operators inside the +conditions of if or while statements. + +This feature is only provided for compatibility with @sc{matlab} and should +not be used unless you are porting old code that relies on this feature. + +To obtain short-circuit behavior for logical expressions in new programs, +you should always use the @samp{&&} and @samp{||} operators. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@end deftypefn */) { static bool warned = false; if (! warned)
--- a/libinterp/parse-tree/pt-eval.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/parse-tree/pt-eval.cc Tue Jun 21 16:07:51 2016 -0400 @@ -1194,20 +1194,20 @@ } DEFUN (max_recursion_depth, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} max_recursion_depth ()\n\ -@deftypefnx {} {@var{old_val} =} max_recursion_depth (@var{new_val})\n\ -@deftypefnx {} {} max_recursion_depth (@var{new_val}, \"local\")\n\ -Query or set the internal limit on the number of times a function may\n\ -be called recursively.\n\ -\n\ -If the limit is exceeded, an error message is printed and control returns to\n\ -the top level.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} max_recursion_depth () +@deftypefnx {} {@var{old_val} =} max_recursion_depth (@var{new_val}) +@deftypefnx {} {} max_recursion_depth (@var{new_val}, "local") +Query or set the internal limit on the number of times a function may +be called recursively. + +If the limit is exceeded, an error message is printed and control returns to +the top level. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@end deftypefn */) { return SET_INTERNAL_VARIABLE (max_recursion_depth); } @@ -1225,21 +1225,21 @@ */ DEFUN (silent_functions, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} silent_functions ()\n\ -@deftypefnx {} {@var{old_val} =} silent_functions (@var{new_val})\n\ -@deftypefnx {} {} silent_functions (@var{new_val}, \"local\")\n\ -Query or set the internal variable that controls whether internal\n\ -output from a function is suppressed.\n\ -\n\ -If this option is disabled, Octave will display the results produced by\n\ -evaluating expressions within a function body that are not terminated with\n\ -a semicolon.\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} silent_functions () +@deftypefnx {} {@var{old_val} =} silent_functions (@var{new_val}) +@deftypefnx {} {} silent_functions (@var{new_val}, "local") +Query or set the internal variable that controls whether internal +output from a function is suppressed. + +If this option is disabled, Octave will display the results produced by +evaluating expressions within a function body that are not terminated with +a semicolon. + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@end deftypefn */) { return SET_INTERNAL_VARIABLE (silent_functions); }
--- a/libinterp/parse-tree/pt-mat.cc Tue Jun 21 13:08:25 2016 -0700 +++ b/libinterp/parse-tree/pt-mat.cc Tue Jun 21 16:07:51 2016 -0400 @@ -1345,30 +1345,30 @@ */ DEFUN (string_fill_char, args, nargout, - "-*- texinfo -*-\n\ -@deftypefn {} {@var{val} =} string_fill_char ()\n\ -@deftypefnx {} {@var{old_val} =} string_fill_char (@var{new_val})\n\ -@deftypefnx {} {} string_fill_char (@var{new_val}, \"local\")\n\ -Query or set the internal variable used to pad all rows of a character\n\ -matrix to the same length.\n\ -\n\ -The value must be a single character and the default is @qcode{\" \"} (a\n\ -single space). For example:\n\ -\n\ -@example\n\ -@group\n\ -string_fill_char (\"X\");\n\ -[ \"these\"; \"are\"; \"strings\" ]\n\ - @result{} \"theseXX\"\n\ - \"areXXXX\"\n\ - \"strings\"\n\ -@end group\n\ -@end example\n\ -\n\ -When called from inside a function with the @qcode{\"local\"} option, the\n\ -variable is changed locally for the function and any subroutines it calls.\n\ -The original variable value is restored when exiting the function.\n\ -@end deftypefn") + doc: /* -*- texinfo -*- +@deftypefn {} {@var{val} =} string_fill_char () +@deftypefnx {} {@var{old_val} =} string_fill_char (@var{new_val}) +@deftypefnx {} {} string_fill_char (@var{new_val}, "local") +Query or set the internal variable used to pad all rows of a character +matrix to the same length. + +The value must be a single character and the default is @qcode{" "} (a +single space). For example: + +@example +@group +string_fill_char ("X"); +[ "these"; "are"; "strings" ] + @result{} "theseXX" + "areXXXX" + "strings" +@end group +@end example + +When called from inside a function with the @qcode{"local"} option, the +variable is changed locally for the function and any subroutines it calls. +The original variable value is restored when exiting the function. +@end deftypefn */) { return SET_INTERNAL_VARIABLE (string_fill_char); }
--- a/liboctave/module.mk Tue Jun 21 13:08:25 2016 -0700 +++ b/liboctave/module.mk Tue Jun 21 16:07:51 2016 -0400 @@ -30,8 +30,7 @@ BUILT_SOURCES += \ $(BUILT_INCS) \ - $(BUILT_LIBOCTAVE_OPERATORS_SOURCES) \ - liboctave/liboctave-build-info.cc + $(BUILT_LIBOCTAVE_OPERATORS_SOURCES) LIBOCTAVE_BUILT_NODISTFILES = \ liboctave/liboctave-build-info.cc @@ -118,6 +117,7 @@ -e "s|%OCTAVE_HG_ID%|`cat $(builddir)/HG-ID`|" $< > $@-t && \ $(simple_move_if_change_rule) + EXTRA_DIST += $(liboctave_EXTRA_DIST) liboctave_DISTCLEANFILES += \
--- a/liboctave/numeric/DASPK-opts.in Tue Jun 21 13:08:25 2016 -0700 +++ b/liboctave/numeric/DASPK-opts.in Tue Jun 21 16:07:51 2016 -0400 @@ -103,7 +103,7 @@ initial conditions that are consistent). If this option is set to a nonzero value, you must also set the -@qcode{\"algebraic variables\"} option to declare which variables in the +@qcode{"algebraic variables"} option to declare which variables in the problem are algebraic. END_DOC_ITEM @@ -139,12 +139,12 @@ @item MXNH Maximum number of values of the artificial stepsize parameter to be -tried if the @qcode{\"compute consistent initial condition\"} option has +tried if the @qcode{"compute consistent initial condition"} option has been set to 1 (default is 5). Note that the maximum total number of Newton iterations allowed is -@code{MXNIT*MXNJ*MXNH} if the @qcode{\"compute consistent initial -condition\"} option has been set to 1 and @code{MXNIT*MXNJ} if it is +@code{MXNIT*MXNJ*MXNH} if the @qcode{"compute consistent initial +condition"} option has been set to 1 and @code{MXNIT*MXNJ} if it is set to 2. @item LSOFF @@ -194,7 +194,7 @@ NAME = "exclude algebraic variables from error test" DOC_ITEM Set to a nonzero value to exclude algebraic variables from the error -test. You must also set the @qcode{\"algebraic variables\"} option to +test. You must also set the @qcode{"algebraic variables"} option to declare which variables in the problem are algebraic (default is 0). END_DOC_ITEM @@ -212,8 +212,8 @@ in the equation set). This option is required by the -@qcode{\"compute consistent initial condition\"} and -@qcode{\"exclude algebraic variables from error test\"} options. +@qcode{"compute consistent initial condition"} and +@qcode{"exclude algebraic variables from error test"} options. END_DOC_ITEM TYPE = "Array<octave_idx_type>" @@ -239,7 +239,7 @@ NAME = "enforce inequality constraints" DOC_ITEM Set to one of the following values to enforce the inequality -constraints specified by the @qcode{\"inequality constraint types\"} +constraints specified by the @qcode{"inequality constraint types"} option (default is 0). @enumerate @@ -282,7 +282,7 @@ @end table This option only has an effect if the -@qcode{\"enforce inequality constraints\"} option is nonzero. +@qcode{"enforce inequality constraints"} option is nonzero. END_DOC_ITEM TYPE = "Array<octave_idx_type>"
--- a/liboctave/numeric/LSODE-opts.in Tue Jun 21 13:08:25 2016 -0700 +++ b/liboctave/numeric/LSODE-opts.in Tue Jun 21 16:07:51 2016 -0400 @@ -74,12 +74,12 @@ system. Valid values are @table @asis -@item @qcode{\"adams\"} -@itemx @qcode{\"non-stiff\"} +@item @qcode{"adams"} +@itemx @qcode{"non-stiff"} No Jacobian used (even if it is available). -@item @qcode{\"bdf\"} -@itemx @qcode{\"stiff\"} +@item @qcode{"bdf"} +@itemx @qcode{"stiff"} Use stiff backward differentiation formula (BDF) method. If a function to compute the Jacobian is not supplied, @code{lsode} will compute a finite difference approximation of the Jacobian matrix.