Mercurial > octave
annotate libinterp/corefcn/sparse.cc @ 33617:ec2635a02328 bytecode-interpreter tip
maint: Merge default to bytecode-interpreter.
author | Markus Mützel <markus.muetzel@gmx.de> |
---|---|
date | Tue, 21 May 2024 18:29:03 +0200 |
parents | 5fded8395daa |
children |
rev | line source |
---|---|
27923
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
1 //////////////////////////////////////////////////////////////////////// |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
2 // |
32632
2e484f9f1f18
maint: update Octave Project Developers copyright for the new year
John W. Eaton <jwe@octave.org>
parents:
32059
diff
changeset
|
3 // Copyright (C) 1998-2024 The Octave Project Developers |
27923
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
4 // |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
5 // See the file COPYRIGHT.md in the top-level directory of this |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
6 // distribution or <https://octave.org/copyright/>. |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
7 // |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
8 // This file is part of Octave. |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
9 // |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
10 // Octave is free software: you can redistribute it and/or modify it |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
11 // under the terms of the GNU General Public License as published by |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
12 // the Free Software Foundation, either version 3 of the License, or |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
13 // (at your option) any later version. |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
14 // |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
15 // Octave is distributed in the hope that it will be useful, but |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
16 // WITHOUT ANY WARRANTY; without even the implied warranty of |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
17 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
18 // GNU General Public License for more details. |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
19 // |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
20 // You should have received a copy of the GNU General Public License |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
21 // along with Octave; see the file COPYING. If not, see |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
22 // <https://www.gnu.org/licenses/>. |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
23 // |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
24 //////////////////////////////////////////////////////////////////////// |
5164 | 25 |
21724
aba2e6293dd8
use "#if ..." consistently instead of "#ifdef" and "#ifndef"
John W. Eaton <jwe@octave.org>
parents:
21547
diff
changeset
|
26 #if defined (HAVE_CONFIG_H) |
21301
40de9f8f23a6
Use '#include "config.h"' rather than <config.h>.
Rik <rik@octave.org>
parents:
21200
diff
changeset
|
27 # include "config.h" |
5164 | 28 #endif |
29 | |
30 #include <cstdlib> | |
31 #include <string> | |
32 | |
33 #include "variables.h" | |
34 #include "utils.h" | |
35 #include "pager.h" | |
11097
ffb2f1ef2097
make issparse, sparse, and spalloc built-in functions
John W. Eaton <jwe@octave.org>
parents:
10846
diff
changeset
|
36 #include "defun.h" |
21100
e39e05d90788
Switch gripe_XXX to either err_XXX or warn_XXX naming scheme.
Rik <rik@octave.org>
parents:
21062
diff
changeset
|
37 #include "errwarn.h" |
5164 | 38 #include "quit.h" |
10479
ded9beac7582
optimize sparse matrix assembly
Jaroslav Hajek <highegg@gmail.com>
parents:
10155
diff
changeset
|
39 #include "unwind-prot.h" |
5164 | 40 |
41 #include "ov-re-sparse.h" | |
42 #include "ov-cx-sparse.h" | |
43 #include "ov-bool-sparse.h" | |
44 | |
31605
e88a07dec498
maint: Use macros to begin/end C++ namespaces.
Rik <rik@octave.org>
parents:
30801
diff
changeset
|
45 OCTAVE_BEGIN_NAMESPACE(octave) |
29958
32c3a5805893
move DEFUN and DEFMETHOD functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents:
29569
diff
changeset
|
46 |
11097
ffb2f1ef2097
make issparse, sparse, and spalloc built-in functions
John W. Eaton <jwe@octave.org>
parents:
10846
diff
changeset
|
47 DEFUN (issparse, args, , |
21966
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
48 doc: /* -*- texinfo -*- |
30559
841a10208c38
doc: Use TF for output variable in documentation for isXXX functions in libinterp/ directory.
Rik <rik@octave.org>
parents:
30390
diff
changeset
|
49 @deftypefn {} {@var{tf} =} issparse (@var{x}) |
21966
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
50 Return true if @var{x} is a sparse matrix. |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
51 @seealso{ismatrix} |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
52 @end deftypefn */) |
5164 | 53 { |
17787
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
54 if (args.length () != 1) |
20803
c22206c1a88f
eliminate return statements after calls to print_usage
John W. Eaton <jwe@octave.org>
parents:
20667
diff
changeset
|
55 print_usage (); |
c22206c1a88f
eliminate return statements after calls to print_usage
John W. Eaton <jwe@octave.org>
parents:
20667
diff
changeset
|
56 |
23583
b7747a2c88b2
maint: Deprecate is_sparse_type and replace with issparse.
Rik <rik@octave.org>
parents:
23581
diff
changeset
|
57 return ovl (args(0).issparse ()); |
5164 | 58 } |
59 | |
26213
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
60 /* |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
61 %!assert (issparse (sparse (1)), true) |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
62 %!assert (issparse (1), false) |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
63 %!assert (issparse (sparse (false)), true) |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
64 %!assert (issparse (true), false) |
32058
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
65 %!test |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
66 %! warning ("off", "Octave:sparse:double-conversion", "local"); |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
67 %! assert (issparse (sparse (single ([1 2]))), true); |
26213
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
68 %!assert (issparse (single ([1, 2])), false) |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
69 %!assert (issparse (sparse ([1+i, 2]')), true) |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
70 %!assert (issparse ([1+i, 2]'), false) |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
71 |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
72 %!assert (issparse ([]), false) |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
73 %!assert (issparse (sparse([])), true) |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
74 %!assert (issparse ("test"), false) |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
75 %!assert (issparse (struct ("one", {1})), false) |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
76 %!assert (issparse (cell (1)), false) |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
77 |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
78 ## Test input validation |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
79 %!error issparse () |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
80 %!error issparse (1,2) |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
81 */ |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
82 |
11097
ffb2f1ef2097
make issparse, sparse, and spalloc built-in functions
John W. Eaton <jwe@octave.org>
parents:
10846
diff
changeset
|
83 DEFUN (sparse, args, , |
21966
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
84 doc: /* -*- texinfo -*- |
31972
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
85 @deftypefn {} {@var{S} =} sparse (@var{A}) |
32058
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
86 @deftypefnx {} {@var{S} =} sparse (@var{m}, @var{n}) |
31972
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
87 @deftypefnx {} {@var{S} =} sparse (@var{i}, @var{j}, @var{sv}) |
32058
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
88 @deftypefnx {} {@var{S} =} sparse (@var{i}, @var{j}, @var{sv}, @var{m}, @var{n}) |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
89 @deftypefnx {} {@var{S} =} sparse (@var{i}, @var{j}, @var{sv}, @var{m}, @var{n}, "unique") |
31972
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
90 @deftypefnx {} {@var{S} =} sparse (@var{i}, @var{j}, @var{sv}, @var{m}, @var{n}, @var{nzmax}) |
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
91 Create a sparse matrix from a full matrix @var{A} or row, column, value |
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
92 triplets. |
21966
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
93 |
31972
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
94 If @var{A} is a full matrix, convert it to a sparse matrix representation, |
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
95 removing all zero values in the process. The matrix @var{A} should be of type |
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
96 logical or double. |
21966
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
97 |
32058
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
98 If two inputs @var{m} (rows) and @var{n} (columns) are specified then create |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
99 an empty sparse matrix with the specified dimensions. |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
100 |
21966
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
101 Given the integer index vectors @var{i} and @var{j}, and a 1-by-@code{nnz} |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
102 vector of real or complex values @var{sv}, construct the sparse matrix |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
103 @code{S(@var{i}(@var{k}),@var{j}(@var{k})) = @var{sv}(@var{k})} with overall |
31972
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
104 dimensions @var{m} and @var{n}. If any of @var{i}, @var{j}, or @var{sv} are |
21966
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
105 scalars, they are expanded to have a common size. |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
106 |
31972
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
107 If @var{m} or @var{n} are not specified then their values are derived from the |
21966
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
108 maximum index in the vectors @var{i} and @var{j} as given by |
31972
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
109 @w{@code{@var{m} = max (@var{i})}}, @w{@code{@var{n} = max (@var{j})}}. |
21966
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
110 |
31972
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
111 @strong{Note}: If multiple values are specified with the same @var{i}, |
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
112 @var{j} indices, the corresponding value in @var{S} will be the sum of the |
28960
e5a1087f15d5
doc: Use @xref, @pxref rather than "see @code{}" in TexInfo in libinterp/
Rik <rik@octave.org>
parents:
28907
diff
changeset
|
113 values at the repeated location. @xref{XREFaccumarray,,@code{accumarray}}, for |
e5a1087f15d5
doc: Use @xref, @pxref rather than "see @code{}" in TexInfo in libinterp/
Rik <rik@octave.org>
parents:
28907
diff
changeset
|
114 an example of how to produce different behavior such as taking the minimum |
e5a1087f15d5
doc: Use @xref, @pxref rather than "see @code{}" in TexInfo in libinterp/
Rik <rik@octave.org>
parents:
28907
diff
changeset
|
115 instead. |
21966
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
116 |
31972
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
117 If the option @qcode{"unique"} is given, and more than one value is specified |
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
118 at the same @var{i}, @var{j} indices, then only the last specified value will |
32058
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
119 be used. For completeness, the option @qcode{"sum"} can be given and will |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
120 be ignored as the default behavior is to sum values at repeated locations. |
21966
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
121 |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
122 @code{sparse (@var{m}, @var{n})} will create an empty @var{m}x@var{n} sparse |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
123 matrix and is equivalent to @code{sparse ([], [], [], @var{m}, @var{n})} |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
124 |
31972
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
125 The optional final argument reserves space for @var{nzmax} values in the sparse |
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
126 array and is useful if the eventual number of nonzero values will be greater |
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
127 than the number of values in @var{sv} used during the initial construction of |
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
128 the array. @xref{XREFspalloc,,@code{spalloc}}, for more information and usage |
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
129 instructions. |
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
130 |
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
131 Example 1 (convert full matrix to sparse to save memory): |
21966
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
132 |
31972
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
133 @example |
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
134 @group |
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
135 x = full (diag (1:1000)); |
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
136 sizeof (x) |
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
137 @result{} 8000000 |
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
138 s = sparse (x); |
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
139 sizeof (xs) |
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
140 @result{} 24008 |
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
141 @end group |
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
142 @end example |
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
143 |
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
144 Example 2 (sum at repeated indices): |
21966
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
145 |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
146 @example |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
147 @group |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
148 @var{i} = [1 1 2]; @var{j} = [1 1 2]; @var{sv} = [3 4 5]; |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
149 sparse (@var{i}, @var{j}, @var{sv}, 3, 4) |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
150 @result{} |
26600
f6730533820e
doc: clean up doc example blocks for accuracy and consistent formatting
Mike Miller <mtmiller@octave.org>
parents:
26376
diff
changeset
|
151 Compressed Column Sparse (rows = 3, cols = 4, nnz = 2 [17%]) |
21966
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
152 |
26600
f6730533820e
doc: clean up doc example blocks for accuracy and consistent formatting
Mike Miller <mtmiller@octave.org>
parents:
26376
diff
changeset
|
153 (1, 1) -> 7 |
f6730533820e
doc: clean up doc example blocks for accuracy and consistent formatting
Mike Miller <mtmiller@octave.org>
parents:
26376
diff
changeset
|
154 (2, 2) -> 5 |
21966
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
155 @end group |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
156 @end example |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
157 |
31972
87beb2f167ea
doc: Correct and improve documentation for sparse() function.
Rik <rik@octave.org>
parents:
31706
diff
changeset
|
158 Example 3 ("unique" option): |
21966
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
159 |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
160 @example |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
161 @group |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
162 @var{i} = [1 1 2]; @var{j} = [1 1 2]; @var{sv} = [3 4 5]; |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
163 sparse (@var{i}, @var{j}, @var{sv}, 3, 4, "unique") |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
164 @result{} |
26600
f6730533820e
doc: clean up doc example blocks for accuracy and consistent formatting
Mike Miller <mtmiller@octave.org>
parents:
26376
diff
changeset
|
165 Compressed Column Sparse (rows = 3, cols = 4, nnz = 2 [17%]) |
21966
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
166 |
26600
f6730533820e
doc: clean up doc example blocks for accuracy and consistent formatting
Mike Miller <mtmiller@octave.org>
parents:
26376
diff
changeset
|
167 (1, 1) -> 4 |
f6730533820e
doc: clean up doc example blocks for accuracy and consistent formatting
Mike Miller <mtmiller@octave.org>
parents:
26376
diff
changeset
|
168 (2, 2) -> 5 |
21966
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
169 @end group |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
170 @end example |
30329
81d26e8481a6
maint: Shorten @seealso lines to less than 80 characters (bug #57599)
Rik <rik@octave.org>
parents:
29961
diff
changeset
|
171 @seealso{full, accumarray, spalloc, spdiags, speye, spones, sprand, sprandn, |
81d26e8481a6
maint: Shorten @seealso lines to less than 80 characters (bug #57599)
Rik <rik@octave.org>
parents:
29961
diff
changeset
|
172 sprandsym, spconvert, spfun} |
21966
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
173 @end deftypefn */) |
5164 | 174 { |
17787
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
175 int nargin = args.length (); |
5164 | 176 |
20803
c22206c1a88f
eliminate return statements after calls to print_usage
John W. Eaton <jwe@octave.org>
parents:
20667
diff
changeset
|
177 if (nargin == 0 || nargin > 6) |
c22206c1a88f
eliminate return statements after calls to print_usage
John W. Eaton <jwe@octave.org>
parents:
20667
diff
changeset
|
178 print_usage (); |
c22206c1a88f
eliminate return statements after calls to print_usage
John W. Eaton <jwe@octave.org>
parents:
20667
diff
changeset
|
179 |
20939
b17fda023ca6
maint: Use new C++ archetype in more files.
Rik <rik@octave.org>
parents:
20853
diff
changeset
|
180 octave_value retval; |
b17fda023ca6
maint: Use new C++ archetype in more files.
Rik <rik@octave.org>
parents:
20853
diff
changeset
|
181 |
17787
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
182 if (nargin == 1) |
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
183 { |
18112
b560bac0fca2
maint: Don't use space between 'args' and '(' when doing indexing.
Rik <rik@octave.org>
parents:
18100
diff
changeset
|
184 octave_value arg = args(0); |
32058
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
185 if (arg.isfloat ()) |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
186 { |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
187 if (arg.is_single_type ()) |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
188 warning_with_id ("Octave:sparse:double-conversion", |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
189 "sparse: input array cast to double"); |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
190 if (arg.iscomplex ()) |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
191 retval = arg.sparse_complex_matrix_value (); |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
192 else |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
193 retval = arg.sparse_matrix_value (); |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
194 } |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
195 else if (arg.islogical ()) |
17787
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
196 retval = arg.sparse_bool_matrix_value (); |
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
197 else |
21100
e39e05d90788
Switch gripe_XXX to either err_XXX or warn_XXX naming scheme.
Rik <rik@octave.org>
parents:
21062
diff
changeset
|
198 err_wrong_type_arg ("sparse", arg); |
17787
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
199 } |
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
200 else if (nargin == 2) |
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
201 { |
33446
5fded8395daa
rename yTYPE_value functions strict_TYPE_value
John W. Eaton <jwe@octave.org>
parents:
33365
diff
changeset
|
202 octave_idx_type m = args(0).strict_idx_type_value ("sparse: M must be a non-negative integer"); |
5fded8395daa
rename yTYPE_value functions strict_TYPE_value
John W. Eaton <jwe@octave.org>
parents:
33365
diff
changeset
|
203 octave_idx_type n = args(1).strict_idx_type_value ("sparse: N must be a non-negative integer"); |
10479
ded9beac7582
optimize sparse matrix assembly
Jaroslav Hajek <highegg@gmail.com>
parents:
10155
diff
changeset
|
204 |
26213
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
205 if (m < 0 || n < 0) |
32059
bade9602c5a1
Validate M and N dimension inputs to sparse().
Rik <rik@octave.org>
parents:
32058
diff
changeset
|
206 error ("sparse: dimensions M and N must be non-negative"); |
26213
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
207 |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
208 retval = SparseMatrix (m, n); |
17787
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
209 } |
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
210 else if (nargin >= 3) |
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
211 { |
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
212 bool summation = true; |
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
213 if (nargin > 3 && args(nargin-1).is_string ()) |
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
214 { |
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
215 std::string opt = args(nargin-1).string_value (); |
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
216 if (opt == "unique") |
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
217 summation = false; |
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
218 else if (opt == "sum" || opt == "summation") |
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
219 summation = true; |
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
220 else |
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
221 error ("sparse: invalid option: %s", opt.c_str ()); |
5164 | 222 |
17787
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
223 nargin -= 1; |
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
224 } |
5164 | 225 |
20555
f90c8372b7ba
eliminate many more simple uses of error_state
John W. Eaton <jwe@octave.org>
parents:
20542
diff
changeset
|
226 octave_idx_type m, n, nzmax; |
f90c8372b7ba
eliminate many more simple uses of error_state
John W. Eaton <jwe@octave.org>
parents:
20542
diff
changeset
|
227 m = n = nzmax = -1; |
f90c8372b7ba
eliminate many more simple uses of error_state
John W. Eaton <jwe@octave.org>
parents:
20542
diff
changeset
|
228 if (nargin == 6) |
17787
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
229 { |
20555
f90c8372b7ba
eliminate many more simple uses of error_state
John W. Eaton <jwe@octave.org>
parents:
20542
diff
changeset
|
230 nzmax = args(5).idx_type_value (); |
21062
d9c1884d1aaa
maint: Eliminate space between variable and decrement '--' operator.
Rik <rik@octave.org>
parents:
20939
diff
changeset
|
231 nargin--; |
20555
f90c8372b7ba
eliminate many more simple uses of error_state
John W. Eaton <jwe@octave.org>
parents:
20542
diff
changeset
|
232 } |
10527
b4d2080b6df7
Replace nzmax by nnz as needed
David Bateman <dbateman@free.fr>
parents:
10521
diff
changeset
|
233 |
20555
f90c8372b7ba
eliminate many more simple uses of error_state
John W. Eaton <jwe@octave.org>
parents:
20542
diff
changeset
|
234 if (nargin == 5) |
f90c8372b7ba
eliminate many more simple uses of error_state
John W. Eaton <jwe@octave.org>
parents:
20542
diff
changeset
|
235 { |
33446
5fded8395daa
rename yTYPE_value functions strict_TYPE_value
John W. Eaton <jwe@octave.org>
parents:
33365
diff
changeset
|
236 m = args(3).strict_idx_type_value ("sparse: M must be a non-negative integer"); |
5fded8395daa
rename yTYPE_value functions strict_TYPE_value
John W. Eaton <jwe@octave.org>
parents:
33365
diff
changeset
|
237 n = args(4).strict_idx_type_value ("sparse: N must be a non-negative integer"); |
5164 | 238 |
20667
8742e0b1cc49
eliminate more uses of error_state
John W. Eaton <jwe@octave.org>
parents:
20555
diff
changeset
|
239 if (m < 0 || n < 0) |
32059
bade9602c5a1
Validate M and N dimension inputs to sparse().
Rik <rik@octave.org>
parents:
32058
diff
changeset
|
240 error ("sparse: dimensions M and N must be non-negative"); |
20555
f90c8372b7ba
eliminate many more simple uses of error_state
John W. Eaton <jwe@octave.org>
parents:
20542
diff
changeset
|
241 } |
10479
ded9beac7582
optimize sparse matrix assembly
Jaroslav Hajek <highegg@gmail.com>
parents:
10155
diff
changeset
|
242 |
32059
bade9602c5a1
Validate M and N dimension inputs to sparse().
Rik <rik@octave.org>
parents:
32058
diff
changeset
|
243 int argidx = 0; // index being checked when index_vector throws |
20555
f90c8372b7ba
eliminate many more simple uses of error_state
John W. Eaton <jwe@octave.org>
parents:
20542
diff
changeset
|
244 try |
f90c8372b7ba
eliminate many more simple uses of error_state
John W. Eaton <jwe@octave.org>
parents:
20542
diff
changeset
|
245 { |
29961
7d6709900da7
eliminate octave:: namespace tags in DEFUN and DEFMETHOD and more
John W. Eaton <jwe@octave.org>
parents:
29958
diff
changeset
|
246 idx_vector i = args(0).index_vector (); |
32058
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
247 argidx = 1; |
29961
7d6709900da7
eliminate octave:: namespace tags in DEFUN and DEFMETHOD and more
John W. Eaton <jwe@octave.org>
parents:
29958
diff
changeset
|
248 idx_vector j = args(1).index_vector (); |
5164 | 249 |
32058
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
250 octave_value arg = args(2); // temp var for code readability |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
251 if (arg.isfloat ()) |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
252 { |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
253 if (arg.is_single_type ()) |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
254 warning_with_id ("Octave:sparse:double-conversion", |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
255 "sparse: input array cast to double"); |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
256 if (arg.iscomplex ()) |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
257 retval = SparseComplexMatrix (arg.complex_array_value (), |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
258 i, j, m, n, summation, nzmax); |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
259 else |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
260 retval = SparseMatrix (arg.array_value (), |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
261 i, j, m, n, summation, nzmax); |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
262 } |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
263 else if (arg.islogical ()) |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
264 retval = SparseBoolMatrix (arg.bool_array_value (), |
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
265 i, j, m, n, summation, nzmax); |
20555
f90c8372b7ba
eliminate many more simple uses of error_state
John W. Eaton <jwe@octave.org>
parents:
20542
diff
changeset
|
266 else |
32058
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
267 err_wrong_type_arg ("sparse", arg); |
20555
f90c8372b7ba
eliminate many more simple uses of error_state
John W. Eaton <jwe@octave.org>
parents:
20542
diff
changeset
|
268 } |
29961
7d6709900da7
eliminate octave:: namespace tags in DEFUN and DEFMETHOD and more
John W. Eaton <jwe@octave.org>
parents:
29958
diff
changeset
|
269 catch (index_exception& ie) |
20555
f90c8372b7ba
eliminate many more simple uses of error_state
John W. Eaton <jwe@octave.org>
parents:
20542
diff
changeset
|
270 { |
f90c8372b7ba
eliminate many more simple uses of error_state
John W. Eaton <jwe@octave.org>
parents:
20542
diff
changeset
|
271 // Rethrow to allow more info to be reported later. |
32058
e242124f1240
Overhaul input validation of sparse() function.
Rik <rik@octave.org>
parents:
31972
diff
changeset
|
272 ie.set_pos_if_unset (2, argidx+1); |
20555
f90c8372b7ba
eliminate many more simple uses of error_state
John W. Eaton <jwe@octave.org>
parents:
20542
diff
changeset
|
273 throw; |
17787
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
274 } |
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
275 } |
5164 | 276 |
17787
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
277 return retval; |
5164 | 278 } |
10513
c5005bc2b7a9
implement working spalloc
Jaroslav Hajek <highegg@gmail.com>
parents:
10479
diff
changeset
|
279 |
26213
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
280 /* |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
281 ## Tests for sparse constructor are in test/sparse.tst |
28907
11f1207111c5
maint: Don't use semicolon at end of single-line BIST tests.
Rik <rik@octave.org>
parents:
28888
diff
changeset
|
282 %!assert (1) |
26213
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
283 */ |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
284 |
11097
ffb2f1ef2097
make issparse, sparse, and spalloc built-in functions
John W. Eaton <jwe@octave.org>
parents:
10846
diff
changeset
|
285 DEFUN (spalloc, args, , |
21966
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
286 doc: /* -*- texinfo -*- |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
287 @deftypefn {} {@var{s} =} spalloc (@var{m}, @var{n}, @var{nz}) |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
288 Create an @var{m}-by-@var{n} sparse matrix with pre-allocated space for at |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
289 most @var{nz} nonzero elements. |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
290 |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
291 This is useful for building a matrix incrementally by a sequence of indexed |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
292 assignments. Subsequent indexed assignments after @code{spalloc} will reuse |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
293 the pre-allocated memory, provided they are of one of the simple forms |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
294 |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
295 @itemize |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
296 @item @code{@var{s}(I:J) = @var{x}} |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
297 |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
298 @item @code{@var{s}(:,I:J) = @var{x}} |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
299 |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
300 @item @code{@var{s}(K:L,I:J) = @var{x}} |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
301 @end itemize |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
302 |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
303 @b{and} that the following conditions are met: |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
304 |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
305 @itemize |
27081
c0d8ce61c1c9
Always reserve at least 1 element of storage for sparse matrices (bug #56232).
Rik <rik@octave.org>
parents:
26600
diff
changeset
|
306 @item the assignment does not decrease @code{nnz (@var{S})}. |
21966
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
307 |
27081
c0d8ce61c1c9
Always reserve at least 1 element of storage for sparse matrices (bug #56232).
Rik <rik@octave.org>
parents:
26600
diff
changeset
|
308 @item after the assignment, @code{nnz (@var{S})} does not exceed @var{nz}. |
21966
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
309 |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
310 @item no index is out of bounds. |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
311 @end itemize |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
312 |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
313 Partial movement of data may still occur, but in general the assignment will |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
314 be more memory and time efficient under these circumstances. In particular, |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
315 it is possible to efficiently build a pre-allocated sparse matrix from a |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
316 contiguous block of columns. |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
317 |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
318 The amount of pre-allocated memory for a given matrix may be queried using |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
319 the function @code{nzmax}. |
27081
c0d8ce61c1c9
Always reserve at least 1 element of storage for sparse matrices (bug #56232).
Rik <rik@octave.org>
parents:
26600
diff
changeset
|
320 |
c0d8ce61c1c9
Always reserve at least 1 element of storage for sparse matrices (bug #56232).
Rik <rik@octave.org>
parents:
26600
diff
changeset
|
321 Programming Note: Octave always reserves memory for at least one value, |
c0d8ce61c1c9
Always reserve at least 1 element of storage for sparse matrices (bug #56232).
Rik <rik@octave.org>
parents:
26600
diff
changeset
|
322 even if @var{nz} is 0. |
21966
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
323 @seealso{nzmax, sparse} |
112b20240c87
move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents:
21743
diff
changeset
|
324 @end deftypefn */) |
10513
c5005bc2b7a9
implement working spalloc
Jaroslav Hajek <highegg@gmail.com>
parents:
10479
diff
changeset
|
325 { |
17787
175b392e91fe
Use GNU style coding conventions for code in libinterp/
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
326 int nargin = args.length (); |
10513
c5005bc2b7a9
implement working spalloc
Jaroslav Hajek <highegg@gmail.com>
parents:
10479
diff
changeset
|
327 |
20803
c22206c1a88f
eliminate return statements after calls to print_usage
John W. Eaton <jwe@octave.org>
parents:
20667
diff
changeset
|
328 if (nargin < 2 || nargin > 3) |
c22206c1a88f
eliminate return statements after calls to print_usage
John W. Eaton <jwe@octave.org>
parents:
20667
diff
changeset
|
329 print_usage (); |
c22206c1a88f
eliminate return statements after calls to print_usage
John W. Eaton <jwe@octave.org>
parents:
20667
diff
changeset
|
330 |
c22206c1a88f
eliminate return statements after calls to print_usage
John W. Eaton <jwe@octave.org>
parents:
20667
diff
changeset
|
331 octave_idx_type m = args(0).idx_type_value (); |
c22206c1a88f
eliminate return statements after calls to print_usage
John W. Eaton <jwe@octave.org>
parents:
20667
diff
changeset
|
332 octave_idx_type n = args(1).idx_type_value (); |
20939
b17fda023ca6
maint: Use new C++ archetype in more files.
Rik <rik@octave.org>
parents:
20853
diff
changeset
|
333 |
20803
c22206c1a88f
eliminate return statements after calls to print_usage
John W. Eaton <jwe@octave.org>
parents:
20667
diff
changeset
|
334 octave_idx_type nz = 0; |
c22206c1a88f
eliminate return statements after calls to print_usage
John W. Eaton <jwe@octave.org>
parents:
20667
diff
changeset
|
335 if (nargin == 3) |
c22206c1a88f
eliminate return statements after calls to print_usage
John W. Eaton <jwe@octave.org>
parents:
20667
diff
changeset
|
336 nz = args(2).idx_type_value (); |
20555
f90c8372b7ba
eliminate many more simple uses of error_state
John W. Eaton <jwe@octave.org>
parents:
20542
diff
changeset
|
337 |
26213
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
338 if (m < 0 || n < 0 || nz < 0) |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
339 error ("spalloc: M, N, and NZ must be non-negative"); |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
340 |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
341 return ovl (SparseMatrix (dim_vector (m, n), nz)); |
10513
c5005bc2b7a9
implement working spalloc
Jaroslav Hajek <highegg@gmail.com>
parents:
10479
diff
changeset
|
342 } |
26213
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
343 |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
344 /* |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
345 %!assert (issparse (spalloc (1,1))) |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
346 %!assert (spalloc (1,1), sparse (1,1)) |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
347 %!test |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
348 %! s = spalloc (1,1,5); |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
349 %! assert (s, sparse (1,1)); |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
350 %! assert (nzmax (s), 5); |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
351 %!assert (spalloc (1,2), sparse (1,2)) |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
352 %!assert (spalloc (1,2,2), sparse (1,2)) |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
353 %!assert (spalloc (2,1), sparse (2,1)) |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
354 %!assert (spalloc (2,1,2), sparse (2,1)) |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
355 |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
356 %!error spalloc () |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
357 %!error spalloc (1) |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
358 %!error spalloc (1,2,3,4) |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
359 %!error <M, N, and NZ must be non-negative> spalloc (-1, 1, 1) |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
360 %!error <M, N, and NZ must be non-negative> spalloc (1, -1, 1) |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
361 %!error <M, N, and NZ must be non-negative> spalloc (1, 1, -1) |
ff0eadb417ec
Add BIST tests to sparse.cc (patch #9011).
Rik <rik@octave.org>
parents:
25646
diff
changeset
|
362 */ |
29958
32c3a5805893
move DEFUN and DEFMETHOD functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents:
29569
diff
changeset
|
363 |
31605
e88a07dec498
maint: Use macros to begin/end C++ namespaces.
Rik <rik@octave.org>
parents:
30801
diff
changeset
|
364 OCTAVE_END_NAMESPACE(octave) |