<?xml version="1.0" encoding="iso-8859-1"?>
 <chapter id="functions">
  <title>Funes</title>

  <sect1 id="functions.user-defined">
   <title>Funes definidas pelo usurio</title>
 
   <para>
    Uma funo pode ser definida usando-se a sintaxe como a seguinte:
 
    <informalexample>
     <programlisting role="php">
function foo ($arg_1, $arg_2, ..., $arg_n) {
    echo "Funo-exemplo.\n";
    return $retval;
}
     </programlisting>
    </informalexample>
   </para>
     
   <simpara>
    Qualquer cdigo PHP vlido aparece dentro de uma funo, mesmo outras funes
    e definies de <link linkend="keyword.class">classes</link>.
   </simpara>
   <simpara>
    No PHP3, as funes precisam ser definidas antes de serem referenciadas. Esse
    requisito no existe no PHP4.
   </simpara>
   <simpara>
    O PHP no suporta sobrecarga de funes, e tambm no  possvel cancelar ou
    alterar a definio de funes previamente declaradas.
   </simpara>
   <simpara>
    O PHP3 no suporta nmero varivel de argumentos para funes, apesar de os 
    argumentos padres serem suportados (veja <link
    linkend="functions.arguments.default">Valores padro de argumentos
    </link> para mais informaes). O PHP4 suporta ambos: veja <link
    linkend="functions.variable-arg-list">Listas de argumentos com comprimento
    varivel</link> e as referncias de funo de
    <function>func_num_args</function>,
    <function>func_get_arg</function>, e
    <function>func_get_args</function> para mais informaes.
   </simpara>

  </sect1>
 
  <sect1 id="functions.arguments">
   <title>Argumentos de funes</title>
 
   <simpara>
    Informao pode ser passada para funes atravs da lista de argumentos, que  uma 
    lista de variveis e/ou constantes delimitados por vrgulas.
   </simpara> 
   <para>
     O PHP suporta a passagem de argumentos por valor (o padro), <link
     linkend="functions.arguments.by-reference">passagem por referncia
     </link>, e <link
     linkend="functions.arguments.default">valores padro de argumento
     </link>. Listas de argumentos de comprimento varivel so suportadas apenas
     no PHP4 e posteriores; veja <link
     linkend="functions.variable-arg-list">Listas de argumentos de comprimento 
     varivel</link> e as referncias de funo de
     <function>func_num_args</function>,
     <function>func_get_arg</function>, e
     <function>func_get_args</function> para mais informaes. Um efeito similar
     pode ser atingido no PHP3 pela passagem de uma matriz de argumentos para uma
     funo:
 
    <informalexample>
     <programlisting role="php">
function takes_array($input) {
    echo "$input[0] + $input[1] = ", $input[0]+$input[1];
}
     </programlisting>
    </informalexample>
   </para>
 
   <sect2 id="functions.arguments.by-reference">
    <title>Fazendo argumentos serem passados por referncia</title>
 
    <simpara>
     Por padro, argumentos de funo so passados por valor (de forma que se
     voc mudar o valor do argumento dentro da funo, ele no  mudado fora
     da funo). Se voc deseja permitir que uma funo modifique seus argumentos,
     voc precisa pass-los por referncia.
    </simpara>
    <para>
     Se voc quer que um argumento para uma funo sempre seja passado por
     referncia, voc pode preceder o nome do argumento com um "e comercial" (&amp;)
     na definio da funo:
 
     <informalexample>
      <programlisting role="php">
function add_some_extra(&amp;$string) {
    $string .= 'e algo mais.';
}
$str = 'Isto  uma string, ';
add_some_extra($str);
echo $str;    // outputs 'Isto  uma string, e algo mais.'
      </programlisting>
     </informalexample>
    </para>
 
    <para>
     Se voc deseja passar uma varivel por referncia a uma funo que no faz isto por
     padro, voc pode preceder o nome do argumento com um "e comercial" na chamada da
     funo:
 
     <informalexample>
      <programlisting role="php">
function foo ($bar) {
    $bar .= ' e algo mais.';
}
$str = 'Isto  uma string, ';
foo ($str);
echo $str;    // outputs 'Isto  uma string, '
foo (&amp;$str);
echo $str;    // outputs 'Isto  uma string, e algo mais.'
      </programlisting>
     </informalexample>
    </para>

   </sect2>
 
   <sect2 id="functions.arguments.default">
    <title>Valores padro de argumentos</title>
 
    <para>
     Uma funo pode definir valores padro no estilo C++ para argumentos escalares, como
     a seguir:
 
     <informalexample>
      <programlisting role="php">
function makecoffee ($type = "cappucino") {
    return "Fazendo uma xcara de $type.\n";
}
echo makecoffee ();
echo makecoffee ("caf expresso");
      </programlisting>
     </informalexample>
    </para>
 
    <para>
     The output from the above snippet is:
 
     <screen>
Fazendo uma xcara de cappucino.
Fazendo uma xcara de caf expresso.
     </screen>
    </para>
 
    <simpara>
     O valor padro precisa ser uma expresso constante, no (por
     exemplo) uma varivel ou um membro de classe.
    </simpara>
    <para>
     Note que usando argumentos padro, qualquer padro dever estar do lado
     direito de argumentos no-padro; caso contrrio, as coisas no funcionaro
     como esperado. Considere o seguinte trecho de cdigo:
 
     <informalexample>
      <programlisting role="php">
function makeyogurt ($type = "azeda", $flavour) {
    return "Fazendo uma taa de $flavour $type.\n";
}
 
echo makeyogurt ("framboesa");   // no vai funcionar como o esperado
      </programlisting>
     </informalexample>
    </para>
 
    <para>
     A sada do exemplo acima :
 
     <screen>
Warning: Missing argument 2 in call to makeyogurt() in 
/usr/local/etc/httpd/htdocs/php3test/functest.html on line 41
Fazendo uma taa de framboesa.
     </screen>
    </para>
 
    <para>
     Agora, compare o que est acima com este:
 
     <informalexample>
      <programlisting role="php">
function makeyogurt ($flavour, $type = "azeda") {
    return "Fazendo uma taa de $flavour $type.\n";
}
 
echo makeyogurt ("framboesa");   // funciona como o esperado
      </programlisting>
     </informalexample>
    </para>
 
    <para>
     A sada deste exemplo :
 
     <screen>
Fazendo uma taa de framboesa azeda.
     </screen>
    </para>

   </sect2>

   <sect2 id="functions.variable-arg-list">
    <title>Listas de argumentos de comprimento varivel</title>
	
    <simpara>
     O PHP4 tem suporte para listas de argumentos de comprimento varivel
     nas funes definidas pelo usurio. Isto  realmente bem fcil, usando 
     as funes <function>func_num_args</function>,
     <function>func_get_arg</function>, e
     <function>func_get_args</function>.
    </simpara>

    <simpara>
     Nenhuma sintaxe especial  requerida, e as listas de argumentos ainda 
     podem ser fornecidas explicitamente com as definies de funes e se
     comportaro normalmente.
    </simpara>

   </sect2>

  </sect1>
 
  <sect1 id="functions.returning-values">
   <title>Returnando valores</title>
 
   <para>
    Valores so retornados pelo uso de comandos opcionais de retorno. Qualquer
    tipo pode ser retornado, incluindo listas e objetos.
 
    <informalexample>
     <programlisting role="php">
function square ($num) {
    return $num * $num;
}
echo square (4);   // imprime '16'.
     </programlisting>
    </informalexample>
   </para>
      
   <para>
    Voc no pode retornar mltiplos valores a partir de uma funo, mas 
    resultados similares podem ser obtidos retornando uma lista.
 
    <informalexample>
     <programlisting role="php">
function small_numbers() {
    return array (0, 1, 2);
}
list ($zero, $one, $two) = small_numbers();
     </programlisting>
    </informalexample>
   </para>

  </sect1>
 
  <sect1 id="functions.old-syntax">
   <title><literal>old_function</literal></title>
 
   <simpara>
    O comando <literal>old_function</literal> permite que voc declare uma 
    funo usando uma sintaxe idntica ao PHP/FI2 (exceto pelo fato de que
    voc precisa substituir 'function' com 'old_function').
   </simpara>
   <simpara>
    Esta  uma implementao obsoleta, e deve ser usada somente pelo
    conversor PHP/FI2->PHP3.
   </simpara>
   <warning>
    <para>
     Funes declaradas como <literal>old_function</literal> no podem ser chamadas
     a partir de cdigo interno do PHP. Entre outras coisas, isso significa que voc
     no pode us-las em funes como
     <function>usort</function>, <function>array_walk</function>, e
     <function>register_shutdown_function</function>. Voc pode contornar essa 
     limitao escrevendo um invlucro de funo (no formato PHP3 normal) para chamar
     o <literal>old_function</literal>.
    </para>
   </warning>

  </sect1>

  <sect1 id="functions.variable-functions">
   <title>Variable functions</title>

   <para>
    O PHP suporta o conceito de funes variveis. Isto significa que se um nome de 
    varivel tem parnteses juntos como ele, o PHP procurar uma funo com o mesmo
    nome, qualquer que seja a avaliao da varivel, e tentar execut-la. Entre outras
    coisas, isto pode ser usado para implementar retornos, tabelas de funo e 
    assim por diante.
   </para>

   <para>
    <example>
     <title>Exemplo de funes variveis</title>
     <programlisting role="php">
&lt;?php
function foo() {
    echo "Em foo()&lt;br>\n";
}

function bar( $arg = '' ) {
    echo "Em bar(); argumento era '$arg'.&lt;br>\n";
}

$func = 'foo';
$func();
$func = 'bar';
$func( 'teste' );
?>
     </programlisting>
    </example>
   </para>

  </sect1>
 
 </chapter>
 
 <!-- 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:"../../manual.ced"
 sgml-exposed-tags:nil
 sgml-local-catalogs:nil
 sgml-local-ecat-files:nil
 End:
 -->