changeset 33029:0b8f3470d1fb stable

doc: Clarify object types for isX functions (bug #48088) * libinterp/corefcn/data.cc (isscalar, isvector, isrow, iscolumn, ismatrix, issquare): Change docstring to indicate the functions apply to arrays of any type. * libinterp/octave-value/ov-null-mat.cc (isnull): Replace matrix with array in docstring. * scripts/linear-algebra/isbanded.m, isdefinite.m, ishermitian.m, issymmetric.m, istril, istriu: Note in docstrings that functions return true for numeric matrices. * scripts/linear-algebra/isdiag.m: Note in docstring that function returns true for numeric matrices. Define meaning of diagonal.
author Nicholas R. Jankowski <jankowski.nicholas@gmail.com>
date Thu, 15 Feb 2024 21:42:27 -0500
parents 9cb993582499
children 459ad9067f62 388c87433483
files libinterp/corefcn/data.cc libinterp/octave-value/ov-null-mat.cc scripts/linear-algebra/isbanded.m scripts/linear-algebra/isdefinite.m scripts/linear-algebra/isdiag.m scripts/linear-algebra/ishermitian.m scripts/linear-algebra/issymmetric.m scripts/linear-algebra/istril.m scripts/linear-algebra/istriu.m
diffstat 9 files changed, 22 insertions(+), 21 deletions(-) [+]
line wrap: on
line diff
--- a/libinterp/corefcn/data.cc	Thu Feb 15 10:09:45 2024 -0800
+++ b/libinterp/corefcn/data.cc	Thu Feb 15 21:42:27 2024 -0500
@@ -3858,7 +3858,7 @@
 @deftypefn {} {@var{tf} =} isscalar (@var{x})
 Return true if @var{x} is a scalar.
 
-A scalar is an object with two dimensions for which @code{size (@var{x})}
+A scalar is a single element object of any type for which @code{size (@var{x})}
 returns @w{@code{[1, 1]}}.
 @seealso{isvector, ismatrix, size}
 @end deftypefn */)
@@ -3897,9 +3897,9 @@
 @deftypefn {} {@var{tf} =} isvector (@var{x})
 Return true if @var{x} is a vector.
 
-A vector is a 2-D object where one of the dimensions is equal to 1 (either
-@nospell{1xN} or @nospell{Nx1}).  As a consequence of this definition, a 1x1
-object (a scalar) is also a vector.
+A vector is a 2-D array of any type where one of the dimensions is equal to 1
+(either @nospell{1xN} or @nospell{Nx1}).  As a consequence of this definition,
+a 1x1 object (a scalar) is also a vector.
 @seealso{isscalar, ismatrix, iscolumn, isrow, size}
 @end deftypefn */)
 {
@@ -3938,7 +3938,7 @@
 @deftypefn {} {@var{tf} =} isrow (@var{x})
 Return true if @var{x} is a row vector.
 
-A row vector is a 2-D object for which @code{size (@var{x})} returns
+A row vector is a 2-D array of any type for which @code{size (@var{x})} returns
 @w{@code{[1, N]}} with non-negative N.
 @seealso{iscolumn, isscalar, isvector, ismatrix, size}
 @end deftypefn */)
@@ -3987,8 +3987,8 @@
 @deftypefn {} {@var{tf} =} iscolumn (@var{x})
 Return true if @var{x} is a column vector.
 
-A column vector is a 2-D object for which @code{size (@var{x})} returns
-@w{@code{[N, 1]}} with non-negative N.
+A column vector is a 2-D array of any type for which @code{size (@var{x})}
+returns @w{@code{[N, 1]}} with non-negative N.
 @seealso{isrow, isscalar, isvector, ismatrix, size}
 @end deftypefn */)
 {
@@ -4036,7 +4036,7 @@
 @deftypefn {} {@var{tf} =} ismatrix (@var{x})
 Return true if @var{x} is a 2-D array.
 
-A matrix is an object with two dimensions (@code{ndims (@var{x}) == 2}) for
+A matrix is an array of any type where @code{ndims (@var{x}) == 2} and for
 which @code{size (@var{x})} returns @w{@code{[M, N]}} with non-negative M and
 N.
 @seealso{isscalar, isvector, iscell, isstruct, issparse, isa}
@@ -4085,8 +4085,8 @@
 @deftypefn {} {@var{tf} =} issquare (@var{x})
 Return true if @var{x} is a 2-D square array.
 
-A square array is a 2-D object for which @code{size (@var{x})} returns
-@w{@code{[N, N]}} where N is a non-negative integer.
+A square array is a 2-D array of any type for which @code{size (@var{x})}
+returns @w{@code{[N, N]}} where N is a non-negative integer.
 @seealso{isscalar, isvector, ismatrix, size}
 @end deftypefn */)
 {
--- a/libinterp/octave-value/ov-null-mat.cc	Thu Feb 15 10:09:45 2024 -0800
+++ b/libinterp/octave-value/ov-null-mat.cc	Thu Feb 15 21:42:27 2024 -0500
@@ -101,7 +101,7 @@
 DEFUN (isnull, args, ,
        doc: /* -*- texinfo -*-
 @deftypefn {} {@var{tf} =} isnull (@var{x})
-Return true if @var{x} is a special null matrix, string, or single quoted
+Return true if @var{x} is a special null array, string, or single quoted
 string.
 
 Indexed assignment with such a null value on the right-hand side should delete
--- a/scripts/linear-algebra/isbanded.m	Thu Feb 15 10:09:45 2024 -0800
+++ b/scripts/linear-algebra/isbanded.m	Thu Feb 15 21:42:27 2024 -0500
@@ -25,7 +25,7 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {} {@var{tf} =} isbanded (@var{A}, @var{lower}, @var{upper})
-## Return true if @var{A} is a matrix with entries confined between
+## Return true if @var{A} is a numeric matrix with entries confined between
 ## @var{lower} diagonals below the main diagonal and @var{upper} diagonals
 ## above the main diagonal.
 ##
--- a/scripts/linear-algebra/isdefinite.m	Thu Feb 15 10:09:45 2024 -0800
+++ b/scripts/linear-algebra/isdefinite.m	Thu Feb 15 21:42:27 2024 -0500
@@ -26,8 +26,8 @@
 ## -*- texinfo -*-
 ## @deftypefn  {} {@var{tf} =} isdefinite (@var{A})
 ## @deftypefnx {} {@var{tf} =} isdefinite (@var{A}, @var{tol})
-## Return true if @var{A} is symmetric positive definite matrix within the
-## tolerance specified by @var{tol}.
+## Return true if @var{A} is symmetric positive definite numeric matrix within
+## the tolerance specified by @var{tol}.
 ##
 ## If @var{tol} is omitted, use a tolerance of
 ## @code{100 * eps * norm (@var{A}, "fro")}.
--- a/scripts/linear-algebra/isdiag.m	Thu Feb 15 10:09:45 2024 -0800
+++ b/scripts/linear-algebra/isdiag.m	Thu Feb 15 21:42:27 2024 -0500
@@ -25,7 +25,8 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {} {@var{tf} =} isdiag (@var{A})
-## Return true if @var{A} is a diagonal matrix.
+## Return true if @var{A} is a diagonal numeric matrix which is defined as a
+## 2-D array where all elements above and below the main diagonal are zero.
 ## @seealso{isbanded, istril, istriu, diag, bandwidth}
 ## @end deftypefn
 
--- a/scripts/linear-algebra/ishermitian.m	Thu Feb 15 10:09:45 2024 -0800
+++ b/scripts/linear-algebra/ishermitian.m	Thu Feb 15 21:42:27 2024 -0500
@@ -28,8 +28,8 @@
 ## @deftypefnx {} {@var{tf} =} ishermitian (@var{A}, @var{tol})
 ## @deftypefnx {} {@var{tf} =} ishermitian (@var{A}, @qcode{"skew"})
 ## @deftypefnx {} {@var{tf} =} ishermitian (@var{A}, @qcode{"skew"}, @var{tol})
-## Return true if @var{A} is a Hermitian or skew-Hermitian matrix within the
-## tolerance specified by @var{tol}.
+## Return true if @var{A} is a Hermitian or skew-Hermitian numeric matrix
+## within the tolerance specified by @var{tol}.
 ##
 ## The default tolerance is zero (uses faster code).
 ##
--- a/scripts/linear-algebra/issymmetric.m	Thu Feb 15 10:09:45 2024 -0800
+++ b/scripts/linear-algebra/issymmetric.m	Thu Feb 15 21:42:27 2024 -0500
@@ -28,8 +28,8 @@
 ## @deftypefnx {} {@var{tf} =} issymmetric (@var{A}, @var{tol})
 ## @deftypefnx {} {@var{tf} =} issymmetric (@var{A}, @qcode{"skew"})
 ## @deftypefnx {} {@var{tf} =} issymmetric (@var{A}, @qcode{"skew"}, @var{tol})
-## Return true if @var{A} is a symmetric or skew-symmetric matrix within the
-## tolerance specified by @var{tol}.
+## Return true if @var{A} is a symmetric or skew-symmetric numeric matrix
+## within the tolerance specified by @var{tol}.
 ##
 ## The default tolerance is zero (uses faster code).
 ##
--- a/scripts/linear-algebra/istril.m	Thu Feb 15 10:09:45 2024 -0800
+++ b/scripts/linear-algebra/istril.m	Thu Feb 15 21:42:27 2024 -0500
@@ -25,7 +25,7 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {} {@var{tf} =} istril (@var{A})
-## Return true if @var{A} is a lower triangular matrix.
+## Return true if @var{A} is a lower triangular numeric matrix.
 ##
 ## A lower triangular matrix has nonzero entries only on the main diagonal and
 ## below.
--- a/scripts/linear-algebra/istriu.m	Thu Feb 15 10:09:45 2024 -0800
+++ b/scripts/linear-algebra/istriu.m	Thu Feb 15 21:42:27 2024 -0500
@@ -25,7 +25,7 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {} {@var{tf} =} istriu (@var{A})
-## Return true if @var{A} is an upper triangular matrix.
+## Return true if @var{A} is an upper triangular numeric matrix.
 ##
 ## An upper triangular matrix has nonzero entries only on the main diagonal and
 ## above.