1function [I,J,X] = extracttuples (A, desc)
2%GRB.EXTRACTTUPLES extract a list of entries from a matrix.
3%
4%   [I,J,X] = GrB.extracttuples (A, desc)
5%
6% GrB.extracttuples extracts all entries from either a MATLAB or
7% GraphBLAS matrix.  If A is a MATLAB sparse or full matrix,
8% [I,J,X] = GrB.extracttuples (A) is identical to [I,J,X] = find (A).
9%
10% For a GraphBLAS matrix G, GrB.extracttuples (G) returns any explicit
11% zero entries in G, while find (G) excludes them.
12%
13% The descriptor is optional.  desc.base is a string, either 'default',
14% 'zero-based', 'one-based int', or 'one-based'.  This parameter
15% determines the type of output for I and J.  The default is one-based,
16% so that I and J are returned as double vectors, with one-based indices.
17% If max(size(A)) > flintmax, however, the default is 'one-based int', so
18% that I and J are int64 vectors with one-based indices.  One-based
19% indices in I are in the range 1 to m, and the indices in J are in the
20% range 1 to n, if A is m-by-n.  This is identical to [I,J,X] = find (A)
21% for a MATLAB sparse or full matrix.
22%
23% If 'zero-based', I and J are returned as int64 arrays, with zero-based
24% indices.  The entries in I and J are in the range 0 to m-1 and 0 to
25% n-1, respectively, if [m n] = size (A).  This usage is not the
26% conventional 1-based indexing in MATLAB, but it is the fastest method.
27%
28% The overloaded [I,J,X] = find (A) method for a GraphBLAS matrix A uses
29% desc.base of 'default', and always removes explicit zeros.
30%
31% See also GrB/find, GrB/build.
32
33% SuiteSparse:GraphBLAS, Timothy A. Davis, (c) 2017-2021, All Rights Reserved.
34% SPDX-License-Identifier: GPL-3.0-or-later
35
36if (isobject (A))
37    A = A.opaque ;
38end
39if (nargin < 2)
40    desc.base = 'default' ;
41end
42
43switch (nargout)
44    case 1
45        I = gbextracttuples (A, desc) ;
46    case 2
47        [I, J] = gbextracttuples (A, desc) ;
48    case 3
49        [I, J, X] = gbextracttuples (A, desc) ;
50end
51
52