fbde7f05052ddccfbd79d6f9fa80d9d5365cdfaf
[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) 2012 - 2016 - Scilab Enterprises
5  * Copyright (C) 2016, 2018 - Samuel GOUGEON
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>Concaténation. 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 être mélangés entre eux dans
46                     une même famille, mais pas entre familles :
47                     <itemizedlist>
48                         <listitem>
49                             Matrices de booléens, nombres décimaux, nombres complexes, polynômes,
50                             fractions rationnelles : le type de l'objet résultant est le type de
51                             l'élément le plus complexe, des booléens (le moins complexe) aux
52                             fractions rationelles à coefficients complexes
53                             (voir les règles de <link linkend="brackets_Types_conversions">
54                             <emphasis role="italic">transtypages</emphasis></link>).
55                         </listitem>
56                         <listitem>Matrices d'entiers encodés de type entier
57                             <link linkend="inttype">inttype</link> quelconque.
58                             <warning>
59                             Des entiers de types différents ne peuvent pas être concaténés entre eux.
60                             </warning>
61                         </listitem>
62                         <listitem>
63                             Tableaux de cellules.
64                         </listitem>
65                         <listitem>
66                             Tableaux de structures ayant les mêmes champs. Les champs peuvent être
67                             dans des ordres différents 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                         Tableaux de cellules (si les <literal>mi</literal> en sont).
83                         Tableaux de structures (si les <literal>mi</literal> en sont).
84                     </para>
85                 </listitem>
86             </varlistentry>
87             <varlistentry>
88                 <term>e1, e2,..  </term>
89                 <listitem>
90                     <para>Objets d'entrée (litéraux tels que <literal>-1.23</literal>
91                     ou <literal>"abcd"</literal>, variables, ou expressions telles
92                     que <literal>a+%pi</literal>)
93                     </para>
94                 </listitem>
95             </varlistentry>
96             <varlistentry>
97                 <term>mylist</term>
98                 <listitem>
99                     <para>Liste simple du type list(..)</para>
100                 </listitem>
101             </varlistentry>
102             <varlistentry>
103                 <term>S.field</term>
104                 <listitem>
105                     <para>
106                         Tableau de structures ayant un champ nommé <literal>field</literal>.
107                     </para>
108                 </listitem>
109             </varlistentry>
110             <varlistentry>
111                 <term>i1, i2, ..</term>
112                 <listitem>
113                     <para>
114                         Indices des éléments de <varname>S</varname> sélectionnés.
115                     </para>
116                 </listitem>
117             </varlistentry>
118             <varlistentry>
119                 <term>r1, r2,...  </term>
120                 <listitem>
121                     <para>Récipients = variables de sortie</para>
122                 </listitem>
123             </varlistentry>
124         </variablelist>
125     </refsection>
126     <refsection role="description">
127         <title>Description</title>
128         <variablelist>
129             <varlistentry>
130                 <term>[] (figurant à droite) : crochets concaténateurs</term>
131                 <listitem>
132                     <para>[..] assemble les objets de types simples et compatibles
133                         pour former un vecteur, une matrice ou une hypermatrice
134                         homogène.
135                     </para>
136                     <note>La concaténation horizontale ou verticale de N éléments
137                         est un opérateur binaire itératif : la concaténation
138                         est réalisée de proche en proche entre 2 élements consécutifs,
139                         de la gauche vers la droite, et de haut en bas. Ainsi,
140                         <literal>[1 3 5 7]</literal> est effectuée par
141                         <literal>[[[1 3] 5] 7]</literal>.
142                     </note>
143                     <para>Dans les crochets,
144                         <itemizedlist>
145                             <listitem>
146                                 les espaces (blancs ou tabulations) ou les virgules servent de
147                                 séparateurs.
148                                 <note>
149                                 Il est préférable d'utiliser des virgules, en particulier lorsque
150                                 des nombres complexes ou des polynômes sont fournis en expressions
151                                 litérales. Par exemple, <literal>[2 1 +%i]</literal> sera interprété
152                                 comme <literal>[2, 1, %i]</literal>, alors que
153                                 <literal>[2 1 + %i]</literal> sera compris comme
154                                 <literal>[2, 1+%i]</literal>.
155                                 </note>
156                             </listitem>
157                             <listitem>
158                                 les points-virgules ou les changements de lignes sont utilisés comme
159                                 séparateurs de lignes. Pour peu que la ligne courante soit complète,
160                                 le passage à la ligne ne pré-requiert pas les points de
161                                 poursuite-à-la-ligne <literal>..</literal>.
162                             </listitem>
163                         </itemizedlist>
164                     </para>
165                     <refsect3 id="brackets_Types_conversions">
166                         <title>Transtypages</title>
167                         <para>
168                             Avec quelques restrictions, les crochets peuvent être utilisés sur une
169                             série de valeurs ayant des types distincts mais compatibles.
170                             Des valeurs sont alors converties de proche en proche dans le type de
171                             données dominant. Les principales règles de conversion implicite sont
172                             les suivantes :
173                             <orderedlist>
174                                 <listitem>
175                                     booléen &lt; entier encodé.
176                                 </listitem>
177                                 <listitem>
178                                     booléen &lt; nombre décimal &lt; nombre complexe
179                                 </listitem>
180                                 <listitem>décimal &lt; polynôme &lt; fraction rationelle
181                                     <warning>
182                                         Les booléens et les polynômes ne sont pas compatibles entre
183                                         eux :
184                                         <itemizedlist>
185                                             <listitem>
186                                                 <literal>[%t 2. %z]</literal> est accepté, car :
187                                                 <literal>[%t 2.]</literal> est d'abord converti en
188                                                 <literal>[1. 2.]</literal>, puis
189                                                 <literal>[[1. 2.] %z]</literal> est accepté.
190                                             </listitem>
191                                             <listitem>
192                                                 <literal>[%z %t 2.]</literal> est refusé et produit
193                                                 une erreur. En effet, <literal>[%z %t]</literal>
194                                                 n'est pas permis et bloque la suite.
195                                             </listitem>
196                                         </itemizedlist>
197                                     </warning>
198                                 </listitem>
199                                 <listitem>
200                                     Le résultat est encodé en valeurs complexes (avec parties
201                                     imaginaires éventuellement nulles) dés qu'un élément
202                                     -- valeur, polynôme, ou fraction rationnelle -- à valeur
203                                     complexe est rencontré.
204                                     <para>
205                                         De même, le résultat est encodé sous forme creuse dés qu'un
206                                         élément encodé creux est rencontré.
207                                     </para>
208                                 </listitem>
209                                 <listitem>
210                                     Des polynômes ou des fractions rationnelles de différentes
211                                     variables peuvent être concaténés entre eux. Le premier polynôme
212                                     ou fraction rationnelle listé donne alors le nom de sa variable
213                                     au résultat de la concaténation :
214                                     <literal>[%z, 1+%s, 1-%i*%s]
215                                         // => [z, 1+z, 1-iz]
216                                     </literal>.
217                                 </listitem>
218                                 <listitem>
219                                     Tout entier encodé peut être concaténé uniquement avec des
220                                     booléens ou d'autres entiers du même type entier
221                                     (<link linkend="inttype">inttype</link>). Ainsi, les expressions
222                                     <literal>[int8(2) uint8(7)]</literal>,
223                                     <literal>[int8(2) int16(7)]</literal>,
224                                     <literal>[int8(2) 1.]</literal> produiront toutes une erreur.
225                                 </listitem>
226                                 <listitem>
227                                     Les éléments de texte (type "string") peuvent être concaténés
228                                     (au sens ensembliste, avec les crochets) uniquement entre eux
229                                     ou avec la matrice vide
230                                 <literal>[]</literal>.
231                                 </listitem>
232                             </orderedlist>
233                         </para>
234                     </refsect3>
235                     <refsect3 id="brackets_overloading">
236                         <title>Surcharge</title>
237                         <para>
238                             <itemizedlist>
239                                 <listitem>[,]: concaténation horizontale : cet opérateur n-aire
240                                     (pouvant être appliqué à un nombre arbitraire n de données)
241                                     est en fait un 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>
246                                     [;]: la concaténation verticale est également un opérateur
247                                     binaire, itéré du haut vers le bas. Son code de surcharge est
248                                     <literal>"f"</literal>.
249                                 </listitem>
250                             </itemizedlist>
251                         </para>
252                     </refsect3>
253                     <para/>
254                     <refsect3>
255                         <title>Extensions</title>
256                         <para>
257                           <itemizedlist>
258                             <listitem>
259                               Pour concaténer des listes simples, utiliser <link linkend="lstcat">lstcat</link>.
260                             </listitem>
261                             <listitem>
262                               Pour assembler des vecteurs ou matrices ou hypermatrices ou autres
263                               tableaux selon une dimension > 2 et construire un hypertableau à N
264                               dimensions, utiliser <link linkend="cat">cat</link>.
265                             </listitem>
266                           </itemizedlist>
267                         </para>
268                     </refsect3>
269                 </listitem>
270             </varlistentry>
271             <varlistentry>
272                 <term>[] figurant à gauche d'une affectation <literal>"="</literal></term>
273                 <listitem>
274                     <para>
275                         Dans ce cas, les crochets ne désignent en rien une concaténation. Ils
276                         délimitent une série de variables servant de récipients.
277                     </para>
278                     <para>
279                         <itemizedlist>
280                             <listitem>
281                                 Les termes entre crochets doivent alors impérativement être des
282                                 variables. Les expressions litérales ou symboliques sont rejetées.
283                             </listitem>
284                             <listitem>
285                                 Les variables sont séparées par des virgules ou des espaces.
286                                 Lorsqu'il s'agit de la liste des arguments de sortie d'une function,
287                                 les virgules sont obligatoires.
288                             </listitem>
289                             <listitem>Dans une affectation distributive, il doit
290                                 y avoir <emphasis role="italic">au plus</emphasis>
291                                 autant de récipients que de sources de données provenant du terme de
292                                 droite, pas plus. S'il y moins de récipients à gauche que de sources
293                                 à droite, les sources non collectées sont ignorées. Exemples :
294                                 <simplelist>
295                                     <member><literal>[a,b] = (%pi,"Hi", %z)</literal>
296                                         est correct, mais <literal>%z</literal>
297                                         sera ignoré.
298                                     </member>
299                                     <member><literal>[a,b,c] = (%pi,"Hi")</literal>
300                                         produit une erreur, car <literal>c</literal>
301                                         attend du contenu.
302                                     </member>
303                                 </simplelist>                            </listitem>
304                             <listitem>
305                                 <literal>[a,b,a] = (%pi, %z, "Allo")</literal> réalise les
306                                 affectations de la gauche vers la droite, de sorte que finalement
307                                 <literal>a = "Allo"</literal>.
308                             </listitem>
309                         </itemizedlist>
310                     </para>
311                 </listitem>
312             </varlistentry>
313         </variablelist>
314     </refsection>
315     <refsection role="examples">
316         <title>Exemples</title>
317         <programlisting role="example"><![CDATA[
318 // Concaténation horizontale
319 a = [ %pi 4 -1 ]
320 b1 = grand(3,4,"uin",0,10)
321 b2 = grand(3,2,"uin",0,10)
322 b = [b1 b2]  // b1, b2.. doivent avoir le même nombre de lignes
323
324 // Concaténation verticale
325 a = [-2 ; 10 ; 7]
326
327 b1 = grand(2,4,"uin",0,10)
328 b2 = grand(3,4,"uin",0,10)
329 b = [b1 ; b2] // // b1, b2.. doivent avoir le même nombre de colonnes
330
331 // Double concaténation horizontale et verticale
332 a = [ 3 7 ; 6, 5 ]
333 b = [ 1:3 ; 7:3:13]
334 c = [ a b ; a b]
335
336 d = [ 3 5
337       1 4
338     ]
339 e = [ d d d
340       d d d
341     ]
342 // Concaténation de types d'objets variés :
343 ['this is' ; 'a column' ; 'of texts']
344
345 s = poly(0,'s');[1/s,2/s]
346 [tf2ss(1/s),tf2ss(2/s)]
347
348 [%t %f %f %T %F]
349
350 // Concaténation d'objets de types compatibles différents, avec transtypages automatiques
351 [%T int8(-5)]
352 [%T %pi %f 2]
353 [%pi, 2+%i, %F]
354 v = [%pi+0*%i, %F, %z, (1-%z)^2 ]; typeof(v), isreal(v)
355 v = [10 1/%z], typeof(v)
356
357 // Concaténations hétérogènes d'objets de types incompatibles => ERREURS
358 [%F %z]
359 [int8(%pi) uint8(%e)]
360 [int8(%pi) int16(%e)]
361 [int8(%pi) %e]
362
363 // Concaténation de tableaux de cellules :
364 c1 = {%pi %t};
365 c2 = {%z "abc"};
366 c = [[{%i} c1] ; [c2, {1/%z^2}]]  // virgule obligatoire sinon c2{1/%z^2} => erreur
367  ]]></programlisting>
368
369         <para>
370             <emphasis role="bold">Affectations distributives :</emphasis>
371         </para>
372         <programlisting role="example"><![CDATA[
373 // Variables des réponses d'une function.
374 // Elles sont le plus souvent optionnelles, l'une après l'autre
375 M = rand(3,3);
376 [u, s] = schur(M) // Nous attendons et utilisons à la fois u et s
377 u = schur(M)      // Nous attendons et stockons uniquement u
378
379 // Liste directe (implicite) d'objets à affecter
380 [a, b, c] = (%pi, %t, "test")
381 [a, b] = (%e, %f, "Hello")
382 [a, b, a] = (%pi, %t, "test"); a
383
384 // Liste explicite d'objets à affecter
385 L = list(%z, %i, %t, %pi, "Text");
386 [a, b, c] = L(:)
387
388 // Tableau de structures :
389 // Sélection de certaines cellules et affectation de leurs contenus
390 s(2,3).r = %pi; s(2,1).r = %i; s(2,2) = %e;
391 s(2,:).r
392 s.r([2 4 6])
393 [a, b, c] = s.r([2 4 6])
394
395 // Expressions gauches interdites et rejetées (=> erreur)
396 [m, n, m+n] = myfun(a,b) // "m+n" est une expression, non un nom de variable.
397 [p, 4.5, q] = myfun(a,b) // "4.5 est une valeur littérale, non un nom de variable.
398 [r, s+3 ] = myfun(a,b)   // "s+3" est une expression mixte, non un nom de variable
399  ]]></programlisting>
400         <screen><![CDATA[--> [a, b, c] = (%pi, %t, "test")
401  a  =
402    3.1415927
403
404  b  =
405   T
406
407  c  =
408  test
409
410 --> [a, b] = (%e, %f, "Hello")
411  a  =
412    2.7182818
413
414  b  =
415   F
416
417 --> [a, b, a] = (%pi, %t, "test"); a
418  a  =
419  test
420 ]]></screen>
421     </refsection>
422     <refsection role="see also">
423         <title>Voir aussi</title>
424         <simplelist type="inline">
425             <member>
426                 <link linkend="cat">cat</link>
427             </member>
428             <member>
429                 <link linkend="lstcat">lstcat</link>
430             </member>
431             <member>
432                 <link linkend="comma">comma</link>
433             </member>
434             <member>
435                 <link linkend="semicolon">semicolon</link>
436             </member>
437             <member>
438                 <link linkend="parentheses">parentheses</link>
439             </member>
440             <member>
441                 <link linkend="empty">empty</link>
442             </member>
443             <member>
444                 <link linkend="overloading">overloading</link>
445             </member>
446         </simplelist>
447     </refsection>
448     <refsection role="history">
449         <title>Historique</title>
450         <revhistory>
451             <revision>
452                 <revnumber>6.0</revnumber>
453                 <revdescription>
454                     Crochets <literal>[..]</literal> et accolades <literal>{..}</literal> ont
455                     désormais des fonctions distinctes.
456                 </revdescription>
457             </revision>
458             <revision>
459                 <revnumber>6.1</revnumber>
460                 <revdescription>
461                     <itemizedlist>
462                         <listitem>
463                             Booléens et entiers encodés peuvent désormais être concaténés ensemble,
464                             comme dans [%t, int8(-5)].
465                         </listitem>
466                         <listitem>
467                             [a, b, ..] = (A, B,..) réalise désormais les affectations de la gauche
468                             vers la droite.
469                         </listitem>
470                     </itemizedlist>
471                 </revdescription>
472             </revision>
473         </revhistory>
474     </refsection>
475 </refentry>