Mercurial > hg > octave-lyh
annotate scripts/miscellaneous/orderfields.m @ 10793:be55736a0783
Grammarcheck the documentation from m-files.
author | Rik <octave@nomad.inbox5.com> |
---|---|
date | Sun, 18 Jul 2010 20:35:16 -0700 |
parents | 95c3e38098bf |
children | fd0a3ac60b0e |
rev | line source |
---|---|
8920 | 1 ## Copyright (C) 2006, 2007, 2009 Paul Kienzle |
5881 | 2 ## |
3 ## This file is part of Octave. | |
4 ## | |
5 ## Octave is free software; you can redistribute it and/or modify it | |
6 ## under the terms of the GNU General Public License as published by | |
7016 | 7 ## the Free Software Foundation; either version 3 of the License, or (at |
8 ## your option) any later version. | |
5881 | 9 ## |
10 ## Octave is distributed in the hope that it will be useful, but | |
11 ## WITHOUT ANY WARRANTY; without even the implied warranty of | |
12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
13 ## General Public License for more details. | |
14 ## | |
15 ## You should have received a copy of the GNU General Public License | |
7016 | 16 ## along with Octave; see the file COPYING. If not, see |
17 ## <http://www.gnu.org/licenses/>. | |
5881 | 18 |
19 ## -*- texinfo -*- | |
10122
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
20 ## @deftypefn {Function File} {[@var{t}, @var{p}] =} orderfields (@var{s1}[, @var{s2}]) |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
21 ## Return a copy of @var{s1} with fields arranged alphabetically or |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
22 ## as specified by @var{s2}. |
5881 | 23 ## |
24 ## Given one struct, arrange field names in @var{s1} alphabetically. | |
25 ## | |
10122
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
26 ## If the second argument is a struct, arrange field names in @var{s1} |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
27 ## as they appear in @var{s2}. The second argument may also specify the |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
28 ## order in a permutation vector or a cell array of strings containing |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
29 ## the fieldnames of @var{s1} in the desired order. |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
30 ## |
10793
be55736a0783
Grammarcheck the documentation from m-files.
Rik <octave@nomad.inbox5.com>
parents:
10549
diff
changeset
|
31 ## The optional second output argument @var{p} is assigned the permutation |
be55736a0783
Grammarcheck the documentation from m-files.
Rik <octave@nomad.inbox5.com>
parents:
10549
diff
changeset
|
32 ## vector |
10122
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
33 ## which converts the original name order into the new name order. |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
34 ## |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
35 ## Examples: |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
36 ## |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
37 ## @example |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
38 ## @group |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
39 ## s = struct("d", 4, "b", 2, "a", 1, "c", 3); |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
40 ## t1 = orderfields(s) |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
41 ## @result{} t1 = |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
42 ## @{ |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
43 ## a = 1 |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
44 ## b = 2 |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
45 ## c = 3 |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
46 ## d = 4 |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
47 ## @} |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
48 ## @end group |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
49 ## @group |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
50 ## t = struct("d", @{@}, "c", @{@}, "b", "a", @{@}); |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
51 ## t2 = orderfields(s, t) |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
52 ## @result{} t2 = |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
53 ## @{ |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
54 ## d = 4 |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
55 ## c = 3 |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
56 ## b = 2 |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
57 ## a = 1 |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
58 ## @} |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
59 ## @end group |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
60 ## @group |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
61 ## t3 = orderfields(s, [3, 2, 4, 1]); |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
62 ## @result{} t3 = |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
63 ## @{ |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
64 ## a = 1 |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
65 ## b = 2 |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
66 ## c = 3 |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
67 ## d = 4 |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
68 ## @} |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
69 ## @end group |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
70 ## @group |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
71 ## [t4, p] = orderfields(s, @{"d", "c", "b", "a"@}) |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
72 ## @result{} t4 = @{ |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
73 ## d = 4 |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
74 ## c = 3 |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
75 ## b = 2 |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
76 ## a = 1 |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
77 ## @} |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
78 ## p = |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
79 ## 1 |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
80 ## 4 |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
81 ## 2 |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
82 ## 3 |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
83 ## @end group |
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
84 ## @end example |
5881 | 85 ## |
86 ## @seealso{getfield, rmfield, isfield, isstruct, fieldnames, struct} | |
87 ## @end deftypefn | |
88 | |
89 ## Author: Paul Kienzle <pkienzle@users.sf.net> | |
90 ## Adapted-By: jwe | |
91 | |
92 function [t, p] = orderfields (s1, s2) | |
93 | |
94 if (nargin == 1 || nargin == 2) | |
95 if (! isstruct (s1)) | |
96 error ("orderfields: expecting argument to be a struct"); | |
97 endif | |
98 else | |
99 print_usage (); | |
100 endif | |
101 | |
102 if (nargin == 1) | |
103 ## One structure: return the fields in alphabetical order. | |
6862 | 104 if (isstruct (s1)) |
5881 | 105 names = sort (fieldnames (s1)); |
106 endif | |
107 elseif (nargin == 2) | |
6862 | 108 if (isstruct (s2)) |
5881 | 109 ## Two structures: return the fields in the order of s2. |
110 names = fieldnames (s2); | |
111 if (! isequal (sort (fieldnames (s1)), sort (names))) | |
10549 | 112 error ("orderfields: structures do not have same fields"); |
5881 | 113 endif |
114 elseif (iscellstr (s2)) | |
115 ## A structure and a list of fields: order by the list of fields. | |
116 t1 = sort (fieldnames (s1)); | |
117 t2 = sort (s2(:)); | |
118 if (! isequal (t1, t2)) | |
10549 | 119 error ("orderfields: name list does not match structure fields"); |
5881 | 120 endif |
121 names = s2; | |
122 elseif (isvector (s2)) | |
123 ## A structure and a permutation vector: permute the order of s1. | |
124 names = fieldnames (s1); | |
125 t1 = sort (s2); | |
126 t1 = t1(:)'; | |
6862 | 127 t2 = 1:numel (names); |
5881 | 128 if (! isequal (t1, t2)) |
10549 | 129 error ("orderfields: invalid permutation vector"); |
5881 | 130 endif |
6862 | 131 names = names (s2); |
5881 | 132 endif |
133 endif | |
134 | |
135 ## Find permutation vector which converts the original name order | |
136 ## into the new name order. Note: could save a couple of sorts | |
137 ## in some cases, but performance isn't critical. | |
138 | |
139 if (nargout == 2) | |
140 [oldel, oldidx] = sort (fieldnames (s1)); | |
141 [newel, newidx] = sort (names); | |
142 p = oldidx(newidx); | |
143 endif | |
144 | |
145 ## Permute the names in the structure. | |
6862 | 146 if (numel (s1) == 0) |
8605
9fc72c114ce1
Really fix indexing in orderfields.m
Jason Riedy <jason@acm.org>
parents:
8594
diff
changeset
|
147 args = cell (1, 2 * numel (names)); |
9fc72c114ce1
Really fix indexing in orderfields.m
Jason Riedy <jason@acm.org>
parents:
8594
diff
changeset
|
148 args(1:2:end) = names; |
8455
fd11a08a9b31
disallow invalid {}-indexed assigments
Jaroslav Hajek <highegg@gmail.com>
parents:
7017
diff
changeset
|
149 args(2:2:end) = {[]}; |
8605
9fc72c114ce1
Really fix indexing in orderfields.m
Jason Riedy <jason@acm.org>
parents:
8594
diff
changeset
|
150 t = struct (args{:}); |
6862 | 151 else |
8612
20d23d65cc84
fix & optimize orderfields
Jaroslav Hajek <highegg@gmail.com>
parents:
8605
diff
changeset
|
152 n = numel (s1); |
8605
9fc72c114ce1
Really fix indexing in orderfields.m
Jason Riedy <jason@acm.org>
parents:
8594
diff
changeset
|
153 for i = 1:numel (names) |
9fc72c114ce1
Really fix indexing in orderfields.m
Jason Riedy <jason@acm.org>
parents:
8594
diff
changeset
|
154 el = names(i); |
8612
20d23d65cc84
fix & optimize orderfields
Jaroslav Hajek <highegg@gmail.com>
parents:
8605
diff
changeset
|
155 [t(1:n).(el)] = s1(:).(el); |
8605
9fc72c114ce1
Really fix indexing in orderfields.m
Jason Riedy <jason@acm.org>
parents:
8594
diff
changeset
|
156 endfor |
8612
20d23d65cc84
fix & optimize orderfields
Jaroslav Hajek <highegg@gmail.com>
parents:
8605
diff
changeset
|
157 ## inherit dimensions |
20d23d65cc84
fix & optimize orderfields
Jaroslav Hajek <highegg@gmail.com>
parents:
8605
diff
changeset
|
158 t = reshape (t, size (s1)); |
6862 | 159 endif |
5881 | 160 |
161 endfunction | |
8594
756b0ba61350
orderfields.m: avoid loop for non-empty cases. New tests.
Jason Riedy <jason@acm.org>
parents:
8455
diff
changeset
|
162 |
8605
9fc72c114ce1
Really fix indexing in orderfields.m
Jason Riedy <jason@acm.org>
parents:
8594
diff
changeset
|
163 %!shared a, b, c |
8594
756b0ba61350
orderfields.m: avoid loop for non-empty cases. New tests.
Jason Riedy <jason@acm.org>
parents:
8455
diff
changeset
|
164 %! a = struct ("foo", {1, 2}, "bar", {3, 4}); |
756b0ba61350
orderfields.m: avoid loop for non-empty cases. New tests.
Jason Riedy <jason@acm.org>
parents:
8455
diff
changeset
|
165 %! b = struct ("bar", 6, "foo", 5); |
8605
9fc72c114ce1
Really fix indexing in orderfields.m
Jason Riedy <jason@acm.org>
parents:
8594
diff
changeset
|
166 %! c = struct ("bar", {7, 8}, "foo", 9); |
8594
756b0ba61350
orderfields.m: avoid loop for non-empty cases. New tests.
Jason Riedy <jason@acm.org>
parents:
8455
diff
changeset
|
167 %!test |
756b0ba61350
orderfields.m: avoid loop for non-empty cases. New tests.
Jason Riedy <jason@acm.org>
parents:
8455
diff
changeset
|
168 %! a(2) = orderfields (b, a); |
756b0ba61350
orderfields.m: avoid loop for non-empty cases. New tests.
Jason Riedy <jason@acm.org>
parents:
8455
diff
changeset
|
169 %! assert (a(2).foo, 5) |
8605
9fc72c114ce1
Really fix indexing in orderfields.m
Jason Riedy <jason@acm.org>
parents:
8594
diff
changeset
|
170 %! assert (a(2).bar, 6) |
8594
756b0ba61350
orderfields.m: avoid loop for non-empty cases. New tests.
Jason Riedy <jason@acm.org>
parents:
8455
diff
changeset
|
171 %!test |
10122
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
172 %! [a(2), p] = orderfields (b, [2 1]); |
8594
756b0ba61350
orderfields.m: avoid loop for non-empty cases. New tests.
Jason Riedy <jason@acm.org>
parents:
8455
diff
changeset
|
173 %! assert (a(2).foo, 5) |
8605
9fc72c114ce1
Really fix indexing in orderfields.m
Jason Riedy <jason@acm.org>
parents:
8594
diff
changeset
|
174 %! assert (a(2).bar, 6) |
10122
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8920
diff
changeset
|
175 %! assert (p, [2; 1]); |
8594
756b0ba61350
orderfields.m: avoid loop for non-empty cases. New tests.
Jason Riedy <jason@acm.org>
parents:
8455
diff
changeset
|
176 %!test |
756b0ba61350
orderfields.m: avoid loop for non-empty cases. New tests.
Jason Riedy <jason@acm.org>
parents:
8455
diff
changeset
|
177 %! a(2) = orderfields (b, fieldnames (a)); |
756b0ba61350
orderfields.m: avoid loop for non-empty cases. New tests.
Jason Riedy <jason@acm.org>
parents:
8455
diff
changeset
|
178 %! assert (a(2).foo, 5) |
8605
9fc72c114ce1
Really fix indexing in orderfields.m
Jason Riedy <jason@acm.org>
parents:
8594
diff
changeset
|
179 %! assert (a(2).bar, 6) |
9fc72c114ce1
Really fix indexing in orderfields.m
Jason Riedy <jason@acm.org>
parents:
8594
diff
changeset
|
180 %!test |
9fc72c114ce1
Really fix indexing in orderfields.m
Jason Riedy <jason@acm.org>
parents:
8594
diff
changeset
|
181 %! a(1:2) = orderfields (c, fieldnames (a)); |
9fc72c114ce1
Really fix indexing in orderfields.m
Jason Riedy <jason@acm.org>
parents:
8594
diff
changeset
|
182 %! assert (a(2).foo, 9) |
9fc72c114ce1
Really fix indexing in orderfields.m
Jason Riedy <jason@acm.org>
parents:
8594
diff
changeset
|
183 %! assert (a(2).bar, 8) |
9fc72c114ce1
Really fix indexing in orderfields.m
Jason Riedy <jason@acm.org>
parents:
8594
diff
changeset
|
184 |
9fc72c114ce1
Really fix indexing in orderfields.m
Jason Riedy <jason@acm.org>
parents:
8594
diff
changeset
|
185 %!test |
9fc72c114ce1
Really fix indexing in orderfields.m
Jason Riedy <jason@acm.org>
parents:
8594
diff
changeset
|
186 %! aa.x = {1, 2}; |
9fc72c114ce1
Really fix indexing in orderfields.m
Jason Riedy <jason@acm.org>
parents:
8594
diff
changeset
|
187 %! aa.y = 3; |
9fc72c114ce1
Really fix indexing in orderfields.m
Jason Riedy <jason@acm.org>
parents:
8594
diff
changeset
|
188 %! aa(2).x = {4, 5}; |
9fc72c114ce1
Really fix indexing in orderfields.m
Jason Riedy <jason@acm.org>
parents:
8594
diff
changeset
|
189 %! bb.y = {6, 7}; |
9fc72c114ce1
Really fix indexing in orderfields.m
Jason Riedy <jason@acm.org>
parents:
8594
diff
changeset
|
190 %! bb.x = 8; |
9fc72c114ce1
Really fix indexing in orderfields.m
Jason Riedy <jason@acm.org>
parents:
8594
diff
changeset
|
191 %! aa(2) = orderfields (bb, aa); |
9fc72c114ce1
Really fix indexing in orderfields.m
Jason Riedy <jason@acm.org>
parents:
8594
diff
changeset
|
192 %! assert (aa(2).x, 8); |
9fc72c114ce1
Really fix indexing in orderfields.m
Jason Riedy <jason@acm.org>
parents:
8594
diff
changeset
|
193 %! assert (aa(2).y{1}, 6); |