archived-doc-pt-br/reference/strings/functions/sprintf.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 45042fef652f1b4e904e809fcbfcf31f6c60670b Maintainer: leonardolara Status: ready --><!-- CREDITS: leonardolara -->
<refentry xml:id="function.sprintf" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>sprintf</refname>
  <refpurpose>Retona uma string formatada</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>sprintf</methodname>
   <methodparam><type>string</type><parameter>format</parameter></methodparam>
   <methodparam rep="repeat"><type>mixed</type><parameter>values</parameter></methodparam>
  </methodsynopsis>
  <para>
   Retorna uma string produzida de acordo com a string de formatação informada no parâmetro
   <parameter>format</parameter>.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    &strings.parameter.format;
    <varlistentry>
     <term><parameter>values</parameter></term>
     <listitem>
      <para>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Retorna uma string produzida de acordo com a string de formatação informada no parâmetro
   <parameter>format</parameter>.
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  &strings.errors.sprintf;
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  &strings.changelog.sprintf;
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title>Troca de ordem dos argumentos</title>
   <para>
    A string de formatação suporta troca/numeração de argumentos.
   </para>
   <programlisting role="php">
    <![CDATA[
<?php
$num = 5;
$location = 'árvore';

$format = 'Há %d macacos na %s';
echo sprintf($format, $num, $location);
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
Há 5 macacos na árvore
]]>
   </screen>
  </example>
  <para>
   Entretanto imagine que uma string de formatação está sendo criada em um arquivo separado,
   normalmente porque ele poderia ser internacionalizado e seria re-escrito como:
  </para>
  <example>
   <title>Ordem incorreta de argumentos</title>
   <para>
    A string de formato suporta numeração/troca de argumentos.
   </para>
   <programlisting role="php">
    <![CDATA[
<?php
$num = 5;
$location = 'árvore';

$format = 'A %s contém %d macacos';
echo sprintf($format, $num, $location);
?>
]]>
   </programlisting>
  </example>
  <para>
   Agora existe um problema. A ordem dos marcadores na
   string de formatação não corresponde à ordem dos argumentos no
   código. O código poderia ser deixado inalterado e na string de formatação
   poderiam ser indicados a que argumentos os marcadores se referem.
   A string de formatação seria então escrita assim:
  </para>

  <example>
   <title>Usando marcador de ordenação</title>
   <programlisting role="php">
    <![CDATA[
<?php
$num = 5;
$location = 'árvore';

$format = 'A %2$s contém %1$d macacos';
echo sprintf($format, $num, $location);
?>
]]>
   </programlisting>
  </example>

  <para>
   Uma vantagem adicional é que os marcadores podem ser repetidos sem adicionar
   mais argumentos no código.
  </para>

  <example>
   <title>Marcador repetido</title>
   <programlisting role="php">
    <![CDATA[
<?php
$num = 5;
$location = 'árvore';

$format = 'A %2$s contém %1$d macacos.
           É uma bela %2$s cheia de %1$d macacos.';
echo sprintf($format, $num, $location);
?>
]]>
   </programlisting>
  </example>

  <para>
   Ao usar troca ordem de argumentos, o <emphasis>especificador de posição</emphasis>
   <literal>n$</literal> precisa vir imediatamente
   depois do símbolo de porcentagem (<literal>%</literal>) e antes de qualquer outro
   especificador, como mostrado abaixo.
  </para>

  <example>
   <title>Especificando caractere de preenchimento</title>
   <programlisting role="php">
<![CDATA[
<?php
echo sprintf("%'.9d\n", 123);
echo sprintf("%'.09d\n", 123);
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
......123
000000123
]]>
   </screen>
  </example>

  <example>
   <title>Especificador de posição com outros especificadores</title>
   <programlisting role="php">
<![CDATA[
<?php
$num = 5;
$location = 'árvore';

$format = 'A %2$s contém %1$04d macacos';
echo sprintf($format, $num, $location);
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
A árvore contém 0005 macacos
]]>
   </screen>
  </example>

  <example>
   <title><function>sprintf</function>: inteiros preenchidos com zero à esquerda</title>
   <programlisting role="php">
<![CDATA[
<?php
$year = 2005;
$month = 5;
$day = 6;

$isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);
echo $isodate, PHP_EOL;
?>
]]>
   </programlisting>
  </example>

  <example>
   <title><function>sprintf</function>: formatando moeda</title>
   <programlisting role="php">
<![CDATA[
<?php
$money1 = 68.75;
$money2 = 54.35;
$money = $money1 + $money2;
echo $money, PHP_EOL;

$formatted = sprintf("%01.2f", $money);
echo $formatted, PHP_EOL;
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
123.1
123.10
]]>
   </screen>
  </example>
  <example>
   <title><function>sprintf</function>: notação científica</title>
   <programlisting role="php">
<![CDATA[
<?php
$number = 362525200;

echo sprintf("%.3e", $number), PHP_EOL;
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
3.625e+8
]]>
   </screen>
  </example>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>printf</function></member>
    <member><function>fprintf</function></member>
    <member><function>vprintf</function></member>
    <member><function>vsprintf</function></member>
    <member><function>vfprintf</function></member>
    <member><function>sscanf</function></member>
    <member><function>fscanf</function></member>
    <member><function>number_format</function></member>
    <member><function>date</function></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->