1function filename_used = save (C, filename)
2%GRB.SAVE Save a single GraphBLAS matrix to a file.
3% GrB.save (C) saves a single @GrB or MATLAB matrix C to a file, with a
4% filename of 'C.mat' that matches the matrix name.  If C is an
5% expression, the filename 'GrB_Matrix.mat' is used.  A second parameter
6% allows for the selection of a different filename, as GrB.save (C,
7% 'myfile.mat').  If A is not already a @GrB matrix, it is converted to
8% one with GrB(A).
9%
10% The object or matrix C is saved as a struct containing the opaque
11% contents of the GrB object, which is then reconstructed by GrB.load.  A
12% matrix saved to a file with GrB.save must be loaded back with GrB.load.
13% It cannot be loaded with the built-in load method.
14%
15% Example:
16%
17%   A = magic (4) ;
18%   GrB.save (A) ;              % A can be a @GrB or MATLAB matrix
19%   clear all
20%   A = GrB.load ('A.mat') ;    % A is now a @GrB matrix
21%
22% See also GrB.load, GrB/struct.
23
24% A note to Octave users:  a file written out by GrB.save in MATLAB
25% should be readable by GrB.load in Octave, and visa versa, as long as
26% the same version of GraphBLAS is used.
27
28% SuiteSparse:GraphBLAS, Timothy A. Davis, (c) 2017-2021, All Rights Reserved.
29% SPDX-License-Identifier: GPL-3.0-or-later
30
31% make sure C is a @GrB object
32if (~isobject (C))
33    C = GrB (C) ;
34end
35
36% Extract the opaque contents of C as a struct.  Give it a long and peculiar
37% name to help ensure it is only loaded by GrB.load.
38GraphBLAS_struct_from_GrB_save = C.opaque ;
39
40% determine the default filename
41if (nargin < 2)
42    filename = inputname (1) ;
43    if (isempty (filename))
44        % inputname returns an empty string if the input argument C
45        % is an expression that has no name
46        filename = 'GrB_Matrix' ;
47    end
48    filename = [filename '.mat'] ;
49end
50
51% save the struct (not the @GrB matrix C) to the file.
52save (filename, 'GraphBLAS_struct_from_GrB_save') ;
53
54% return the chosen filename
55if (nargout > 0)
56    filename_used = filename ;
57end
58
59