* Bug 14873 fixed [doc]: setfield page fixed updated clarified
[scilab.git] / scilab / modules / data_structures / help / pt_BR / setfield.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2006-2008 - INRIA
5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2020 - Samuel GOUGEON
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="http://www.w3.org/1999/xhtml"
18           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
19           xml:id="setfield" xml:lang="pt">
20     <refnamediv>
21         <refname>setfield</refname>
22         <refpurpose>altera o valor de um elemento de uma mlist, tlist ou list</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Seqüência de Chamamento</title>
26         <synopsis>uL = setfield(a, v, L)</synopsis>
27     </refsynopsisdiv>
28     <refsection>
29         <title>Parâmetros</title>
30         <variablelist>
31             <varlistentry>
32                 <term>L</term>
33                 <listitem>
34                     lista do tipo <literal>list</literal>, <literal>tlist</literal> ou
35                     <literal>mlist</literal> : a lista cujo componente deve ser alterado.
36                     <para/>
37                 </listitem>
38             </varlistentry>
39             <varlistentry>
40                 <term>a</term>
41                 <listitem>
42                     Endereço do componente a ser alterado. Pode ser o nome do campo
43                     especificado como uma sequência, ou o índice especificado como
44                     um número inteiro positivo. Veja <link linkend="inserção">inserção</link>
45                     para mais detalhes.
46                     <para/>
47                 </listitem>
48             </varlistentry>
49             <varlistentry>
50                 <term>v</term>
51                 <listitem>
52                     Qualquer objeto Scilab : o valor a ser atribuído.
53                     <para/>
54                 </listitem>
55             </varlistentry>
56             <varlistentry>
57                 <term>uL</term>
58                 <listitem>
59                     A lista atualizada.
60                     <para/>
61                 </listitem>
62             </varlistentry>
63         </variablelist>
64     </refsection>
65     <refsection>
66         <title>Descrição</title>
67         <para>
68             <literal>L=setfield(a,v,L)</literal> addresses and changes the
69             i<superscript>th</superscript> element of a list, in a unified way
70             over lists, tlists and mlists.
71         </para>
72         <para>
73             For simple lists and for tlists, <literal>L=setfield(a,v,L)</literal>
74             is equivalent to <literal>L(a)=v</literal>, that is simpler and should be preferred.
75             The same stands for any mlist if the address <varname>a</varname> is a
76             field's name.
77         </para>
78         <para>
79             However, for any mlist L, if <literal>i</literal> is an index, the insertion
80             <literal>L(i)=v</literal> is not predefined, in order to let the user define
81             an overload implementing a matrix-oriented insertion, if required.
82             Yet <literal>setfield(i,v,L)</literal> is always defined, with the same meaning as
83             for other list and tlist types.
84         </para>
85     </refsection>
86     <refsection>
87         <title>Exemplos</title>
88         <para>
89             For a tlist, <literal>setfield(3, v, T)</literal> is equivalent to
90             <literal>T(3)=v</literal> :
91         </para>
92         <programlisting role="example"><![CDATA[
93 T = tlist(['V','a','b'], [%z (1-%z) %z^2], [%f %t %t]);
94 // The insertion is predefined:
95 T(3) = [%t %t %f];
96 T(3)
97
98 T = setfield(3, [%f %t %f], T);
99 T(3)
100  ]]></programlisting>
101     <screen><![CDATA[
102 --> T = tlist(['V','a','b'], [%z (1-%z) %z^2], [%f %t %t]);
103 --> // The insertion is predefined:
104 --> T(3) = [%t %t %f];
105 --> T(3)
106  ans  =
107   T T F
108
109 --> T = setfield(3, [%f %t %f], T);
110 --> T(3)
111  ans  =
112   F T F
113 ]]></screen>
114         <para>
115             For a mlist, there is no predefined indexed insertion routine, to let
116              the user define a matrix-oriented insertion overload if required.
117         </para>
118         <programlisting role="example"><![CDATA[
119 M = mlist(['V','a','b'], [%z (1-%z) %z^2], [%f %t %t]);
120 M.b = [%t %t %t];
121 M.b                 // OK, while ...
122 M(3) = [%f %t %f];  // => error
123
124 // But a raw direct insertion with setfield() is always possible:
125 M = setfield(3, [%t %f %t], M);
126 getfield(3, M)
127  ]]></programlisting>
128     <screen><![CDATA[
129 --> M = mlist(['V','a','b'], [%z (1-%z) %z^2], [%f %t %t]);
130 --> M.b = [%t %t %t];
131 --> M.b                 // OK, while ...
132  ans  =
133   T T T
134
135 --> M(3) = [%f %t %f];  // => error
136 Function not defined for given argument type(s),
137   check arguments or define function %b_i_V for overloading.
138
139 --> // But a raw direct insertion with setfield() is always possible:
140 --> M = setfield(3, [%t %f %t], M);
141 --> getfield(3, M)
142  ans  =
143   T F T
144 ]]></screen>
145     </refsection>
146     <refsection role="see also">
147         <title>Ver Também</title>
148         <simplelist type="inline">
149             <member>
150                 <link linkend="insertion">insertion</link>
151             </member>
152             <member>
153                 <link linkend="getfield">getfield</link>
154             </member>
155         </simplelist>
156     </refsection>
157     <refsection>
158         <title>Histórico</title>
159         <revhistory>
160             <revision>
161                 <revnumber>6.0.0</revnumber>
162                 <revdescription>
163                     <itemizedlist>
164                         <listitem>
165                             The updated list is now returned, instead of being changed "in place".
166                         </listitem>
167                         <listitem>
168                             setfield() can no longer be used for cells arrays.
169                         </listitem>
170                     </itemizedlist>
171                 </revdescription>
172             </revision>
173         </revhistory>
174     </refsection>
175 </refentry>