1function result = entries (A, varargin)
2%GRB.ENTRIES count or query the entries of a matrix.
3% An entry A(i,j) in a GraphBLAS matrix is one that is present in the
4% data structure.  Unlike a MATLAB sparse matrix, a GraphBLAS matrix can
5% contain explicit zero entries.  All entries in a MATLAB sparse matrix
6% are nonzero.  A MATLAB full matrix has all of its entries present,
7% regardless of their value.  The GrB.entries function looks only at the
8% pattern of A, not its values.  To exclude explicit entries with a value
9% of zero (or any specified additive identity value) use GrB.nonz
10% instead.
11%
12% Let [m n] = size (A)
13%
14% e = GrB.entries (A)         number of entries
15% e = GrB.entries (A, 'all')  number of entries
16% e = GrB.entries (A, 'row')  number of rows with at least one entry
17% e = GrB.entries (A, 'col')  number of columns with at least one entry
18%
19% X = GrB.entries (A, 'list')         list of values of unique entries
20% X = GrB.entries (A, 'all', 'list')  list of values of unique entries
21% I = GrB.entries (A, 'row', 'list')  list of rows with at least one entry
22% J = GrB.entries (A, 'col', 'list')  list of cols with at least one entry
23%
24% d = GrB.entries (A, 'row', 'degree')
25%   If A is m-by-n, then d is a sparse column vector of size m, with d(i)
26%   equal to the number of entries in A(i,:).  If A(i,:) has no entries,
27%   then d(i) is an implicit zero, not present in the pattern of d, so
28%   that I = find (d) is the same I = GrB.entries (A, 'row', 'list').
29%
30% d = GrB.entries (A, 'col', 'degree')
31%   If A is m-by-n, d is a sparse column vector of size n, with d(j)
32%   equal to the number of entries in A(:,j).  If A(:,j) has no entries,
33%   then d(j) is an implicit zero, not present in the pattern of d, so
34%   that I = find (d) is the same I = GrB.entries (A, 'col', 'list').
35%
36% The result is a MATLAB scalar or vector, except for the 'degree'
37% usage, in which case the result is a GrB vector d.
38%
39% Example:
40%
41%   A = magic (5) ;
42%   A (A < 10) = 0             % MATLAB full matrix with some explicit zeros
43%   GrB.entries (A)            % all entries present in a MATLAB full matrix
44%   G = GrB (A)                % contains explicit zeros
45%   GrB.entries (G)
46%   G (A > 18) = sparse (0)    % entries A>18 deleted, has explicit zeros
47%   GrB.entries (G)
48%   GrB.entries (G, 'list')
49%   S = double (G)             % MATLAB sparse matrix; no explicit zeros
50%   GrB.entries (S)
51%   GrB.entries (S, 'list')
52%
53% See also GrB.nonz, nnz, GrB/nnz, nonzeros, GrB/nonzeros.
54
55% SuiteSparse:GraphBLAS, Timothy A. Davis, (c) 2017-2021, All Rights Reserved.
56% SPDX-License-Identifier: GPL-3.0-or-later
57
58if (isobject (A))
59    % A is a GraphBLAS matrix; get its opaque content
60    A = A.opaque ;
61end
62
63% get the count/list of the entries of A
64result = gb_entries (A, varargin {:}) ;
65
66% if gb_entries returned a GraphBLAS struct, return it as a GrB matrix
67if (isstruct (result))
68    result = GrB (result) ;
69end
70
71