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>