Mercurial > octave

annotate libinterp/corefcn/sub2ind.cc @ 30564:796f54d4ddbf stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
update Octave Project Developers copyright for the new year In files that have the "Octave Project Developers" copyright notice, update for 2021. In all .txi and .texi files except gpl.txi and gpl.texi in the doc/liboctave and doc/interpreter directories, change the copyright to "Octave Project Developers", the same as used for other source files. Update copyright notices for 2022 (not done since 2019). For gpl.txi and gpl.texi, change the copyright notice to be "Free Software Foundation, Inc." and leave the date at 2007 only because this file only contains the text of the GPL, not anything created by the Octave Project Developers. Add Paul Thomas to contributors.in.
author John W. Eaton <jwe@octave.org>
date Tue, 28 Dec 2021 18:22:40 -0500
parents 7d6709900da7
children a8d61c30f41a
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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 //
30564
796f54d4ddbf update Octave Project Developers copyright for the new year
John W. Eaton <jwe@octave.org>
parents: 29961
diff changeset
3 // Copyright (C) 2009-2022 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 ////////////////////////////////////////////////////////////////////////
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
25
21724
aba2e6293dd8 use "#if ..." consistently instead of "#ifdef" and "#ifndef"
John W. Eaton <jwe@octave.org>
parents: 21660
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"
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
28 #endif
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
29
19269
65554f5847ac don't include oct-locbuf.h in header files unnecessarily
John W. Eaton <jwe@octave.org>
parents: 17787
diff changeset
30 #include "Array-util.h"
65554f5847ac don't include oct-locbuf.h in header files unnecessarily
John W. Eaton <jwe@octave.org>
parents: 17787
diff changeset
31 #include "oct-locbuf.h"
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
32 #include "quit.h"
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
33
15039
e753177cde93 maint: Move non-dynamically linked functions from DLD-FUNCTIONS/ to corefcn/ directory
Rik <rik@octave.org>
parents: 14501
diff changeset
34 #include "defun.h"
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
35 #include "error.h"
21100
e39e05d90788 Switch gripe_XXX to either err_XXX or warn_XXX naming scheme.
Rik <rik@octave.org>
parents: 21055
diff changeset
36 #include "errwarn.h"
20940
48b2ad5ee801 maint: Rename oct-obj.[cc|h] to ovl.[cc|h] for clarity.
Rik <rik@octave.org>
parents: 20939
diff changeset
37 #include "ovl.h"
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
38
29958
32c3a5805893 move DEFUN and DEFMETHOD functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29826
diff changeset
39 OCTAVE_NAMESPACE_BEGIN
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
40
11586
12df7854fa7c strip trailing whitespace from source files
John W. Eaton <jwe@octave.org>
parents: 11570
diff changeset
41 static dim_vector
10258
e317791645c4 64-bit fixes
John W. Eaton <jwe@octave.org>
parents: 9666
diff changeset
42 get_dim_vector (const octave_value& val, const char *name)
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
43 {
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
44 RowVector dimsv = val.row_vector_value (false, true);
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
45 dim_vector dv;
20232
a9574e3c6e9e Deprecate Array::length() and Sparse::length() in favour of ::numel().
Carnë Draug <carandraug@octave.org>
parents: 20172
diff changeset
46 octave_idx_type n = dimsv.numel ();
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
47
9666
a531dec450c4 allow 1D case for sub2ind and ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents: 9479
diff changeset
48 if (n < 1)
12483
7a5aacf65f81 Rewrite error strings in src/ to use variables named in documentation.
Rik <octave@nomad.inbox5.com>
parents: 11586
diff changeset
49 error ("%s: dimension vector DIMS must not be empty", name);
21055
5e00ed38a58b maint: Replace if/error/else paradigm with just if/error.
Rik <rik@octave.org>
parents: 20956
diff changeset
50
5e00ed38a58b maint: Replace if/error/else paradigm with just if/error.
Rik <rik@octave.org>
parents: 20956
diff changeset
51 dv.resize (std::max (n, static_cast<octave_idx_type> (2)));
5e00ed38a58b maint: Replace if/error/else paradigm with just if/error.
Rik <rik@octave.org>
parents: 20956
diff changeset
52 dv(1) = 1;
5e00ed38a58b maint: Replace if/error/else paradigm with just if/error.
Rik <rik@octave.org>
parents: 20956
diff changeset
53 for (octave_idx_type i = 0; i < n; i++)
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
54 {
21055
5e00ed38a58b maint: Replace if/error/else paradigm with just if/error.
Rik <rik@octave.org>
parents: 20956
diff changeset
55 octave_idx_type ii = dimsv(i);
5e00ed38a58b maint: Replace if/error/else paradigm with just if/error.
Rik <rik@octave.org>
parents: 20956
diff changeset
56 if (ii == dimsv(i) && ii >= 0)
5e00ed38a58b maint: Replace if/error/else paradigm with just if/error.
Rik <rik@octave.org>
parents: 20956
diff changeset
57 dv(i) = ii;
5e00ed38a58b maint: Replace if/error/else paradigm with just if/error.
Rik <rik@octave.org>
parents: 20956
diff changeset
58 else
5e00ed38a58b maint: Replace if/error/else paradigm with just if/error.
Rik <rik@octave.org>
parents: 20956
diff changeset
59 error ("%s: dimension vector DIMS must contain integers", name);
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
60 }
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
61
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
62 return dv;
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
63 }
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
64
15039
e753177cde93 maint: Move non-dynamically linked functions from DLD-FUNCTIONS/ to corefcn/ directory
Rik <rik@octave.org>
parents: 14501
diff changeset
65 DEFUN (sub2ind, args, ,
21966
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 21724
diff changeset
66 doc: /* -*- texinfo -*-
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 21724
diff changeset
67 @deftypefn {} {@var{ind} =} sub2ind (@var{dims}, @var{i}, @var{j})
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 21724
diff changeset
68 @deftypefnx {} {@var{ind} =} sub2ind (@var{dims}, @var{s1}, @var{s2}, @dots{}, @var{sN})
22086
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
69 Convert subscripts to linear indices.
21966
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 21724
diff changeset
70
22850
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
71 The input @var{dims} is a dimension vector where each element is the size of
28961
d9d028b479ac doc: Use @code{} within alternate text for @xref,@pxref macros in libinterp/
Rik <rik@octave.org>
parents: 28907
diff changeset
72 the array in the respective dimension (@pxref{XREFsize,,@code{size}}). The
d9d028b479ac doc: Use @code{} within alternate text for @xref,@pxref macros in libinterp/
Rik <rik@octave.org>
parents: 28907
diff changeset
73 remaining inputs are scalars or vectors of subscripts to be converted.
22850
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
74
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
75 The output vector @var{ind} contains the converted linear indices.
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
76
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
77 Background: Array elements can be specified either by a linear index which
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
78 starts at 1 and runs through the number of elements in the array, or they may
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
79 be specified with subscripts for the row, column, page, etc. The functions
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
80 @code{ind2sub} and @code{sub2ind} interconvert between the two forms.
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
81
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
82 The linear index traverses dimension 1 (rows), then dimension 2 (columns), then
23565
3a730821e4a2 doc: Peridoc grammarcheck of documentation.
Rik <rik@octave.org>
parents: 23220
diff changeset
83 dimension 3 (pages), etc.@: until it has numbered all of the elements.
3a730821e4a2 doc: Peridoc grammarcheck of documentation.
Rik <rik@octave.org>
parents: 23220
diff changeset
84 Consider the following 3-by-3 matrices:
21966
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 21724
diff changeset
85
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 21724
diff changeset
86 @example
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 21724
diff changeset
87 @group
22086
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
88 [(1,1), (1,2), (1,3)] [1, 4, 7]
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
89 [(2,1), (2,2), (2,3)] ==> [2, 5, 8]
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
90 [(3,1), (3,2), (3,3)] [3, 6, 9]
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
91 @end group
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
92 @end example
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
93
22850
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
94 @noindent
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
95 The left matrix contains the subscript tuples for each matrix element. The
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
96 right matrix shows the linear indices for the same matrix.
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
97
22086
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
98 The following example shows how to convert the two-dimensional indices
22850
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
99 @code{(2,1)} and @code{(2,3)} of a 3-by-3 matrix to linear indices with a
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
100 single call to @code{sub2ind}.
22086
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
101
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
102 @example
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
103 @group
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
104 s1 = [2, 2];
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
105 s2 = [1, 3];
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
106 ind = sub2ind ([3, 3], s1, s2)
22851
6eb581b597bc doc: Add missing change from cset 5e111d533c99
Rik <rik@octave.org>
parents: 22850
diff changeset
107 @result{} ind = 2 8
21966
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 21724
diff changeset
108 @end group
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 21724
diff changeset
109 @end example
22850
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
110 @seealso{ind2sub, size}
21966
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 21724
diff changeset
111 @end deftypefn */)
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
112 {
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
113 int nargin = args.length ();
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
114
9666
a531dec450c4 allow 1D case for sub2ind and ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents: 9479
diff changeset
115 if (nargin < 2)
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
116 print_usage ();
20801
a542a9bf177e eliminate return statements after calls to print_usage
John W. Eaton <jwe@octave.org>
parents: 20795
diff changeset
117
28004
403df0b32204 update out_of_range error messages
John W. Eaton <jwe@octave.org>
parents: 27923
diff changeset
118 dim_vector dv = get_dim_vector (args(0), "sub2ind");
403df0b32204 update out_of_range error messages
John W. Eaton <jwe@octave.org>
parents: 27923
diff changeset
119
29961
7d6709900da7 eliminate octave:: namespace tags in DEFUN and DEFMETHOD and more
John W. Eaton <jwe@octave.org>
parents: 29958
diff changeset
120 Array<idx_vector> idxa (dim_vector (nargin-1, 1));
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
121
20801
a542a9bf177e eliminate return statements after calls to print_usage
John W. Eaton <jwe@octave.org>
parents: 20795
diff changeset
122 for (int j = 0; j < nargin - 1; j++)
a542a9bf177e eliminate return statements after calls to print_usage
John W. Eaton <jwe@octave.org>
parents: 20795
diff changeset
123 {
23586
f6c5db0a02e7 maint: Deprecate is_numeric_type and replace with isnumeric.
Rik <rik@octave.org>
parents: 23565
diff changeset
124 if (! args(j+1).isnumeric ())
20939
b17fda023ca6 maint: Use new C++ archetype in more files.
Rik <rik@octave.org>
parents: 20853
diff changeset
125 error ("sub2ind: subscripts must be numeric");
b17fda023ca6 maint: Use new C++ archetype in more files.
Rik <rik@octave.org>
parents: 20853
diff changeset
126
b17fda023ca6 maint: Use new C++ archetype in more files.
Rik <rik@octave.org>
parents: 20853
diff changeset
127 try
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
128 {
20939
b17fda023ca6 maint: Use new C++ archetype in more files.
Rik <rik@octave.org>
parents: 20853
diff changeset
129 idxa(j) = args(j+1).index_vector ();
20555
f90c8372b7ba eliminate many more simple uses of error_state
John W. Eaton <jwe@octave.org>
parents: 20542
diff changeset
130
20939
b17fda023ca6 maint: Use new C++ archetype in more files.
Rik <rik@octave.org>
parents: 20853
diff changeset
131 if (j > 0 && args(j+1).dims () != args(1).dims ())
b17fda023ca6 maint: Use new C++ archetype in more files.
Rik <rik@octave.org>
parents: 20853
diff changeset
132 error ("sub2ind: all subscripts must be of the same size");
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
133 }
29961
7d6709900da7 eliminate octave:: namespace tags in DEFUN and DEFMETHOD and more
John W. Eaton <jwe@octave.org>
parents: 29958
diff changeset
134 catch (index_exception& ie)
20939
b17fda023ca6 maint: Use new C++ archetype in more files.
Rik <rik@octave.org>
parents: 20853
diff changeset
135 {
29163
8f67ad8b3103 maint: Updating naming conventions for exceptions and use const where possible.
Rik <rik@octave.org>
parents: 28961
diff changeset
136 ie.set_pos_if_unset (nargin-1, j+1);
8f67ad8b3103 maint: Updating naming conventions for exceptions and use const where possible.
Rik <rik@octave.org>
parents: 28961
diff changeset
137 ie.set_var ();
8f67ad8b3103 maint: Updating naming conventions for exceptions and use const where possible.
Rik <rik@octave.org>
parents: 28961
diff changeset
138 std::string msg = ie.message ();
8f67ad8b3103 maint: Updating naming conventions for exceptions and use const where possible.
Rik <rik@octave.org>
parents: 28961
diff changeset
139 error_with_id (ie.err_id (), "%s", msg.c_str ());
20939
b17fda023ca6 maint: Use new C++ archetype in more files.
Rik <rik@octave.org>
parents: 20853
diff changeset
140 }
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
141 }
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
142
20939
b17fda023ca6 maint: Use new C++ archetype in more files.
Rik <rik@octave.org>
parents: 20853
diff changeset
143 return ovl (sub2ind (dv, idxa));
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
144 }
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
145
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
146 /*
14501
60e5cf354d80 Update %!tests in DLD-FUNCTIONS/ directory with Octave coding conventions.
Rik <octave@nomad.inbox5.com>
parents: 14360
diff changeset
147 ## Test evaluation
60e5cf354d80 Update %!tests in DLD-FUNCTIONS/ directory with Octave coding conventions.
Rik <octave@nomad.inbox5.com>
parents: 14360
diff changeset
148 %!test
60e5cf354d80 Update %!tests in DLD-FUNCTIONS/ directory with Octave coding conventions.
Rik <octave@nomad.inbox5.com>
parents: 14360
diff changeset
149 %! s1 = [ 1 1 1 1 ; 2 2 2 2 ];
60e5cf354d80 Update %!tests in DLD-FUNCTIONS/ directory with Octave coding conventions.
Rik <octave@nomad.inbox5.com>
parents: 14360
diff changeset
150 %! s2 = [ 1 1 2 2 ; 1 1 2 2 ];
60e5cf354d80 Update %!tests in DLD-FUNCTIONS/ directory with Octave coding conventions.
Rik <octave@nomad.inbox5.com>
parents: 14360
diff changeset
151 %! s3 = [ 1 2 1 2 ; 1 2 1 2 ];
60e5cf354d80 Update %!tests in DLD-FUNCTIONS/ directory with Octave coding conventions.
Rik <octave@nomad.inbox5.com>
parents: 14360
diff changeset
152 %! in = [ 1 101 11 111 ; 2 102 12 112 ];
60e5cf354d80 Update %!tests in DLD-FUNCTIONS/ directory with Octave coding conventions.
Rik <octave@nomad.inbox5.com>
parents: 14360
diff changeset
153 %! assert (sub2ind ([10 10 10], s1, s2, s3), in);
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
154
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
155 # Test low index
14501
60e5cf354d80 Update %!tests in DLD-FUNCTIONS/ directory with Octave coding conventions.
Rik <octave@nomad.inbox5.com>
parents: 14360
diff changeset
156 %!assert (sub2ind ([10 10 10], 1, 1, 1), 1)
20542
dd6345fd8a97 use exceptions for better invalid index error reporting (bug #45957)
Lachlan Andrew <lachlanbis@gmail.com>
parents: 20232
diff changeset
157 %!error <index \(0,_,_\)> sub2ind ([10 10 10], 0, 1, 1)
dd6345fd8a97 use exceptions for better invalid index error reporting (bug #45957)
Lachlan Andrew <lachlanbis@gmail.com>
parents: 20232
diff changeset
158 %!error <index \(_,0,_\)> sub2ind ([10 10 10], 1, 0, 1)
dd6345fd8a97 use exceptions for better invalid index error reporting (bug #45957)
Lachlan Andrew <lachlanbis@gmail.com>
parents: 20232
diff changeset
159 %!error <index \(_,_,0\)> sub2ind ([10 10 10], 1, 1, 0)
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
160
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
161 # Test high index
14501
60e5cf354d80 Update %!tests in DLD-FUNCTIONS/ directory with Octave coding conventions.
Rik <octave@nomad.inbox5.com>
parents: 14360
diff changeset
162 %!assert (sub2ind ([10 10 10], 10, 10, 10), 1000)
20795
ba2367658dc8 Use ':' rather than ';' in error messages from bad indexing (bug #46536).
Rik <rik@octave.org>
parents: 20715
diff changeset
163 %!error <index \(11,_,_\): out of bound 10> sub2ind ([10 10 10], 11, 10, 10)
ba2367658dc8 Use ':' rather than ';' in error messages from bad indexing (bug #46536).
Rik <rik@octave.org>
parents: 20715
diff changeset
164 %!error <index \(_,11,_\): out of bound 10> sub2ind ([10 10 10], 10, 11, 10)
ba2367658dc8 Use ':' rather than ';' in error messages from bad indexing (bug #46536).
Rik <rik@octave.org>
parents: 20715
diff changeset
165 %!error <index \(_,_,11\): out of bound 10> sub2ind ([10 10 10], 10, 10, 11)
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
166
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
167 # Test high index in the trailing dimensions
14501
60e5cf354d80 Update %!tests in DLD-FUNCTIONS/ directory with Octave coding conventions.
Rik <octave@nomad.inbox5.com>
parents: 14360
diff changeset
168 %!assert (sub2ind ([10, 1], 2, 1, 1), 2)
20795
ba2367658dc8 Use ':' rather than ';' in error messages from bad indexing (bug #46536).
Rik <rik@octave.org>
parents: 20715
diff changeset
169 %!error <index \(_,2,_\): out of bound 1> sub2ind ([10, 1], 1, 2, 1)
ba2367658dc8 Use ':' rather than ';' in error messages from bad indexing (bug #46536).
Rik <rik@octave.org>
parents: 20715
diff changeset
170 %!error <index \(_,_,2\): out of bound 1> sub2ind ([10, 1], 1, 1, 2)
14501
60e5cf354d80 Update %!tests in DLD-FUNCTIONS/ directory with Octave coding conventions.
Rik <octave@nomad.inbox5.com>
parents: 14360
diff changeset
171 %!assert (sub2ind ([10 10], 2, 2, 1), 12)
20795
ba2367658dc8 Use ':' rather than ';' in error messages from bad indexing (bug #46536).
Rik <rik@octave.org>
parents: 20715
diff changeset
172 %!error <index \(_,_,2\): out of bound 1> sub2ind ([10 10], 2, 1, 2)
ba2367658dc8 Use ':' rather than ';' in error messages from bad indexing (bug #46536).
Rik <rik@octave.org>
parents: 20715
diff changeset
173 %!error <index \(_,_,2\): out of bound 1> sub2ind ([10 10], 1, 2, 2)
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
174
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
175 # Test handling of empty arguments
14501
60e5cf354d80 Update %!tests in DLD-FUNCTIONS/ directory with Octave coding conventions.
Rik <octave@nomad.inbox5.com>
parents: 14360
diff changeset
176 %!assert (sub2ind ([10 10], zeros (0,0), zeros (0,0)), zeros (0,0))
60e5cf354d80 Update %!tests in DLD-FUNCTIONS/ directory with Octave coding conventions.
Rik <octave@nomad.inbox5.com>
parents: 14360
diff changeset
177 %!assert (sub2ind ([10 10], zeros (2,0), zeros (2,0)), zeros (2,0))
60e5cf354d80 Update %!tests in DLD-FUNCTIONS/ directory with Octave coding conventions.
Rik <octave@nomad.inbox5.com>
parents: 14360
diff changeset
178 %!assert (sub2ind ([10 10], zeros (0,2), zeros (0,2)), zeros (0,2))
60e5cf354d80 Update %!tests in DLD-FUNCTIONS/ directory with Octave coding conventions.
Rik <octave@nomad.inbox5.com>
parents: 14360
diff changeset
179 %!error <all subscripts .* same size> sub2ind ([10 10 10], zeros (0,2), zeros (2,0))
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
180
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
181 # Test handling of arguments of different size
14501
60e5cf354d80 Update %!tests in DLD-FUNCTIONS/ directory with Octave coding conventions.
Rik <octave@nomad.inbox5.com>
parents: 14360
diff changeset
182 %!error <all subscripts .* same size> sub2ind ([10 10], ones (1,2), ones (1,3))
60e5cf354d80 Update %!tests in DLD-FUNCTIONS/ directory with Octave coding conventions.
Rik <octave@nomad.inbox5.com>
parents: 14360
diff changeset
183 %!error <all subscripts .* same size> sub2ind ([10 10], ones (1,2), ones (2,1))
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
184
14501
60e5cf354d80 Update %!tests in DLD-FUNCTIONS/ directory with Octave coding conventions.
Rik <octave@nomad.inbox5.com>
parents: 14360
diff changeset
185 ## Test input validation
60e5cf354d80 Update %!tests in DLD-FUNCTIONS/ directory with Octave coding conventions.
Rik <octave@nomad.inbox5.com>
parents: 14360
diff changeset
186 %!error <dimension vector> sub2ind ([10 10.5], 1, 1)
20542
dd6345fd8a97 use exceptions for better invalid index error reporting (bug #45957)
Lachlan Andrew <lachlanbis@gmail.com>
parents: 20232
diff changeset
187 %!error <index \(1.5,_\)> sub2ind ([10 10], 1.5, 1)
dd6345fd8a97 use exceptions for better invalid index error reporting (bug #45957)
Lachlan Andrew <lachlanbis@gmail.com>
parents: 20232
diff changeset
188 %!error <index \(_,1.5\)> sub2ind ([10 10], 1, 1.5)
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
189 */
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
190
15039
e753177cde93 maint: Move non-dynamically linked functions from DLD-FUNCTIONS/ to corefcn/ directory
Rik <rik@octave.org>
parents: 14501
diff changeset
191 DEFUN (ind2sub, args, nargout,
21966
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 21724
diff changeset
192 doc: /* -*- texinfo -*-
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 21724
diff changeset
193 @deftypefn {} {[@var{s1}, @var{s2}, @dots{}, @var{sN}] =} ind2sub (@var{dims}, @var{ind})
22086
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
194 Convert linear indices to subscripts.
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
195
22850
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
196 The input @var{dims} is a dimension vector where each element is the size of
28961
d9d028b479ac doc: Use @code{} within alternate text for @xref,@pxref macros in libinterp/
Rik <rik@octave.org>
parents: 28907
diff changeset
197 the array in the respective dimension (@pxref{XREFsize,,@code{size}}). The
d9d028b479ac doc: Use @code{} within alternate text for @xref,@pxref macros in libinterp/
Rik <rik@octave.org>
parents: 28907
diff changeset
198 second input @var{ind} contains linear indies to be converted.
22850
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
199
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
200 The outputs @var{s1}, @dots{}, @var{sN} contain the converted subscripts.
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
201
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
202 Background: Array elements can be specified either by a linear index which
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
203 starts at 1 and runs through the number of elements in the array, or they may
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
204 be specified with subscripts for the row, column, page, etc. The functions
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
205 @code{ind2sub} and @code{sub2ind} interconvert between the two forms.
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
206
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
207 The linear index traverses dimension 1 (rows), then dimension 2 (columns), then
23565
3a730821e4a2 doc: Peridoc grammarcheck of documentation.
Rik <rik@octave.org>
parents: 23220
diff changeset
208 dimension 3 (pages), etc.@: until it has numbered all of the elements.
3a730821e4a2 doc: Peridoc grammarcheck of documentation.
Rik <rik@octave.org>
parents: 23220
diff changeset
209 Consider the following 3-by-3 matrices:
21966
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 21724
diff changeset
210
22086
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
211 @example
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
212 @group
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
213 [1, 4, 7] [(1,1), (1,2), (1,3)]
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
214 [2, 5, 8] ==> [(2,1), (2,2), (2,3)]
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
215 [3, 6, 9] [(3,1), (3,2), (3,3)]
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
216 @end group
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
217 @end example
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
218
22850
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
219 @noindent
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
220 The left matrix contains the linear indices for each matrix element. The right
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
221 matrix shows the subscript tuples for the same matrix.
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
222
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
223 The following example shows how to convert the two-dimensional indices
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
224 @code{(2,1)} and @code{(2,3)} of a 3-by-3 matrix to linear indices with a
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
225 single call to @code{sub2ind}.
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
226
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
227 The following example shows how to convert the linear indices @code{2} and
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
228 @code{8} in a 3-by-3 matrix into subscripts.
21966
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 21724
diff changeset
229
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 21724
diff changeset
230 @example
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 21724
diff changeset
231 @group
22086
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
232 ind = [2, 8];
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
233 [r, c] = ind2sub ([3, 3], ind)
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
234 @result{} r = 2 2
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
235 @result{} c = 1 3
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
236 @end group
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
237 @end example
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
238
22850
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
239 If the number of output subscripts exceeds the number of dimensions, the
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
240 exceeded dimensions are set to @code{1}. On the other hand, if fewer
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
241 subscripts than dimensions are provided, the exceeding dimensions are merged
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
242 into the final requested dimension. For clarity, consider the following
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
243 examples:
22086
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
244
23200
895b8edb4f3c doc: Fix build of docs broken in sub2ind (bug #50348).
Ernst Reissner <rei3ner@arcor.de>
parents: 23083
diff changeset
245 @example
22086
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
246 @group
22850
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
247 ind = [2, 8];
22086
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
248 dims = [3, 3];
22850
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
249 ## same as dims = [3, 3, 1]
22086
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
250 [r, c, s] = ind2sub (dims, ind)
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
251 @result{} r = 2 2
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
252 @result{} c = 1 3
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
253 @result{} s = 1 1
22850
5e111d533c99 doc: Rewrite docstrings for sub2ind and ind2sub.
Rik <rik@octave.org>
parents: 22407
diff changeset
254 ## same as dims = [9]
22086
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
255 r = ind2sub (dims, ind)
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
256 @result{} r = 2 8
21966
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 21724
diff changeset
257 @end group
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 21724
diff changeset
258 @end example
29824
6e42c37fbc8a ind2sub: Fix typo in "see also" section of docstring (bug #60842).
Markus Mützel <markus.muetzel@gmx.de>
parents: 29358
diff changeset
259 @seealso{sub2ind, size}
21966
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 21724
diff changeset
260 @end deftypefn */)
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
261 {
20819
f428cbe7576f eliminate unnecessary uses of nargin
John W. Eaton <jwe@octave.org>
parents: 20801
diff changeset
262 if (args.length () != 2)
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
263 print_usage ();
20801
a542a9bf177e eliminate return statements after calls to print_usage
John W. Eaton <jwe@octave.org>
parents: 20795
diff changeset
264
20939
b17fda023ca6 maint: Use new C++ archetype in more files.
Rik <rik@octave.org>
parents: 20853
diff changeset
265 octave_value_list retval;
b17fda023ca6 maint: Use new C++ archetype in more files.
Rik <rik@octave.org>
parents: 20853
diff changeset
266
22086
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
267 // Redimension to provided number of subscripts.
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
268 dim_vector dv = get_dim_vector (args(0), "ind2sub").redim (nargout);
20555
f90c8372b7ba eliminate many more simple uses of error_state
John W. Eaton <jwe@octave.org>
parents: 20542
diff changeset
269
20801
a542a9bf177e eliminate return statements after calls to print_usage
John W. Eaton <jwe@octave.org>
parents: 20795
diff changeset
270 try
a542a9bf177e eliminate return statements after calls to print_usage
John W. Eaton <jwe@octave.org>
parents: 20795
diff changeset
271 {
22086
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
272 retval = Array<octave_value> (ind2sub (dv, args(1).index_vector ()));
20801
a542a9bf177e eliminate return statements after calls to print_usage
John W. Eaton <jwe@octave.org>
parents: 20795
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 (const index_exception& ie)
20801
a542a9bf177e eliminate return statements after calls to print_usage
John W. Eaton <jwe@octave.org>
parents: 20795
diff changeset
275 {
29163
8f67ad8b3103 maint: Updating naming conventions for exceptions and use const where possible.
Rik <rik@octave.org>
parents: 28961
diff changeset
276 error ("ind2sub: invalid index %s", ie.what ());
9479
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
277 }
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
278
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
279 return retval;
d9716e3ee0dd supply optimized compiled sub2ind & ind2sub
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
280 }
22086
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
281
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
282 /*
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
283 ## Examples
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
284 %!test
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
285 %! [r, c] = ind2sub ([3, 3], [2, 8]);
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
286 %! assert (r, [2, 2]);
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
287 %! assert (c, [1, 3]);
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
288
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
289 %!test
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
290 %! [r, c, s] = ind2sub ([3, 3], [2, 8]);
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
291 %! assert (r, [2, 2]);
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
292 %! assert (c, [1, 3]);
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
293 %! assert (s, [1, 1]);
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
294 %! [r, c, s] = ind2sub ([3, 3, 1], [2, 8]);
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
295 %! assert (r, [2, 2]);
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
296 %! assert (c, [1, 3]);
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
297 %! assert (s, [1, 1]);
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
298
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
299 %!test
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
300 %! r = ind2sub ([3, 3], [2, 8]);
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
301 %! assert (r, [2, 8]);
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
302 %! r = ind2sub (9, [2, 8]);
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
303 %! assert (r, [2, 8]);
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
304
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
305 ## 3-dimensional test
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
306 %!test
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
307 %! [r, c, s] = ind2sub ([2, 2, 2], 1:8);
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
308 %! assert (r, [1, 2, 1, 2, 1, 2, 1, 2]);
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
309 %! assert (c, [1, 1, 2, 2, 1, 1, 2, 2]);
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
310 %! assert (s, [1, 1, 1, 1, 2, 2, 2, 2]);
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
311 %! [r, c] = ind2sub ([2, 2, 2], 1:8);
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
312 %! assert (r, [1, 2, 1, 2, 1, 2, 1, 2]);
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
313 %! assert (c, [1, 1, 2, 2, 3, 3, 4, 4]);
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
314 %! r = ind2sub ([2, 2, 2], 1:8);
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
315 %! assert (r, 1:8);
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
316
28907
11f1207111c5 maint: Don't use semicolon at end of single-line BIST tests.
Rik <rik@octave.org>
parents: 28012
diff changeset
317 %!error <DIMS must contain integers> ind2sub ([2, -2], 3)
11f1207111c5 maint: Don't use semicolon at end of single-line BIST tests.
Rik <rik@octave.org>
parents: 28012
diff changeset
318 %!error <index out of range> ind2sub ([2, 2, 2], 1:9)
11f1207111c5 maint: Don't use semicolon at end of single-line BIST tests.
Rik <rik@octave.org>
parents: 28012
diff changeset
319 %!error <invalid index> ind2sub ([2, 2, 2], -1:8)
22086
67a44207da71 ind2sub: Ensure Matlab compatibility and improve documentation (bug #48092).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 21966
diff changeset
320 */
29958
32c3a5805893 move DEFUN and DEFMETHOD functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29826
diff changeset
321
32c3a5805893 move DEFUN and DEFMETHOD functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29826
diff changeset
322 OCTAVE_NAMESPACE_END