octave: libinterp/corefcn/sparse.cc annotate

annotate libinterp/corefcn/sparse.cc @ 32058:e242124f1240

Overhaul input validation of sparse() function. * sparse.cc (Fsparse): Decode input type and identify floating point inputs. If input is of single type, emit new warning "Octave:sparse:double-conversion". If input is neither floating point or logical, then call err_wrong_type_arg() for pretty error message. Rename temporary variable 'k' to "argidx" for clarity. New temporary variable "arg" to increase readability of code. Add FIXME note about unreachable code due to behavior of get_dimensions(). * sparse.cc (Fissparse): Turn off warning about double-conversion temporarily for test which has single input. * warning_ids.m: Add description for new warning ID "Octave:sparse:double-conversion". * mk-sparse-tst.sh: Redo BIST tests for sparse() construction.

author	Rik <rik@octave.org>
date	Wed, 26 Apr 2023 10:09:09 -0700
parents	87beb2f167ea
children	bade9602c5a1

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 //
31706 597f3ee61a48 update Octave Project Developers copyright for the new year John W. Eaton <jwe@octave.org> parents: 31605 diff changeset	3 // Copyright (C) 1998-2023 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 57077d0ddc8e [project @ 2005-02-25 19:55:24 by jwe] jwe parents: diff changeset	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 57077d0ddc8e [project @ 2005-02-25 19:55:24 by jwe] jwe parents: diff changeset	28 #endif
57077d0ddc8e [project @ 2005-02-25 19:55:24 by jwe] jwe parents: diff changeset	29
57077d0ddc8e [project @ 2005-02-25 19:55:24 by jwe] jwe parents: diff changeset	30 #include <cstdlib>
57077d0ddc8e [project @ 2005-02-25 19:55:24 by jwe] jwe parents: diff changeset	31 #include <string>
57077d0ddc8e [project @ 2005-02-25 19:55:24 by jwe] jwe parents: diff changeset	32
57077d0ddc8e [project @ 2005-02-25 19:55:24 by jwe] jwe parents: diff changeset	33 #include "variables.h"
57077d0ddc8e [project @ 2005-02-25 19:55:24 by jwe] jwe parents: diff changeset	34 #include "utils.h"
57077d0ddc8e [project @ 2005-02-25 19:55:24 by jwe] jwe parents: diff changeset	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 57077d0ddc8e [project @ 2005-02-25 19:55:24 by jwe] jwe parents: diff changeset	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 57077d0ddc8e [project @ 2005-02-25 19:55:24 by jwe] jwe parents: diff changeset	40
57077d0ddc8e [project @ 2005-02-25 19:55:24 by jwe] jwe parents: diff changeset	41 #include "ov-re-sparse.h"
57077d0ddc8e [project @ 2005-02-25 19:55:24 by jwe] jwe parents: diff changeset	42 #include "ov-cx-sparse.h"
57077d0ddc8e [project @ 2005-02-25 19:55:24 by jwe] jwe parents: diff changeset	43 #include "ov-bool-sparse.h"
57077d0ddc8e [project @ 2005-02-25 19:55:24 by jwe] jwe parents: diff changeset	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 57077d0ddc8e [project @ 2005-02-25 19:55:24 by jwe] jwe parents: diff changeset	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 57077d0ddc8e [project @ 2005-02-25 19:55:24 by jwe] jwe parents: diff changeset	58 }
57077d0ddc8e [project @ 2005-02-25 19:55:24 by jwe] jwe parents: diff changeset	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 57077d0ddc8e [project @ 2005-02-25 19:55:24 by jwe] jwe parents: diff changeset	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 57077d0ddc8e [project @ 2005-02-25 19:55:24 by jwe] jwe parents: diff changeset	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 {
18454 0821a51a9e1b allow sparse arguments for dimensions in sparse function (bug #41535) John W. Eaton <jwe@octave.org> parents: 17787 diff changeset	202 octave_idx_type m = 0;
0821a51a9e1b allow sparse arguments for dimensions in sparse function (bug #41535) John W. Eaton <jwe@octave.org> parents: 17787 diff changeset	203 octave_idx_type n = 0;
0821a51a9e1b allow sparse arguments for dimensions in sparse function (bug #41535) John W. Eaton <jwe@octave.org> parents: 17787 diff changeset	204
29961 7d6709900da7 eliminate octave:: namespace tags in DEFUN and DEFMETHOD and more John W. Eaton <jwe@octave.org> parents: 29958 diff changeset	205 get_dimensions (args(0), args(1), "sparse", m, n);
10479 ded9beac7582 optimize sparse matrix assembly Jaroslav Hajek <highegg@gmail.com> parents: 10155 diff changeset	206
32058 e242124f1240 Overhaul input validation of sparse() function. Rik <rik@octave.org> parents: 31972 diff changeset	207 // FIXME: this code is never active because get_dimensions()
e242124f1240 Overhaul input validation of sparse() function. Rik <rik@octave.org> parents: 31972 diff changeset	208 // replaces negative dimensions with 0.
26213 ff0eadb417ec Add BIST tests to sparse.cc (patch #9011). Rik <rik@octave.org> parents: 25646 diff changeset	209 if (m < 0 \|\| n < 0)
20555 f90c8372b7ba eliminate many more simple uses of error_state John W. Eaton <jwe@octave.org> parents: 20542 diff changeset	210 error ("sparse: dimensions must be non-negative");
26213 ff0eadb417ec Add BIST tests to sparse.cc (patch #9011). Rik <rik@octave.org> parents: 25646 diff changeset	211
ff0eadb417ec Add BIST tests to sparse.cc (patch #9011). Rik <rik@octave.org> parents: 25646 diff changeset	212 retval = SparseMatrix (m, n);
17787 175b392e91fe Use GNU style coding conventions for code in libinterp/ Rik <rik@octave.org> parents: 17744 diff changeset	213 }
175b392e91fe Use GNU style coding conventions for code in libinterp/ Rik <rik@octave.org> parents: 17744 diff changeset	214 else if (nargin >= 3)
175b392e91fe Use GNU style coding conventions for code in libinterp/ Rik <rik@octave.org> parents: 17744 diff changeset	215 {
175b392e91fe Use GNU style coding conventions for code in libinterp/ Rik <rik@octave.org> parents: 17744 diff changeset	216 bool summation = true;
175b392e91fe Use GNU style coding conventions for code in libinterp/ Rik <rik@octave.org> parents: 17744 diff changeset	217 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	218 {
175b392e91fe Use GNU style coding conventions for code in libinterp/ Rik <rik@octave.org> parents: 17744 diff changeset	219 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	220 if (opt == "unique")
175b392e91fe Use GNU style coding conventions for code in libinterp/ Rik <rik@octave.org> parents: 17744 diff changeset	221 summation = false;
175b392e91fe Use GNU style coding conventions for code in libinterp/ Rik <rik@octave.org> parents: 17744 diff changeset	222 else if (opt == "sum" \|\| opt == "summation")
175b392e91fe Use GNU style coding conventions for code in libinterp/ Rik <rik@octave.org> parents: 17744 diff changeset	223 summation = true;
175b392e91fe Use GNU style coding conventions for code in libinterp/ Rik <rik@octave.org> parents: 17744 diff changeset	224 else
175b392e91fe Use GNU style coding conventions for code in libinterp/ Rik <rik@octave.org> parents: 17744 diff changeset	225 error ("sparse: invalid option: %s", opt.c_str ());
5164 57077d0ddc8e [project @ 2005-02-25 19:55:24 by jwe] jwe parents: diff changeset	226
17787 175b392e91fe Use GNU style coding conventions for code in libinterp/ Rik <rik@octave.org> parents: 17744 diff changeset	227 nargin -= 1;
175b392e91fe Use GNU style coding conventions for code in libinterp/ Rik <rik@octave.org> parents: 17744 diff changeset	228 }
5164 57077d0ddc8e [project @ 2005-02-25 19:55:24 by jwe] jwe parents: diff changeset	229
20555 f90c8372b7ba eliminate many more simple uses of error_state John W. Eaton <jwe@octave.org> parents: 20542 diff changeset	230 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	231 m = n = nzmax = -1;
f90c8372b7ba eliminate many more simple uses of error_state John W. Eaton <jwe@octave.org> parents: 20542 diff changeset	232 if (nargin == 6)
17787 175b392e91fe Use GNU style coding conventions for code in libinterp/ Rik <rik@octave.org> parents: 17744 diff changeset	233 {
20555 f90c8372b7ba eliminate many more simple uses of error_state John W. Eaton <jwe@octave.org> parents: 20542 diff changeset	234 nzmax = args(5).idx_type_value ();
21062 d9c1884d1aaa maint: Eliminate space between variable and decrement '--' operator. Rik <rik@octave.org> parents: 20939 diff changeset	235 nargin--;
20555 f90c8372b7ba eliminate many more simple uses of error_state John W. Eaton <jwe@octave.org> parents: 20542 diff changeset	236 }
10527 b4d2080b6df7 Replace nzmax by nnz as needed David Bateman <dbateman@free.fr> parents: 10521 diff changeset	237
20555 f90c8372b7ba eliminate many more simple uses of error_state John W. Eaton <jwe@octave.org> parents: 20542 diff changeset	238 if (nargin == 5)
f90c8372b7ba eliminate many more simple uses of error_state John W. Eaton <jwe@octave.org> parents: 20542 diff changeset	239 {
29961 7d6709900da7 eliminate octave:: namespace tags in DEFUN and DEFMETHOD and more John W. Eaton <jwe@octave.org> parents: 29958 diff changeset	240 get_dimensions (args(3), args(4), "sparse", m, n);
5164 57077d0ddc8e [project @ 2005-02-25 19:55:24 by jwe] jwe parents: diff changeset	241
32058 e242124f1240 Overhaul input validation of sparse() function. Rik <rik@octave.org> parents: 31972 diff changeset	242 // FIXME: this code is never active because get_dimensions()
e242124f1240 Overhaul input validation of sparse() function. Rik <rik@octave.org> parents: 31972 diff changeset	243 // replaces negative dimensions with 0.
20667 8742e0b1cc49 eliminate more uses of error_state John W. Eaton <jwe@octave.org> parents: 20555 diff changeset	244 if (m < 0 \|\| n < 0)
20555 f90c8372b7ba eliminate many more simple uses of error_state John W. Eaton <jwe@octave.org> parents: 20542 diff changeset	245 error ("sparse: dimensions must be non-negative");
f90c8372b7ba eliminate many more simple uses of error_state John W. Eaton <jwe@octave.org> parents: 20542 diff changeset	246 }
10479 ded9beac7582 optimize sparse matrix assembly Jaroslav Hajek <highegg@gmail.com> parents: 10155 diff changeset	247
32058 e242124f1240 Overhaul input validation of sparse() function. Rik <rik@octave.org> parents: 31972 diff changeset	248 int argidx = 0; // index we're checking when index_vector throws
20555 f90c8372b7ba eliminate many more simple uses of error_state John W. Eaton <jwe@octave.org> parents: 20542 diff changeset	249 try
f90c8372b7ba eliminate many more simple uses of error_state John W. Eaton <jwe@octave.org> parents: 20542 diff changeset	250 {
29961 7d6709900da7 eliminate octave:: namespace tags in DEFUN and DEFMETHOD and more John W. Eaton <jwe@octave.org> parents: 29958 diff changeset	251 idx_vector i = args(0).index_vector ();
32058 e242124f1240 Overhaul input validation of sparse() function. Rik <rik@octave.org> parents: 31972 diff changeset	252 argidx = 1;
29961 7d6709900da7 eliminate octave:: namespace tags in DEFUN and DEFMETHOD and more John W. Eaton <jwe@octave.org> parents: 29958 diff changeset	253 idx_vector j = args(1).index_vector ();
5164 57077d0ddc8e [project @ 2005-02-25 19:55:24 by jwe] jwe parents: diff changeset	254
32058 e242124f1240 Overhaul input validation of sparse() function. Rik <rik@octave.org> parents: 31972 diff changeset	255 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	256 if (arg.isfloat ())
e242124f1240 Overhaul input validation of sparse() function. Rik <rik@octave.org> parents: 31972 diff changeset	257 {
e242124f1240 Overhaul input validation of sparse() function. Rik <rik@octave.org> parents: 31972 diff changeset	258 if (arg.is_single_type ())
e242124f1240 Overhaul input validation of sparse() function. Rik <rik@octave.org> parents: 31972 diff changeset	259 warning_with_id ("Octave:sparse:double-conversion",
e242124f1240 Overhaul input validation of sparse() function. Rik <rik@octave.org> parents: 31972 diff changeset	260 "sparse: input array cast to double");
e242124f1240 Overhaul input validation of sparse() function. Rik <rik@octave.org> parents: 31972 diff changeset	261 if (arg.iscomplex ())
e242124f1240 Overhaul input validation of sparse() function. Rik <rik@octave.org> parents: 31972 diff changeset	262 retval = SparseComplexMatrix (arg.complex_array_value (),
e242124f1240 Overhaul input validation of sparse() function. Rik <rik@octave.org> parents: 31972 diff changeset	263 i, j, m, n, summation, nzmax);
e242124f1240 Overhaul input validation of sparse() function. Rik <rik@octave.org> parents: 31972 diff changeset	264 else
e242124f1240 Overhaul input validation of sparse() function. Rik <rik@octave.org> parents: 31972 diff changeset	265 retval = SparseMatrix (arg.array_value (),
e242124f1240 Overhaul input validation of sparse() function. Rik <rik@octave.org> parents: 31972 diff changeset	266 i, j, m, n, summation, nzmax);
e242124f1240 Overhaul input validation of sparse() function. Rik <rik@octave.org> parents: 31972 diff changeset	267 }
e242124f1240 Overhaul input validation of sparse() function. Rik <rik@octave.org> parents: 31972 diff changeset	268 else if (arg.islogical ())
e242124f1240 Overhaul input validation of sparse() function. Rik <rik@octave.org> parents: 31972 diff changeset	269 retval = SparseBoolMatrix (arg.bool_array_value (),
e242124f1240 Overhaul input validation of sparse() function. Rik <rik@octave.org> parents: 31972 diff changeset	270 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	271 else
32058 e242124f1240 Overhaul input validation of sparse() function. Rik <rik@octave.org> parents: 31972 diff changeset	272 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	273 }
29961 7d6709900da7 eliminate octave:: namespace tags in DEFUN and DEFMETHOD and more John W. Eaton <jwe@octave.org> parents: 29958 diff changeset	274 catch (index_exception& ie)
20555 f90c8372b7ba eliminate many more simple uses of error_state John W. Eaton <jwe@octave.org> parents: 20542 diff changeset	275 {
f90c8372b7ba eliminate many more simple uses of error_state John W. Eaton <jwe@octave.org> parents: 20542 diff changeset	276 // 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	277 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	278 throw;
17787 175b392e91fe Use GNU style coding conventions for code in libinterp/ Rik <rik@octave.org> parents: 17744 diff changeset	279 }
175b392e91fe Use GNU style coding conventions for code in libinterp/ Rik <rik@octave.org> parents: 17744 diff changeset	280 }
5164 57077d0ddc8e [project @ 2005-02-25 19:55:24 by jwe] jwe parents: diff changeset	281
17787 175b392e91fe Use GNU style coding conventions for code in libinterp/ Rik <rik@octave.org> parents: 17744 diff changeset	282 return retval;
5164 57077d0ddc8e [project @ 2005-02-25 19:55:24 by jwe] jwe parents: diff changeset	283 }
10513 c5005bc2b7a9 implement working spalloc Jaroslav Hajek <highegg@gmail.com> parents: 10479 diff changeset	284
26213 ff0eadb417ec Add BIST tests to sparse.cc (patch #9011). Rik <rik@octave.org> parents: 25646 diff changeset	285 /*
ff0eadb417ec Add BIST tests to sparse.cc (patch #9011). Rik <rik@octave.org> parents: 25646 diff changeset	286 ## 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	287 %!assert (1)
26213 ff0eadb417ec Add BIST tests to sparse.cc (patch #9011). Rik <rik@octave.org> parents: 25646 diff changeset	288 */
ff0eadb417ec Add BIST tests to sparse.cc (patch #9011). Rik <rik@octave.org> parents: 25646 diff changeset	289
11097 ffb2f1ef2097 make issparse, sparse, and spalloc built-in functions John W. Eaton <jwe@octave.org> parents: 10846 diff changeset	290 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	291 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	292 @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	293 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	294 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	295
112b20240c87 move docstrings in C++ files out of C strings and into comments John W. Eaton <jwe@octave.org> parents: 21743 diff changeset	296 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	297 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	298 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	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 @itemize
112b20240c87 move docstrings in C++ files out of C strings and into comments John W. Eaton <jwe@octave.org> parents: 21743 diff changeset	301 @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	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 @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	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 @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	306 @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	307
112b20240c87 move docstrings in C++ files out of C strings and into comments John W. Eaton <jwe@octave.org> parents: 21743 diff changeset	308 @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	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 @itemize
27081 c0d8ce61c1c9 Always reserve at least 1 element of storage for sparse matrices (bug #56232). Rik <rik@octave.org> parents: 26600 diff changeset	311 @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	312
27081 c0d8ce61c1c9 Always reserve at least 1 element of storage for sparse matrices (bug #56232). Rik <rik@octave.org> parents: 26600 diff changeset	313 @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	314
112b20240c87 move docstrings in C++ files out of C strings and into comments John W. Eaton <jwe@octave.org> parents: 21743 diff changeset	315 @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	316 @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	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 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	319 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	320 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	321 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	322
112b20240c87 move docstrings in C++ files out of C strings and into comments John W. Eaton <jwe@octave.org> parents: 21743 diff changeset	323 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	324 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	325
c0d8ce61c1c9 Always reserve at least 1 element of storage for sparse matrices (bug #56232). Rik <rik@octave.org> parents: 26600 diff changeset	326 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	327 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	328 @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	329 @end deftypefn */)
10513 c5005bc2b7a9 implement working spalloc Jaroslav Hajek <highegg@gmail.com> parents: 10479 diff changeset	330 {
17787 175b392e91fe Use GNU style coding conventions for code in libinterp/ Rik <rik@octave.org> parents: 17744 diff changeset	331 int nargin = args.length ();
10513 c5005bc2b7a9 implement working spalloc Jaroslav Hajek <highegg@gmail.com> parents: 10479 diff changeset	332
20803 c22206c1a88f eliminate return statements after calls to print_usage John W. Eaton <jwe@octave.org> parents: 20667 diff changeset	333 if (nargin < 2 \|\| nargin > 3)
c22206c1a88f eliminate return statements after calls to print_usage John W. Eaton <jwe@octave.org> parents: 20667 diff changeset	334 print_usage ();
c22206c1a88f eliminate return statements after calls to print_usage John W. Eaton <jwe@octave.org> parents: 20667 diff changeset	335
c22206c1a88f eliminate return statements after calls to print_usage John W. Eaton <jwe@octave.org> parents: 20667 diff changeset	336 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	337 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	338
20803 c22206c1a88f eliminate return statements after calls to print_usage John W. Eaton <jwe@octave.org> parents: 20667 diff changeset	339 octave_idx_type nz = 0;
c22206c1a88f eliminate return statements after calls to print_usage John W. Eaton <jwe@octave.org> parents: 20667 diff changeset	340 if (nargin == 3)
c22206c1a88f eliminate return statements after calls to print_usage John W. Eaton <jwe@octave.org> parents: 20667 diff changeset	341 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	342
26213 ff0eadb417ec Add BIST tests to sparse.cc (patch #9011). Rik <rik@octave.org> parents: 25646 diff changeset	343 if (m < 0 \|\| n < 0 \|\| nz < 0)
ff0eadb417ec Add BIST tests to sparse.cc (patch #9011). Rik <rik@octave.org> parents: 25646 diff changeset	344 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	345
ff0eadb417ec Add BIST tests to sparse.cc (patch #9011). Rik <rik@octave.org> parents: 25646 diff changeset	346 return ovl (SparseMatrix (dim_vector (m, n), nz));
10513 c5005bc2b7a9 implement working spalloc Jaroslav Hajek <highegg@gmail.com> parents: 10479 diff changeset	347 }
26213 ff0eadb417ec Add BIST tests to sparse.cc (patch #9011). Rik <rik@octave.org> parents: 25646 diff changeset	348
ff0eadb417ec Add BIST tests to sparse.cc (patch #9011). Rik <rik@octave.org> parents: 25646 diff changeset	349 /*
ff0eadb417ec Add BIST tests to sparse.cc (patch #9011). Rik <rik@octave.org> parents: 25646 diff changeset	350 %!assert (issparse (spalloc (1,1)))
ff0eadb417ec Add BIST tests to sparse.cc (patch #9011). Rik <rik@octave.org> parents: 25646 diff changeset	351 %!assert (spalloc (1,1), sparse (1,1))
ff0eadb417ec Add BIST tests to sparse.cc (patch #9011). Rik <rik@octave.org> parents: 25646 diff changeset	352 %!test
ff0eadb417ec Add BIST tests to sparse.cc (patch #9011). Rik <rik@octave.org> parents: 25646 diff changeset	353 %! s = spalloc (1,1,5);
ff0eadb417ec Add BIST tests to sparse.cc (patch #9011). Rik <rik@octave.org> parents: 25646 diff changeset	354 %! assert (s, sparse (1,1));
ff0eadb417ec Add BIST tests to sparse.cc (patch #9011). Rik <rik@octave.org> parents: 25646 diff changeset	355 %! assert (nzmax (s), 5);
ff0eadb417ec Add BIST tests to sparse.cc (patch #9011). Rik <rik@octave.org> parents: 25646 diff changeset	356 %!assert (spalloc (1,2), sparse (1,2))
ff0eadb417ec Add BIST tests to sparse.cc (patch #9011). Rik <rik@octave.org> parents: 25646 diff changeset	357 %!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	358 %!assert (spalloc (2,1), sparse (2,1))
ff0eadb417ec Add BIST tests to sparse.cc (patch #9011). Rik <rik@octave.org> parents: 25646 diff changeset	359 %!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	360
ff0eadb417ec Add BIST tests to sparse.cc (patch #9011). Rik <rik@octave.org> parents: 25646 diff changeset	361 %!error spalloc ()
ff0eadb417ec Add BIST tests to sparse.cc (patch #9011). Rik <rik@octave.org> parents: 25646 diff changeset	362 %!error spalloc (1)
ff0eadb417ec Add BIST tests to sparse.cc (patch #9011). Rik <rik@octave.org> parents: 25646 diff changeset	363 %!error spalloc (1,2,3,4)
ff0eadb417ec Add BIST tests to sparse.cc (patch #9011). Rik <rik@octave.org> parents: 25646 diff changeset	364 %!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	365 %!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	366 %!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	367 */
29958 32c3a5805893 move DEFUN and DEFMETHOD functions inside octave namespace John W. Eaton <jwe@octave.org> parents: 29569 diff changeset	368
31605 e88a07dec498 maint: Use macros to begin/end C++ namespaces. Rik <rik@octave.org> parents: 30801 diff changeset	369 OCTAVE_END_NAMESPACE(octave)

Mercurial > octave

annotate libinterp/corefcn/sparse.cc @ 32058:e242124f1240