[doc] gettext printf_conversion mprintf msprintf mfprintf pages updated & fixed
[scilab.git] / scilab / modules / output_stream / help / pt_BR / printf_conversion.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) XXXX-2008 - INRIA
5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2021 - 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:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
19           xmlns:scilab="http://www.scilab.org" xml:id="printf_conversion" xml:lang="pt">
20     <refnamediv>
21         <refname>printf_conversion</refname>
22         <refpurpose>Especificações de conversão de mprintf, msprintf,
23             mfprintf
24         </refpurpose>
25     </refnamediv>
26     <refsection>
27         <title>Descrição</title>
28         <para>Cada especificação de conversão no parâmetro format de
29             <literal>mprintf</literal> , <literal>msprintf</literal> ,
30             <literal>mfprintf</literal> possui a seguinte sintaxe:
31         </para>
32         <itemizedlist>
33             <listitem>
34                 <para>Um sinal % (porcento).</para>
35             </listitem>
36             <listitem>
37                 <para>
38                     An optional integer n ≥ 1 followed by "$". n is the index of the input data
39                     to substitute to the placeholder, in the msprintf, mprintf .. list of input data.
40                     In a format string, placeholders are either all numbered or all non-numbered.
41                     A given numbered placeholder can be used only once in its C-format string
42                     (Scilab limitation).
43                 </para>
44             </listitem>
45             <listitem>
46                 <para>
47                     Zero ou mais <literal>options</literal> (opções), que modificam
48                     o significado da especificação de conversão. A lista seguinte contem
49                     os caracteres <literal>option</literal> e seus significados:
50                 </para>
51                 <table>
52                     <tr>
53                         <th>- :</th>
54                         <td>
55                             Alinhe à esquerda, dentro do campo, o resultado da conversão.
56                         </td>
57                     </tr>
58                     <tr>
59                         <th>+ :</th>
60                         <td>
61                             Comece o resultado de uma conversão com sinal com um sinal (+ ou -).
62                         </td>
63                     </tr>
64                     <tr>
65                         <td style="white-space:nowrap"><emphasis role="bold">' ' :</emphasis></td>
66                         <td>
67                             (space) Prefixe um caractere de espaço ao resultado se o primeiro
68                             caractere de uma conversão com sinal não for um sinal. Se ambas as
69                             opções (espaço) e + aparecerem, a opção (space) é ignorada.
70                         </td>
71                     </tr>
72                     <tr>
73                         <th># :</th>
74                         <td>
75                             Converta o valor para uma forma alternativa. Para as conversões
76                             <literal>c</literal>, <literal>d</literal>, <literal>i</literal>,
77                             <literal>s</literal>, e <literal>u</literal>, a opção
78                             <literal>#</literal> não possui efeito. Para a conversão
79                             <literal>o</literal>, <literal>#</literal> aumenta a precisão para
80                             forçar o primeiro dígito do resultado a ser 0 (zero). Para as
81                             conversões <literal>x</literal> e <literal>X</literal>, um valor
82                             não-nulo possui 0x ou 0X prefixado a ele. Para as conversões
83                             <literal>e, E, f, g,</literal> e <literal>G</literal>, o resultado
84                             sempre contém ponto decimal, Mesmo que nenhum dígito o siga. Para as
85                             conversões <literal>g</literal> e <literal>G</literal>, zeros por
86                             último não são removidos.
87                         </td>
88                     </tr>
89                     <tr>
90                         <th>0 :</th>
91                         <td>
92                             Aumente a largura do campo utilizando zeros à esquerda (seguindo
93                             qualquer indicação de sinal ou base) para as conversões
94                             <literal>d</literal>, <literal>i</literal>, <literal>o</literal>,
95                             <literal>u</literal>, <literal>x</literal>, <literal>X</literal>,
96                             <literal>e</literal>, <literal>E</literal>, <literal>f</literal>,
97                             <literal>g</literal>, e <literal>G</literal>; nenhum aumento de espaço
98                             é realizado. Se ambos os indicadores <literal>0</literal> e
99                             <literal>\-</literal> (barra) aparecerem, o indicador
100                             <literal>0</literal> é ignorado. Para as conversões
101                             <literal>d</literal>, <literal>i</literal>, <literal>o</literal>
102                             <literal>u</literal>, <literal>x</literal>, e <literal>X</literal>, se
103                             uma precisão for especificada, o indicador <literal>0</literal> também
104                             é ignorado.
105                         </td>
106                     </tr>
107                 </table>
108             </listitem>
109             <listitem>
110                 <para>Um string de dígitos decimais opcional que especifica a largura
111                     mínima do campo. Se o valor convertido tiver menos caracteres que a
112                     largura do campo, o campo é aumentado à esquerda até o comprimento
113                     especificado pela largura do campo. Se a opção de ajuste à esquerda for
114                     especificada, o campo é aumentado pela direita.
115                 </para>
116             </listitem>
117             <listitem>
118                 <para>
119                     Uma precisão opcional. A precisão é um ponto <literal>.</literal>
120                     seguido por um string de dígito decimal. Se nenhuma precisão for
121                     fornecida, o parâmetro é tratado como 0 (zero). A precisão
122                     especifica:
123                 </para>
124                 <itemizedlist>
125                     <listitem>
126                         O número mínimo de dígitos a aparecerem nas conversões
127                         <literal>d</literal>, <literal>u</literal>, <literal>o</literal>,
128                         <literal>x</literal>, ou <literal>X</literal>.
129                     </listitem>
130                     <listitem>
131                         O número de dígitos a aparecerem após o ponto decimal nas
132                         conversões <literal>e</literal>, <literal>E</literal>, e
133                         <literal>f</literal>.
134                     </listitem>
135                     <listitem>
136                         O número máximo de dígitos significativos para as conversões
137                         <literal>g</literal> e <literal>G</literal>.
138                     </listitem>
139                     <listitem>
140                         O número máximo de caracteres a serem impressos a partir de um
141                         string em uma convesão <literal>s</literal>.
142                     </listitem>
143                 </itemizedlist>
144             </listitem>
145             <listitem>
146                 <para>O caractere que indica o tipo de conversão a ser
147                     aplicada:
148                 </para>
149                 <table>
150                     <tr>
151                         <th>% :</th>
152                         <td>
153                             Não realiza conversão. Exibe %..
154                             <note>
155                                 This may be useful for instance to print percentages, or
156                                 to process some LaTeX expression including LaTeX comments
157                                 starting with "%", etc.
158                             </note>
159                         </td>
160                     </tr>
161                     <tr>
162                         <th>s :</th>
163                         <td>
164                             Accepts a string or boolean <literal>value</literal> e exibe caracteres
165                             do string até o fim ou até que o número de caracteres indicados pela
166                             precisão seja alcançado. Se nenhuma precisão for especificada, todos os
167                             caracteres até o fim são exibidos.
168                             UTF-8 extended characters are supported in input strings.
169                             Booleans are converted into 'T' or 'F'.
170                         </td>
171                     </tr>
172                     <tr>
173                         <th>c :</th>
174                         <td>Not supported.
175                         </td>
176                     </tr>
177                     <tr>
178                         <td colspan="2">
179                             All following conversions accept any decimal numerical or boolean
180                             input <literal>value</literal>. Only the real part of any input
181                             complex number is considered. Booleans are implicitly converted
182                             into 0 and 1.
183                         </td>
184                     </tr>
185                     <tr>
186                         <th>d,i :</th>
187                         <td>
188                             Converts the input <literal>value</literal> to a signed integer int32
189                             notation. Conversions for input |Numbers| ≥ 2^31 are not reliable.
190                             A precisão especifica o número mínimo de dígitos a aparecer. Se
191                             o valor sendo convertido puder ser representado em menos dígitos, ele
192                             é expandido com zeros à esquerda. A precisão padrão é 1. O resultado
193                             de se converter um valor zero com uma precisão de zero é um string
194                             nulo. A especificação de uma largura de campo com zero como caractere
195                             mais à esquerda faz com que o valor da largura do campo seja
196                             preenchido com zeros à esquerda.
197                         </td>
198                     </tr>
199                     <tr>
200                         <th>u :</th>
201                         <td>
202                             Converts the input <literal>value</literal> to an unsigned integer
203                             uint32 notation. Conversions for input |Numbers| ≥ 2^32 are not reliable.
204                             A precisão especifica o número mínimo de dígitos a aparecer. Se
205                             o valor sendo convertido puder ser representado em menos dígitos, ele
206                             é expandido com zeros à esquerda. A precisão padrão é 1. O resultado
207                             de se converter um valor zero com uma precisão de zero é um string
208                             nulo. A especificação de uma largura de campo com zero como caractere
209                             mais à esquerda faz com que o valor da largura do campo seja
210                             preenchido com zeros à esquerda.
211                         </td>
212                     </tr>
213                     <tr>
214                         <th>o :</th>
215                         <td>
216                             Converts the input <literal>value</literal> to an unsigned octal notation.
217                             Conversions for input |Numbers| ≥ 2^32 are not reliable.
218                             A precisão especifica o número mínimo de dígitos a
219                             aparecer. Se o valor sendo convertido puder ser representado em menos
220                             dígitos, ele é expandido com zeros à esquerda. A precisão padrão é 1.
221                             O resultado de se converter um valor zero com uma precisão de zero é
222                             um string nulo. A especificação de uma largura de campo com zero como
223                             caractere mais à esquerda faz com que o valor da largura do campo seja
224                             preenchido com zeros à esquerda. Não é implicado um valor octal para a
225                             largura do campo.
226                         </td>
227                     </tr>
228                     <tr>
229                         <th>x, X :</th>
230                         <td>
231                             Converts the input <literal>value</literal> to an unsigned hexadecimal
232                             notation. Conversions for input |Numbers| ≥ 2^32 are not reliable.
233                             As letras ``abcdef'' são utilizadas para a
234                             conversão <literal>x</literal>; as letras ``ABCDEF'' são utilizadas
235                             para a conversão <literal>X</literal>. A precisão especifica o número
236                             mínimo de dígitos a aparecer. Se o valor sendo convertido puder ser
237                             representado em menos dígitos, ele é expandido com zeros à esquerda. A
238                             precisão padrão é 1. O resultado de se converter um valor zero com uma
239                             precisão de zero é um string nulo. A especificação de uma largura de
240                             campo com zero como caractere mais à esquerda faz com que o valor da
241                             largura do campo seja preenchido com zeros à esquerda.
242                         </td>
243                     </tr>
244                     <tr>
245                         <th>f :</th>
246                         <td>
247                             Converte o <literal>value</literal> de entrada para a sua notação decimal
248                             no formato% [\-]<literal>ddd.ddd</literal>.
249                             O número de dígitos após o ponto decimal é igual à especificação de
250                             precisão.
251                             <itemizedlist>
252                                 <listitem>
253                                     Se nenhuma precisão for especificada, a saída possui seis dígitos
254                                 </listitem>
255                                 <listitem>
256                                     Se a precisão for zero, nenhum ponto decimal aparece e o sistema
257                                     imprime na saída o valor inteiro mais próximo de
258                                     <literal>value</literal>.
259                                 </listitem>
260                                 <listitem>
261                                     Se a saída possui um ponto decimal, pelo menos um dígito é posto
262                                     antes dele.
263                                 </listitem>
264                             </itemizedlist>
265                         </td>
266                     </tr>
267                     <tr>
268                         <th>e, E :</th>
269                         <td>
270                             Converte o <literal>value</literal> de entrada para a sua forma exponencial
271                             %[\-]<literal>d.ddde</literal>+/\-<literal>dd</literal>.
272                             Há um dígito antes do ponto decimal, e o número de dígitos após o
273                             ponto decimal é igual à especificação de precisão.
274                             <itemizedlist>
275                                 <listitem>
276                                     Se nenhuma precisão for especificada, a saída são seis dígitos.
277                                 </listitem>
278                                 <listitem>
279                                     Se a precisão for zero, nenhum ponto decimal aparece.
280                                 </listitem>
281                                 <listitem>
282                                     A caractere de conversão <literal>E</literal> produz um
283                                     número com o caractere 'E', ao invés de 'e' antes do expoente.
284                                     O expoente sempre contém pelo menos dois dígitos. Se o valor
285                                     for zero, o expoente é zero.
286                                 </listitem>
287                             </itemizedlist>
288                         </td>
289                     </tr>
290                     <tr>
291                         <td style="white-space:nowrap"><emphasis role="bold">g, G :</emphasis></td>
292                         <td>
293                             Converte o <literal>value</literal> de entrada no estilo dos caracteres
294                             de conversão <literal>e</literal>, <literal>E</literal>, ou
295                             <literal>f</literal>, com a precisão especificando o número de dígitos
296                             significativos.
297                             Zeros por último são removidos. Um ponto decimal
298                             aparece apenas se for seguido de um dígito. O estilo depende do valor
299                             convertido. O resultado é o estilo <literal>e</literal>
300                             (<literal>E</literal>, se <literal>G</literal> é o indicador
301                             utilizado) apenas se o expoente resultante da conversão for menor do
302                             que -4, ou se for maior do que ou igual à precisão.
303                         </td>
304                     </tr>
305                 </table>
306             </listitem>
307         </itemizedlist>
308         <para>Uma largura de campo ou uma precisão podem ser indicadas por
309             <literal>*</literal> (asterísco) ao invés de um string de dígito. Neste
310             caso, um parâmetro de valor inteiro provê a largura do campo ou a
311             precisão. O parâmetro de valor convertido para saída não é buscado até que
312             a letra de conversão seja alcançada, então os parâmetros especificando o
313             comprimento de campo ou precisão devem aparecer antes do valor a ser
314             convertido (se houver algum).
315         </para>
316         <para>Se o resultado da conversão for maior que a largura do campo, o
317             campo é expandido para conter o resultado convertido.
318         </para>
319         <para>A representação do sinal de mais depende da opção de formatação
320             especificada, se <literal>+</literal> ou (espaço).
321         </para>
322         <para>
323             Display of exponential form %e is platform dependent with a different number of digits
324             in exponent.
325             <informaltable border="1">
326                 <tr>
327                     <td>Platform</td>
328                     <td>Example: msprintf("%e",1.23e4)</td>
329                 </tr>
330                 <tr>
331                     <td>Windows</td>
332                     <td>1.23000e+004</td>
333                 </tr>
334                 <tr>
335                     <td>Linux/Mac OS</td>
336                     <td>1.23000e+04</td>
337                 </tr>
338             </informaltable>
339         </para>
340         <para>
341             <emphasis role="bold">Special escaped sequences</emphasis> are supported in Scilab
342             C-format strings:
343             <table>
344                 <tr>
345                     <th>\n :</th>
346                     <td>Go to Next line (line feed)</td>
347                 </tr>
348                 <tr>
349                     <th>\r :</th>
350                     <td>Return: go to the head of current line (for overprinting)</td>
351                 </tr>
352                 <tr>
353                     <th>\t :</th>
354                     <td>horizontal Tab</td>
355                 </tr>
356                 <tr>
357                     <th>\\ :</th>
358                     <td>print a backslash \</td>
359                 </tr>
360             </table>
361         </para>
362     </refsection>
363     <refsection>
364         <title>Exemplos</title>
365         <programlisting role="example"><![CDATA[
366 mprintf('a string: %s\n', 'Scilab');
367 mprintf('an integer: %d\n', 10);
368 mprintf('an integer: %4d\n', 10);
369 mprintf('a left justified integer: %-4d\n', 10);
370 mprintf('an integer converted to float: %#fd\n',10);
371 mprintf('an integer with a sign: %+4d\n', 10);
372 mprintf('an integer with a sign: %+4d\n', -10);
373 mprintf('an integer padded with zeros: %04d\n', 10);
374 mprintf('an unsigned integer: %u\n', 10);
375 mprintf('an unsigned integer: %4u\n', -10);
376 mprintf('an integer converted to hexadecimal: %x\n', 10);
377 mprintf('a float: %d\n', %pi);
378 mprintf('a float: %3.2d\n', %pi);
379 mprintf('a float (exponential form): %3.2e\n', %pi);
380 mprintf('a float (exponential form): %3.2g\n', %pi);
381 mprintf('a character: %c\n', 'a');
382 mprintf('a character: %c\n', 'aaa');
383  ]]></programlisting>
384         <para/>
385         <para>
386             With input booleans:
387         </para>
388         <programlisting role="example"><![CDATA[
389 mprintf("\n%%d: %d,  %%u: %u,  %%o: %o,  %%f: %f,  %%e: %e,  %%s: %s\n" + ..
390           "%%d: %d,  %%u: %u,  %%o: %o,  %%f: %f,  %%e: %e,  %%s: %s\n", ..
391         %T, %T, %T, %T, %T, %T, %F, %F, %F, %F, %F, %F);
392      ]]></programlisting>
393         <screen><![CDATA[
394 %d: 1,  %u: 1,  %o: 1,  %f: 1.000000,  %e: 1.000000e+00,  %s: T
395 %d: 0,  %u: 0,  %o: 0,  %f: 0.000000,  %e: 0.000000e+00,  %s: F
396 ]]></screen>
397         <para/>
398         <para>
399             With numbered placeholders:
400         </para>
401         <programlisting role="example"><![CDATA[
402 mprintf("%2$s is %1$d-year old.\n", 32, "Peter");
403      ]]></programlisting>
404         <screen><![CDATA[
405 Peter is 32-year old.
406 ]]></screen>
407         <para/>
408         <para>
409             With escaped sequences and UTF-8 extended characters:
410         </para>
411         <programlisting role="example"><![CDATA[
412 mprintf("The path T:\\abc does not exist.\n");
413 mprintf("abcdefghijk\tαβδ\tεϵ\tζηθικλ\rABCDE\n");
414      ]]></programlisting>
415         <screen><![CDATA[
416 --> mprintf("The path T:\\abc does not exist.\n");
417 The path T:\abc does not exist
418
419 --> mprintf("abcdefghijk\tαβδ\tεϵ\tζηθικλ\rABCDE\n");
420 ABCDEfghijk αβδ εϵ  ζηθικλ
421 ]]></screen>
422     </refsection>
423     <refsection role="see also">
424         <title>Ver Também</title>
425         <simplelist type="inline">
426             <member>
427                 <link linkend="mprintf">mprintf</link>
428             </member>
429             <member>
430                 <link linkend="mfprintf">mfprintf</link>
431             </member>
432             <member>
433                 <link linkend="msprintf">msprintf</link>
434             </member>
435         </simplelist>
436     </refsection>
437     <refsection role="history">
438         <title>Histórico</title>
439         <revhistory>
440             <revision>
441                 <revnumber>6.1.0</revnumber>
442                 <revdescription>
443                     Numbered placeholders "%n$.." are supported.
444                 </revdescription>
445             </revision>
446             <revision>
447                 <revnumber>6.1.1</revnumber>
448                 <revdescription>
449                     Input boolean data can be converted.
450                 </revdescription>
451             </revision>
452         </revhistory>
453     </refsection>
454 </refentry>