(octave.info)Object Sizes

---

Prev: User-defined Data Types Up: Data Types

---

Enter node , (file) or (file)node

3.3 Object Sizes
================

The following functions allow you to determine the size of a variable or
expression.  These functions are defined for all objects.  They return
−1 when the operation doesn’t make sense.  For example, Octave’s data
structure type doesn’t have rows or columns, so the ‘rows’ and ‘columns’
functions return −1 for structure arguments.

 -- : ndims (A)
     Return the number of dimensions of A.

     For any array, the result will always be greater than or equal to
     2.  Trailing singleton dimensions are not counted.

          ndims (ones (4, 1, 2, 1))
              ⇒ 3

     See also: Note: size.

 -- : columns (A)
     Return the number of columns of A.

     See also: Note: rows, Note: size, *note length:
     XREFlength, Note: numel, Note: isscalar,
     Note: isvector, Note: ismatrix.

 -- : rows (A)
     Return the number of rows of A.

     See also: Note: columns, Note: size, Note:
     length, Note: numel, *note isscalar:
     XREFisscalar, Note: isvector, *note ismatrix:
     XREFismatrix.

 -- : numel (A)
 -- : numel (A, IDX1, IDX2, ...)
     Return the number of elements in the object A.

     Optionally, if indices IDX1, IDX2, ... are supplied, return the
     number of elements that would result from the indexing

          A(IDX1, IDX2, ...)

     Note that the indices do not have to be scalar numbers.  For
     example,

          A = 1;
          B = ones (2, 3);
          numel (A, B)

     will return 6, as this is the number of ways to index with B.  Or
     the index could be the string ":" which represents the colon
     operator.  For example,

          A = ones (5, 3);
          numel (A, 2, ":")

     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., ‘object{...}’ or ‘object(...).field’.

     See also: Note: size, Note: length, Note:
     ndims.

 -- : length (A)
     Return the length of the object 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 ‘max (size (A))’).

     See also: Note: numel, Note: size.

 -- : SZ = size (A)
 -- : DIM_SZ = size (A, DIM)
 -- : [ROWS, COLS, ..., DIM_N_SZ] = size (...)
     Return a row vector with the size (number of elements) of each
     dimension for the object A.

     When given a second argument, DIM, return the size of the
     corresponding dimension.

     With a single output argument, ‘size’ returns a row vector.  When
     called with multiple output arguments, ‘size’ returns the size of
     dimension N in the Nth argument.  The number of rows, dimension 1,
     is returned in the first argument, the number of columns, dimension
     2, is returned in the second argument, etc.  If there are more
     dimensions in A than there are output arguments, ‘size’ returns the
     total number of elements in the remaining dimensions in the final
     output argument.

     Example 1: single row vector output

          size ([1, 2; 3, 4; 5, 6])
             ⇒ [ 3, 2 ]

     Example 2: number of elements in 2nd dimension (columns)

          size ([1, 2; 3, 4; 5, 6], 2)
              ⇒ 2

     Example 3: number of output arguments == number of dimensions

          [nr, nc] = size ([1, 2; 3, 4; 5, 6])
              ⇒ nr = 3
              ⇒ nc = 2

     Example 4: number of output arguments < number of dimensions

          [nr, remainder] = size (ones (2, 3, 4, 5))
              ⇒ nr = 2
              ⇒ remainder = 60

     See also: Note: numel, Note: ndims, Note:
     length, Note: rows, *note columns:
     XREFcolumns, Note: size_equal, *note common_size:
     XREFcommon_size.

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

     See also: Note: isnull, Note: isa.

 -- : isnull (X)
     Return true if X is a special null matrix, string, or single quoted
     string.

     Indexed assignment with such a null value on the right-hand side
     should delete array elements.  This function is used in place of
     ‘isempty’ when overloading the indexed assignment method
     (‘subsasgn’) for user-defined classes.  ‘isnull’ is used to
     distinguish between these two cases:

     ‘A(I) = []’

     and

     ‘X = []; A(I) = X’

     In the first assignment, the right-hand side is ‘[]’ which is a
     special null value.  As long as the index I is not empty, this code
     should delete elements from A rather than perform assignment.

     In the second assignment, the right-hand side is empty (because X
     is ‘[]’), but it is *not* null.  This code should assign the empty
     value to elements in A.

     An example from Octave’s built-in char class demonstrates the
     interpreter behavior when ‘isnull’ is used correctly.

          str = "Hello World";
          nm = "Wally";
          str(7:end) = nm                # indexed assignment
            ⇒ str = Hello Wally
          str(7:end) = ""                # indexed deletion
            ⇒ str = Hello

     See also: Note: isempty, Note: isindex.

 -- : sizeof (VAL)
     Return the size of VAL in bytes.

     See also: Note: whos.

 -- : size_equal (A, B, ...)
     Return true if the dimensions of all arguments agree.

     Trailing singleton dimensions are ignored.  When called with a
     single argument, or no argument, ‘size_equal’ returns true.

     See also: Note: size, Note: numel, Note:
     ndims, Note: common_size.

 -- : squeeze (X)
     Remove singleton dimensions from X and return the result.

     Note that for compatibility with MATLAB, all objects have a minimum
     of two dimensions and row vectors are left unchanged.

     See also: Note: reshape.