Mercurial > hg > octave-shane
changeset 11431:0d9640d755b1
Improve docstrings for all isXXX functions.
Use 'return true' rather than 'return 1'.
Improve the cross-referencing through seealso links.
line wrap: on
line diff
--- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,10 @@ +2010-12-31 Rik <octave@nomad.inbox5.com> + + * interpreter/expr.txi: Add isindex function to documentation + * interpreter/func.txi: Add isargout function to documentation + * interpreter/matrix.txi: Add isfinite function to documentation + * interpreter/numbers.txi: Add ishermitian function to documentation + 2010-12-31 Kai Habel <kai.habel@gmx.de> * interpreter/arith.txi: Add curl and divergence function.
--- a/doc/interpreter/doccheck/mk_undocumented_list +++ b/doc/interpreter/doccheck/mk_undocumented_list @@ -84,6 +84,7 @@ F_DUPFD F_GETFD F_GETFL +finite fntests F_SETFD F_SETFL @@ -91,6 +92,8 @@ i inf inverse +isbool +isfinite j J lower
--- a/doc/interpreter/expr.txi +++ b/doc/interpreter/expr.txi @@ -229,6 +229,8 @@ @DOCSTRING(ind2sub) +@DOCSTRING(isindex) + @node Calling Functions @section Calling Functions
--- a/doc/interpreter/func.txi +++ b/doc/interpreter/func.txi @@ -342,6 +342,8 @@ @DOCSTRING(nargoutchk) +@DOCSTRING(isargout) + @anchor{doc-varargin} @anchor{doc-varargout} @node Variable-length Argument Lists @section Variable-length Argument Lists
--- a/doc/interpreter/matrix.txi +++ b/doc/interpreter/matrix.txi @@ -75,7 +75,7 @@ @DOCSTRING(isnan) -@DOCSTRING(finite) +@DOCSTRING(isfinite) @DOCSTRING(find)
--- a/doc/interpreter/numbers.txi +++ b/doc/interpreter/numbers.txi @@ -816,6 +816,8 @@ @DOCSTRING(issymmetric) +@DOCSTRING(ishermitian) + @DOCSTRING(isdefinite) @DOCSTRING(islogical)
--- a/scripts/ChangeLog +++ b/scripts/ChangeLog @@ -1,3 +1,17 @@ +2010-12-31 Rik <octave@nomad.inbox5.com> + + * general/is_duplicate_entry.m , general/isdir.m, general/isscalar.m, + general/issquare.m, general/isvector.m, linear-algebra/isdefinite.m, + linear-algebra/ishermitian.m, linear-algebra/issymmetric.m, + miscellaneous/isappdata.m, miscellaneous/ismac.m, miscellaneous/ispc.m, + miscellaneous/isunix.m, plot/isfigure.m, plot/ishold.m, plot/isprop.m, + set/ismember.m, specfun/isprime.m, strings/isletter.m, + time/is_leap_year.m : Improve docstring + * general/isa.m: Improve docstring. Change function variable name to + match documentation variable name. + * strings/isstrprop.m: Improve docstring. Change function variable + name to match documentation variable name. Add new test cases. + 2010-12-31 Rik <octave@nomad.inbox5.com> * plot/module.mk: Add isprop.m to list of function files for Automake.
--- a/scripts/general/is_duplicate_entry.m +++ b/scripts/general/is_duplicate_entry.m @@ -21,6 +21,7 @@ ## @deftypefn {Function File} {} is_duplicate_entry (@var{x}) ## Return non-zero if any entries in @var{x} are duplicates of one ## another. +## @seealso{unique} ## @end deftypefn ## Author: A. S. Hodel <scotte@eng.auburn.edu>
--- a/scripts/general/isa.m +++ b/scripts/general/isa.m @@ -17,14 +17,15 @@ ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- -## @deftypefn {Function File} {} isa (@var{x}, @var{class}) -## Return true if @var{x} is a value from the class @var{class}. +## @deftypefn {Function File} {} isa (@var{obj}, @var{class}) +## Return true if @var{obj} is an object from the class @var{class}. +## @seealso{class, typeinfo} ## @end deftypefn ## Author: Paul Kienzle <pkienzle@users.sf.net> ## Adapted-by: jwe -function retval = isa (x, cname) +function retval = isa (obj, cname) if (nargin != 2) print_usage (); @@ -37,14 +38,14 @@ "int8", "int16", "int32", "int64"}; if (strcmp (cname, "float")) - retval = any (strcmp (class (x), float_classes)); + retval = any (strcmp (class (obj), float_classes)); elseif (strcmp (cname, "numeric")) - retval = any (strcmp (class (x), fnum_classes)); + retval = any (strcmp (class (obj), fnum_classes)); else - class_of_x = class (x); + class_of_x = class (obj); retval = strcmp (class_of_x, cname); - if (! retval && isobject (x)) - retval = __isa_parent__ (x, cname); + if (! retval && isobject (obj)) + retval = __isa_parent__ (obj, cname); endif endif
--- a/scripts/general/isdir.m +++ b/scripts/general/isdir.m @@ -19,6 +19,7 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} isdir (@var{f}) ## Return true if @var{f} is a directory. +## @seealso{is_absolute_filename, is_rooted_relative_filename} ## @end deftypefn function t = isdir (x)
--- a/scripts/general/isscalar.m +++ b/scripts/general/isscalar.m @@ -17,9 +17,9 @@ ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- -## @deftypefn {Function File} {} isscalar (@var{a}) -## Return 1 if @var{a} is a scalar. Otherwise, return 0. -## @seealso{size, rows, columns, length, isscalar, ismatrix} +## @deftypefn {Function File} {} isscalar (@var{x}) +## Return true if @var{x} is a scalar. +## @seealso{isvector, ismatrix} ## @end deftypefn ## Author: jwe
--- a/scripts/general/issquare.m +++ b/scripts/general/issquare.m @@ -18,9 +18,8 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} issquare (@var{x}) -## If @var{x} is a square matrix, return true. -## Otherwise, return false. -## @seealso{size, rows, columns, length, ismatrix, isscalar, isvector} +## Return true if @var{x} is a square matrix. +## @seealso{isscalar, isvector, ismatrix, size} ## @end deftypefn ## Author: A. S. Hodel <scotte@eng.auburn.edu>
--- a/scripts/general/isvector.m +++ b/scripts/general/isvector.m @@ -17,9 +17,11 @@ ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- -## @deftypefn {Function File} {} isvector (@var{a}) -## Return 1 if @var{a} is a vector. Otherwise, return 0. -## @seealso{size, rows, columns, length, isscalar, ismatrix} +## @deftypefn {Function File} {} 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 ## Author: jwe
--- a/scripts/linear-algebra/isdefinite.m +++ b/scripts/linear-algebra/isdefinite.m @@ -24,7 +24,7 @@ ## positive semidefinite. Otherwise, return -1. If @var{tol} ## is omitted, use a tolerance of ## @code{100 * eps * norm (@var{x}, "fro")} -## @seealso{issymmetric} +## @seealso{issymmetric, ishermitian} ## @end deftypefn ## Author: Gabriele Pannocchia <g.pannocchia@ing.unipi.it>
--- a/scripts/linear-algebra/ishermitian.m +++ b/scripts/linear-algebra/ishermitian.m @@ -19,14 +19,14 @@ ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- -## @deftypefn {Function File} {} ishermitian (@var{x}, @var{tol}) -## Return true if @var{x} is symmetric within the tolerance specified by -## @var{tol}, -## otherwise return false. The default tolerance is zero (uses faster code). +## @deftypefn {Function File} {} ishermitian (@var{x}) +## @deftypefnx {Function File} {} ishermitian (@var{x}, @var{tol}) +## Return true if @var{x} is Hermitian within the tolerance specified by +## @var{tol}. +## The default tolerance is zero (uses faster code). ## Matrix @var{x} is considered symmetric if -## @code{norm (@var{x} - @var{x}.', inf) / norm (@var{x}, inf) < @var{tol}}. -## @seealso{size, rows, columns, length, ismatrix, isscalar, -## issquare, isvector} +## @code{norm (@var{x} - @var{x}', Inf) / norm (@var{x}, Inf) < @var{tol}}. +## @seealso{issymmetric, isdefinite} ## @end deftypefn ## Author: A. S. Hodel <scotte@eng.auburn.edu>
--- a/scripts/linear-algebra/issymmetric.m +++ b/scripts/linear-algebra/issymmetric.m @@ -19,14 +19,13 @@ ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- -## @deftypefn {Function File} {} issymmetric (@var{x}, @var{tol}) +## @deftypefn {Function File} {} issymmetric (@var{x}) +## @deftypefnx {Function File} {} issymmetric (@var{x}, @var{tol}) ## Return true if @var{x} is a symmetric matrix within the tolerance specified -## by @var{tol}, otherwise return false. The default tolerance is zero (uses -## faster code). +## by @var{tol}. The default tolerance is zero (uses faster code). ## Matrix @var{x} is considered symmetric if -## @code{norm (@var{x} - @var{x}.', inf) / norm (@var{x}, inf) < @var{tol}}. -## @seealso{size, rows, columns, length, ismatrix, isscalar, -## issquare, isvector} +## @code{norm (@var{x} - @var{x}.', Inf) / norm (@var{x}, Inf) < @var{tol}}. +## @seealso{ishermitian, isdefinite} ## @end deftypefn ## Author: A. S. Hodel <scotte@eng.auburn.edu>
--- a/scripts/miscellaneous/isappdata.m +++ b/scripts/miscellaneous/isappdata.m @@ -16,8 +16,9 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {@var{V} =} isappdata (@var{h}, @var{name}) -## Returns a logical vector indicating whether the named application data -## for the object(s) with handle(s) @var{H} exists. +## Return true if the named application data, @var{name}, exists for the +## object with handle @var{h}. +## @seealso{getappdata, setappdata, rmappdata} ## @end deftypefn ## Author: Ben Abbott <bpabbott@mac.com>
--- a/scripts/miscellaneous/ismac.m +++ b/scripts/miscellaneous/ismac.m @@ -18,8 +18,8 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} ismac () -## Return 1 if Octave is running on a Mac OS X system and 0 otherwise. -## @seealso{ispc, isunix} +## Return true if Octave is running on a Mac OS X system and false otherwise. +## @seealso{isunix, ispc} ## @end deftypefn function retval = ismac ()
--- a/scripts/miscellaneous/ispc.m +++ b/scripts/miscellaneous/ispc.m @@ -18,8 +18,8 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} ispc () -## Return 1 if Octave is running on a Windows system and 0 otherwise. -## @seealso{ismac, isunix} +## Return true if Octave is running on a Windows system and false otherwise. +## @seealso{isunix, ismac} ## @end deftypefn function retval = ispc ()
--- a/scripts/miscellaneous/isunix.m +++ b/scripts/miscellaneous/isunix.m @@ -18,7 +18,7 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} isunix () -## Return 1 if Octave is running on a Unix-like system and 0 otherwise. +## Return true if Octave is running on a Unix-like system and false otherwise. ## @seealso{ismac, ispc} ## @end deftypefn
--- a/scripts/plot/isfigure.m +++ b/scripts/plot/isfigure.m @@ -19,7 +19,8 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} isfigure (@var{h}) ## Return true if @var{h} is a graphics handle that contains a figure -## object and false otherwise. +## object. +## @seealso{ishandle} ## @end deftypefn ## Author: jwe
--- a/scripts/plot/ishold.m +++ b/scripts/plot/ishold.m @@ -18,8 +18,9 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} ishold -## Return true if the next line will be added to the current plot, or -## false if the plot device will be cleared before drawing the next line. +## Return true if the next plot will be added to the current plot, or +## false if the plot device will be cleared before drawing the next plot. +## @seealso{hold} ## @end deftypefn function retval = ishold (h)
--- a/scripts/plot/isprop.m +++ b/scripts/plot/isprop.m @@ -17,8 +17,8 @@ ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- -## @deftypefn {Function File} {@var{res} =} isprop (@var{h}, @var{prop}) -## Determines if @var{prop} is a property of the object with handle, @var{h}. +## @deftypefn {Function File} {@var{res} =} isprop (@var{h}, @var{prop}) +## Return true if @var{prop} is a property of the object with handle @var{h}. ## @seealso{get, set} ## @end deftypefn
--- a/scripts/set/ismember.m +++ b/scripts/set/ismember.m @@ -21,10 +21,10 @@ ## @deftypefn {Function File} {@var{tf} =} ismember (@var{A}, @var{S}) ## @deftypefnx {Function File} {[@var{tf}, @var{S_idx}] =} ismember (@var{A}, @var{S}) ## @deftypefnx {Function File} {[@var{tf}, @var{S_idx}] =} ismember (@var{A}, @var{S}, "rows") -## Return a matrix @var{tf} with the same shape as @var{A} which has a 1 if -## @code{A(i,j)} is in @var{S} and 0 if it is not. If a second output argument -## is requested, the index into @var{S} of each of the matching elements is -## also returned. +## Return a logical matrix @var{tf} with the same shape as @var{A} which is +## true (1) if @code{A(i,j)} is in @var{S} and false (0) if it is not. If a +## second output argument is requested, the index into @var{S} of each of the +## matching elements is also returned. ## ## @example ## @group
--- a/scripts/specfun/isprime.m +++ b/scripts/specfun/isprime.m @@ -18,12 +18,19 @@ ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- -## @deftypefn {Function File} {} isprime (@var{n}) -## Return true if @var{n} is a prime number, false otherwise. +## @deftypefn {Function File} {} isprime (@var{x}) +## Return a logical array which is true where the elements of @var{x} are +## prime numbers and false where they are not. +## +## If the maximum value in @var{x} is very large, then you should be using +## special purpose factorization code. ## -## If max(n) is very large, then you should be using special purpose -## factorization code. -## +## @example +## @group +## isprime (1:6) +## @result{} [0, 1, 1, 0, 1, 0] +## @end group +## @end example ## @seealso{primes, factor, gcd, lcm} ## @end deftypefn
--- a/scripts/strings/isletter.m +++ b/scripts/strings/isletter.m @@ -18,8 +18,10 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} isletter (@var{s}) -## Returns true if @var{s} is a letter, false otherwise. -## @seealso{isalpha} +## Return a logical array which is true where the elements of @var{s} +## are letters and false where they are not. This is an alias for +## the @code{isalpha} function. +## @seealso{isalpha, isdigit, ispunct, isspace, iscntrl, isalnum} ## @end deftypefn ## Author: jwe
--- a/scripts/strings/isstrprop.m +++ b/scripts/strings/isstrprop.m @@ -17,7 +17,7 @@ ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- -## @deftypefn {Function File} {} isstrprop (@var{str}, @var{pred}) +## @deftypefn {Function File} {} isstrprop (@var{str}, @var{prop}) ## Test character string properties. For example: ## ## @example @@ -32,58 +32,60 @@ ## ## Numeric arrays are converted to character strings. ## -## The second argument @var{pred} may be one of +## The second argument @var{prop} must be one of ## ## @table @code ## @item "alpha" -## True for characters that are alphabetic +## True for characters that are alphabetic (letters). ## ## @item "alnum" ## @itemx "alphanum" ## True for characters that are alphabetic or digits. -## -## @item "ascii" -## True for characters that are in the range of ASCII encoding. -## -## @item "cntrl" -## True for control characters. +## +## @item "lower" +## True for lower-case letters. +## +## @item "upper" +## True for upper-case letters. ## ## @item "digit" -## True for decimal digits. -## -## @item "graph" -## @itemx "graphic" -## True for printing characters except space. -## -## @item "lower" -## True for lower-case letters. -## -## @item "print" -## True for printing characters including space. -## -## @item "punct" -## True for printing characters except space or letter or digit. -## +## True for decimal digits (0-9). +## +## @item "xdigit" +## True for hexadecimal digits (a-fA-F0-9). +## ## @item "space" ## @itemx "wspace" ## True for whitespace characters (space, formfeed, newline, carriage ## return, tab, vertical tab). ## -## @item "upper" -## True for upper-case letters. +## @item "punct" +## True for punctuation characters (printing characters except space +## or letter or digit). +## +## @item "cntrl" +## True for control characters. +## +## @item "graph" +## @itemx "graphic" +## True for printing characters except space. +## +## @item "print" +## True for printing characters including space. +## +## @item "ascii" +## True for characters that are in the range of ASCII encoding. ## -## @item "xdigit" -## True for hexadecimal digits. ## @end table ## -## @seealso{isalnum, isalpha, isascii, iscntrl, isdigit, isgraph, -## islower, isprint, ispunct, isspace, isupper, isxdigit} +## @seealso{isalpha, isalnum, islower, isupper, isdigit, isxdigit, +## isspace, ispunct, iscntrl, isgraph, isprint, isascii} ## @end deftypefn -function retval = isstrprop (str, pred) +function retval = isstrprop (str, prop) if (nargin == 2) - switch (pred) + switch (prop) case "alpha" retval = isalpha (str); case {"alnum", "alphanum"} @@ -109,7 +111,7 @@ case "xdigit" retval = isxdigit (str); otherwise - error ("isstrprop: invalid predicate"); + error ("isstrprop: invalid string property"); endswitch else print_usage (); @@ -117,5 +119,12 @@ endfunction -%!error <invalid predicate> isstrprop ("abc123", "foo"); -%!assert (isstrprop ("abc123", "alpha"), logical ([1, 1, 1, 0, 0, 0])); \ No newline at end of file +%!error <invalid string property> isstrprop ("abc123", "foo") +%!assert (isstrprop ("abc123", "alpha"), logical ([1, 1, 1, 0, 0, 0])) +%!assert (isstrprop ("Hello World", "wspace"), isspace ("Hello World")) +%!assert (isstrprop ("Hello World", "graphic"), isgraph ("Hello World")) + +%%Input Validation +%!error isstrprop () +%!error isstrprop ("abc123") +%!error isstrprop ("abc123", "alpha", "alpha")
--- a/scripts/time/is_leap_year.m +++ b/scripts/time/is_leap_year.m @@ -17,9 +17,10 @@ ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- -## @deftypefn {Function File} {} is_leap_year (@var{year}) -## Return 1 if the given year is a leap year and 0 otherwise. If no -## arguments are provided, @code{is_leap_year} will use the current year. +## @deftypefn {Function File} {} is_leap_year () +## @deftypefnx {Function File} {} is_leap_year (@var{year}) +## Return true if the given year is a leap year and false otherwise. If no +## year is provided, @code{is_leap_year} will use the current year. ## For example: ## ## @example
--- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,3 +1,26 @@ +2010-12-31 Rik <octave@nomad.inbox5.com> + + * data.cc (islogical, isinteger, iscomplex, isfloat, isempty, + isnumeric, ismatrix, issorted): Improve docstring + * graphics.cc (ishandle): Improve docstring + * lex.ll (iskeyword): Improve docstring + * mappers.cc (isalnum, isalpha, isascii, iscntrl, isdigit, isinf, + isgraph, islower, isna, isnan, isprint, ispunct, isspace, isupper, + isxdigit): Improve docstring + (finite/isfinite): Make finite an alias for isfinite rather than the + reverse. Improve docstring. + * ov-cell.cc (iscell, iscellstr): Improve docstring + * ov-class.cc (isobject, ismethod): Improve docstring + * ov-null-mat.cc (isnull): Improve docstring + * ov-struct.cc (isstruct, isfield): Improve docstring + * ov-usr-fcn.cc (isargout): Improve docstring + * sparse.cc (issparse): Improve docstring + * strfns.cc (ischar): Improve docstring + * sysdep.cc (isieee): Improve docstring + * utils.cc (isvarname, is_absolute_filename, + is_rooted_relative_filename, isindex): Improve docstring + * variables.cc (isglobal): Improve docstring + 2010-12-28 Rik <octave@nomad.inbox5.com> * data.cc (and, ctranspose, eq, ge, gt, ldivide, le, lt, minus,
--- a/src/data.cc +++ b/src/data.cc @@ -2494,8 +2494,10 @@ DEFUN (islogical, args, , "-*- texinfo -*-\n\ -@deftypefn {Built-in Function} {} islogical (@var{x})\n\ +@deftypefn {Built-in Function} {} islogical (@var{x})\n\ +@deftypefnx {Built-in Function} {} isbool (@var{x})\n\ Return true if @var{x} is a logical object.\n\ +@seealso{isfloat, isinteger, ischar, isnumeric, isa}\n\ @end deftypefn") { octave_value retval; @@ -2528,9 +2530,9 @@ "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} isinteger (@var{x})\n\ Return true if @var{x} is an integer object (int8, uint8, int16, etc.).\n\ -Note that @code{isinteger (14)} is false because numeric constants in\n\ +Note that @w{@code{isinteger (14)}} is false because numeric constants in\n\ Octave are double precision floating point values.\n\ -@seealso{isreal, isnumeric, class, isa}\n\ +@seealso{isfloat, ischar, islogical, isnumeric, isa}\n\ @end deftypefn") { octave_value retval; @@ -2547,6 +2549,7 @@ "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} iscomplex (@var{x})\n\ Return true if @var{x} is a complex-valued numeric object.\n\ +@seealso{isreal, isnumeric}\n\ @end deftypefn") { octave_value retval; @@ -2563,6 +2566,8 @@ "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} isfloat (@var{x})\n\ Return true if @var{x} is a floating-point numeric object.\n\ +Objects of class double or single are floating-point objects.\n\ +@seealso{isinteger, ischar, islogical, isnumeric, isa}\n\ @end deftypefn") { octave_value retval; @@ -2874,6 +2879,7 @@ Return true if @var{x} is a non-complex matrix or scalar.\n\ For compatibility with @sc{matlab}, this includes logical and character\n\ matrices.\n\ +@seealso{iscomplex, isnumeric}\n\ @end deftypefn") { octave_value retval; @@ -2889,8 +2895,9 @@ DEFUN (isempty, args, , "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} isempty (@var{a})\n\ -Return 1 if @var{a} is an empty matrix (either the number of rows, or\n\ -the number of columns, or both are zero). Otherwise, return 0.\n\ +Return true if @var{a} is an empty matrix (any one of its dimensions is\n\ +zero). Otherwise, return false.\n\ +@seealso{isnull}\n\ @end deftypefn") { octave_value retval = false; @@ -2906,10 +2913,10 @@ DEFUN (isnumeric, args, , "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} isnumeric (@var{x})\n\ -Return nonzero if @var{x} is a numeric object, i.e., an integer, real or\n\ +Return true if @var{x} is a numeric object, i.e., an integer, real, or\n\ complex array. Logical and character arrays are not considered to be\n\ numeric.\n\ -@seealso{ischar, islogical, isinteger}\n\ +@seealso{isinteger, isfloat, isreal, iscomplex, islogical, ischar, iscell, isstruct}\n\ @end deftypefn") { octave_value retval; @@ -2925,8 +2932,11 @@ DEFUN (ismatrix, args, , "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} ismatrix (@var{a})\n\ -Return 1 if @var{a} is a numeric, logical or character matrix or scalar.\n\ -Otherwise, return 0.\n\ +Return true if @var{a} is a numeric, logical, or character matrix.\n\ +Scalars (1x1 matrices) and vectors (1xN or Nx1 matrices) are subsets\n\ +of the more general N-dimensional matrix and @code{ismatrix} will return\n\ +true for these objects as well.\n\ +@seealso{isscalar, isvector, iscell, isstruct, issparse}\n\ @end deftypefn") { octave_value retval = false; @@ -5772,15 +5782,17 @@ "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} issorted (@var{a}, @var{mode})\n\ @deftypefnx {Built-in Function} {} issorted (@var{a}, @code{\"rows\"}, @var{mode})\n\ -Returns true if the array is sorted according to @var{mode}, which\n\ +Return true if the array is sorted according to @var{mode}, which\n\ may be either \"ascending\", \"descending\", or \"either\". By default,\n\ - @var{mode} is \"ascending\". NaNs are treated as by @code{sort}.\n\ -If @var{rows} is supplied and has the value \"rows\", checks whether\n\ -the array is sorted by rows as if output by @code{sortrows} (with no\n\ -options).\n\ + @var{mode} is \"ascending\". NaNs are treated in the same manner as\n\ +@code{sort}.\n\ \n\ -This function does not yet support sparse matrices.\n\ -@seealso{sortrows, sort}\n\ +If the optional argument \"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") { octave_value retval;
--- a/src/graphics.cc +++ b/src/graphics.cc @@ -5902,6 +5902,10 @@ "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} ishandle (@var{h})\n\ Return true if @var{h} is a graphics handle and false otherwise.\n\ +@var{h} may also be a matrix of handles in which case a logical\n\ +array is returned that is true where the elements of @var{h} are\n\ +graphics handles and false where they are not.\n\ +@seealso{isfigure}\n\ @end deftypefn") { gh_manager::autolock guard;
--- a/src/lex.ll +++ b/src/lex.ll @@ -3390,9 +3390,11 @@ DEFUN (iskeyword, args, , "-*- texinfo -*-\n\ -@deftypefn {Built-in Function} {} iskeyword (@var{name})\n\ +@deftypefn {Built-in Function} {} iskeyword ()\n\ +@deftypefnx {Built-in Function} {} iskeyword (@var{name})\n\ Return true if @var{name} is an Octave keyword. If @var{name}\n\ is omitted, return a list of keywords.\n\ +@seealso{isvarname, exist}\n\ @end deftypefn") { octave_value retval;
--- a/src/mappers.cc +++ b/src/mappers.cc @@ -753,11 +753,13 @@ return retval; } -DEFUN (finite, args, , +DEFUN (isfinite, args, , "-*- texinfo -*-\n\ -@deftypefn {Mapping Function} {} finite (@var{x})\n\ -Return 1 for elements of @var{x} that are finite values and zero\n\ -otherwise. For example:\n\ +@deftypefn {Mapping Function} {} isfinite (@var{x})\n\ +@deftypefnx {Mapping Function} {} finite (@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\ +For example:\n\ \n\ @example\n\ @group\n\ @@ -765,6 +767,7 @@ @result{} [ 1, 0, 0, 0 ]\n\ @end group\n\ @end example\n\ +@seealso{isinf, isnan, isna}\n\ @end deftypefn") { octave_value retval; @@ -963,8 +966,10 @@ DEFUNX ("isalnum", Fisalnum, args, , "-*- texinfo -*-\n\ @deftypefn {Mapping Function} {} isalnum (@var{s})\n\ -Return 1 for characters that are letters or digits (@code{isalpha\n\ -(@var{s})} or @code{isdigit (@var{s})} is true).\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. This is equivalent to\n\ +(@code{isalpha (@var{s}) | isdigit (@var{s})}).\n\ +@seealso{isalpha, isdigit, ispunct, isspace, iscntrl}\n\ @end deftypefn") { octave_value retval; @@ -978,10 +983,11 @@ DEFUNX ("isalpha", Fisalpha, args, , "-*- texinfo -*-\n\ -@deftypefn {Mapping Function} {} isalpha (@var{s})\n\ -@deftypefnx {Mapping Function} {} isletter (@var{s})\n\ -Return true for characters that are letters (@code{isupper (@var{s})}\n\ -or @code{islower (@var{s})} is true).\n\ +@deftypefn {Mapping Function} {} 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. This is equivalent to\n\ +(@code{islower (@var{s}) | isupper (@var{s})}).\n\ +@seealso{isdigit, ispunct, isspace, iscntrl, isalnum, islower, isupper}\n\ @end deftypefn") { octave_value retval; @@ -996,7 +1002,9 @@ DEFUNX ("isascii", Fisascii, args, , "-*- texinfo -*-\n\ @deftypefn {Mapping Function} {} isascii (@var{s})\n\ -Return 1 for characters that are ASCII (in the range 0 to 127 decimal).\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") { octave_value retval; @@ -1011,7 +1019,9 @@ DEFUNX ("iscntrl", Fiscntrl, args, , "-*- texinfo -*-\n\ @deftypefn {Mapping Function} {} iscntrl (@var{s})\n\ -Return 1 for control characters.\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") { octave_value retval; @@ -1026,7 +1036,9 @@ DEFUNX ("isdigit", Fisdigit, args, , "-*- texinfo -*-\n\ @deftypefn {Mapping Function} {} isdigit (@var{s})\n\ -Return 1 for characters that are decimal digits.\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") { octave_value retval; @@ -1041,8 +1053,9 @@ DEFUN (isinf, args, , "-*- texinfo -*-\n\ @deftypefn {Mapping Function} {} isinf (@var{x})\n\ -Return 1 for elements of @var{x} that are infinite and zero\n\ -otherwise. For example:\n\ +Return a logical array which is true where the elements of @var{x} are\n\ +are infinite and false where they are not.\n\ +For example:\n\ \n\ @example\n\ @group\n\ @@ -1050,6 +1063,7 @@ @result{} [ 0, 1, 0, 0 ]\n\ @end group\n\ @end example\n\ +@seealso{isfinite, isnan, isna}\n\ @end deftypefn") { octave_value retval; @@ -1080,7 +1094,10 @@ DEFUNX ("isgraph", Fisgraph, args, , "-*- texinfo -*-\n\ @deftypefn {Mapping Function} {} isgraph (@var{s})\n\ -Return 1 for printable characters (but not the space character).\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") { octave_value retval; @@ -1095,7 +1112,9 @@ DEFUNX ("islower", Fislower, args, , "-*- texinfo -*-\n\ @deftypefn {Mapping Function} {} islower (@var{s})\n\ -Return 1 for characters that are lower case letters.\n\ +Return a logical array which is true where the elements of @var{s} are\n\ +lower case letters and false where they are not.\n\ +@seealso{isupper, isalpha, isletter, isalnum}\n\ @end deftypefn") { octave_value retval; @@ -1110,8 +1129,9 @@ DEFUN (isna, args, , "-*- texinfo -*-\n\ @deftypefn {Mapping Function} {} isna (@var{x})\n\ -Return 1 for elements of @var{x} that are NA (missing) values and zero\n\ -otherwise. For example:\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\ +For example:\n\ \n\ @example\n\ @group\n\ @@ -1119,7 +1139,7 @@ @result{} [ 0, 0, 1, 0 ]\n\ @end group\n\ @end example\n\ -@seealso{isnan}\n\ +@seealso{isnan, isinf, isfinite}\n\ @end deftypefn") { octave_value retval; @@ -1150,8 +1170,9 @@ DEFUN (isnan, args, , "-*- texinfo -*-\n\ @deftypefn {Mapping Function} {} isnan (@var{x})\n\ -Return 1 for elements of @var{x} that are NaN values and zero\n\ -otherwise. NA values are also considered NaN values. For example:\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\ +NA values are also considered NaN values. For example:\n\ \n\ @example\n\ @group\n\ @@ -1159,7 +1180,7 @@ @result{} [ 0, 0, 1, 1 ]\n\ @end group\n\ @end example\n\ -@seealso{isna}\n\ +@seealso{isna, isinf, isfinite}\n\ @end deftypefn") { octave_value retval; @@ -1190,7 +1211,10 @@ DEFUNX ("isprint", Fisprint, args, , "-*- texinfo -*-\n\ @deftypefn {Mapping Function} {} isprint (@var{s})\n\ -Return 1 for printable characters (including the space character).\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") { octave_value retval; @@ -1205,7 +1229,9 @@ DEFUNX ("ispunct", Fispunct, args, , "-*- texinfo -*-\n\ @deftypefn {Mapping Function} {} ispunct (@var{s})\n\ -Return 1 for punctuation characters.\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") { octave_value retval; @@ -1220,8 +1246,10 @@ DEFUNX ("isspace", Fisspace, args, , "-*- texinfo -*-\n\ @deftypefn {Mapping Function} {} isspace (@var{s})\n\ -Return 1 for whitespace characters (space, formfeed, newline,\n\ -carriage return, tab, and vertical tab).\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") { octave_value retval; @@ -1236,7 +1264,9 @@ DEFUNX ("isupper", Fisupper, args, , "-*- texinfo -*-\n\ @deftypefn {Mapping Function} {} isupper (@var{s})\n\ -Return 1 for upper case letters.\n\ +Return a logical array which is true where the elements of @var{s} are\n\ +upper case letters and false where they are not.\n\ +@seealso{islower, isalpha, isletter, isalnum}\n\ @end deftypefn") { octave_value retval; @@ -1251,7 +1281,9 @@ DEFUNX ("isxdigit", Fisxdigit, args, , "-*- texinfo -*-\n\ @deftypefn {Mapping Function} {} isxdigit (@var{s})\n\ -Return 1 for characters that are hexadecimal digits.\n\ +Return a logical array which is true where the elements of @var{s} are\n\ +hexadecimal digits (0-9 and a-fA-F).\n\ +@seealso{isdigit}\n\ @end deftypefn") { octave_value retval; @@ -1837,4 +1869,4 @@ DEFALIAS (gammaln, lgamma); -DEFALIAS (isfinite, finite); +DEFALIAS (finite, isfinite);
--- a/src/ov-cell.cc +++ b/src/ov-cell.cc @@ -1255,8 +1255,8 @@ DEFUN (iscell, args, , "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} iscell (@var{x})\n\ -Return true if @var{x} is a cell array object. Otherwise, return\n\ -false.\n\ +Return true if @var{x} is a cell array object.\n\ +@seealso{ismatrix, isstruct, iscellstr, isa}\n\ @end deftypefn") { octave_value retval; @@ -1332,7 +1332,8 @@ "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} iscellstr (@var{cell})\n\ Return true if every element of the cell array @var{cell} is a\n\ -character string\n\ +character string.\n\ +@seealso{ischar}\n\ @end deftypefn") { octave_value retval;
--- a/src/ov-class.cc +++ b/src/ov-class.cc @@ -1832,6 +1832,7 @@ "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} isobject (@var{x})\n\ Return true if @var{x} is a class object.\n\ +@seealso{class, typeinfo, isa, ismethod}\n\ @end deftypefn") { octave_value retval; @@ -1849,6 +1850,7 @@ @deftypefn {Built-in Function} {} ismethod (@var{x}, @var{method})\n\ Return true if @var{x} is a class object and the string @var{method}\n\ is a method of this class.\n\ +@seealso{isobject}\n\ @end deftypefn") { octave_value retval;
--- a/src/ov-null-mat.cc +++ b/src/ov-null-mat.cc @@ -91,11 +91,11 @@ DEFUN (isnull, args, , "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} isnull (@var{x})\n\ -Return 1 if @var{x} is a special null matrix, string or single quoted string.\n\ -Indexed assignment with such a value as right-hand side should delete array\n\ -elements. This function should be used when overloading indexed assignment\n\ -for user-defined classes instead of @code{isempty}, to distinguish the\n\ -cases:\n\ +Return true if @var{x} is a special null matrix, string, or single quoted\n\ +string. Indexed assignment with such a value on the right-hand side should\n\ +delete array elements. This function should be used when overloading\n\ +indexed assignment for user-defined classes instead of @code{isempty}, to\n\ +distinguish the cases:\n\ @table @asis\n\ @item @code{A(I) = []}\n\ This should delete elements if @code{I} is nonempty.\n\ @@ -103,6 +103,7 @@ @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") { octave_value retval;
--- a/src/ov-struct.cc +++ b/src/ov-struct.cc @@ -1885,9 +1885,9 @@ DEFUN (isstruct, args, , "-*- texinfo -*-\n\ -@deftypefn {Built-in Function} {} isstruct (@var{expr})\n\ -Return 1 if the value of the expression @var{expr} is a structure\n\ -(or a structure array).\n\ +@deftypefn {Built-in Function} {} isstruct (@var{x})\n\ +Return true if @var{x} is a structure or a structure array.\n\ +@seealso{ismatrix, iscell, isa}\n\ @end deftypefn") { octave_value retval; @@ -1945,10 +1945,10 @@ DEFUN (isfield, args, , "-*- texinfo -*-\n\ -@deftypefn {Built-in Function} {} isfield (@var{expr}, @var{name})\n\ -Return true if the expression @var{expr} is a structure and it\n\ +@deftypefn {Built-in Function} {} isfield (@var{x}, @var{name})\n\ +Return true if the @var{x} is a structure and it\n\ includes an element named @var{name}. If @var{name} is a cell\n\ -array, a logical array of equal dimension is returned.\n\ +array of strings then a logical array of equal dimension is returned.\n\ @end deftypefn") { octave_value retval;
--- a/src/ov-usr-fcn.cc +++ b/src/ov-usr-fcn.cc @@ -751,14 +751,16 @@ DEFUN (isargout, args, , "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} isargout (@var{k})\n\ -Within a function, given an index @var{k} within the range @code{1:max(nargout,1)},\n\ -return a logical value indicating whether the argument will be assigned on\n\ -output to a variable or cell or struct element. If the result is false,\n\ -the argument will be ignored using the tilde (~) special output argument.\n\ -If @var{k} is outside the range @code{1:max(nargout,1)}, the function yields false.\n\ -@var{k} can also be an array, in\n\ -which case the function works element-wise and a logical array is returned.\n\ -At the top level, @code{isargout} returns an error.\n\ +Within a function, return a logical value indicating whether the argument\n\ +@var{k} will be assigned on output to a variable. If the result is false,\n\ +the argument has been ignored during the function call through the use of\n\ +the tilde (~) special output argument. Functions can use @code{isargout} to\n\ +avoid performing unnecessary calculations for 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, nargin, varargin, varargout}\n\ @end deftypefn") {
--- a/src/sparse.cc +++ b/src/sparse.cc @@ -43,8 +43,9 @@ DEFUN (issparse, args, , "-*- texinfo -*-\n\ -@deftypefn {Loadable Function} {} issparse (@var{expr})\n\ -Return 1 if the value of the expression @var{expr} is a sparse matrix.\n\ +@deftypefn {Loadable Function} {} issparse (@var{x})\n\ +Return true if @var{x} is a sparse matrix.\n\ +@seealso{ismatrix}\n\ @end deftypefn") { if (args.length() != 1)
--- a/src/strfns.cc +++ b/src/strfns.cc @@ -297,8 +297,9 @@ DEFUN (ischar, args, , "-*- texinfo -*-\n\ -@deftypefn {Built-in Function} {} ischar (@var{a})\n\ -Return 1 if @var{a} is a character array. Otherwise, return 0.\n\ +@deftypefn {Built-in Function} {} ischar (@var{x})\n\ +Return true if @var{x} is a character array.\n\ +@seealso{isfloat, isinteger, islogical, isnumeric, iscellstr, isa}\n\ @end deftypefn") { octave_value retval;
--- a/src/sysdep.cc +++ b/src/sysdep.cc @@ -728,8 +728,8 @@ DEFUN (isieee, , , "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} isieee ()\n\ -Return 1 if your computer claims to conform to the IEEE standard for\n\ -floating point calculations.\n\ +Return true if your computer @emph{claims} to conform to the IEEE standard\n\ +for floating point calculations. No actual tests are performed.\n\ @end deftypefn") { oct_mach_info::float_format flt_fmt = oct_mach_info::native_float_format ();
--- a/src/utils.cc +++ b/src/utils.cc @@ -94,7 +94,8 @@ DEFUN (isvarname, args, , "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} isvarname (@var{name})\n\ -Return true if @var{name} is a valid variable name\n\ +Return true if @var{name} is a valid variable name.\n\ +@seealso{exist, who}\n\ @end deftypefn") { octave_value retval; @@ -733,6 +734,7 @@ "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} 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") { octave_value retval = false; @@ -750,6 +752,7 @@ "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} 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") { octave_value retval = false; @@ -1296,12 +1299,13 @@ DEFUN (isindex, args, , "-*- texinfo -*-\n\ -@deftypefn {Built-in Function} {} isindex (@var{ind}, @var{n})\n\ -Returns true if @var{ind} is a valid index. Valid indices can be\n\ -either positive integers (though possibly real data), or logical arrays.\n\ -If present, @var{n} specifies the extent of the dimension to be indexed.\n\ -Note that, if possible, the internal conversion result is cached so that\n\ -subsequent indexing will not perform the checking again.\n\ +@deftypefn {Built-in Function} {} isindex (@var{ind})\n\ +@deftypefnx {Built-in Function} {} isindex (@var{ind}, @var{n})\n\ +Return true if @var{ind} is a valid index. Valid indices are\n\ +either positive integers (although possibly of real datatype), or logical\n\ +arrays. If present, @var{n} specifies the maximum extent of the dimension\n\ +to be indexed. When possible the internal result is cached so that\n\ +subsequent indexing using @var{ind} will not perform the check again.\n\ @end deftypefn") { octave_value retval;
--- a/src/variables.cc +++ b/src/variables.cc @@ -355,8 +355,8 @@ DEFUN (isglobal, args, , "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} isglobal (@var{name})\n\ -Return 1 if @var{name} is globally visible. Otherwise, return 0. For\n\ -example,\n\ +Return true if @var{name} is a globally visible variable.\n\ +For example:\n\ \n\ @example\n\ @group\n\ @@ -365,6 +365,7 @@ @result{} 1\n\ @end group\n\ @end example\n\ +@seealso{isvarname, exist}\n\ @end deftypefn") { return do_isglobal (args);