help brackets: page overhauled and rewritten
[scilab.git] / scilab / modules / core / help / fr_FR / 1_keywords / brackets.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) 2016 - Samuel GOUGEON
5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  *
7  * This file is hereby licensed under the terms of the GNU GPL v2.0,
8  * pursuant to article 5.3.4 of the CeCILL v.2.1.
9  * This file was originally licensed under the terms of the CeCILL v2.1,
10  * and continues to be available under such terms.
11  * For more information, see the COPYING file which you should have received
12  * along with this program.
13  *
14  -->
15 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
16           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
17           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
18           xml:lang="fr" xml:id="brackets">
19     <refnamediv>
20         <refname>brackets [,;]</refname>
21         <refpurpose>Concatenation. Récipients d'une affectation. Résultats d'une function</refpurpose>
22     </refnamediv>
23     <refsynopsisdiv>
24         <title>Syntaxe</title>
25         <synopsis>
26             Mh = [m11 m12 m13.. m1N] or [m11, m12, m13,.., m1N]
27             Mv = [m11 ; m21 ; m31..; mN1]
28             M  = [m11, m12,...; m21, m22,...;...]
29             [r1, r2,...] = func(...)
30             [r1, r2,.., rN] = (e1, e2, .., eN)
31             [r1, r2,.., rk] = (e1, e2, .., ek,.., eN)
32             [r1, r2,.., rN] = mylist(:)
33             [r1, r2,.., rN] = S.field([i1 i2.. iN])
34         </synopsis>
35     </refsynopsisdiv>
36     <refsection role="parameters">
37         <title>Arguments</title>
38         <variablelist>
39             <varlistentry>
40                 <term>m11, m12,...  </term>
41                 <listitem>
42                     <para>
43                     Ensemble d'objets à concaténer (rassembler) et à fusionner :
44                     les conteneurs individuels initiaux des objets sont supprimés.
45                     Les types d'objets des familles suivantes peuvent
46                     être mélangés entre eux dans une même famille, mais pas
47                     entre familles :
48                     <itemizedlist>
49                         <listitem>
50                             Matrices de booléens, nombres décimaux,
51                             nombres complexes, polynômes, fractions rationnelles :
52                             le type de l'objet résultant est le type de l'élément le
53                             plus complexe, des booléens (le moins complexe) aux fractions
54                             rationelles à coefficients complexes
55                             (voir les règles de
56                             <link linkend="brackets_Types_conversions">
57                             <emphasis role="italic">transtypages</emphasis></link>).
58                         </listitem>
59                         <listitem>Matrices d'entiers encodés de type entier
60                             <link linkend="inttype">inttype</link> quelconque.
61                             <warning>Des entiers de types différents ne peuvent
62                             pas être concaténés entre eux.
63                             </warning>
64                         </listitem>
65                         <listitem>Tableaux de structures ayant les mêmes champs.
66                             Les champs peuvent être dans des ordres différents
67                             d'un tableau à l'autre.
68                         </listitem>
69                         <listitem>
70                             Listes de type <link linkend="syslin">syslin</link>
71                         </listitem>
72                     </itemizedlist>
73                     </para>
74                 </listitem>
75             </varlistentry>
76             <varlistentry>
77                 <term>M, Mh, Mv</term>
78                 <listitem>
79                     <para>
80                         Matrices ayant le type des éléments <varname>m##</varname>
81                         (s'ils ont tous le même type).
82                     </para>
83                 </listitem>
84             </varlistentry>
85             <varlistentry>
86                 <term>e1, e2,..  </term>
87                 <listitem>
88                     <para>Objets d'entrée (litéraux tels que <literal>-1.23</literal>
89                     ou <literal>"abcd"</literal>, variables, ou expressions telles
90                     que <literal>a+%pi</literal>)
91                     </para>
92                 </listitem>
93             </varlistentry>
94             <varlistentry>
95                 <term>mylist</term>
96                 <listitem>
97                     <para>Liste simple du type list(..)</para>
98                 </listitem>
99             </varlistentry>
100             <varlistentry>
101                 <term>S.field</term>
102                 <listitem>
103                     <para>
104                         Tableau de structures ayant un champ nommé <literal>field</literal>.
105                     </para>
106                 </listitem>
107             </varlistentry>
108             <varlistentry>
109                 <term>i1, i2, ..</term>
110                 <listitem>
111                     <para>
112                         Indices des éléments de <varname>S</varname> sélectionnés.
113                     </para>
114                 </listitem>
115             </varlistentry>
116             <varlistentry>
117                 <term>r1, r2,...  </term>
118                 <listitem>
119                     <para>Récipients = variables de sortie</para>
120                 </listitem>
121             </varlistentry>
122         </variablelist>
123     </refsection>
124     <refsection role="description">
125         <title>Description</title>
126         <variablelist>
127             <varlistentry>
128                 <term>[] (figurant à droite) : crochets concaténateurs</term>
129                 <listitem>
130                     <para>[..] assemble les objets de types simples et compatibles
131                         pour former un vecteur, une matrice ou une hypermatrice
132                         homogène.
133                     </para>
134                     <note>La concaténation horizontale ou verticale de N éléments
135                         est un opérateur binaire itératif : la concaténation
136                         est réalisée de proche en proche entre 2 élements consécutifs,
137                         de la gauche vers la droite, et de haut en bas. Ainsi,
138                         <literal>[1 3 5 7]</literal> est effectuée par
139                         <literal>[[[1 3] 5] 7]</literal>.
140                     </note>
141                     <para>Dans les crochets,
142                         <itemizedlist>
143                             <listitem>les espaces (blancs ou tabulations) ou
144                                 les virgules servent de séparateurs.
145                                 <note>Il est préférable d'utiliser des virgules,
146                                 en particulier lorsque des nombres complexes
147                                 ou des polynômes sont fournis en expressions
148                                 litérales. Par exemple, <literal>[2 1 +%i]</literal>
149                                 sera interprété comme <literal>[2, 1, %i]</literal>,
150                                 alors que <literal>[2 1 + %i]</literal> sera
151                                 compris comme <literal>[2, 1+%i]</literal>.
152                                 </note>
153                             </listitem>
154                             <listitem>les points-virgules ou les changements de
155                             lignes sont utilisés comme séparateurs de lignes.
156                             Pour peu que la ligne courante soit complète, le
157                             passage à la ligne ne pré-requiert pas les points de
158                             poursuite-à-la-ligne <literal>..</literal>.
159                             </listitem>
160                         </itemizedlist>
161                     </para>
162                     <refsect3 id="brackets_Types_conversions">
163                         <title>Transtypages</title>
164                         <para>
165                             Avec quelques restrictions, les crochets peuvent être
166                             utilisés sur une série de valeurs ayant des types distincts
167                             mais compatibles. Des valeurs sont alors converties
168                             de proche en proche dans le type de données dominant.
169                             Les principales règles de conversion implicite sont
170                             les suivantes :
171                             <orderedlist>
172                                 <listitem>booléen &lt; nombre décimal &lt; nombre complexe
173                                 </listitem>
174                                 <listitem>décimal &lt; polynôme &lt; fraction rationelle
175                                     <warning>Les booléens et les polynômes ne sont pas
176                                         compatibles entre eux :
177                                         <itemizedlist>
178                                             <listitem>
179                                                 <literal>[%t 2. %z]</literal> est accepté, car :
180                                                 <literal>[%t 2.]</literal> est d'abord
181                                                 converti en
182                                                 <literal>[1. 2.]</literal>, puis
183                                                 <literal>[[1. 2.] %z]</literal> est
184                                                 accepté.
185                                             </listitem>
186                                             <listitem>
187                                                 <literal>[%z %t 2.]</literal> est
188                                                 refusé et produit une erreur.
189                                                 En effet, <literal>[%z %t]</literal>
190                                                 n'est pas permis et bloque la suite.
191                                             </listitem>
192                                         </itemizedlist>
193                                     </warning>
194                                 </listitem>
195                                 <listitem>
196                                     Le résultat est encodé en valeurs complexes (avec
197                                     parties imaginaires éventuellement nulles) dés qu'un
198                                     élément -- valeur, polynôme, ou fraction rationnelle --
199                                     à valeur complexe est rencontré.
200                                     <para>De même, le résultat est encodé sous forme
201                                     creuse
202                                     dés qu'un élément encodé creux est rencontré.
203                                     </para>
204                                 </listitem>
205                                 <listitem>
206                                     Des polynômes ou des fractions rationnelles
207                                     de différentes variables peuvent
208                                     être concaténés entre eux. Le premier polynôme
209                                     ou fraction rationnelle listé donne alors le
210                                     nom de sa variable au résultat de la concaténation :
211                                     <literal>[%z, 1+%s, 1-%i*%s]
212                                         // => [z, 1+z, 1-iz]
213                                     </literal>.
214                                 </listitem>
215                                 <listitem>
216                                     Tout entier encodé peut être concaténé uniquement
217                                     avec d'autres entiers du même type entier
218                                     (<link linkend="inttype">inttype</link>). Ainsi,
219                                     les expressions
220                                     <literal>[%t int8(2)]</literal>,
221                                     <literal>[int8(2) uint8(7)]</literal>,
222                                     <literal>[int8(2) int16(7)]</literal>,
223                                     <literal>[int8(2) 1.]</literal> produiront
224                                     toutes une erreur.
225                                 </listitem>
226                                 <listitem>Les éléments de texte (type "string") peuvent
227                                 être concaténés (au sens ensembliste, avec les crochets)
228                                 uniquement entre eux ou avec la matrice vide
229                                 <literal>[]</literal>.
230                                 </listitem>
231                             </orderedlist>
232                         </para>
233                     </refsect3>
234                     <refsect3 id="brackets_overloading">
235                         <title>Surcharge</title>
236                         <para>
237                             <itemizedlist>
238                                 <listitem>[,]: concaténation horizontale :
239                                     cet opérateur n-aire (pouvant être appliqué à un
240                                     nombre arbitraire n de données) est en fait un
241                                     opérateur binaire automatiquement itéré de la
242                                     gauche vers la droite. Son code de surcharge est
243                                     <literal>"c"</literal>.
244                                 </listitem>
245                                 <listitem>[;]: la concaténation verticale est
246                                     également un opérateur binaire, itéré du haut
247                                     vers le bas. Son code de surcharge est
248                                     <literal>"f"</literal>.
249                                 </listitem>
250                             </itemizedlist>
251                         </para>
252                     </refsect3>
253                 </listitem>
254             </varlistentry>
255             <varlistentry>
256                 <term>[] figurant à gauche d'une affectation <literal>"="</literal></term>
257                 <listitem>
258                     <para>
259                     Dans ce cas, les crochets ne désignent en rien une concaténation.
260                     Ils délimitent une série de variables servant de récipients.
261                     </para>
262                     <para>
263                         <itemizedlist>
264                             <listitem>Les termes entre crochets doivent alors
265                                 impérativement être des variables. Les expressions
266                                 litérales ou symboliques sont rejetées.
267                             </listitem>
268                             <listitem>Les variables sont séparées par des virgules
269                               ou des espaces. Lorsqu'il s'agit de la liste des
270                               arguments de sortie d'une function, les virgules
271                               sont obligatoires.
272                             </listitem>
273                             <listitem>Dans une affectation distributive, il doit
274                                 y avoir <emphasis role="italic">au plus</emphasis>
275                                 autant de récipients que de sources de données
276                                 provenant du terme de droite, pas plus. S'il y
277                                 moins de récipients à gauche que de sources à droite,
278                                 les sources non collectées sont ignorées. Exemples :
279                                 <simplelist>
280                                     <member><literal>[a,b] = (%pi,"Hi", %z)</literal>
281                                         est correct, mais <literal>%z</literal>
282                                         sera ignoré.
283                                     </member>
284                                     <member><literal>[a,b,c] = (%pi,"Hi")</literal>
285                                         produit une erreur, car <literal>c</literal>
286                                         attend du contenu.
287                                     </member>
288                                 </simplelist>                            </listitem>
289                             <listitem>La même variable peut être utilisée plusieurs
290                                 fois dans la liste de gauche entre crochets.
291                                 Le cas échéant, les affectations successives réalisées
292                                 de gauche à droite dans la liste écrasent les contenus
293                                 pré-existants. Exemple :
294                                 <literal>[a,b,a]=(%pi,%z,"Allo")</literal>
295                                 est équivalent à <literal>a="Allo", b=%z</literal>.
296                             </listitem>
297                         </itemizedlist>
298                     </para>
299                 </listitem>
300             </varlistentry>
301         </variablelist>
302     </refsection>
303     <refsection role="examples">
304         <title>Exemples</title>
305         <programlisting role="example"><![CDATA[
306 // Concaténation horizontale
307 a = [ %pi 4 -1 ]
308 b1 = grand(3,4,"uin",0,10)
309 b2 = grand(3,2,"uin",0,10)
310 b = [b1 b2]  // b1, b2.. doivent avoir le même nombre de lignes
311
312 // Concaténation verticale
313 a = [-2 ; 10 ; 7]
314
315 b1 = grand(2,4,"uin",0,10)
316 b2 = grand(3,4,"uin",0,10)
317 b = [b1 ; b2] // // b1, b2.. doivent avoir le même nombre de colonnes
318
319 // Double concaténation horizontale et verticale
320 a = [ 3 7 ; 6, 5 ]
321 b = [ 1:3 ; 7:3:13]
322 c = [ a b ; a b]
323
324 d = [ 3 5
325       1 4
326     ]
327 e = [ d d d
328       d d d
329     ]
330 // Concaténation de types d'objets variés :
331 ['this is' ; 'a column' ; 'of texts']
332
333 s = poly(0,'s');[1/s,2/s]
334 [tf2ss(1/s),tf2ss(2/s)]
335
336 [%t %f %f %T %F]
337
338 // Concaténation d'objets de types compatibles différents, avec transtypages automatiques
339 [%T %pi %f 2]
340 [%pi, 2+%i, %F]
341 v = [%pi+0*%i, %F, %z, (1-%z)^2 ]; typeof(v), isreal(v)
342 v = [10 1/%z], typeof(v)
343
344 // Concaténations hétérogènes d'objets de types incompatibles => ERREURS
345 [%F %z]
346 [%F int8(5)]
347 [int8(%pi) uint8(%e)]
348 [int8(%pi) int16(%e)]
349  ]]></programlisting>
350
351         <para>
352             <emphasis role="bold">Affectations distributives :</emphasis>
353         </para>
354         <programlisting role="example"><![CDATA[
355 // Variables des réponses d'une function.
356 // Elles sont le plus souvent optionnelles, l'une après l'autre
357 M = rand(3,3);
358 [u, s] = schur(M) // Nous attendons et utilisons à la fois u et s
359 u = schur(M)      // Nous attendons et stockons uniquement u
360
361 // Liste directe (implicite) d'objets à affecter
362 [a, b, c] = (%pi, %t, "test")
363 [a, b] = (%e, %f, "Hello")
364 [a, b, a] = (%pi, %t, "test");
365
366 // Liste explicite d'objets à affecter
367 L = list(%z, %i, %t, %pi, "Text");
368 [a, b, c] = L(:)
369
370 // Tableau de structures :
371 // Sélection de certaines cellules et affectation de leurs contenus
372 s(2,3).r = %pi; s(2,1).r = %i; s(2,2) = %e;
373 s(2,:).r
374 s.r([2 4 6])
375 [a, b, c] = s.r([2 4 6])
376
377 // Expressions gauches interdites et rejetées (=> erreur)
378 [m, n, m+n] = myfun(a,b) // "m+n" est une expression, non un nom de variable.
379 [p, 4.5, q] = myfun(a,b) // "4.5 est une valeur littérale, non un nom de variable.
380 [r, s+3 ] = myfun(a,b)   // "s+3" est une expression mixte, non un nom de variable
381  ]]></programlisting>
382         <screen><![CDATA[--> [a, b, c] = (%pi, %t, "test")
383  c  =
384  test
385
386  b  =
387   T
388
389  a  =
390    3.1415927
391
392 --> [a, b] = (%e, %f, "Hello")
393  b  =
394   F
395
396  a  =
397    2.7182818
398
399 --> [a, b, a] = (%pi, %t, "test"); a
400  a  =
401    3.1415927
402 ]]></screen>
403     </refsection>
404     <refsection role="see also">
405         <title>Voir aussi</title>
406         <simplelist type="inline">
407             <member>
408                 <link linkend="empty">empty</link>
409             </member>
410             <member>
411                 <link linkend="parentheses">parentheses</link>
412             </member>
413             <member>
414                 <link linkend="lstcat">lstcat</link>
415             </member>
416             <member>
417                 <link linkend="comma">comma</link>
418             </member>
419             <member>
420                 <link linkend="semicolon">semicolon</link>
421             </member>
422             <member>
423                 <link linkend="overloading">overloading</link>
424             </member>
425         </simplelist>
426     </refsection>
427     <refsection role="history">
428         <title>Historique</title>
429         <revhistory>
430             <revision>
431                 <revnumber>6.0</revnumber>
432                 <revdescription>
433                     Crochets <literal>[..]</literal> et accolades
434                     <literal>{..}</literal> ont désormais des fonctions distinctes.
435                 </revdescription>
436             </revision>
437         </revhistory>
438     </refsection>
439 </refentry>