bugGNU Octave - Bugs: bug #48088, document that issquare, iscolumn,...

 
 

bug #48088: document that issquare, iscolumn, isempty, etc operate on cell arrays

Submitter:  Francesco Potortì <pot>
Submitted:  Thu 02 Jun 2016 11:26:40 AM UTC
 
Category:  Documentation Severity:  2 - Minor
Priority:  3 - Low Item Group:  Documentation
Status:  Patch Submitted Assigned to:  None
Originator Name:  Open/Closed:  * Open
Release:  * dev Operating System:  * Any
* Mandatory Fields

Add a New Comment (Rich Markup)
   

Comment Type & Canned Response:
       

 

( Jump to the original submission )

Fri 12 Nov 2021 04:22:46 AM UTC, comment #7: 

i think the term object is generic enough to address the issue in the bug. but i notice it's not consistent across all functions mentioned.

in Octave 6.4.0:

issquare:

     Return true if X is a 2-D square array.

     A square array is a 2-D object for which 'size (X)' returns
     '[N, N]' where N is a non-negative integer.

isrow (same with iscolumn):

     Return true if X is a row vector.

     A row vector is a 2-D array for which 'size (X)' returns '[1, N]'
     with non-negative N.

isempty:

     Return true if A is an empty matrix (any one of its dimensions is
     zero).

ismatrix:

     Return true if X is a 2-D array.

     A matrix is an object with two dimensions ('ndims (X) == 2') for
     which 'size (X)' returns '[M, N]' with non-negative M and N.

isvector:

     Return true if X is a vector.

     A vector is a 2-D array where one of the dimensions is equal to 1
     (either 1xN or Nx1).  As a consequence of this definition, a 1x1
     array (a scalar) is also a vector.

isscalar:

     Return true if X is a scalar.

     A scalar is an object with two dimensions for which 'size (X)'
     returns '[1, 1]'.

isnull, isdiag, issymettric, istril, and istriu are specific to matrices, so no changes there.  I don't see any others in the is* list.

Attached is a patch that makes the docstring changes for isrow, iscolumn, isempty, and isvector to use the 'object' terminology (all in data.cc).

The revised docstrings:

isrow (and column):

     Return true if X is a row vector.

     A row vector is a 2-D object for which 'size (X)' returns '[1, N]'
     with non-negative N.

isempty:

     Return true if A is an empty object (any one of its dimensions is
     zero).

isvector:

     Return true if X is a vector.

     A vector is a 2-D object where one of the dimensions is equal to 1
     (either 1xN or Nx1).  As a consequence of this definition, a 1x1
     object (a scalar) is also a vector.

Please add a comment if there are other functions i missed.

(file #52255)

Nicholas Jankowski <nrjank>
Project Member
Mon 19 Apr 2021 03:15:06 PM UTC, comment #6: 

Yes, I think this is probably good enough and certainly better than my initial proposal

The only drawback is that we are defining here what an array is.  The manual only speaks about character arrays, cell arrays, struct arrays, Java arrays.  The notion that an "array" is a generic concept including also matrices would probably be a useful addition to the manual, especially for use in function descriptions, as this is not unique to issquare.

Francesco Potortì <pot>
Sun 07 Mar 2021 05:51:58 AM UTC, comment #5: 

For version 6.1.0

help issquare
'issquare' is a built-in function from the file libinterp/corefcn/data.cc

 -- issquare (X)
     Return true if X is a 2-D square array.

     A square array is a 2-D object for which 'size (X)' returns
     '[N, N]' where N is a non-negative integer.

     See also: isscalar, isvector, ismatrix, size.

This is better than comment #0.
Francesco, what are your thoughts?

Anonymous
Fri 24 Jun 2016 03:41:24 PM UTC, comment #4: 

Well, certainly the word "matrix" should either removed from the help or accompanied by other possible types to which issquare applies.

Ideally, I would like to find something along these lines:

return true if X is square.
X can be a matrix, cell array or any other type for which size(X) returns [r, c] with r == c.

Maybe your proposal is good as well.

Francesco Potortì <pot>
Fri 24 Jun 2016 04:43:00 AM UTC, comment #3: 

The Matlab documentation often lists the types a function can be applied to.

However, "help isrow" for example, simply gives the definition in terms of "size", without mentioning whether the argument is a matrix, a cell array or a class object.

Perhaps "issquare" could say
  Return true of X has size(X) = [r, c] with r == c.

Francesco, would that be sufficient for you?

Lachlan Andrew <lachlan>
Thu 02 Jun 2016 03:13:16 PM UTC, comment #2: 

Should be briefly mentioned in all functions. The way I use the documentation, it would be almost useless otherwise.

Francesco Potortì <pot>
Thu 02 Jun 2016 02:42:04 PM UTC, comment #1: 

This applies to all the "shape" functions, isempty, isrow, iscolumn, issquare, ismatrix, isvector, etc.

Should each function have to mention cell arrays? Or should the documentation section on cell arrays say something like "many functions that operate on matrices also apply to cell arrays")?

Mike Miller <mtmiller>
Project Administrator
Thu 02 Jun 2016 11:26:40 AM UTC, original submission:  

> help issquare

'issquare' is a built-in function from the file libinterp/corefcn/data.cc

 -- Function File: issquare (X)
     Return true if X is a square matrix.

     See also: isscalar, isvector, ismatrix, size.

Francesco Potortì <pot>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

Attached Files
file #52255:  issquare_on_object_docfix_bug48088.diff added by nrjank (2KiB - application/octet-stream)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by nrjank (Updated the item)
  • -email is unavailable- added by lachlan (Posted a comment)
  • -email is unavailable- added by siko1056 (Updated the item)
  • -email is unavailable- added by pot (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only project members can vote.

     

     

     

     

    Follow 8 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2021-11-12 nrjank Attached File- Added issquare_on_object_docfix_bug48088.diff, #52255
        StatusConfirmed Patch Submitted
    2019-03-04 mtmiller Release4.0.2 dev
    2019-03-04 mtmiller Carbon-CopyRemoved 80942 -
    2016-06-02 mtmiller SummaryDocs from issquare() should mention that it works for cell arrays too. document that issquare, iscolumn, isempty, etc operate on cell arrays
    2016-06-02 mtmiller Severity3 - Normal 2 - Minor
    2016-06-02 siko1056 Priority5 - Normal 3 - Low
        StatusNone Confirmed

    Back to the top


    Powered by Savane 3.9