octave-nkf: scripts/miscellaneous/setfield.m annotate

annotate scripts/miscellaneous/setfield.m @ 15615:808e4f13e220

doc: Update struct documentation to match new indexing rules * container.txi: Mention that fields can now be arbitrary strings and issues that this may cause with Matlab. * setfield.m: Completely rewrite docstring. More examples. * getfield.m: Remove most of the docstring and refer to setfield's docstring instead.

author	Jordi Gutiérrez Hermoso <jordigh@octave.org>
date	Tue, 20 Nov 2012 16:17:01 -0500
parents	f3d52523cde1
children	7eff3032d144

rev	line source
14138 72c96de7a403 maint: update copyright notices for 2012 John W. Eaton <jwe@octave.org> parents: 12931 diff changeset	1 ## Copyright (C) 2000-2012 Etienne Grossmann
9849 87fd803c583b rewrite getfield and setfield Jaroslav Hajek <highegg@gmail.com> parents: 9051 diff changeset	2 ## Copyright (C) 2009 VZLU Prague
5820 27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	3 ##
27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	4 ## This file is part of Octave.
27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	5 ##
27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	6 ## Octave is free software; you can redistribute it and/or modify it
27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	7 ## under the terms of the GNU General Public License as published by
7016 93c65f2a5668 [project @ 2007-10-12 06:40:56 by jwe] jwe parents: 6547 diff changeset	8 ## the Free Software Foundation; either version 3 of the License, or (at
93c65f2a5668 [project @ 2007-10-12 06:40:56 by jwe] jwe parents: 6547 diff changeset	9 ## your option) any later version.
5820 27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	10 ##
27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	11 ## Octave is distributed in the hope that it will be useful, but
27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	12 ## WITHOUT ANY WARRANTY; without even the implied warranty of
27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	13 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	14 ## General Public License for more details.
27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	15 ##
27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	16 ## You should have received a copy of the GNU General Public License
7016 93c65f2a5668 [project @ 2007-10-12 06:40:56 by jwe] jwe parents: 6547 diff changeset	17 ## along with Octave; see the file COPYING. If not, see
93c65f2a5668 [project @ 2007-10-12 06:40:56 by jwe] jwe parents: 6547 diff changeset	18 ## <http://www.gnu.org/licenses/>.
5820 27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	19
27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	20 ## -- texinfo --
15615 808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	21 ## @deftypefn {Function File} {@var{s} =} setfield (@var{s}, @var{field}, @var{val})
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	22 ## @deftypefnx {Function File} {@var{s} =} setfield (@var{s}, @var{idx1}, @var{field1}, @var{idx2}, @var{field2}, @dots{}, @var{val})
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	23 ##
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	24 ## Set a field member @var{field} in a structure @var{s} equal to @var{val}. For example:
5820 27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	25 ##
27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	26 ## @example
27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	27 ## @group
15615 808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	28 ## @var{s} = struct ();
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	29 ## @var{s} = setfield (@var{s}, "foo bar", 42);
5820 27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	30 ## @end group
27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	31 ## @end example
27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	32 ##
15615 808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	33 ## @noindent
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	34 ## This is equivalent to
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	35 ##
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	36 ## @example
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	37 ## @var{s}.("foo bar") = 42;
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	38 ## @end example
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	39 ##
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	40 ## @noindent
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	41 ## Note that ordinary structure syntax @code{@var{s}.foo bar = 42} cannot be
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	42 ## used here, as the field name is not a valid Octave identifier. Using
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	43 ## arbitrary strings for field name is incompatible with @sc{Matlab}, so
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	44 ## this usage will warn if the @code{Octave:matlab-incompatible} warning
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	45 ## is set. @xref{doc-warning_ids}.
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	46 ##
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	47 ## With the second calling form, set a field on a structure array,
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	48 ## possibly nested, with successive nested indices @var{idx1},
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	49 ## @var{idx2}, @dots{} and fields @var{field1}, @var{field2}, @dots{}
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	50 ## The indices must be cells containing the desired index at this
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	51 ## nesting depth.
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	52 ##
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	53 ## Thus consider instead,
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	54 ##
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	55 ## @example
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	56 ## @group
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	57 ## @var{s} = struct ("baz", 42);
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	58 ## setfield (@var{s}, @{1@}, "foo", @{1@}, "bar", 5)
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	59 ## @result{} ans =
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	60 ## scalar structure containing the fields:
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	61 ## baz = 42
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	62 ## foo =
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	63 ## scalar structure containing the fields:
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	64 ## bar = 54
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	65 ## @end group
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	66 ## @end example
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	67 ##
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	68 ## Here we first have an ordinary structure array with one field
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	69 ## @code{baz} set to 42. Then we set another field in a nested scalar structure
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	70 ## indexing with two single cells containing the unique desired indices.
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	71 ##
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	72 ## Finally an example with nested structure arrays,
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	73 ##
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	74 ## @example
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	75 ## @group
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	76 ## @var{sa}.foo = 1;
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	77 ## @var{sa} = setfield (@var{sa}, @{2@}, "bar", @{3@}, "baz", 6);
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	78 ## @var{sa}(2).bar(3)
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	79 ## @result{} ans =
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	80 ## scalar structure containing the fields:
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	81 ## baz = 6
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	82 ## @end group
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	83 ## @end example
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	84 ##
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	85 ## Here @var{sa} is a structure array whose field @code{fd} at elements
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	86 ## 1 and 2 field is in turn
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	87 ## another structure array whose third element is a structure
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	88 ##
10122 9d1a14e12431 Update docs and add tests for container functions Thorsten Meyer <thorsten.meyier@gmx.de> parents: 9849 diff changeset	89 ## Note that the same result as in the above example could be achieved by:
5820 27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	90 ##
27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	91 ## @example
9051 1bf0ce0930be Grammar check TexInfo in all .m files Rik <rdrider0-list@yahoo.com> parents: 8920 diff changeset	92 ## @group
15615 808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	93 ## @var{SA}.foo = 1;
808e4f13e220 doc: Update struct documentation to match new indexing rules Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14363 diff changeset	94 ## @var{SA}(2).bar(3).baz = 6
9051 1bf0ce0930be Grammar check TexInfo in all .m files Rik <rdrider0-list@yahoo.com> parents: 8920 diff changeset	95 ## @end group
5820 27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	96 ## @end example
27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	97 ## @seealso{getfield, rmfield, isfield, isstruct, fieldnames, struct}
27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	98 ## @end deftypefn
27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	99
27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	100 ## Author: Etienne Grossmann <etienne@cs.uky.edu>
27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	101
27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	102 function obj = setfield (obj, varargin)
9849 87fd803c583b rewrite getfield and setfield Jaroslav Hajek <highegg@gmail.com> parents: 9051 diff changeset	103 if (nargin < 3)
87fd803c583b rewrite getfield and setfield Jaroslav Hajek <highegg@gmail.com> parents: 9051 diff changeset	104 print_usage ();
87fd803c583b rewrite getfield and setfield Jaroslav Hajek <highegg@gmail.com> parents: 9051 diff changeset	105 endif
87fd803c583b rewrite getfield and setfield Jaroslav Hajek <highegg@gmail.com> parents: 9051 diff changeset	106 subs = varargin(1:end-1);
87fd803c583b rewrite getfield and setfield Jaroslav Hajek <highegg@gmail.com> parents: 9051 diff changeset	107 rhs = varargin{end};
12931 cefd568ea073 Replace function handles with function names in cellfun calls for 15% speedup. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	108 flds = cellfun ("isclass", subs, "char");
cefd568ea073 Replace function handles with function names in cellfun calls for 15% speedup. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	109 idxs = cellfun ("isclass", subs, "cell");
9849 87fd803c583b rewrite getfield and setfield Jaroslav Hajek <highegg@gmail.com> parents: 9051 diff changeset	110 if (all (flds \| idxs))
87fd803c583b rewrite getfield and setfield Jaroslav Hajek <highegg@gmail.com> parents: 9051 diff changeset	111 typs = merge (flds, {"."}, {"()"});
87fd803c583b rewrite getfield and setfield Jaroslav Hajek <highegg@gmail.com> parents: 9051 diff changeset	112 obj = subsasgn (obj, struct ("type", typs, "subs", subs), rhs);
87fd803c583b rewrite getfield and setfield Jaroslav Hajek <highegg@gmail.com> parents: 9051 diff changeset	113 else
87fd803c583b rewrite getfield and setfield Jaroslav Hajek <highegg@gmail.com> parents: 9051 diff changeset	114 error ("setfield: invalid index");
87fd803c583b rewrite getfield and setfield Jaroslav Hajek <highegg@gmail.com> parents: 9051 diff changeset	115 endif
5820 27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	116 endfunction
27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	117
14363 f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks Rik <octave@nomad.inbox5.com> parents: 14138 diff changeset	118
5820 27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	119 %!test
27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	120 %! x.a = "hello";
14363 f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks Rik <octave@nomad.inbox5.com> parents: 14138 diff changeset	121 %! x = setfield (x, "b", "world");
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks Rik <octave@nomad.inbox5.com> parents: 14138 diff changeset	122 %! y = struct ("a", "hello", "b", "world");
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks Rik <octave@nomad.inbox5.com> parents: 14138 diff changeset	123 %! assert (x,y);
5820 27c966e4b2dc [project @ 2006-05-17 21:00:54 by jwe] jwe parents: diff changeset	124 %!test
14363 f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks Rik <octave@nomad.inbox5.com> parents: 14138 diff changeset	125 %! oo(1,1).f0 = 1;
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks Rik <octave@nomad.inbox5.com> parents: 14138 diff changeset	126 %! oo = setfield (oo,{1,2},"fd",{3},"b", 6);
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks Rik <octave@nomad.inbox5.com> parents: 14138 diff changeset	127 %! assert (oo(1,2).fd(3).b, 6);
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks Rik <octave@nomad.inbox5.com> parents: 14138 diff changeset	128

Mercurial > octave-nkf

annotate scripts/miscellaneous/setfield.m @ 15615:808e4f13e220