* Bug 16450 fixed: [double, integer] & [double ; integer] implemented
[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 - 2020 - 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é &lt; nombre décimal &lt; nombre complexe
176                                 </listitem>
177                                 <listitem>décimal &lt; polynôme &lt; fraction rationelle
178                                     <warning>
179                                         Les booléens et les polynômes ne sont pas compatibles entre
180                                         eux :
181                                         <itemizedlist>
182                                             <listitem>
183                                                 <literal>[%t 2. %z]</literal> est accepté, car :
184                                                 <literal>[%t 2.]</literal> est d'abord converti en
185                                                 <literal>[1. 2.]</literal>, puis
186                                                 <literal>[[1. 2.] %z]</literal> est accepté.
187                                             </listitem>
188                                             <listitem>
189                                                 <literal>[%z %t 2.]</literal> est refusé et produit
190                                                 une erreur. En effet, <literal>[%z %t]</literal>
191                                                 n'est pas permis et bloque la suite.
192                                             </listitem>
193                                         </itemizedlist>
194                                     </warning>
195                                 </listitem>
196                                 <listitem>
197                                     Tout entier encodé peut être concaténé uniquement avec des
198                                     booléens, des nombres réels ou complexes, ou d'autres entiers
199                                     du même type entier
200                                     (<link linkend="inttype">inttype</link>). Ainsi, les expressions
201                                     <literal>[int8(2) uint8(7)]</literal>,
202                                     <literal>[int8(2) int16(7)]</literal>,
203                                     <literal>[int8(2), 7+0*%z]</literal>,
204                                     <literal>[int8(2), sparse(7)]</literal>, ou
205                                     <literal>[int8(2), sparse(%t)]</literal>
206                                     produiront toutes une erreur.
207                                 </listitem>
208                                 <listitem>
209                                     Le résultat est encodé en valeurs complexes (avec parties
210                                     imaginaires éventuellement nulles) dés qu'un élément
211                                     -- valeur, polynôme, ou fraction rationnelle -- à valeur
212                                     complexe est rencontré.
213                                     <para>
214                                         De même, le résultat est encodé sous forme creuse dés qu'un
215                                         élément encodé creux est rencontré.
216                                     </para>
217                                 </listitem>
218                                 <listitem>
219                                     Des polynômes ou des fractions rationnelles de différentes
220                                     variables peuvent être concaténés entre eux. Le premier polynôme
221                                     ou fraction rationnelle listé donne alors le nom de sa variable
222                                     au résultat de la concaténation :
223                                     <literal>[%z, 1+%s, 1-%i*%s]
224                                         // => [z, 1+z, 1-iz]
225                                     </literal>.
226                                 </listitem>
227                                 <listitem>
228                                     Les éléments de texte (type "string") peuvent être concaténés
229                                     (au sens ensembliste, avec les crochets) uniquement entre eux
230                                     ou avec la matrice vide
231                                 <literal>[]</literal>.
232                                 </listitem>
233                             </orderedlist>
234                         </para>
235                     </refsect3>
236                     <refsect3 id="brackets_overloading">
237                         <title>Surcharge</title>
238                         <para>
239                             <itemizedlist>
240                                 <listitem>[,]: concaténation horizontale : cet opérateur n-aire
241                                     (pouvant être appliqué à un nombre arbitraire n de données)
242                                     est en fait un opérateur binaire automatiquement itéré de la
243                                     gauche vers la droite. Son code de surcharge est
244                                     <literal>"c"</literal>.
245                                 </listitem>
246                                 <listitem>
247                                     [;]: la concaténation verticale est également un opérateur
248                                     binaire, itéré du haut vers le bas. Son code de surcharge est
249                                     <literal>"f"</literal>.
250                                 </listitem>
251                             </itemizedlist>
252                         </para>
253                     </refsect3>
254                     <para/>
255                     <refsect3>
256                         <title>Extensions</title>
257                         <para>
258                           <itemizedlist>
259                             <listitem>
260                               Pour concaténer des listes simples, utiliser <link linkend="lstcat">lstcat</link>.
261                             </listitem>
262                             <listitem>
263                               Pour assembler des vecteurs ou matrices ou hypermatrices ou autres
264                               tableaux selon une dimension > 2 et construire un hypertableau à N
265                               dimensions, utiliser <link linkend="cat">cat</link>.
266                             </listitem>
267                           </itemizedlist>
268                         </para>
269                     </refsect3>
270                 </listitem>
271             </varlistentry>
272             <varlistentry>
273                 <term>[] figurant à gauche d'une affectation <literal>"="</literal></term>
274                 <listitem>
275                     <para>
276                         Dans ce cas, les crochets ne désignent en rien une concaténation. Ils
277                         délimitent une série de variables servant de récipients.
278                     </para>
279                     <para>
280                         <itemizedlist>
281                             <listitem>
282                                 Les termes entre crochets doivent alors impérativement être des
283                                 variables. Les expressions litérales ou symboliques sont rejetées.
284                             </listitem>
285                             <listitem>
286                                 Les variables sont séparées par des virgules ou des espaces.
287                                 Lorsqu'il s'agit de la liste des arguments de sortie d'une function,
288                                 les virgules sont obligatoires.
289                             </listitem>
290                             <listitem>Dans une affectation distributive, il doit
291                                 y avoir <emphasis role="italic">au plus</emphasis>
292                                 autant de récipients que de sources de données provenant du terme de
293                                 droite, pas plus. S'il y moins de récipients à gauche que de sources
294                                 à droite, les sources non collectées sont ignorées. Exemples :
295                                 <simplelist>
296                                     <member><literal>[a,b] = (%pi,"Hi", %z)</literal>
297                                         est correct, mais <literal>%z</literal>
298                                         sera ignoré.
299                                     </member>
300                                     <member><literal>[a,b,c] = (%pi,"Hi")</literal>
301                                         produit une erreur, car <literal>c</literal>
302                                         attend du contenu.
303                                     </member>
304                                 </simplelist>                            </listitem>
305                             <listitem>
306                                 <literal>[a,b,a] = (%pi, %z, "Allo")</literal> réalise les
307                                 affectations de la gauche vers la droite, de sorte que finalement
308                                 <literal>a = "Allo"</literal>.
309                             </listitem>
310                         </itemizedlist>
311                     </para>
312                 </listitem>
313             </varlistentry>
314         </variablelist>
315     </refsection>
316     <refsection role="examples">
317         <title>Exemples</title>
318         <programlisting role="example"><![CDATA[
319 // Concaténation horizontale
320 a = [ %pi 4 -1 ]
321 b1 = grand(3,4,"uin",0,10)
322 b2 = grand(3,2,"uin",0,10)
323 b = [b1 b2]  // b1, b2.. doivent avoir le même nombre de lignes
324
325 // Concaténation verticale
326 a = [-2 ; 10 ; 7]
327
328 b1 = grand(2,4,"uin",0,10)
329 b2 = grand(3,4,"uin",0,10)
330 b = [b1 ; b2] // // b1, b2.. doivent avoir le même nombre de colonnes
331
332 // Double concaténation horizontale et verticale
333 a = [ 3 7 ; 6, 5 ]
334 b = [ 1:3 ; 7:3:13]
335 c = [ a b ; a b]
336
337 d = [ 3 5
338       1 4
339     ]
340 e = [ d d d
341       d d d
342     ]
343 // Concaténation de types d'objets variés :
344 ['this is' ; 'a column' ; 'of texts']
345
346 s = poly(0,'s');[1/s,2/s]
347 [tf2ss(1/s),tf2ss(2/s)]
348
349 [%t %f %f %T %F]
350      ]]></programlisting>
351         <para>
352             Concaténation d'objets de types distincts compatibles, avec
353             transtypages automatiques
354         </para>
355         <programlisting role="example"><![CDATA[
356 [%T int8(-5)]
357 [%T %pi %f 2]
358 [%pi, 2+%i, %F]
359 [%pi int16(-1000.84) 1.23]
360 v = [%pi+0*%i, %F, %z, (1-%z)^2 ]; typeof(v), isreal(v)
361 v = [10 1/%z], typeof(v)
362
363 // Cas particulier : int16 et uint8 ensemble, finalement concaténés
364 //   par conversion décimale se propageant de gauche à droite :
365 [%pi int16(-1000.84) uint8(87)]
366      ]]></programlisting>
367         <para>
368             Concaténations hétérogènes d'objets de types incompatibles => ERREURS
369         </para>
370         <programlisting role="example"><![CDATA[
371 [%F %z]
372 [int8(%pi) uint8(%e)]
373 [int8(%pi) int16(%e)]
374 [int8(-70), sparse(18)]
375 [int8(-70), sparse([%T %F])]
376      ]]></programlisting>
377         <para>
378             Concaténation de tableaux de cellules :
379         </para>
380         <programlisting role="example"><![CDATA[
381 c1 = {%pi %t};
382 c2 = {%z "abc"};
383 c = [[{%i} c1] ; [c2, {1/%z^2}]]  // virgule obligatoire sinon c2{1/%z^2} => erreur
384  ]]></programlisting>
385
386         <para>
387             <emphasis role="bold">Affectations distributives :</emphasis>
388         </para>
389         <programlisting role="example"><![CDATA[
390 // Variables des réponses d'une function.
391 // Elles sont le plus souvent optionnelles, l'une après l'autre
392 M = rand(3,3);
393 [u, s] = schur(M) // Nous attendons et utilisons à la fois u et s
394 u = schur(M)      // Nous attendons et stockons uniquement u
395
396 // Liste directe (implicite) d'objets à affecter
397 [a, b, c] = (%pi, %t, "test")
398 [a, b] = (%e, %f, "Hello")
399 [a, b, a] = (%pi, %t, "test"); a
400
401 // Liste explicite d'objets à affecter
402 L = list(%z, %i, %t, %pi, "Text");
403 [a, b, c] = L(:)
404
405 // Tableau de structures :
406 // Sélection de certaines cellules et affectation de leurs contenus
407 s(2,3).r = %pi; s(2,1).r = %i; s(2,2) = %e;
408 s(2,:).r
409 s.r([2 4 6])
410 [a, b, c] = s.r([2 4 6])
411
412 // Expressions gauches interdites et rejetées (=> erreur)
413 [m, n, m+n] = myfun(a,b) // "m+n" est une expression, non un nom de variable.
414 [p, 4.5, q] = myfun(a,b) // "4.5 est une valeur littérale, non un nom de variable.
415 [r, s+3 ] = myfun(a,b)   // "s+3" est une expression mixte, non un nom de variable
416  ]]></programlisting>
417         <screen><![CDATA[--> [a, b, c] = (%pi, %t, "test")
418  a  =
419    3.1415927
420
421  b  =
422   T
423
424  c  =
425  test
426
427 --> [a, b] = (%e, %f, "Hello")
428  a  =
429    2.7182818
430
431  b  =
432   F
433
434 --> [a, b, a] = (%pi, %t, "test"); a
435  a  =
436  test
437 ]]></screen>
438     </refsection>
439     <refsection role="see also">
440         <title>Voir aussi</title>
441         <simplelist type="inline">
442             <member>
443                 <link linkend="cat">cat</link>
444             </member>
445             <member>
446                 <link linkend="lstcat">lstcat</link>
447             </member>
448             <member>
449                 <link linkend="comma">comma</link>
450             </member>
451             <member>
452                 <link linkend="semicolon">semicolon</link>
453             </member>
454             <member>
455                 <link linkend="parentheses">parentheses</link>
456             </member>
457             <member>
458                 <link linkend="empty">empty</link>
459             </member>
460             <member>
461                 <link linkend="overloading">overloading</link>
462             </member>
463         </simplelist>
464     </refsection>
465     <refsection role="history">
466         <title>Historique</title>
467         <revhistory>
468             <revision>
469                 <revnumber>6.0</revnumber>
470                 <revdescription>
471                     Crochets <literal>[..]</literal> et accolades <literal>{..}</literal> ont
472                     désormais des fonctions distinctes.
473                 </revdescription>
474             </revision>
475             <revision>
476                 <revnumber>6.1.0</revnumber>
477                 <revdescription>
478                     <itemizedlist>
479                         <listitem>
480                             Booléens et entiers encodés peuvent désormais être concaténés ensemble,
481                             comme dans [%t, int8(-5)].
482                         </listitem>
483                         <listitem>
484                             [a, b, ..] = (A, B,..) réalise désormais les affectations de la gauche
485                             vers la droite.
486                         </listitem>
487                     </itemizedlist>
488                 </revdescription>
489             </revision>
490             <revision>
491                 <revnumber>6.1.1</revnumber>
492                 <revdescription>
493                     Concaténer des entiers encodés avec des réels ou complexes
494                     est désormais possible.
495                 </revdescription>
496             </revision>
497         </revhistory>
498     </refsection>
499 </refentry>