cvs: phpdoc /pt_BR/functions array.xml
| From: | Lucas Rocha | Date: | Thu, 13 Dec 2001 16:14:37 +0000 |
| Subject: | cvs: phpdoc /pt_BR/functions array.xml | ||
| Groups: | php.doc | ||
| Request: | Send a blank email to phpdoc+get-969339704@lists.php.net to get a copy of this message | ||
lucasr Thu Dec 13 11:14:37 2001 EDT
Modified files:
/phpdoc/pt_BR/functions array.xml
Log:
Adding the translated array.xml to pt_BR Manual. Not reviewed!
Index: phpdoc/pt_BR/functions/array.xml diff -u /dev/null phpdoc/pt_BR/functions/array.xml:1.3 --- /dev/null Thu Dec 13 11:14:37 2001 +++ phpdoc/pt_BR/functions/array.xml Thu Dec 13 11:14:37 2001 @@ -0,0 +1,3712 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- $Revision: 1.3 $ --> + <reference id="ref.array"> + <title>Array Functions</title> + <titleabbrev>Arrays</titleabbrev> + <partintro> + <simpara> + Essas funções permitem a interação e manipulação de arrays de + várias formas. Arrays são essenciais para armazenar, gerenciar, + operar sobre um conjunto de variáveis. + </simpara> + <simpara> + Arras simples e multidimensionais (matrizes) são suportados, e podem + ser criados pelo usuário ou por outras funções. + Existem diversas funções específicas para bancos de dados para preencher + arrays com os dados retornados em consultas, e vários outros tipos de funções + também retornam arrays. + </simpara> + <para> + Por favor, veja a seção <link linkend="language.types.array">Arrays</link> + do manual para uma explicação mais detalhada sobre como arrays são + implementados e utilizados no PHP. + </para> + <para> + Veja também <function>is_array</function>, <function>explode</function>, + <function>implode</function>, <function>split</function> + e <function>join</function>. + </para> + </partintro> + + <refentry id="function.array"> + <refnamediv> + <refname>array</refname> + <refpurpose> + Cria um array + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array</function></funcdef> + <paramdef>mixed + <parameter><optional>...</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Retorna um array de parâmetros fornecidos. Índices podem ser atribuidos + aos parâmetros através do operador <literal>=></literal>. + </para> + <para> + <note> + <para> + <function>array</function> é uma estrutura utilizada para representar + literais de arrays, e não uma função. + </para> + </note> + </para> + <para> + A forma "index => values", separados por vírgulas, definem índice e + valores respectivamente. O índice por de ser do tipo string ou numérico. + Quando o índice é omitido, um índice numérico inteiro é automaticamente + gerado, começando do 0. Se o índice é um inteiro, o próximo índice a ser + gerado será igual ao maior índice inteiro + 1. Note que quando dois + índices idênticos são definidos, o último sobrescreve o primeiro. + </para> + <para> + O exemplo a seguir demonstra como criar um array com duas dimensões, como + especificar chaves em arrays associativos, e como definir índices + numéricos em arrays normais. + <example> + <title>Exemplo de <function>array</function></title> + <programlisting role="php"> +<![CDATA[ +$frutas = array ( + "frutas" => array ("a"=>"laranja", "b"=>"banana", "c"=>"melancia"), + "numeros" => array (1, 2, 3, 4, 5, 6), + "buracos" => array ("primeiro", 5 => "segundo", "terceiro") +); +]]> + </programlisting> + </example> + </para> + <para> + <example> + <title>Índices automáticos com <function>array</function></title> + <programlisting role="php"> +<![CDATA[ +$array = array( 1, 1, 1, 1, 1, 8=>1, 4=>1, 19, 3=>13); +print_r($array); +]]> + </programlisting> + <para> + vai mostrar : + <screen role="php"> +<![CDATA[ +Array +( + [0] => 1 + [1] => 1 + [2] => 1 + [3] => 13 + [4] => 1 + [8] => 1 + [9] => 19 +) +]]> + </screen> + </para> + </example> + Note que o índice 3 é definido duas vezes, e retêm seu último valor + 13. O índice 4 é definido depois do índice 8, e o índice gerado depois + dele foi 9, uma vez que o maior índice era 8. + </para> + <para> + Esse exemplo cria um array com o índices a partir do 1. + <example> + <title>Array com índices a partir do 1 com <function>array</function></title> + <programlisting role="php"> +<![CDATA[ +$trimestre = array(1 => 'Janeiro', 'Fevereiro', 'Marco'); +print_r($trimestre); +]]> + </programlisting> + <para> + vai mostrar : + <screen> +<![CDATA[ +Array +( + [1] => 'Janeiro' + [2] => 'Fevereiro' + [3] => 'Marco' +) +]]> + </screen> + </para> + </example> + </para> + <para> + Veja também: <function>list</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-change-key-case"> + <refnamediv> + <refname>array_change_key_case</refname> + <refpurpose>Retorna um array com todas as chaves string em maiúsculo ou + minúsculo</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_change_key_case</function></funcdef> + <paramdef>array <parameter>input</parameter></paramdef> + <paramdef>int <parameter><optional>case</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_change_key_case</function> muda as chaves chaves do + array <parameter>input</parameter> para maiúsculo ou minúsculo. A mudança + depende do último parâmetro opcional <parameter>case</parameter>. + Você pode passar duas constantes para ele, + <constant>CASE_UPPER</constant> e + <constant>CASE_LOWER</constant>. O padrão é + <constant>CASE_LOWER</constant>. + Essa função deixará os índices numéricos inalterados. + </para> + <example> + <title>Exemplo de <function>array_change_key_case</function></title> + <programlisting role="php"> +<![CDATA[ +$input_array = array("primeiRo" => 1, "segunDo" => 4); +print_r(array_change_key_case($input_array, CASE_UPPER); +]]> + </programlisting> + <para> + A saída deste programa será: + <screen> +<![CDATA[ +Array +( + [PRIMEIRO] => 1 + [SEGUNDO] => 2 +) +]]> + </screen> + </para> + </example> + </refsect1> + </refentry> + + <refentry id="function.array-chunk"> + <refnamediv> + <refname>array_chunk</refname> + <refpurpose>Divide um array em pedaços</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_chunk</function></funcdef> + <paramdef>array <parameter>input</parameter></paramdef> + <paramdef>int <parameter>size</parameter></paramdef> + <paramdef>bool <parameter><optional>preserve_keys</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_chunk</function> divide um array em diversos + arrays tendo como tamanho o valor de <parameter>size</parameter>. + Você provavelmente terá um array com menos valores no final. + Você gerará arrays como membros de um array multidimensional com índices + numéricos que começam do 0. + </para> + <para> + Passando o valor &true; para parâmetro <parameter>preserve_keys</parameter>, + você pode forçar a preservação das chaves do array original. Se for + passado o valor &false;, novos índices numéricos serão usados em cada + array resultante começando do valor 0. O padrão é &false;. + </para> + <example> + <title><function>array_chunk</function> example</title> + <programlisting role="php"> +<![CDATA[ +$input_array = array('a', 'b', 'c', 'd', 'e'); +print_r(array_chunk($input_array, 2)); +print_r(array_chunk($input_array, 2, TRUE)); +]]> + </programlisting> + <para> + A saída deste programa será: + <screen> +<![CDATA[ +Array +( + [0] => Array + ( + [0] => a + [1] => b + ) + + [1] => Array + ( + [0] => c + [1] => d + ) + + [2] => Array + ( + [0] => e + ) + +) +Array +( + [0] => Array + ( + [0] => a + [1] => b + ) + + [1] => Array + ( + [2] => c + [3] => d + ) + + [2] => Array + ( + [4] => e + ) + +) +]]> + </screen> + </para> + </example> + </refsect1> + </refentry> + + <refentry id="function.array-count-values"> + <refnamediv> + <refname>array_count_values</refname> + <refpurpose>Conta todos os valores de um array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_count_values</function></funcdef> + <paramdef>array <parameter>input</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_count_values</function> retorna um array utlizando os valores + do array <parameter>input</parameter> como chaves e seus respectivos + números de ocorrências como valores. + </para> + <para> + <example> + <title>Exemplo de <function>array_count_values</function></title> + <programlisting role="php"> +<![CDATA[ +$array = array (1, "ola", 1, "mundo", "ola"); +array_count_values ($array); // retorna o array (1=>2, "ola"=>2, "mundo"=>1) +]]> + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.array-diff"> + <refnamediv> + <refname>array_diff</refname> + <refpurpose>Calcula as diferenças entre arrays</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_diff</function></funcdef> + <paramdef>array <parameter>array1</parameter></paramdef> + <paramdef>array <parameter>array2</parameter></paramdef> + <paramdef>array + <parameter><optional> ...</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_diff</function> retorna um array contendo todos os + valores de <parameter>array1</parameter> que não estão presentes + em nenhum dos outros argumentos. + Note que as chaves são preservadas. + </para> + <para> + <example> + <title>Exemplo de <function>array_diff</function></title> + <programlisting role="php"> +<![CDATA[ +$array1 = array ("a" => "verde", "vermelho", "azul", "vermelho"); +$array2 = array ("b" => "verde", "amarelo", "vermelho"); +$result = array_diff ($array1, $array2); +]]> + </programlisting> + </example> + </para> + <para> + Isso faz com que <varname>$result</varname> tenha + <literal>array ("azul");</literal>. Ocorrências multiplas em + $array1 são tratados da mesma forma. + </para> + <note> + <simpara> + Dois elementos são considerados iguais se, e somente se, + <literal>(string) $elem1 === (string) $elem2</literal>. Em palavras: + quando a representação em string é a mesma. + <!-- TODO: example of it... --> + </simpara> + </note> + <warning> + <simpara> + Não estava funcinando no PHP 4.0.4! + <!-- TODO: when exactly was this broken?... --> + </simpara> + </warning> + <para> + Veja também <function>array_intersect</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-filter"> + <refnamediv> + <refname>array_filter</refname> + <refpurpose> + Filtra os elementos de um array de acordo com uma função + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_filter</function></funcdef> + <paramdef>array <parameter>input</parameter></paramdef> + <paramdef>mixed + <parameter><optional>callback</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_filter</function> retorna um array contendo + todos os elementos do array <parameter>input</parameter> filtrados + de acordo com a função aplicada. Se o array + <parameter>input</parameter> é associativo, então as chaves + são preservadas. + </para> + <para> + <example> + <title>Exemplo de <function>array_filter</function></title> + <programlisting role="php"> +<![CDATA[ +function impar($var) { + return ($var % 2 == 1); +} + +function par($var) { + return ($var % 2 == 0); +} + +$array1 = array ("a"=>1, "b"=>2, "c"=>3, "d"=>4, "e"=>5); +$array2 = array (6, 7, 8, 9, 10, 11, 12); + +$impar_arr = array_filter($array1, "impar"); +$par_arr = array_filter($array2, "par"); +]]> + </programlisting> + </example> + </para> + <para> + Isso faz com que <varname>$impar_arr</varname> tenha + <literal>array ("a"=>1, "c"=>3, "e"=>5);</literal>, + e <varname>$par_arr</varname> tenha + <literal>array (6, 8, 10, 12);</literal>, + </para> + <para> + Veja também <function>array_map</function>, + <function>array_reduce</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-flip"> + <refnamediv> + <refname>array_flip</refname> + <refpurpose>Inverte a relações entre chaves e valores</refpurpose> + </refnamediv> + <refsect1> + <title>Descrições</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_flip</function></funcdef> + <paramdef>array <parameter>trans</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_flip</function> retorna um <type>array</type> com + com a relação entre as chaves e seus valores invertida, ou seja, + as chaves de <parameter>trans</parameter> passam a ser valores e + os valores de <parameter>trans</parameter> passam a ser as chaves. + </para> + <para> + Note que os valores de <parameter>trans</parameter> devem ser chaves + válidas, ou seja, eles precisam ser <type>inteiros</type> ou <type>string</type>. + Um aviso será mostrado se um valor é de um tipo inválido para chaves, + e o par chave/valor em questão <emphasis>não será invertido</emphasis>. + </para> + <para> + se um valor tem várias ocorrências, a última chave será usada + como valor, e todos os outros serão perdidos. + </para> + <para> + <function>array_flip</function> retorna &false; + se falhar. + </para> + <para> + <example> + <title>Exemplo de <function>array_flip</function></title> + <programlisting role="php"> +<![CDATA[ +$trans = array_flip ($trans); +$original = strtr ($str, $trans); +]]> + </programlisting> + </example> + </para> + <para> + <example> + <title>Exemplo de <function>array_flip</function> : collision</title> + <programlisting role="php"> +<![CDATA[ +$trans = array ("a" => 1, "b" => 1, "c" => 2); +$trans = array_flip ($trans); +// agora $trans é : array(1 => "b", 2 => "c"); +]]> + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.array-fill"> + <refnamediv> + <refname>array_fill</refname> + <refpurpose>Preenche um array com valores</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_fill</function></funcdef> + <paramdef>int <parameter>start_index</parameter></paramdef> + <paramdef>int <parameter>num</parameter></paramdef> + <paramdef>mixed <parameter>value</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_fill</function> preenche um array com + o número de entradas igual a <parameter>num</parameter> com o valor do + parâmetro <parameter>value</parameter>, e chaves começando a partir de + <parameter>start_index</parameter>. + </para> + <para> + <example> + <title>Exemplo de <function>array_fill</function></title> + <programlisting role="php"> +<![CDATA[ +$a = array_fill(5, 6, 'banana'); + +/* +$a agora tem os seguintes valores: + +$a[5] = "banana"; +$a[6] = "banana"; +$a[7] = "banana"; +$a[8] = "banana"; +$a[9] = "banana"; +$a[10] = "banana"; +*/ +]]> + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.array-intersect"> + <refnamediv> + <refname>array_intersect</refname> + <refpurpose>Calcula a interseção entre arrays</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_intersect</function></funcdef> + <paramdef>array <parameter>array1</parameter></paramdef> + <paramdef>array <parameter>array2</parameter></paramdef> + <paramdef>array + <parameter><optional> ...</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_intersect</function> retorna um array + contendo todos os valores de <parameter>array1</parameter> + que estão presentes nos outros argumentos. + Note que as chaves são preservadas. + </para> + <para> + <example> + <title>Exemplo de <function>array_intersect</function></title> + <programlisting role="php"> +<![CDATA[ +$array1 = array ("a" => "verde", "vermelho", "azul"); +$array2 = array ("b" => "verde", "amarelo", "vermelho"); +$result = array_intersect ($array1, $array2); +]]> + </programlisting> + </example> + </para> + <para> + Isso faz com que <varname>$result</varname> tenha <literal>array ("a" + => "verde", "vermelho");</literal> + </para> + <note> + <simpara> + Dois elementos são considerados iguais se, e somente se, + <literal>(string) $elem1 === (string) $elem2</literal>. Em palavras: + quando a representação em string é a mesma. + <!-- TODO: example of it... --> + </simpara> + </note> + <warning> + <simpara> + Essa função não funcionava no PHP 4.0.4! + <!-- TODO: when exactly was this broken?... --> + </simpara> + </warning> + <para> + Veja também <function>array_diff</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-key-exists"> + <refnamediv> + <refname>array_key_exists</refname> + <refpurpose>Checa se uma chave existe num array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>array_key_exists</function></funcdef> + <paramdef>mixed <parameter>key</parameter></paramdef> + <paramdef>array <parameter>search</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_key_exists</function> retorna &true; se a chave + <parameter>key</parameter> existe no array. + <parameter>key</parameter> pode ser qualquer valor possível para uma + chave de um array. + </para> + <para> + <example> + <title>Exemplo de <function>array_key_exists</function></title> + <programlisting role="php"> +<![CDATA[ +$busca_array = array("primeiro" => 1, "segundo" => 4); +if (array_key_exists("primeiro", $busca_array)) { + echo "O elemento 'primeiro' está no array!"; +} +]]> + </programlisting> + </example> + </para> + <note> + <simpara> + O nome dessa função é <function>key_exists</function> + no PHP versão 4.0.6. + </simpara> + </note> + <para> + Veja também <function>isset</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-keys"> + <refnamediv> + <refname>array_keys</refname> + <refpurpose>Retorna todas as chaves de um array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_keys</function></funcdef> + <paramdef>array <parameter>input</parameter></paramdef> + <paramdef>mixed + <parameter> + <optional>search_value</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_keys</function> retorna as chaves, numéricas e + string, do array <parameter>input</parameter>. + </para> + <para> + Se o parâmetro opcional <parameter>search_value</parameter> for + especificado, então apenas as chaves para esse valor sãò retornadas. + Do contrário, todas as chaves de <parameter>input</parameter> serãao retornadas. + </para> + <para> + <example> + <title>Exemplo de <function>array_keys</function></title> + <programlisting role="php"> +<![CDATA[ +$array = array (0 => 100, "cor" => "vermelho"); +array_keys ($array); // retorna o array (0, "color") + +$array = array ("azul", "vermelho", "verde", "azul", "azul"); +array_keys ($array, "azul"); // retorna o array (0, 3, 4) + +$array = array ("cor" => array("azul", "vermelho", "verde"), "tamanho" => array("pequeno", "medio", "grande")); +array_keys ($array); // retorna o array ("cor", "tamanho") +]]> + </programlisting> + </example> + </para> + <note> + <para> + Essa função adicionada no PHP 4,abaixo está uma implementação + para aqueles que ainda usam PHP 3. + <example> + <title> + Implementação de <function>array_keys</function> para usuários do PHP 3 + </title> + <programlisting role="php"> +<![CDATA[ +function array_keys ($arr, $term="") { + $t = array(); + while (list($k,$v) = each($arr)) { + if ($term && $v != $term) { + continue; + $t[] = $k; + } + return $t; + } +} +]]> + </programlisting> + </example> + </para> + </note> + <para> + Veja também <function>array_values</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-map"> + <refnamediv> + <refname>array_map</refname> + <refpurpose> + Aplica uma função em todos os elementos dos arrays dados + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_map</function></funcdef> + <paramdef>mixed <parameter>callback</parameter></paramdef> + <paramdef>array <parameter>arr1</parameter></paramdef> + <paramdef>array + <parameter><optional>arr2...</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_map</function> retorna um array contendo todos + os elementos de <parameter>arr1</parameter> depois de aplicada + a função callback em cada um. O número de parâmetros que a função + callback aceita deve coincidir com o número de arrays passados para a + <function>array_map</function> + </para> + <para> + <example> + <title>Exemplo de <function>array_map</function></title> + <programlisting role="php"> +<![CDATA[ +function cubo($n) { + return $n*$n*$n; +} + +$a = array(1, 2, 3, 4, 5); +$b = array_map("cubo", $a); +]]> + </programlisting> + </example> + </para> + <para> + Isso resultará em <varname>$b</varname> contendo + <literal>array (1, 8, 27, 64, 125);</literal> + </para> + <para> + <example> + <title><function>array_map</function> - usando mais arrays</title> + <programlisting role="php"> +<![CDATA[ +function mostrar_Espanhol($n, $m) { + return "O número $n é chamado de $m na Espanha"; +} + +function map_Espanhol($n, $m) { + return array ($n => $m); +} + +$a = array(1, 2, 3, 4, 5); +$b = array("uno", "dos", "tres", "cuatro", "cinco"); + +$c = array_map("mostrar_Espanhol", $a, $b); + +print_r($c); + +// mostrará: +// Array +// ( +// [0] => O número 1 é chamado de uno na Espanha +// [1] => O número 2 é chamado de dos na Espanha +// [2] => O número 3 é chamado de tres na Espanha +// [3] => O número 4 é chamado de cuatro na Espanha +// [4] => O número 5 é chamado de cinco na Espanha +// ) + +$d = array_map("map_Espanhol", $a , $b); + +print_r($d); + +// will output: +// Array +// ( +// [0] => Array +// ( +// [1] => uno +// ) +// +// [1] => Array +// ( +// [2] => dos +// ) +// +// [2] => Array +// ( +// [3] => tres +// ) +// +// [3] => Array +// ( +// [4] => cuatro +// ) +// +// [4] => Array +// ( +// [5] => cinco +// ) +// +// ) +]]> + </programlisting> + </example> + </para> + <para> + Normalmente quando se usa dois ou mais arrays, eles devem ter o mesmo tamanho + porque a função callback é aplicada paralelamente aos elementos + correpondentes. + Se os arrays tem tamanhos diferentes, o menos array será extendido com + elementos em branco. + </para> + <para> + Um modo interessante de usar essa função é na construção de um array de + arrays, o que pode ser facilmente feito usando &null; + como o nome da função callback. + </para> + <para> + <example> + <title>Criando um array de arrays</title> + <programlisting role="php"> +<![CDATA[ +$a = array(1, 2, 3, 4, 5); +$b = array("um", "dois", "tres", "quatro", "cinco"); +$c = array("uno", "dos", "tres", "cuatro", "cinco"); + +$d = array_map(null, $a, $b, $c); +print_r($d); + +// mostrará: +// Array +// ( +// [0] => Array +// ( +// [0] => 1 +// [1] => um +// [2] => uno +// ) +// +// [1] => Array +// ( +// [0] => 2 +// [1] => dois +// [2] => dos +// ) +// +// [2] => Array +// ( +// [0] => 3 +// [1] => tres +// [2] => tres +// ) +// +// [3] => Array +// ( +// [0] => 4 +// [1] => quatro +// [2] => cuatro +// ) +// +// [4] => Array +// ( +// [0] => 5 +// [1] => cinco +// [2] => cinco +// ) +// +// ) +]]> + </programlisting> + </example> + </para> + <para> + Veja também <function>array_filter</function>, + <function>array_reduce</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-merge"> + <refnamediv> + <refname>array_merge</refname> + <refpurpose>Funde dois ou mais arrays</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_merge</function></funcdef> + <paramdef>array <parameter>array1</parameter></paramdef> + <paramdef>array <parameter>array2</parameter></paramdef> + <paramdef>array + <parameter><optional>...</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_merge</function> funde os elementos dois ou mais + arrays de forma que os elementos de um são colocados no final + do array anterior. Retorna esse array resultante. + </para> + <para> + Se os arrays dados têm as mesmas chaves string, então o último + valor para uma chave irá sobrescrever todos os outros. Se, no entanto, + os arrays tem as mesmas chaves numéricas, o último valor para uma chave + não sobrescreverá o valor original, e sim adicionado ao array + resultante. + </para> + <para> + <example> + <title>Exemplo de <function>array_merge</function></title> + <programlisting role="php"> +<![CDATA[ +$array1 = array ("cor" => "vermelho", 2, 4); +$array2 = array ("a", "b", "cor" => "verde", "forma" => "trapezoide", 4); +$result = array_merge ($array1, $array2); +]]> + </programlisting> + </example> + </para> + <para> + O array resultante será <literal>array("cor" => "verde", 2, 4, + "a", "b", "forma" => "trapezoide", 4)</literal>. + </para> + <para> + Veja também <function>array_merge_recursive</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-merge-recursive"> + <refnamediv> + <refname>array_merge_recursive</refname> + <refpurpose>Funde dois ou mais arrays recursivamente</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_merge_recursive</function></funcdef> + <paramdef>array <parameter>array1</parameter></paramdef> + <paramdef>array <parameter>array2</parameter></paramdef> + <paramdef>array + <parameter><optional>...</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_merge_recursive</function> funde os elementos de + dois ou mais de forma que os elementos de um são colocados + no final do array anterior. Retorna esse array resultante. + </para> + <para> + Se os arrays dados tem as mesmas chaves string, então os valores para + uma chave são fundidos em um array, e isso é feito recursivamente, + sendo que se um dos valores for um array também, este função irá fundi-lo + com os valores correspondentes no array resultante também. Se, no + entanto, os arrays tem as mesmas chaves numéricas, o último valor para + uma chave não sobrescreverá o valor original, e sim adicionado ao array + resultante. + </para> + <para> + <example> + <title>Exemplo de <function>array_merge_recursive</function></title> + <programlisting role="php"> +<![CDATA[ +$ar1 = array ("cor" => array ("favorita" => "vermelho"), 5); +$ar2 = array (10, "cor" => array ("favorita" => "verde", "azul")); +$result = array_merge_recursive ($ar1, $ar2); +]]> + </programlisting> + </example> + </para> + <para> + O array resultante será <literal>array ("cor" => array + ("favorita" => array ("vermelho", "verde"), "azul"), 5, 10)</literal>. + </para> + <para> + Veja também <function>array_merge</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-multisort"> + <refnamediv> + <refname>array_multisort</refname> + <refpurpose>Classifica múltiplos arrays ou multi-dimensionais</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>array_multisort</function></funcdef> + <paramdef>array <parameter>ar1</parameter></paramdef> + <paramdef>mixed + <parameter><optional>arg</optional></parameter> + </paramdef> + <paramdef>mixed + <parameter><optional>...</optional></parameter> + </paramdef> + <paramdef>array + <parameter><optional>...</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_multisort</function> pode ser usada para classificar + vários arrays de uma vez ou apenas um array multi-dimensional de acordo com + uma das dimensões. A associação entre chaves e valores é mantida. + </para> + <para> + Os arrays dados são tratados como colunas de uma tabela a ser + classificada pelas linhas - isso lembra a funcionalidade da cláusula + ORDER BY da SQL. O primeiro array é o principal na classificação. As + linhas (valores) no primeiro array serve de base para a classificação do próximo, + e assim por diante. + </para> + <para> + A estrutura de argumentos dessa função não é muito normal, mas + bastante flexível. O primeiro argmento de todos deve ser um array. + Subsequentemente, cada argumento pode ser um array ou um dos sinais de + classificação da lista a seguir. + </para> + <para> + Sinais de ordem de classificação: + <itemizedlist> + <listitem> + <simpara>SORT_ASC - classifica na ordem crescente</simpara> + </listitem> + <listitem> + <simpara>SORT_DESC - classifica na ordem descrescente</simpara> + </listitem> + </itemizedlist> + </para> + <para> + Sinais de tipos de classificação: + <itemizedlist> + <listitem> + <simpara>SORT_REGULAR - compara os elementos normalmente</simpara> + </listitem> + <listitem> + <simpara>SORT_NUMERIC - compara os elementos como itens numéricos</simpara> + </listitem> + <listitem> + <simpara>SORT_STRING - compara os elementos como strings</simpara> + </listitem> + </itemizedlist> + </para> + <para> + Não podem existir dois sinais de classificação do mesmo tipo + especificados depois de um mesmo array. Apenas um. Os sinais de classificação + especificados depois de um array se aplicam apenas para esse array - a + eles são atribuídos por padrão os valores SORT_ASC e SORT_REGULAR depois + de cada novo argumento do tipo array. + </para> + <para> + Retorna &true; se obtiver sucesso, &false; + se falhar. + </para> + <para> + <example> + <title>Classificando múltiplos arrays</title> + <programlisting role="php"> +<![CDATA[ +$ar1 = array ("10", 100, 100, "a"); +$ar2 = array (1, 3, "2", 1); +array_multisort ($ar1, $ar2); +]]> + </programlisting> + </example> + </para> + <para> + Nesse exemplo, depois da classificação, o primeiro array terá 1-, "a", + 100, 100. O segundo conterá 1, 1, "2", 3. Os elementos do segundo array + que correpondem aos do primeiro (100 e 100) também foram classificados. + </para> + <para> + <example> + <title>Classificando um array multi-dimensional</title> + <programlisting role="php"> +<![CDATA[ +$ar = array (array ("10", 100, 100, "a"), array (1, 3, "2", 1)); +array_multisort ($ar[0], SORT_ASC, SORT_STRING, + $ar[1], SORT_NUMERIC, SORT_DESC); +]]> + </programlisting> + </example> + </para> + <para> + Nesse exemplo, depois da classificação, o primeiro array terá 10, 100, + 100, "a" (foi classificado como strings em ordem crescente), e o segundo + conterá 1, 3, "2", 1 (classificado como números, em ordem descrescente). + </para> + </refsect1> + </refentry> + + <refentry id="function.array-pad"> + <refnamediv> + <refname>array_pad</refname> + <refpurpose> + Expande um array para um certo comprimento com um certo valor + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_pad</function></funcdef> + <paramdef>array <parameter>input</parameter></paramdef> + <paramdef>int <parameter>pad_size</parameter></paramdef> + <paramdef>mixed <parameter>pad_value</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_pad</function> retorna uma cópia de + <parameter>input</parameter> expandido para o comprimento especificado + por <parameter>pad_size</parameter> com o valor + <parameter>pad_value</parameter>. Se + <parameter>pad_size</parameter> for positivo então o array é + expandido pela direita, se for negativo, pela esquerda. Se o + valor absoluto de <parameter>pad_size</parameter> for menor ou igual + ao comprimento de <parameter>input</parameter>, então ele permanece + inalterado. + </para> + <para> + <example> + <title>Exemplo de <function>array_pad</function></title> + <programlisting role="php"> +<![CDATA[ +$input = array (12, 10, 9); + +$result = array_pad ($input, 5, 0); +// result is array (12, 10, 9, 0, 0) + +$result = array_pad ($input, -7, -1); +// result is array (-1, -1, -1, -1, 12, 10, 9) + +$result = array_pad ($input, 2, "noop"); +// not padded +]]> + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.array-pop"> + <refnamediv> + <refname>array_pop</refname> + <refpurpose>Retira um elemento do final do array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>array_pop</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_pop</function> retira e retorna o último + valor de <parameter>array</parameter>, diminuindo-o + <parameter>array</parameter> em um elemento. + Se <parameter>array</parameter> estiver vazio (ou se não for um array), + o valor &null; é retornado. + </para> + <para> + <example> + <title>Exemplo de <function>array_pop</function></title> + <programlisting role="php"> +<![CDATA[ +$cesta = array ("laranja", "melancia", "morango"); +$fruta = array_pop ($cesta); +]]> + </programlisting> + </example> + </para> + <para> + Depois disso, <varname>$cesta</varname> terá dois elementos: + "laranja" e "melancia", and <varname>$fruta</varname> terá + "morango". + </para> + <para> + Veja também <function>array_push</function>, + <function>array_shift</function>, e + <function>array_unshift</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-push"> + <refnamediv> + <refname>array_push</refname> + <refpurpose> + Adiciona um ou mais elementos no final de um array + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>array_push</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>mixed <parameter>var</parameter></paramdef> + <paramdef>mixed + <parameter><optional>...</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_push</function> trata + <parameter>array</parameter> como uma pilha, e adiciona + as variáveis passadas como argumentos no final de <parameter>array</parameter>. + O comprimento de <parameter>array</parameter> aumenta de acordo com o + número de variáveis adicionadas.. Tem o mesmo efeito de: + <programlisting role="php"> +<![CDATA[ +$array[] = $var; +]]> + </programlisting> + repetido para cada argumento <parameter>var</parameter>. + </para> + <para> + Retorna o novo número de elementos do array. + </para> + <para> + <example> + <title>Exemplo de <function>array_push</function></title> + <programlisting role="php"> +<![CDATA[ +$pilha = array (1, 2); +array_push ($pilha, "+", 3); +]]> + </programlisting> + </example> + </para> + <para> + Esse exemplo resultará em <varname>$pilha</varname> contendo 4 + elementos: 1, 2, "+", e 3. + </para> + <para> + Veja também: <function>array_pop</function>, + <function>array_shift</function>, e + <function>array_unshift</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-rand"> + <refnamediv> + <refname>array_rand</refname> + <refpurpose> + Pega um ou mais elementos aleatórios do array + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>array_rand</function></funcdef> + <paramdef>array <parameter>input</parameter></paramdef> + <paramdef>int + <parameter><optional>num_req</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_rand</function> é bastante útil quando se quer + pegar aleatoriamente um ou mais elementos de um array. Ela recebe + o array <parameter>input</parameter> e outro argumento opcional + <parameter>num_req</parameter> o qual especifica quantos elementos + se quer pegar - se não for especificado, o padrão é 1. + </para> + <para> + Se estiver pegando apenas um elemento , <function>array_rand</function> + retorna a chave para este elemento aleatório. De outra forma, ele retorna + um array com as chaves desses elementos aleatórios. Assim é possível + pegar chaves e valores aleatórios. + </para> + <para> + Não esqueça de chamar a função <function>srand</function> para disparar + o gerador de números aleatórios. + </para> + <para> + <example> + <title>Exemplo de <function>array_rand</function></title> + <programlisting role="php"> +<![CDATA[ +srand ((float) microtime() * 10000000); +$input = array ("Neo", "Morpheus", "Trinity", "Cypher", "Tank"); +$rand_keys = array_rand ($input, 2); +print $input[$rand_keys[0]]."\n"; +print $input[$rand_keys[1]]."\n"; +]]> + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.array-reverse"> + <refnamediv> + <refname>array_reverse</refname> + <refpurpose> + Retorna um array com os elementos na ordem inversa + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_reverse</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>bool + <parameter><optional>preserve_keys</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_reverse</function> recebe o argumento + <parameter>array</parameter> e retorna um novo array com ordem + dos elementos invertida, preservando as chaves se o argumento + <parameter>preserve_keys</parameter> for &true;. + </para> + <para> + <example> + <title>Exemplo de <function>array_reverse</function></title> + <programlisting role="php"> +<![CDATA[ +$input = array ("php", 4.0, array ("verde", "vermelho")); +$result = array_reverse ($input); +$result_keyed = array_reverse ($input, TRUE); +]]> + </programlisting> + </example> + </para> + <para> + Isso fará com que <varname>$result</varname> e + <varname>$result_keyed</varname> sejam <literal>array(array + ("green", "red"), 4.0, "php")</literal>. Mas + <varname>$result_keyed[0]</varname> ainda será + <literal>"php"</literal>. + </para> + <note> + <para> + O segundo argumento foi adicionado no PHP 4.0.3. + </para> + </note> + </refsect1> + </refentry> + + <refentry id="function.array-reduce"> + <refnamediv> + <refname>array_reduce</refname> + <refpurpose> + Reduz um array para um único elemento através de um processo iterativo + utilizando uma função de callback. + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>array_reduce</function></funcdef> + <paramdef>array <parameter>input</parameter></paramdef> + <paramdef>mixed <parameter>callback</parameter></paramdef> + <paramdef>int + <parameter><optional>initial</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_reduce</function> aplica iterativamente a função + <parameter>callback</parameter> nos elementos de <parameter>input</parameter>, + de forma a reduzi-lo a um único valor. Se o argumento opcional <parameter>initial</parameter> + for passado, ele será utlizado no início do processo, ou como + um resultado final se o array estiver vazio. + </para> + <para> + <example> + <title>Exemplo de <function>array_reduce</function></title> + <programlisting role="php"> +<![CDATA[ +function soma($v, $w) { + $v += $w; + return $v; +} + +function multiplicacao($v, $w) { + $v *= $w; + return $v; +} + +$a = array(1, 2, 3, 4, 5); +$x = array(); +$b = array_reduce($a, "soma"); +$c = array_reduce($a, "multiplicacao", 10); +$d = array_reduce($x, "soma", 1); +]]> + </programlisting> + </example> + </para> + <para> + Isso resultará em <varname>$b</varname> contendo + <literal>15</literal>, <varname>$c</varname> contendo + <literal>1200</literal> (= 1*2*3*4*5*10), e + <varname>$d</varname> contendo <literal>1</literal>. + </para> + <para> + Veja também <function>array_filter</function>, + <function>array_map</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-shift"> + <refnamediv> + <refname>array_shift</refname> + <refpurpose> + Retira o primeiro elemento de um array + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>array_shift</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_shift</function> retira o primeiro elemento de + <parameter>array</parameter> e o retorna, diminuindo + <parameter>array</parameter> em um elemento e movendo todos os outros + para trás. Se <parameter>array</parameter> estiver vazio (ou se não for + um array), o valor &null; é retornado. + </para> + <para> + <example> + <title>Exemplo de <function>array_shift</function></title> + <programlisting role="php"> +<![CDATA[ +$args = array ("-v", "-f"); +$opt = array_shift ($args); +]]> + </programlisting> + </example> + </para> + <para> + Isso resultaria em <varname>$args</varname> contendo apenas o elemento + "-f", e <varname>$opt</varname> sendo "-v". + </para> + <para> + Veja também <function>array_unshift</function>, + <function>array_push</function>, e + <function>array_pop</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-slice"> + <refnamediv> + <refname>array_slice</refname> + <refpurpose>Extrai uma "fatia" de um array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_slice</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>int <parameter>offset</parameter></paramdef> + <paramdef>int + <parameter> + <optional>length</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_slice</function> retorna a sequência de elementos + de <parameter>array</parameter> especificada pelos parâmetros + <parameter>offset</parameter> e <parameter>length</parameter>. + </para> + <para> + Se <parameter>offset</parameter> for positivo, a sequência + começará no início de <parameter>array</parameter>. Se + <parameter>offset</parameter> for negativo, a sequência + começará dessa distância do final de <parameter>array</parameter>. + </para> + <para> + Se <parameter>length</parameter> for especificado e positivo, então + a sequência terá essa quantidade de elementos. Se + <parameter>length</parameter> for especificado e negativo então + a sequência para dessa quantidade elementos a partir do final do + array. Se for omitido, então a sequência terá todos os elementos + a partir de <parameter>offset</parameter> até o final de + <parameter>array</parameter>. + </para> + <para> + <example> + <title>Exemplos de <function>array_slice</function></title> + <programlisting role="php"> +<![CDATA[ +$input = array ("a", "b", "c", "d", "e"); + +$output = array_slice ($input, 2); // retorna "c", "d", e "e" +$output = array_slice ($input, 2, -1); // retorna "c", "d" +$output = array_slice ($input, -2, 1); // retorna "d" +$output = array_slice ($input, 0, 3); // retorna "a", "b", e "c" +]]> + </programlisting> + </example> + </para> + <para> + Veja também <function>array_splice</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-splice"> + <refnamediv> + <refname>array_splice</refname> + <refpurpose> + Remove uma região do array e substitui por outros elementos + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_splice</function></funcdef> + <paramdef>array <parameter>input</parameter></paramdef> + <paramdef>int <parameter>offset</parameter></paramdef> + <paramdef>int + <parameter><optional>length</optional></parameter> + </paramdef> + <paramdef>array + <parameter> + <optional>replacement</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_splice</function> remove os elementos especificados + por <parameter>offset</parameter> e + <parameter>length</parameter> do array + <parameter>input</parameter>, e os substitui com os elementos + do array <parameter>replacement</parameter>, se for especificado. + </para> + <para> + Se <parameter>offset</parameter> for positivo então o começo da + região a ser removida será nessa posição a partir do início do array + <parameter>input</parameter>. Se <parameter>offset</parameter> for negativo + então o ínicio será dessa distância do final de <parameter>input</parameter>. + </para> + <para> + Se <parameter>length</parameter> for omitido, todos os elementos + a partir de <parameter>offset</parameter> até o final do array são + removidos. Se <parameter>length</parameter> for especificado e positivo, então + essa quantidade de elementos será removida. Se <parameter>length</parameter> + for especificado e negativo então o final da região a ser removida será + nessa quantidade de elementos a partir do final do array. + Dica: para remover todos elementos a partir de <parameter>offset</parameter> + até o final do array quando <parameter>replacement</parameter> também é especificado, use + <literal>count($input)</literal> para o argumento <parameter>length</parameter>. + </para> + <para> + Se o array <parameter>replacement</parameter> for especificado, então + os elementos removidos serão substituidos pelo elementos desse array. + Se <parameter>offset</parameter> e + <parameter>length</parameter> dados de forma que nada será removido, + então os elementos de <parameter>replacement</parameter> serão inseridos + no lugar especificado por <parameter>offset</parameter>. + Dica: se a substituição for de apenas um elemento + então não será necessário colocar <literal>array()</literal> + para ele, a não ser que elementos seja um array. + </para> + <para> + As seguintes equivalências abaixo são válidas: + <programlisting role="php"> +<![CDATA[ +array_push ($input, $x, $y) array_splice ($input, count ($input), 0, + array ($x, $y)) +array_pop ($input) array_splice ($input, -1) +array_shift ($input) array_splice ($input, 0, 1) +array_unshift ($input, $x, $y) array_splice ($input, 0, 0, array ($x, $y)) +$a[$x] = $y array_splice ($input, $x, 1, $y) +]]> + </programlisting> + </para> + <para> + Retorna um array contendo os elementos removidos. + </para> + <para> + <example> + <title>Exemplos de <function>array_splice</function></title> + <programlisting role="php"> +<![CDATA[ +$input = array ("vermelho", "verde", "azul", "amarelo"); +array_splice ($input, 2); +// $input será agora array ("vermelho", "verde") + +$input = array ("vermelho", "verde", "azul", "amarelo"); +array_splice ($input, 1, -1); +// $input será agora array ("vermelho", "amarelo") + +$input = array ("vermelho", "verde", "azul", "amarelo"); +array_splice ($input, 1, count($input), "laranja"); +// $input será agora array ("vermelho", "laranja") + +$input = array ("vermelho", "verde", "azul", "amarelo"); +array_splice ($input, -1, 1, array("preto", "marrom")); +// $input será agora array ("vermelho", "verde", "azul", "preto", "marron") +]]> + </programlisting> + </example> + </para> + <para> + Veja também <function>array_slice</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-sum"> + <refnamediv> + <refname>array_sum</refname> + <refpurpose> + Calcula a soma dos elementos de um array + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>array_sum</function></funcdef> + <paramdef>array <parameter>arr</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_sum</function> retorna a soma dos valores + de um array como inteiro ou real. + </para> + <para> + <example> + <title>Exemplos de <function>array_sum</function></title> + <programlisting role="php"> +<![CDATA[ +$a = array(2, 4, 6, 8); +echo "sum(a) = ".array_sum($a)."\n"; +// imprime: sum(a) = 20 + +$b = array("a"=>1.2,"b"=>2.3,"c"=>3.4); +echo "sum(b) = ".array_sum($b)."\n"; +// imprime: sum(b) = 6.9 +]]> + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.array-unique"> + <refnamediv> + <refname>array_unique</refname> + <refpurpose>Remove o valores duplicados de um array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_unique</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_unique</function> recebe o argumento + <parameter>array</parameter> e retorna um novo array sem valores + duplicados. + </para> + <para> + Note que as chaves são preservadas. <function>array_unique</function> irá + manter a primeira chave encontrada para cada valor, e ignorar + as chaves posteriores. + </para> + <note> + <simpara> + Dois elementos são considerados iguais se, e somente se, + <literal>(string) $elem1 === (string) $elem2</literal>. Em palavras: + quando a represetação em string é a mesma. + <!-- TODO: example of it... --> + </simpara> + <simpara> + O primeiro será usado. + </simpara> + </note> + <warning> + <simpara> + Essa função não funcionava no PHP 4.0.4! + <!-- TODO: when exactly was this broken?... --> + </simpara> + </warning> + <para> + <example> + <title>Exemplo de <function>array_unique</function></title> + <programlisting role="php"> +<![CDATA[ +$input = array ("a" => "verde", "vermelho", "b" => "verde", "azul", "vermelho"); +$result = array_unique ($input); +print_r($result); +// a saída será : +//Array +//( +// [a] => verde +// [0] => vermelho +// [1] => azul +//) +]]> + </programlisting> + </example> + </para> + <para> + <example> + <title><function>array_unique</function> e tipos</title> + <programlisting role="php"> +<![CDATA[ +$input = array (4,"4","3",4,3,"3"); +$result = array_unique ($input); +var_dump($result); + +/* saída: +array(2) { + [0]=> + int(4) + [1]=> + string(1) "3" +} +*/ +]]> + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.array-unshift"> + <refnamediv> + <refname>array_unshift</refname> + <refpurpose> + Adiciona um ou mais elementos no início de um array + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>array_unshift</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>mixed <parameter>var</parameter></paramdef> + <paramdef>mixed + <parameter> + <optional>...</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_unshift</function> adiciona os elementos passados como + argumentos no início de <parameter>array</parameter>. Note que a lista + de elementos é adicionada como um todo, de forma que eles ficam na + mesma ordem. + </para> + <para> + Retorna o novo número de elementos de <parameter>array</parameter>. + </para> + <para> + <example> + <title>Exemplo de <function>array_unshift</function></title> + <programlisting role="php"> +<![CDATA[ +$queue = array ("p1", "p3"); +array_unshift ($queue, "p4", "p5", "p6"); +]]> + </programlisting> + </example> + </para> + <para> + Isso resultaria em <varname>$queue</varname> contendo 5 + elementos: "p4", "p5", "p6", "p1", e "p3". + </para> + <para> + Veja também <function>array_shift</function>, + <function>array_push</function>, e + <function>array_pop</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-values"> + <refnamediv> + <refname>array_values</refname> + <refpurpose>Retorna todos os valores de um array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_values</function></funcdef> + <paramdef>array <parameter>input</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_values</function> retorna todos os valores do array + <parameter>input</parameter>. + </para> + <para> + <example> + <title>Exemplo de <function>array_values</function></title> + <programlisting role="php"> +<![CDATA[ +$array = array ("tamanho" => "G", "cor" => "dourado"); +array_values ($array); // retorna o array ("G", "dourado") +]]> + </programlisting> + </example> + </para> + <note> + <para> + Essa função foi adicionada no PHP 4, abaixo segue uma implementação para + aqueles que ainda usam PHP 3. + <example> + <title> + Implementação de <function>array_values</function> para PHP 3 + users + </title> + <programlisting role="php"> +<![CDATA[ +function array_values ($arr) { + $t = array(); + while (list($k, $v) = each ($arr)) { + $t[] = $v; + } + return $t; +} +]]> + </programlisting> + </example> + </para> + </note> + <para> + Veja também <function>array_keys</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-walk"> + <refnamediv> + <refname>array_walk</refname> + <refpurpose> + Aplica uma determinada funcão em cada elemento de um array + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>array_walk</function></funcdef> + <paramdef>array <parameter>arr</parameter></paramdef> + <paramdef>string <parameter>func</parameter></paramdef> + <paramdef>mixed + <parameter><optional>userdata</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <simpara> + Aplica uma função definida pelo usuário nomeada pelo argumento + <parameter>func</parameter> em cada elemento de <parameter>arr</parameter>. + <parameter>func</parameter> terá como primeiro o argumento o valor do + elemento e sua chave como segndo parâmetro. Se + <parameter>userdata</parameter> for especificado, ele será usado como + terceiro argumento da função do usuário. <parameter>func</parameter> + deve ser uma função definida pelo usuário, e não uma função nativa do PHP. + Dessa forma, você não pode usar <function>array_walk</function> juntamente com + <function>str2lower</function>, primeiro deve ser definida uma função do + usuário, e depois passá-la como argumento. + </simpara> + <simpara> + Se <parameter>func</parameter> necessita de mais de dois ou três + argumentos, dependendo de <parameter>userdata</parameter>, um + será mostrado a cada vez que + <function>array_walk</function> executar + <parameter>func</parameter>. Esses avisos podem ser suprimidos + adicionando o operador '@' a chamada da função <function>array_walk</function>, + ou usando <function>error_reporting</function>. + </simpara> + <note> + <para> + Se <parameter>func</parameter> precisar alterar realmente os valores + do array, especifique que o primeiro parâmetro de + <parameter>func</parameter> deve ser passado por referência. Então + qualquer mudança feita nesses elementos serão feitas no próprio arra + também. + itself. + </para> + </note> + <note> + <para> + A passagem das chaves e do terceiro argumento para <parameter>func</parameter> foi + adicionada no PHP 4.0. + </para> + <para> + No PHP 4 <function>reset</function> precisa ser chamada necessariamente + uma vez que <function>array_walk</function> não reinicializa o array por + padrão. + </para> + </note> + <para> + <example> + <title>Exemplo de <function>array_walk</function></title> + <programlisting role="php"> +<![CDATA[ +$frutas = array ("d"=>"limao", "a"=>"laranja", "b"=>"banana", "c"=>"melancia"); + +function test_alter (&$item1, $key, $prefix) { + $item1 = "$prefix: $item1"; +} + +function test_print ($item2, $key) { + echo "$key. $item2<br>\n"; +} + +array_walk ($frutas, 'test_print'); +reset ($frutas); +array_walk ($frutas, 'test_alter', 'fruta'); +reset ($frutas); +array_walk ($frutas, 'test_print'); +]]> + </programlisting> + </example> + </para> + <simpara> + Veja também <function>each</function> e <function>list</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.arsort"> + <refnamediv> + <refname>arsort</refname> + <refpurpose> + Classifica um array em ordem descrescente mantendo a associação entre os + índices e os elementos + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>arsort</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>int + <parameter><optional>sort_flags</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Essa função classifica um array de forma que a correlação entre índices e + elementos é mantida. Usada principalmente para classificar arrays + associativos onde a ordem dos elementos é um fator importante. + </para> + <example> + <title>Exemplo de <function>arsort</function></title> + <programlisting role="php"> +<![CDATA[ +$frutas = array ("d"=>"limao", "a"=>"laranja", "b"=>"banana", "c"=>"melancia"); +arsort ($frutas); +reset ($frutas); +while (list ($chave, $valor) = each ($frutas)) { + echo "$chave = $valor\n"; +} +]]> + </programlisting> + <para> + A saída desse exemplo seria: + <screen> +<![CDATA[ +c = melancia +d = limao +a = laranja +b = banana +]]> + </screen> + </para> + </example> + <para> + As frutas foram classificadas na ordem alfabética inversa, e os índices + associados a cada elemento foram mantidos. + </para> + <para> + Você pode modificar o comportamento da classificação usando o parâmetro + opcional <parameter>sort_flags</parameter>, para detalhes veja + <function>sort</function>. + </para> + <para> + Veja também: <function>asort</function>, <function>rsort</function>, + <function>ksort</function>, e <function>sort</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.asort"> + <refnamediv> + <refname>asort</refname> + <refpurpose> + Classifica um array mantendo a associação entre os índices e + os elementos + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>asort</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>int + <parameter><optional>sort_flags</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Essa função classifica um array de forma que a correlação entre índices e + elementos é mantida. É usada principalmente para classificar arrays + associativos onde a ordem dos elementos é um fator importante. + </para> + <example> + <title>Exemplo de <function>asort</function></title> + <programlisting role="php"> +<![CDATA[ +$frutas = array ("d"=>"limao", "a"=>"laranja", "b"=>"banana", "c"=>"melancia"); +asort ($frutas); +reset ($frutas); +while (list ($chave, $valor) = each ($frutas)) { + echo "$chave = $valor\n"; +} +]]> + </programlisting> + <para> + A saída desse programa seria: + <screen> +<![CDATA[ +b = banana +a = laranja +d = limao +c = melancia +]]> + </screen> + </para> + </example> + <para> + As frutas foram classificadas na ordem alfabética, e os índices + associados a cada elemento foram mantidos. + </para> + <para> + Você pode modificar o comportamento da classificação usando o parâmetro + opcional <parameter>sort_flags</parameter>, para mais detalhes + veja <function>sort</function>. + </para> + <para> + veja também <function>arsort</function>, <function>rsort</function>, + <function>ksort</function>, e <function>sort</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.compact"> + <refnamediv> + <refname>compact</refname> + <refpurpose> + Cria um array contendo variáveis e seus valores + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>compact</function></funcdef> + <paramdef>mixed <parameter>varname</parameter></paramdef> + <paramdef>mixed + <parameter><optional>...</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>compact</function> recebe um número variável de + parâmetros. Cada Parâmetro pode ser tanto uma string contendo o nome da + variável, como também pode ser um array de nomes de variáveis. Sendo um + array, ele pode conter outros arrays de nomes de variáveis; + <function>compact</function> os trata recursivamente. + </para> + <para> + Para cada um dos parâmetros passados, <function>compact</function> procura + uma variável com o nome especificado na tabela de símbolos e a adiciona + no array de saída de forma que o nome da variável será a chave e o seu + conteúdo será o valor para esta chave. + Em resumo, ela faz o oposto de <function>extract</function>. + Retorna um array de saída com todas as variáveis adicionadas ele. + </para> + <para> + Qualquer string com nome de uma variável que não exista será simplesmente + ignorada. + </para> + <para> + <example> + <title>Exemplo de <function>compact</function></title> + <programlisting role="php"> +<![CDATA[ +$cidade = "Sao Paulo"; +$estado = "SP"; +$evento = "SIGGRAPH"; + +$localidade = array ("cidade", "estado"); + +$result = compact ("evento", "nada_aqui", $localidade); +]]> + </programlisting> + <para> + Depois disso, <varname>$result</varname> será <literal>array + ("evento" => "SIGGRAPH", "cidade" => "Sao Paulo", + "estado" => "SP")</literal>. + </para> + </example> + </para> + <para> + Veja também <function>extract</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.count"> + <refnamediv> + <refname>count</refname> + <refpurpose>Conta o número de elementos de uma variável</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>count</function></funcdef> + <paramdef>mixed <parameter>var</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Retorna o número de elementos de <parameter>var</parameter>, + que normalmente é um <type>array</type> (uma vez que qualquer outra coisa + só terá apenas um elemento). + </para> + <para> + Se <parameter>var</parameter> não for um array, <literal>1</literal> será + retornado (excessão: <literal>count(&null;)</literal> retorna + <literal>0</literal>). + </para> + <warning> + <para> + <function>count</function> pode retornar 0 para uma variável + que não existe, mas também pode retornar 0 para uma variável que tenha + sido inicializada como um array vazio. Use + <function>isset</function> para checar se uma variável existe. + </para> + </warning> + <para> + Por favor, veja a sessão <link linkend="language.types.array">Arrays</link> + do manual para uma explicação mais detalhada sobre como os arrays são + implementados e utilizados no PHP. + </para> + <para> + <example> + <title>Exemplo de <function>count</function></title> + <programlisting role="php"> + <!-- TODO: examples about count(null), count(false), count(object).. --> +<![CDATA[ +$a[0] = 1; +$a[1] = 3; +$a[2] = 5; +$result = count ($a); +// $result == 3 + +$b[0] = 7; +$b[5] = 9; +$b[10] = 11; +$result = count ($b); +// $result == 3; +]]> + </programlisting> + </example> + </para> + <note> + <para> + A função <function>sizeof</function> é um apelido para + <function>count</function>. + </para> + </note> + <para> + Veja também: <function>sizeof</function>, + <function>isset</function>, e + <function>is_array</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.current"> + <refnamediv> + <refname>current</refname> + <refpurpose>Retorna o elemento corrente em um array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>current</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Todo array tem um ponteiro interno para o elemento "atual", + o qual é inicializado para apontar para o primeiro elemento inserido em + um array. + </para> + <para> + A função <function>current</function> simplismente retorna + o elemento do array para o qual esse ponteiro interno está apontando. + Não move o ponteiro de forma alguma. Se o ponteiro interno + estiver apontando para além do final da lista de elementos, + <function>current</function> retorna &false;. + <warning> + <para> + Se o array contêm elementos vazios (0 ou "", a + string vazia) então esta função retorna &false; + para esses elementos. Isso faz com que seja impossível + determinar se você está realmente no final da lista de elementos de + array usando <function>current</function>. Para percorrer + devidamente um array que pode conter elementos vazios, use a função + <function>each</function>. + </para> + </warning> + </para> + <para> + Veja também: <function>end</function>, <function>next</function>, + <function>prev</function>, e <function>reset</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.each"> + <refnamediv> + <refname>each</refname> + <refpurpose> + Retorna o par chave/valor corrente de um array e avança o seu cursor + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>each</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Retorna o par chave/valor corrente de + <parameter>array</parameter> e avança o seu cursor. Esse + par é retornado num array de quatro elementos, com as chaves + <emphasis>0</emphasis>, <emphasis>1</emphasis>, + <emphasis>key</emphasis>, e + <emphasis>value</emphasis>. Os elementos <emphasis>0</emphasis> e + <emphasis>key</emphasis> contêm o nome da chave do elemento do array, e + <emphasis>1</emphasis> e <emphasis>value</emphasis> contêm o valor. + </para> + <para> + Se o cursor interno do array estiver apontando para além do final do + array, <function>each</function> retorna &false;. + </para> + <para> + <example> + <title>Exemplos de <function>each</function></title> + <programlisting role="php"> +<![CDATA[ +$foo = array ("bob", "fred", "jussi", "jouni", "egon", "marliese"); +$bar = each ($foo); +]]> + </programlisting> + <para> + <varname>$bar</varname> agora contem os seguintes pares de chaves e + valores: + <itemizedlist spacing="compact"> + <listitem><simpara>0 => 0</simpara></listitem> + <listitem><simpara>1 => 'bob'</simpara></listitem> + <listitem><simpara>key => 0</simpara></listitem> + <listitem><simpara>value => 'bob'</simpara></listitem> + </itemizedlist> + <programlisting role="php"> +<![CDATA[ +$foo = array ("Robert" => "Bob", "Seppo" => "Sepi"); +$bar = each ($foo); +]]> + </programlisting> + </para> + <para> + <varname>$bar</varname> agora contem os seguintes pares de chaves e + valores: + <itemizedlist spacing="compact"> + <listitem><simpara>0 => 'Robert'</simpara></listitem> + <listitem><simpara>1 => 'Bob'</simpara></listitem> + <listitem><simpara>key => 'Robert'</simpara></listitem> + <listitem><simpara>value => 'Bob'</simpara></listitem> + </itemizedlist> + </para> + </example> + </para> + <para> + <function>each</function> é tipicamente usada em conjunto com + <function>list</function> para percorrer o array; por exemplo, + <varname>$HTTP_POST_VARS</varname>: + <example> + <title> + Percorrendo <varname>$HTTP_POST_VARS</varname> usando + <function>each</function> + </title> + <programlisting role="php"> +<![CDATA[ +echo "Valores submetidos pelo método POST:<br>"; +reset ($HTTP_POST_VARS); +while (list ($chave, $valor) = each ($HTTP_POST_VARS)) { + echo "$chave => $valor<br>"; +} +]]> + </programlisting> + </example> + </para> + <para> + Depois da execução de <function>each</function>, o cursor interno do + array vai apontar para o prócimo elemento do array, ou no último + elemento se ele chegar ao final do array. Você deve usar + <function>reset</function> se quiser percorrer o array novamente. + </para> + <para> + Veja também <function>key</function>, <function>list</function>, + <function>current</function>, <function>reset</function>, + <function>next</function>, e <function>prev</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.end"> + <refnamediv> + <refname>end</refname> + <refpurpose> + Faz com que o ponteiro interno de um array aponte para o seu último + elemento + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>end</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>end</function> avança o ponteiro interno de <parameter>array</parameter> + até o seu último elemento, e retorna esse elemento. + </para> + <para> + Veja também: <function>current</function>, + <function>each</function>, <function>end</function>, + <function>next</function>, e <function>reset</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.extract"> + <refnamediv> + <refname>extract</refname> + <refpurpose> + Importa variáveis para a tabela de símbolos a partir de um array + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>extract</function></funcdef> + <paramdef>array <parameter>var_array</parameter></paramdef> + <paramdef>int + <parameter><optional>extract_type</optional></parameter> + </paramdef> + <paramdef>string + <parameter><optional>prefix</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Essa é usada para importar variáveis a partir de um array para a tabela + de símbolos corrente. Recebe o array associativo + <parameter>var_array</parameter> e trata as suas chaves como + os nomes das variáveis e os valores como valores das variáveis. + Para cada par chave/valor ele criará uma variável na tabela de símbolos + corrente, seguindo os parâmetros + <parameter>extract_type</parameter> e + <parameter>prefix</parameter>. + </para> + <note> + <para> + Desde a versão 4.0.5 essa função retorna o número de variáveis + extraídas. + </para> + </note> + <para> + <function>extract</function> checa se cada chave do array constituinum + nome de variável válido e por colisões com as variáveis já existentes na + tabela de símbolos. O modo com que chaves inválidas ou númericas e colisões + são tratadas é determinado pelo argumento + <parameter>extract_type</parameter>. Esse argumento pode receber os + seguintes valores: + <variablelist> + <varlistentry> + <term>EXTR_OVERWRITE</term> + <listitem> + <simpara> + Se houver uma colisão, sobrescreve a variável existente. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>EXTR_SKIP</term> + <listitem> + <simpara> + Se houver uma colisão, não sobrescreve a variável existente. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>EXTR_PREFIX_SAME</term> + <listitem> + <simpara>Se houver uma colisão, adiciona um prefixo ao nome da + variável definido pelo argumento + <parameter>prefix</parameter>. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>EXTR_PREFIX_ALL</term> + <listitem> + <simpara> + Adiciona um prefixo ao nome de todas as variáveis definido por + <parameter>prefix</parameter>. Desde o PHP 4.0.5 estão incluídos + nomes numéricos. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>EXTR_PREFIX_INVALID</term> + <listitem> + <simpara> + Adiciona um prefixo definido por <parameter>prefix</parameter> apenas + para variáveis como nomes inválidos ou numéricos. Essa opção foi adicionada no + PHP 4.0.5. + </simpara> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + Se <parameter>extract_type</parameter> não for especificado, é assumido + o valor EXTR_OVERWRITE por padrão. + </para> + <para> + Note que <parameter>prefix</parameter> só é necessário se + <parameter>extract_type</parameter> for EXTR_PREFIX_SAME, + EXTR_PREFIX_ALL, ou EXTR_PREFIX_INVALID. se o nome com o prefixo + não for um nome de variável válido, ela não será importada para a tabela + de símbolos. + </para> + <para> + <function>extract</function> retorna o número de variáveis importadas + com sucesso para a tbela de símbolos. + </para> + <para> + Um uso comum de extract e na importação de + variáveis contidas num array associativo retornado pela função + <function>wddx_deserialize</function>. + </para> + <para> + <example> + <title>Exemplo de <function>extract</function></title> + <programlisting role="php"> +<![CDATA[ +<?php + +/* Suponha que $var_array é um array retornado pela função + wddx_deserialize */ + +$tamanho = "grande"; +$var_array = array ("cor" => "azul", + "tamanho" => "medio", + "forma" => "esfera"); +extract ($var_array, EXTR_PREFIX_SAME, "wddx"); + +print "$cor, $tamanho, $forma, $wddx_tamanho\n"; + +?> +]]> + </programlisting> + </example> + </para> + <para> + O exemplo acima produziria: + <programlisting> +<![CDATA[ +azul, grande, esfera, medio +]]> + </programlisting> + </para> + <para> + O <varname>$tamanho</varname> não foi sobrescrito, porque + nós especificamos EXTR_PREFIX_SAME, o que resultou na criação da variável + <varname>$wddx_tamanho</varname>. Se EXTR_SKIP fosse + utilizado, então $wddx_tamanho não seria criada. + EXTR_OVERWRITE teria feito com que <varname>$size</varname> tivesse + o valor "medio", e EXTR_PREFIX_ALL resultaria em novas variáveis + com os nomes <varname>$wddx_cor</varname>, + <varname>$wddx_tamanho</varname>, e + <varname>$wddx_forma</varname>. + </para> + <para> + Você deve usar um arra associativo, um array indexado numericamente não + produzirá resultados. + </para> + <para> + Veja também: <function>compact</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.in-array"> + <refnamediv> + <refname>in_array</refname> + <refpurpose>Retorna &true; se um valor existe no array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>in_array</function></funcdef> + <paramdef>mixed <parameter>needle</parameter></paramdef> + <paramdef>array <parameter>haystack</parameter></paramdef> + <paramdef>bool + <parameter><optional>strict</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Procura em <parameter>haystack</parameter> pelo valor + <parameter>needle</parameter> e retorna &true; + se este valor for encontrado no array, e &false; em caso contrário. + </para> + <para> + Se o terceiro parâmetro <parameter>strict</parameter> for + &true; então <function>in_array</function> + também irá checar os <link linkend="language.types">tipos</link> de + <parameter>needle</parameter> em <parameter>haystack</parameter>. + </para> + <para> + <example> + <title>Exemplo de <function>in_array</function></title> + <programlisting role="php"> +<![CDATA[ +$os = array ("Mac", "NT", "Irix", "Linux"); +if (in_array ("Irix", $os)) { + print "Tem Irix"; +} +]]> + </programlisting> + </example> + </para> + <para> + <example> + <title><function>in_array</function> com checagem de tipos</title> + <programlisting role="php"> +<![CDATA[ +<?php +$a = array('1.10', 12.4, 1.13); + +if (in_array('12.4', $a, TRUE)) + echo "'12.4' encontrado com checagem de tipo\n"; +if (in_array(1.13, $a, TRUE)) + echo "1.13 encontrado com checagem de tipo\n"; +?> + +// Isso irá produzir: + +1.13 encontrado com checagem de tipo +]]> + </programlisting> + </example> + </para> + <para> + Veja também <function>array_search</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-search"> + <refnamediv> + <refname>array_search</refname> + <refpurpose> + Procura por um valor em um array e retorna sua chave correspondente + caso seja encontrado + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>array_search</function></funcdef> + <paramdef>mixed <parameter>needle</parameter></paramdef> + <paramdef>array <parameter>haystack</parameter></paramdef> + <paramdef>bool <parameter><optional>strict</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Procura em <parameter>haystack</parameter> pelo valor + <parameter>needle</parameter> e retorna sua chave se for encontrado no + array, &false; em caso contrário. + </para> + <para> + se o terceiro parâmetro opcional <parameter>strict</parameter> for + fornecido como &true; então <function>array_search</function> + também fará uma checagem de tipos de <parameter>needle</parameter> + em <parameter>haystack</parameter>. + </para> + <para> + Veja também <function>in_array</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.key"> + <refnamediv> + <refname>key</refname> + <refpurpose>Retorna uma chave de um array associativo</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>key</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>key</function> retorna a chave da posição corrente de um + array. + </para> + <para> + Veja também <function>current</function> e <function>next</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.krsort"> + <refnamediv> + <refname>krsort</refname> + <refpurpose>Classifica um array pelas chaves em ordem descrescente</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>krsort</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>int + <parameter><optional>sort_flags</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Classifica um array pelas chaves em ordem descrescente, mantendo a + correlação entre entre as chaves e os valores. Essa função é bastante + útil em arrays associativos. + <example> + <title>Exemplo de <function>krsort</function></title> + <programlisting role="php"> +<![CDATA[ +$frutas = array ("d"=>"limao", "a"=>"laranja", "b"=>"banana", "c"=>"melancia"); +krsort ($frutas); +reset ($frutas); +while (list ($chave, $valor) = each ($frutas)) { + echo "$chave = $valor\n"; +} +]]> + </programlisting> + </example> + </para> + <para> + A saída deste programa seria: + </para> + <para> + <informalexample> + <programlisting> +<![CDATA[ +d = limao +c = melancia +b = banana +a = laranja +]]> + </programlisting> + </informalexample> + </para> + <para> + Você pode alterar o comportamento da classificação utilizando o + parâmetro opcional <parameter>sort_flags</parameter>, para mais detalhes + veja <function>sort</function>. + </para> + <simpara> + Veja também <function>asort</function>, <function>arsort</function>, + <function>ksort</function> <function>sort</function>, + <function>natsort</function> e <function>rsort</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.ksort"> + <refnamediv> + <refname>ksort</refname> + <refpurpose>Classifica um array pelas chaves</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ksort</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>int + <parameter><optional>sort_flags</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Classifica um array pelas chaves, mantendo a correlação entre as chaves e + os valores. Essa função é bastante útil principalmente em arrays + associativos. + <example> + <title>Exemplo de <function>ksort</function></title> + <programlisting role="php"> +<![CDATA[ +$frutas = array ("d"=>"limao", "a"=>"laranja", "b"=>"banana", "c"=>"melancia"); +ksort ($frutas); +reset ($frutas); +while (list ($chave, $valor) = each ($frutas)) { + echo "$chave = $valor\n"; +} +]]> + </programlisting> + </example> + </para> + <para> + O programa acima mostraria: + </para> + <para> + <informalexample> + <programlisting> +<![CDATA[ +a = laranja +b = banana +c = melancia +d = limao +]]> + </programlisting> + </informalexample> + </para> + <para> + Você pode modificar o comportamento da classificação através do parâmetro + opcional <parameter>sort_flags</parameter>, para mais detalhes + veja <function>sort</function>. + </para> + <simpara> + Veja também <function>asort</function>, <function>arsort</function>, + <function>sort</function>, <function>natsort</function>, e + <function>rsort</function>. + </simpara> + <note> + <para> + O segundo parâmetro foi adicionado a partir do PHP 4. + </para> + </note> + </refsect1> + </refentry> + + <refentry id="function.list"> + <refnamediv> + <refname>list</refname> + <refpurpose> + Cria variáveis como se fossem arrays + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>list</function></funcdef> + <varargs/> + </funcprototype> + </funcsynopsis> + <para> + Assim como <function>array</function>, não é exatamente uma função, + e sim uma estrutura da própria linguagem. <function>list</function> é usada + para criar uma lista de variáveis em apenas um operação. + <example> + <title>Exemplo de <function>list</function></title> + <programlisting role="php"> +<![CDATA[ +<table> + <tr> + <th>Nome do empregado</th> + <th>Salário</th> + </tr> + +<?php + +$resultado = mysql_query ("SELECT id, nome, salario FROM empregados",$conn); +while (list ($id, $nome, $salario) = mysql_fetch_row ($resultado)) { + print (" <tr>\n". + " <td><a href=\"info.php3?id=$id\">$nome</a></td>\n". + " <td>$salario</td>\n". + " </tr>\n"); +} + +?> + +</table> +]]> + </programlisting> + </example> + </para> + <para> + Veja também <function>each</function> e <function>array</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.natsort"> + <refnamediv> + <refname>natsort</refname> + <refpurpose> + Classifica um array utlizando o algoritmo da "ordem natural" + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>natsort</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Essa função é um implementação do algoritmo que ordena + strings alfanuméricas da forma como um ser humano faria. Isso é + chamado de "ordenação natural". Um exemplo da diferença entre + esse algoritmo e o algoritmo com o qual o computador classifica strings + (usado em <function>sort</function>) pode ser visto abaixo: + </para> + <para> + <example> + <title>Exemplo de <function>natsort</function></title> + <programlisting role="php"> +<![CDATA[ +$array1 = $array2 = array ("img12.png", "img10.png", "img2.png", "img1.png"); + +sort($array1); +echo "Classificação normal\n"; +print_r($array1); + +natsort($array2); +echo "\nClassificação da \"ordem natural\"\n"; +print_r($array2); +]]> + </programlisting> + </example> + </para> + <para> + O código acima geraria a seguinte saída: + </para> + <para> + <informalexample> + <programlisting> +<![CDATA[ +Classificação normal +Array +( + [0] => img1.png + [1] => img10.png + [2] => img12.png + [3] => img2.png +) + +Classificação da "ordem natural" +Array +( + [3] => img1.png + [2] => img2.png + [1] => img10.png + [0] => img12.png +) +]]> + </programlisting> + </informalexample> + Para mais informações veja: Martin Pool's <ulink + url="&url.strnatcmp;">Natural Order String Comparison</ulink> + page. + </para> + <para> + Veja também <function>natcasesort</function>, + <function>strnatcmp</function> e + <function>strnatcasecmp</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.natcasesort"> + <refnamediv> + <refname>natcasesort</refname> + <refpurpose> + Classifica um array utilizando o algoritmo da "ordem natural" sem + diferenciar maiúsculas e minúsculas + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>natcasesort</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Essa função implementa o algoritmo de classificação que ordena + strings alfanuméricas da forma que os humanas fariam. Essa forma de + classificação é denominada "ordenação natural". + </para> + <para> + <function>natcasesort</function> é uma versão de + <function>natsort</function> que não diferencia letras maiúsculas e + minúsculas. Veja <function>natsort</function> + para saber a diferença entrre esse algoritmo e os algoritmos + utlizados normalmente para ordenação de strings. + </para> + <para> + Para mais informações veja: Martin Pool's <ulink + url="&url.strnatcmp;">Natural Order String Comparison</ulink> + page. + </para> + <para> + Veja também <function>sort</function>, + <function>natsort</function>, + <function>strnatcmp</function> e + <function>strnatcasecmp</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.next"> + <refnamediv> + <refname>next</refname> + <refpurpose> + Avança o ponteiro interno de um array + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>next</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Retorna o elemento do array que está na próxima posição que é apontada + pelo ponteiro interno do array, &false; caso não existam mais elementos. + </para> + <para> + <function>next</function> funciona de forma semelhante a + <function>current</function>, com uma diferença. Ele avança o + ponteiro interno do array em uma posição antes de retornar o + elemento. Isso significa que ela retorna o próximo elemento do array + avançando o ponteiro interno em uma posição. Se o ponteiro + interno apontar para além do final da lista de elementos + , <function>next</function> retorna &false;. + <warning> + <para> + Se o array contiver elementos vazios, ou elementos tiverem chaves + com 0 como valor então essa função retorna &false; + para esses elementos. Para percorrer um array que + pode conter elementos vazios ou elementos que tenham chaves com 0 como valor + veja a função <function>each</function>. + </para> + </warning> + </para> + <para> + Veja também: + <function>current</function>, <function>end</function>, + <function>prev</function>, e <function>reset</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.pos"> + <refnamediv> + <refname>pos</refname> + <refpurpose>Retorna o elemento atual do array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>pos</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <simpara> + Essa função é igual a <function>current</function>. + </simpara> + <para> + See also: + <function>end</function>, <function>next</function>, + <function>prev</function> e <function>reset</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.prev"> + <refnamediv> + <refname>prev</refname> + <refpurpose>Retrocede o ponteiro interno de um array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>prev</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Retorna o elemento do array que está na posição anterior a posição apontada + pelo ponteiro interno, ou &false; se houver mais elementos. + <warning> + <para> + Se o array contiver elementos vazios então essa função retornará + &false; para esses elementos. + Para percorrer corretamente arrays que podem conter elementos vazios + veja a função <function>each</function>. + </para> + </warning> + </para> + <para> + <function>prev</function> funciona da mesma forma que + <function>next</function>, com a única sendo a de que a primeira + retrocede o ponteiro interno em uma posição ao invés de avançá-lo. + </para> + <para> + Veja também: <function>current</function>, <function>end</function>, + <function>next</function>, e <function>reset</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.range"> + <refnamediv> + <refname>range</refname> + <refpurpose> + Cria um array contendo uma faixa de elementos + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>range</function></funcdef> + <paramdef>mixed <parameter>low</parameter></paramdef> + <paramdef>mixed <parameter>high</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>range</function> retorna um array com elementos de + <parameter>low</parameter> até <parameter>high</parameter>, + com intervalo fechado. Se low > high, será de high até low. + <example> + <title>Exemplos de <function>range</function></title> + <programlisting role="php"> +<![CDATA[ +foreach(range(0, 9) as $numero) { + echo $numero; +} +foreach(range('a', 'z') as $letra) { + echo $letra; +} +foreach(range('z', 'a') as $letra) { + echo $letra; +} +]]> + </programlisting> + </example> + </para> + <note> + <para> + Até a versão 4.1.0, a função <function>range</function> só gerava + arrays de inteiros em ordem crescente. O suporte para + sequências de caracteres e arrays descrescentes foi adicionado no PHP 4.1.0. + </para> + </note> + <para> + Veja <function>shuffle</function> para outro exemplo de utilização dessa + função. + </para> + </refsect1> + </refentry> + + <refentry id="function.reset"> + <refnamediv> + <refname>reset</refname> + <refpurpose> + Faz o ponteiro interno de um array apontar para o seu primeiro elemento + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>reset</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>reset</function> retrocede o ponteiro interno de <parameter>array</parameter> + para o primeiro elemento. + </para> + <para> + <function>reset</function> retorna o valor do primeiro elemento do array. + </para> + <para> + Veja também: <function>current</function>, + <function>each</function>, <function>next</function>, + e <function>prev</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.rsort"> + <refnamediv> + <refname>rsort</refname> + <refpurpose>Classifica um array em ordem descrescente</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>rsort</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>int + <parameter><optional>sort_flags</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + essa função classifica um array para a ordem descrescente (do maior para o menor). + <example> + <title>Exemplo de <function>rsort</function></title> + <programlisting role="php"> +<![CDATA[ +$frutas = array ("limao", "laranja", "banana", "melancia"); +rsort ($frutas); +reset ($frutas); +while (list ($chave, $valor) = each ($frutas)) { + echo "$chave = $valor\n"; +} +]]> + </programlisting> + </example> + </para> + <para> + Esse exemplo mostraria: + </para> + <para> + <informalexample> + <programlisting> +<![CDATA[ +0 = melancia +1 = limao +2 = laranja +3 = banana +]]> + </programlisting> + </informalexample> + </para> + <para> + As frutas foram classificadas em ordem alfabética decrescente. + </para> + <para> + Você pode alterar o comportamento da classificação utilizando o parâmetro + opcional <parameter>sort_flags</parameter>, para mais detalhes + veja <function>sort</function>. + </para> + <para> + Veja também: <function>arsort</function>, + <function>asort</function>, <function>ksort</function>, + <function>sort</function>, e <function>usort</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.shuffle"> + <refnamediv> + <refname>shuffle</refname> + <refpurpose>Mistura os elementos de um array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>shuffle</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Essa função mistura de forma aleatória os elementos de um + array. Você deve usar essa função em conjunto com <function>srand</function>. + <example> + <title>Exemplo de <function>shuffle</function></title> + <programlisting role="php"> +<![CDATA[ +$numeros = range (1,20); +srand ((float)microtime()*1000000); +shuffle ($numeros); +while (list (, $numero) = each ($numeros)) { + echo "$numero "; +} +]]> + </programlisting> + </example> + </para> + <para> + Veja também <function>arsort</function>, <function>asort</function>, + <function>ksort</function>, <function>rsort</function>, + <function>sort</function> e <function>usort</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.sizeof"> + <refnamediv> + <refname>sizeof</refname> + <refpurpose>Retorna o número de elementos de uma variável</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>sizeof</function></funcdef> + <paramdef>mixed <parameter>var</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>sizeof</function> é igual a + <function>count</function>. + </para> + <para> + Veja também <function>count</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.sort"> + <refnamediv> + <refname>sort</refname> + <refpurpose>Classifica um array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>sort</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>int + <parameter><optional>sort_flags</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Essa função classifica um array. Os elementos serão ordenador + do menor para o maior ao final da execução dessa função. + <example> + <title>Exemplo de <function>sort</function></title> + <programlisting role="php"> +<![CDATA[ +<?php + +$frutas = array ("limao", "laranja", "banana", "melancia"); +sort ($frutas); +reset ($frutas); +while (list ($chave, $valor) = each ($frutas)) { + echo "frutas[".$chave."] = ".$valor."\n"; +} + +?> +]]> + </programlisting> + </example> + </para> + <para> + A saída desse programa seria: + </para> + <para> + <informalexample> + <programlisting> +<![CDATA[ +fruits[0] = banana +fruits[1] = laranja +fruits[2] = limao +fruits[3] = melancia +]]> + </programlisting> + </informalexample> + </para> + <para> + As frutas foram classificadas em ordem alfabética. + </para> + <para> + O segundo argumento opcional <parameter>sort_flags</parameter> + pode ser usada para modificar o comportamento da classificação podendo + receber os seguintes valores: + </para> + <para> + Sinais de tipo de classificação: + <itemizedlist> + <listitem> + <simpara>SORT_REGULAR - compara os itens normalmente</simpara> + </listitem> + <listitem> + <simpara>SORT_NUMERIC - compara os itens como valores numéricos</simpara> + </listitem> + <listitem> + <simpara>SORT_STRING - compara os itens como strings</simpara> + </listitem> + </itemizedlist> + </para> + <para> + Veja também: <function>arsort</function>, + <function>asort</function>, <function>ksort</function>, + <function>natsort</function>, <function>natcasesort</function>, + <function>rsort</function>, <function>usort</function>, + <function>array_multisort</function>, e + <function>uksort</function>. + </para> + <note> + <para> + O segundo parâmetro foi adicionado a partir do PHP 4. + </para> + </note> + </refsect1> + </refentry> + + <refentry id="function.uasort"> + <refnamediv> + <refname>uasort</refname> + <refpurpose> + Classifica um array utlizando uma função de comparação definida pelo usuário e mantendo + as associações dos índices + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>uasort</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>function <parameter>cmp_function</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Essa função classifica um array de forma que a correlação entre os + índices e os elementos com que estão associados. Essa função usada + principalmente para classificar arrays associativos onde a ordem dos + elementos é um fator importante. A função de comparacão é definida pelo + usuário. + </para> + <note> + <para> + Por favor, veja <function>usort</function> e + <function>uksort</function> para exemplos de funções de comparação definidas pelo + usuário. + </para> + </note> + <para> + Veja também: <function>usort</function>, <function>uksort</function>, + <function>sort</function>, <function>asort</function>, + <function>arsort</function>, <function>ksort</function> + e <function>rsort</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.uksort"> + <refnamediv> + <refname>uksort</refname> + <refpurpose> + Classifica um array pelas chaves utilizando uma função de comparação + definida pelo usuário. + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>uksort</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>function <parameter>cmp_function</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Essa função ia classificar as chaves de um array usando uma função de + comparação definida pelo usuário. Se o array + precisa ser classificado utilizando um critério não trivial, você deve + usar essa função. + </para> + <para> + <example> + <title>Exemplo de <function>uksort</function></title> + <programlisting role="php"> +<![CDATA[ +function cmp ($a, $b) { + if ($a == $b) return 0; + return ($a > $b) ? -1 : 1; +} + +$a = array (4 => "quatro", 3 => "tres", 20 => "vinte", 10 => "dez"); + +uksort ($a, "cmp"); + +while (list ($chave, $valor) = each ($a)) { + echo "$chave: $valor\n"; +} +]]> + </programlisting> + </example> + </para> + <para> + Esse exemplo mostraria: + </para> + <para> + <informalexample> + <programlisting> +<![CDATA[ +20: vinte +10: dez +4: quatro +3: tres +]]> + </programlisting> + </informalexample> + </para> + <para> + Veja também: <function>usort</function>, <function>uasort</function>, + <function>sort</function>, <function>asort</function>, + <function>arsort</function>, <function>ksort</function>, + <function>natsort</function> e <function>rsort</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.usort"> + <refnamediv> + <refname>usort</refname> + <refpurpose> + Classifica um array pelos valores utilizando uma função de comparação + definida pelo usuário + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>usort</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>string <parameter>cmp_function</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Essa função irá classificar um array pelos valores usando uma função de + classificação definida pelo usuário. Se o array precisar ser classificado + utilizando um critério não trivial, você deve usar essa função. + </para> + <para> + A função de comparação deve retornar um inteiro menor, igual ou maior que + zero se o primeiro argumento for considerado respectivamente menor, + igual, ou maior que o segundo. Se dois elementos forem iguais, a ordem + deles será indefinida. + </para> + <para> + Também é possível utilizar uma função membro de um objeto como a função + de comparação. Veja o exemplo 3 abaixo: + </para> + <para> + <example> + <title>Exemplo de <function>usort</function></title> + <programlisting role="php"> +<![CDATA[ +function cmp ($a, $b) { + if ($a == $b) return 0; + return ($a > $b) ? -1 : 1; +} + +$a = array (3, 2, 5, 6, 1); + +usort ($a, "cmp"); + +while (list ($chave, $valor) = each ($a)) { + echo "$chave: $valor\n"; +} +]]> + </programlisting> + </example> + </para> + <para> + Esse exemplo mostraria: + </para> + <para> + <informalexample> + <programlisting> +<![CDATA[ +0: 6 +1: 5 +2: 3 +3: 2 +4: 1 +]]> + </programlisting> + </informalexample> + </para> + <note> + <para> + Obviamente que nesse caso trivial a função<function>rsort</function> + seria mais apropriada. + </para> + </note> + <para> + <example> + <title> + Exemplo de <function>usort</function> usando um array multi-dimensional + </title> + <programlisting role="php"> +<![CDATA[ +function cmp ($a, $b) { + return strcmp($a["fruta"], $b["fruta"]); +} + +$frutas[0]["fruta"] = "limoes"; +$frutas[1]["fruta"] = "abacaxis"; +$frutas[2]["fruta"] = "goiabas"; + +usort($frutas, "cmp"); + +while (list ($chave, $valor) = each ($frutas)) { + echo "\$frutas[$chave]: " . $valor["fruta"] . "\n"; +} +]]> + </programlisting> + </example> + </para> + <para> + Na classificação de um array multi-dimensional, $a e $b contêm + referências para o primeiro índice do array. + </para> + <para> + Esse exemplo mostraria: + </para> + <para> + <informalexample> + <programlisting> +<![CDATA[ +$fruits[0]: abacaxis +$fruits[1]: goiabas +$fruits[2]: limoes +]]> + </programlisting> + </informalexample> + </para> + + <para> + <example> + <title> + Exemplo de <function>usort</function> usando uma função membro de um + objeto + </title> + <programlisting role="php"> +class TestObj { + var $name; + + function TestObj($name) + { + $this->name = $name; + } + + /* Essa é a função estática de comparação */ + function cmp_obj($a, $b) + { + $al = strtolower($a->name); + $bl = strtolower($b->name); + if ($al == $bl) return 0; + return ($al > $bl) ? +1 : -1; + } +} + +$a[] = new TestObj("c"); +$a[] = new TestObj("b"); +$a[] = new TestObj("d"); + +uasort($a, array ("TestObj", "cmp_obj")); + +foreach ($a as $item) { + print $item->name."\n"; +} + </programlisting> + </example> + </para> + <para> + Esse exemplo mostraria: + </para> + <para> + <informalexample> + <programlisting> +b +c +d + </programlisting> + </informalexample> + </para> + <para> + <warning> + <para> + + </para> + </warning> + </para> + <para> + Veja também: <function>uasort</function>, + <function>uksort</function>, <function>sort</function>, + <function>asort</function>, + <function>arsort</function>,<function>ksort</function>, + <function>natsort</function>, e <function>rsort</function>. + </para> + </refsect1> + </refentry> + + </reference> + +<!-- 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 +sgml-parent-document:nil +sgml-default-dtd-file:"../../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 +-->
Index: phpdoc/pt_BR/functions/array.xml diff -u /dev/null phpdoc/pt_BR/functions/array.xml:1.3 --- /dev/null Thu Dec 13 11:14:37 2001 +++ phpdoc/pt_BR/functions/array.xml Thu Dec 13 11:14:37 2001 @@ -0,0 +1,3712 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- $Revision: 1.3 $ --> + <reference id="ref.array"> + <title>Array Functions</title> + <titleabbrev>Arrays</titleabbrev> + <partintro> + <simpara> + Essas funções permitem a interação e manipulação de arrays de + várias formas. Arrays são essenciais para armazenar, gerenciar, + operar sobre um conjunto de variáveis. + </simpara> + <simpara> + Arras simples e multidimensionais (matrizes) são suportados, e podem + ser criados pelo usuário ou por outras funções. + Existem diversas funções específicas para bancos de dados para preencher + arrays com os dados retornados em consultas, e vários outros tipos de funções + também retornam arrays. + </simpara> + <para> + Por favor, veja a seção <link linkend="language.types.array">Arrays</link> + do manual para uma explicação mais detalhada sobre como arrays são + implementados e utilizados no PHP. + </para> + <para> + Veja também <function>is_array</function>, <function>explode</function>, + <function>implode</function>, <function>split</function> + e <function>join</function>. + </para> + </partintro> + + <refentry id="function.array"> + <refnamediv> + <refname>array</refname> + <refpurpose> + Cria um array + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array</function></funcdef> + <paramdef>mixed + <parameter><optional>...</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Retorna um array de parâmetros fornecidos. Índices podem ser atribuidos + aos parâmetros através do operador <literal>=></literal>. + </para> + <para> + <note> + <para> + <function>array</function> é uma estrutura utilizada para representar + literais de arrays, e não uma função. + </para> + </note> + </para> + <para> + A forma "index => values", separados por vírgulas, definem índice e + valores respectivamente. O índice por de ser do tipo string ou numérico. + Quando o índice é omitido, um índice numérico inteiro é automaticamente + gerado, começando do 0. Se o índice é um inteiro, o próximo índice a ser + gerado será igual ao maior índice inteiro + 1. Note que quando dois + índices idênticos são definidos, o último sobrescreve o primeiro. + </para> + <para> + O exemplo a seguir demonstra como criar um array com duas dimensões, como + especificar chaves em arrays associativos, e como definir índices + numéricos em arrays normais. + <example> + <title>Exemplo de <function>array</function></title> + <programlisting role="php"> +<![CDATA[ +$frutas = array ( + "frutas" => array ("a"=>"laranja", "b"=>"banana", "c"=>"melancia"), + "numeros" => array (1, 2, 3, 4, 5, 6), + "buracos" => array ("primeiro", 5 => "segundo", "terceiro") +); +]]> + </programlisting> + </example> + </para> + <para> + <example> + <title>Índices automáticos com <function>array</function></title> + <programlisting role="php"> +<![CDATA[ +$array = array( 1, 1, 1, 1, 1, 8=>1, 4=>1, 19, 3=>13); +print_r($array); +]]> + </programlisting> + <para> + vai mostrar : + <screen role="php"> +<![CDATA[ +Array +( + [0] => 1 + [1] => 1 + [2] => 1 + [3] => 13 + [4] => 1 + [8] => 1 + [9] => 19 +) +]]> + </screen> + </para> + </example> + Note que o índice 3 é definido duas vezes, e retêm seu último valor + 13. O índice 4 é definido depois do índice 8, e o índice gerado depois + dele foi 9, uma vez que o maior índice era 8. + </para> + <para> + Esse exemplo cria um array com o índices a partir do 1. + <example> + <title>Array com índices a partir do 1 com <function>array</function></title> + <programlisting role="php"> +<![CDATA[ +$trimestre = array(1 => 'Janeiro', 'Fevereiro', 'Marco'); +print_r($trimestre); +]]> + </programlisting> + <para> + vai mostrar : + <screen> +<![CDATA[ +Array +( + [1] => 'Janeiro' + [2] => 'Fevereiro' + [3] => 'Marco' +) +]]> + </screen> + </para> + </example> + </para> + <para> + Veja também: <function>list</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-change-key-case"> + <refnamediv> + <refname>array_change_key_case</refname> + <refpurpose>Retorna um array com todas as chaves string em maiúsculo ou + minúsculo</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_change_key_case</function></funcdef> + <paramdef>array <parameter>input</parameter></paramdef> + <paramdef>int <parameter><optional>case</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_change_key_case</function> muda as chaves chaves do + array <parameter>input</parameter> para maiúsculo ou minúsculo. A mudança + depende do último parâmetro opcional <parameter>case</parameter>. + Você pode passar duas constantes para ele, + <constant>CASE_UPPER</constant> e + <constant>CASE_LOWER</constant>. O padrão é + <constant>CASE_LOWER</constant>. + Essa função deixará os índices numéricos inalterados. + </para> + <example> + <title>Exemplo de <function>array_change_key_case</function></title> + <programlisting role="php"> +<![CDATA[ +$input_array = array("primeiRo" => 1, "segunDo" => 4); +print_r(array_change_key_case($input_array, CASE_UPPER); +]]> + </programlisting> + <para> + A saída deste programa será: + <screen> +<![CDATA[ +Array +( + [PRIMEIRO] => 1 + [SEGUNDO] => 2 +) +]]> + </screen> + </para> + </example> + </refsect1> + </refentry> + + <refentry id="function.array-chunk"> + <refnamediv> + <refname>array_chunk</refname> + <refpurpose>Divide um array em pedaços</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_chunk</function></funcdef> + <paramdef>array <parameter>input</parameter></paramdef> + <paramdef>int <parameter>size</parameter></paramdef> + <paramdef>bool <parameter><optional>preserve_keys</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_chunk</function> divide um array em diversos + arrays tendo como tamanho o valor de <parameter>size</parameter>. + Você provavelmente terá um array com menos valores no final. + Você gerará arrays como membros de um array multidimensional com índices + numéricos que começam do 0. + </para> + <para> + Passando o valor &true; para parâmetro <parameter>preserve_keys</parameter>, + você pode forçar a preservação das chaves do array original. Se for + passado o valor &false;, novos índices numéricos serão usados em cada + array resultante começando do valor 0. O padrão é &false;. + </para> + <example> + <title><function>array_chunk</function> example</title> + <programlisting role="php"> +<![CDATA[ +$input_array = array('a', 'b', 'c', 'd', 'e'); +print_r(array_chunk($input_array, 2)); +print_r(array_chunk($input_array, 2, TRUE)); +]]> + </programlisting> + <para> + A saída deste programa será: + <screen> +<![CDATA[ +Array +( + [0] => Array + ( + [0] => a + [1] => b + ) + + [1] => Array + ( + [0] => c + [1] => d + ) + + [2] => Array + ( + [0] => e + ) + +) +Array +( + [0] => Array + ( + [0] => a + [1] => b + ) + + [1] => Array + ( + [2] => c + [3] => d + ) + + [2] => Array + ( + [4] => e + ) + +) +]]> + </screen> + </para> + </example> + </refsect1> + </refentry> + + <refentry id="function.array-count-values"> + <refnamediv> + <refname>array_count_values</refname> + <refpurpose>Conta todos os valores de um array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_count_values</function></funcdef> + <paramdef>array <parameter>input</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_count_values</function> retorna um array utlizando os valores + do array <parameter>input</parameter> como chaves e seus respectivos + números de ocorrências como valores. + </para> + <para> + <example> + <title>Exemplo de <function>array_count_values</function></title> + <programlisting role="php"> +<![CDATA[ +$array = array (1, "ola", 1, "mundo", "ola"); +array_count_values ($array); // retorna o array (1=>2, "ola"=>2, "mundo"=>1) +]]> + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.array-diff"> + <refnamediv> + <refname>array_diff</refname> + <refpurpose>Calcula as diferenças entre arrays</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_diff</function></funcdef> + <paramdef>array <parameter>array1</parameter></paramdef> + <paramdef>array <parameter>array2</parameter></paramdef> + <paramdef>array + <parameter><optional> ...</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_diff</function> retorna um array contendo todos os + valores de <parameter>array1</parameter> que não estão presentes + em nenhum dos outros argumentos. + Note que as chaves são preservadas. + </para> + <para> + <example> + <title>Exemplo de <function>array_diff</function></title> + <programlisting role="php"> +<![CDATA[ +$array1 = array ("a" => "verde", "vermelho", "azul", "vermelho"); +$array2 = array ("b" => "verde", "amarelo", "vermelho"); +$result = array_diff ($array1, $array2); +]]> + </programlisting> + </example> + </para> + <para> + Isso faz com que <varname>$result</varname> tenha + <literal>array ("azul");</literal>. Ocorrências multiplas em + $array1 são tratados da mesma forma. + </para> + <note> + <simpara> + Dois elementos são considerados iguais se, e somente se, + <literal>(string) $elem1 === (string) $elem2</literal>. Em palavras: + quando a representação em string é a mesma. + <!-- TODO: example of it... --> + </simpara> + </note> + <warning> + <simpara> + Não estava funcinando no PHP 4.0.4! + <!-- TODO: when exactly was this broken?... --> + </simpara> + </warning> + <para> + Veja também <function>array_intersect</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-filter"> + <refnamediv> + <refname>array_filter</refname> + <refpurpose> + Filtra os elementos de um array de acordo com uma função + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_filter</function></funcdef> + <paramdef>array <parameter>input</parameter></paramdef> + <paramdef>mixed + <parameter><optional>callback</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_filter</function> retorna um array contendo + todos os elementos do array <parameter>input</parameter> filtrados + de acordo com a função aplicada. Se o array + <parameter>input</parameter> é associativo, então as chaves + são preservadas. + </para> + <para> + <example> + <title>Exemplo de <function>array_filter</function></title> + <programlisting role="php"> +<![CDATA[ +function impar($var) { + return ($var % 2 == 1); +} + +function par($var) { + return ($var % 2 == 0); +} + +$array1 = array ("a"=>1, "b"=>2, "c"=>3, "d"=>4, "e"=>5); +$array2 = array (6, 7, 8, 9, 10, 11, 12); + +$impar_arr = array_filter($array1, "impar"); +$par_arr = array_filter($array2, "par"); +]]> + </programlisting> + </example> + </para> + <para> + Isso faz com que <varname>$impar_arr</varname> tenha + <literal>array ("a"=>1, "c"=>3, "e"=>5);</literal>, + e <varname>$par_arr</varname> tenha + <literal>array (6, 8, 10, 12);</literal>, + </para> + <para> + Veja também <function>array_map</function>, + <function>array_reduce</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-flip"> + <refnamediv> + <refname>array_flip</refname> + <refpurpose>Inverte a relações entre chaves e valores</refpurpose> + </refnamediv> + <refsect1> + <title>Descrições</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_flip</function></funcdef> + <paramdef>array <parameter>trans</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_flip</function> retorna um <type>array</type> com + com a relação entre as chaves e seus valores invertida, ou seja, + as chaves de <parameter>trans</parameter> passam a ser valores e + os valores de <parameter>trans</parameter> passam a ser as chaves. + </para> + <para> + Note que os valores de <parameter>trans</parameter> devem ser chaves + válidas, ou seja, eles precisam ser <type>inteiros</type> ou <type>string</type>. + Um aviso será mostrado se um valor é de um tipo inválido para chaves, + e o par chave/valor em questão <emphasis>não será invertido</emphasis>. + </para> + <para> + se um valor tem várias ocorrências, a última chave será usada + como valor, e todos os outros serão perdidos. + </para> + <para> + <function>array_flip</function> retorna &false; + se falhar. + </para> + <para> + <example> + <title>Exemplo de <function>array_flip</function></title> + <programlisting role="php"> +<![CDATA[ +$trans = array_flip ($trans); +$original = strtr ($str, $trans); +]]> + </programlisting> + </example> + </para> + <para> + <example> + <title>Exemplo de <function>array_flip</function> : collision</title> + <programlisting role="php"> +<![CDATA[ +$trans = array ("a" => 1, "b" => 1, "c" => 2); +$trans = array_flip ($trans); +// agora $trans é : array(1 => "b", 2 => "c"); +]]> + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.array-fill"> + <refnamediv> + <refname>array_fill</refname> + <refpurpose>Preenche um array com valores</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_fill</function></funcdef> + <paramdef>int <parameter>start_index</parameter></paramdef> + <paramdef>int <parameter>num</parameter></paramdef> + <paramdef>mixed <parameter>value</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_fill</function> preenche um array com + o número de entradas igual a <parameter>num</parameter> com o valor do + parâmetro <parameter>value</parameter>, e chaves começando a partir de + <parameter>start_index</parameter>. + </para> + <para> + <example> + <title>Exemplo de <function>array_fill</function></title> + <programlisting role="php"> +<![CDATA[ +$a = array_fill(5, 6, 'banana'); + +/* +$a agora tem os seguintes valores: + +$a[5] = "banana"; +$a[6] = "banana"; +$a[7] = "banana"; +$a[8] = "banana"; +$a[9] = "banana"; +$a[10] = "banana"; +*/ +]]> + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.array-intersect"> + <refnamediv> + <refname>array_intersect</refname> + <refpurpose>Calcula a interseção entre arrays</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_intersect</function></funcdef> + <paramdef>array <parameter>array1</parameter></paramdef> + <paramdef>array <parameter>array2</parameter></paramdef> + <paramdef>array + <parameter><optional> ...</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_intersect</function> retorna um array + contendo todos os valores de <parameter>array1</parameter> + que estão presentes nos outros argumentos. + Note que as chaves são preservadas. + </para> + <para> + <example> + <title>Exemplo de <function>array_intersect</function></title> + <programlisting role="php"> +<![CDATA[ +$array1 = array ("a" => "verde", "vermelho", "azul"); +$array2 = array ("b" => "verde", "amarelo", "vermelho"); +$result = array_intersect ($array1, $array2); +]]> + </programlisting> + </example> + </para> + <para> + Isso faz com que <varname>$result</varname> tenha <literal>array ("a" + => "verde", "vermelho");</literal> + </para> + <note> + <simpara> + Dois elementos são considerados iguais se, e somente se, + <literal>(string) $elem1 === (string) $elem2</literal>. Em palavras: + quando a representação em string é a mesma. + <!-- TODO: example of it... --> + </simpara> + </note> + <warning> + <simpara> + Essa função não funcionava no PHP 4.0.4! + <!-- TODO: when exactly was this broken?... --> + </simpara> + </warning> + <para> + Veja também <function>array_diff</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-key-exists"> + <refnamediv> + <refname>array_key_exists</refname> + <refpurpose>Checa se uma chave existe num array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>array_key_exists</function></funcdef> + <paramdef>mixed <parameter>key</parameter></paramdef> + <paramdef>array <parameter>search</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_key_exists</function> retorna &true; se a chave + <parameter>key</parameter> existe no array. + <parameter>key</parameter> pode ser qualquer valor possível para uma + chave de um array. + </para> + <para> + <example> + <title>Exemplo de <function>array_key_exists</function></title> + <programlisting role="php"> +<![CDATA[ +$busca_array = array("primeiro" => 1, "segundo" => 4); +if (array_key_exists("primeiro", $busca_array)) { + echo "O elemento 'primeiro' está no array!"; +} +]]> + </programlisting> + </example> + </para> + <note> + <simpara> + O nome dessa função é <function>key_exists</function> + no PHP versão 4.0.6. + </simpara> + </note> + <para> + Veja também <function>isset</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-keys"> + <refnamediv> + <refname>array_keys</refname> + <refpurpose>Retorna todas as chaves de um array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_keys</function></funcdef> + <paramdef>array <parameter>input</parameter></paramdef> + <paramdef>mixed + <parameter> + <optional>search_value</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_keys</function> retorna as chaves, numéricas e + string, do array <parameter>input</parameter>. + </para> + <para> + Se o parâmetro opcional <parameter>search_value</parameter> for + especificado, então apenas as chaves para esse valor sãò retornadas. + Do contrário, todas as chaves de <parameter>input</parameter> serãao retornadas. + </para> + <para> + <example> + <title>Exemplo de <function>array_keys</function></title> + <programlisting role="php"> +<![CDATA[ +$array = array (0 => 100, "cor" => "vermelho"); +array_keys ($array); // retorna o array (0, "color") + +$array = array ("azul", "vermelho", "verde", "azul", "azul"); +array_keys ($array, "azul"); // retorna o array (0, 3, 4) + +$array = array ("cor" => array("azul", "vermelho", "verde"), "tamanho" => array("pequeno", "medio", "grande")); +array_keys ($array); // retorna o array ("cor", "tamanho") +]]> + </programlisting> + </example> + </para> + <note> + <para> + Essa função adicionada no PHP 4,abaixo está uma implementação + para aqueles que ainda usam PHP 3. + <example> + <title> + Implementação de <function>array_keys</function> para usuários do PHP 3 + </title> + <programlisting role="php"> +<![CDATA[ +function array_keys ($arr, $term="") { + $t = array(); + while (list($k,$v) = each($arr)) { + if ($term && $v != $term) { + continue; + $t[] = $k; + } + return $t; + } +} +]]> + </programlisting> + </example> + </para> + </note> + <para> + Veja também <function>array_values</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-map"> + <refnamediv> + <refname>array_map</refname> + <refpurpose> + Aplica uma função em todos os elementos dos arrays dados + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_map</function></funcdef> + <paramdef>mixed <parameter>callback</parameter></paramdef> + <paramdef>array <parameter>arr1</parameter></paramdef> + <paramdef>array + <parameter><optional>arr2...</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_map</function> retorna um array contendo todos + os elementos de <parameter>arr1</parameter> depois de aplicada + a função callback em cada um. O número de parâmetros que a função + callback aceita deve coincidir com o número de arrays passados para a + <function>array_map</function> + </para> + <para> + <example> + <title>Exemplo de <function>array_map</function></title> + <programlisting role="php"> +<![CDATA[ +function cubo($n) { + return $n*$n*$n; +} + +$a = array(1, 2, 3, 4, 5); +$b = array_map("cubo", $a); +]]> + </programlisting> + </example> + </para> + <para> + Isso resultará em <varname>$b</varname> contendo + <literal>array (1, 8, 27, 64, 125);</literal> + </para> + <para> + <example> + <title><function>array_map</function> - usando mais arrays</title> + <programlisting role="php"> +<![CDATA[ +function mostrar_Espanhol($n, $m) { + return "O número $n é chamado de $m na Espanha"; +} + +function map_Espanhol($n, $m) { + return array ($n => $m); +} + +$a = array(1, 2, 3, 4, 5); +$b = array("uno", "dos", "tres", "cuatro", "cinco"); + +$c = array_map("mostrar_Espanhol", $a, $b); + +print_r($c); + +// mostrará: +// Array +// ( +// [0] => O número 1 é chamado de uno na Espanha +// [1] => O número 2 é chamado de dos na Espanha +// [2] => O número 3 é chamado de tres na Espanha +// [3] => O número 4 é chamado de cuatro na Espanha +// [4] => O número 5 é chamado de cinco na Espanha +// ) + +$d = array_map("map_Espanhol", $a , $b); + +print_r($d); + +// will output: +// Array +// ( +// [0] => Array +// ( +// [1] => uno +// ) +// +// [1] => Array +// ( +// [2] => dos +// ) +// +// [2] => Array +// ( +// [3] => tres +// ) +// +// [3] => Array +// ( +// [4] => cuatro +// ) +// +// [4] => Array +// ( +// [5] => cinco +// ) +// +// ) +]]> + </programlisting> + </example> + </para> + <para> + Normalmente quando se usa dois ou mais arrays, eles devem ter o mesmo tamanho + porque a função callback é aplicada paralelamente aos elementos + correpondentes. + Se os arrays tem tamanhos diferentes, o menos array será extendido com + elementos em branco. + </para> + <para> + Um modo interessante de usar essa função é na construção de um array de + arrays, o que pode ser facilmente feito usando &null; + como o nome da função callback. + </para> + <para> + <example> + <title>Criando um array de arrays</title> + <programlisting role="php"> +<![CDATA[ +$a = array(1, 2, 3, 4, 5); +$b = array("um", "dois", "tres", "quatro", "cinco"); +$c = array("uno", "dos", "tres", "cuatro", "cinco"); + +$d = array_map(null, $a, $b, $c); +print_r($d); + +// mostrará: +// Array +// ( +// [0] => Array +// ( +// [0] => 1 +// [1] => um +// [2] => uno +// ) +// +// [1] => Array +// ( +// [0] => 2 +// [1] => dois +// [2] => dos +// ) +// +// [2] => Array +// ( +// [0] => 3 +// [1] => tres +// [2] => tres +// ) +// +// [3] => Array +// ( +// [0] => 4 +// [1] => quatro +// [2] => cuatro +// ) +// +// [4] => Array +// ( +// [0] => 5 +// [1] => cinco +// [2] => cinco +// ) +// +// ) +]]> + </programlisting> + </example> + </para> + <para> + Veja também <function>array_filter</function>, + <function>array_reduce</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-merge"> + <refnamediv> + <refname>array_merge</refname> + <refpurpose>Funde dois ou mais arrays</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_merge</function></funcdef> + <paramdef>array <parameter>array1</parameter></paramdef> + <paramdef>array <parameter>array2</parameter></paramdef> + <paramdef>array + <parameter><optional>...</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_merge</function> funde os elementos dois ou mais + arrays de forma que os elementos de um são colocados no final + do array anterior. Retorna esse array resultante. + </para> + <para> + Se os arrays dados têm as mesmas chaves string, então o último + valor para uma chave irá sobrescrever todos os outros. Se, no entanto, + os arrays tem as mesmas chaves numéricas, o último valor para uma chave + não sobrescreverá o valor original, e sim adicionado ao array + resultante. + </para> + <para> + <example> + <title>Exemplo de <function>array_merge</function></title> + <programlisting role="php"> +<![CDATA[ +$array1 = array ("cor" => "vermelho", 2, 4); +$array2 = array ("a", "b", "cor" => "verde", "forma" => "trapezoide", 4); +$result = array_merge ($array1, $array2); +]]> + </programlisting> + </example> + </para> + <para> + O array resultante será <literal>array("cor" => "verde", 2, 4, + "a", "b", "forma" => "trapezoide", 4)</literal>. + </para> + <para> + Veja também <function>array_merge_recursive</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-merge-recursive"> + <refnamediv> + <refname>array_merge_recursive</refname> + <refpurpose>Funde dois ou mais arrays recursivamente</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_merge_recursive</function></funcdef> + <paramdef>array <parameter>array1</parameter></paramdef> + <paramdef>array <parameter>array2</parameter></paramdef> + <paramdef>array + <parameter><optional>...</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_merge_recursive</function> funde os elementos de + dois ou mais de forma que os elementos de um são colocados + no final do array anterior. Retorna esse array resultante. + </para> + <para> + Se os arrays dados tem as mesmas chaves string, então os valores para + uma chave são fundidos em um array, e isso é feito recursivamente, + sendo que se um dos valores for um array também, este função irá fundi-lo + com os valores correspondentes no array resultante também. Se, no + entanto, os arrays tem as mesmas chaves numéricas, o último valor para + uma chave não sobrescreverá o valor original, e sim adicionado ao array + resultante. + </para> + <para> + <example> + <title>Exemplo de <function>array_merge_recursive</function></title> + <programlisting role="php"> +<![CDATA[ +$ar1 = array ("cor" => array ("favorita" => "vermelho"), 5); +$ar2 = array (10, "cor" => array ("favorita" => "verde", "azul")); +$result = array_merge_recursive ($ar1, $ar2); +]]> + </programlisting> + </example> + </para> + <para> + O array resultante será <literal>array ("cor" => array + ("favorita" => array ("vermelho", "verde"), "azul"), 5, 10)</literal>. + </para> + <para> + Veja também <function>array_merge</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-multisort"> + <refnamediv> + <refname>array_multisort</refname> + <refpurpose>Classifica múltiplos arrays ou multi-dimensionais</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>array_multisort</function></funcdef> + <paramdef>array <parameter>ar1</parameter></paramdef> + <paramdef>mixed + <parameter><optional>arg</optional></parameter> + </paramdef> + <paramdef>mixed + <parameter><optional>...</optional></parameter> + </paramdef> + <paramdef>array + <parameter><optional>...</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_multisort</function> pode ser usada para classificar + vários arrays de uma vez ou apenas um array multi-dimensional de acordo com + uma das dimensões. A associação entre chaves e valores é mantida. + </para> + <para> + Os arrays dados são tratados como colunas de uma tabela a ser + classificada pelas linhas - isso lembra a funcionalidade da cláusula + ORDER BY da SQL. O primeiro array é o principal na classificação. As + linhas (valores) no primeiro array serve de base para a classificação do próximo, + e assim por diante. + </para> + <para> + A estrutura de argumentos dessa função não é muito normal, mas + bastante flexível. O primeiro argmento de todos deve ser um array. + Subsequentemente, cada argumento pode ser um array ou um dos sinais de + classificação da lista a seguir. + </para> + <para> + Sinais de ordem de classificação: + <itemizedlist> + <listitem> + <simpara>SORT_ASC - classifica na ordem crescente</simpara> + </listitem> + <listitem> + <simpara>SORT_DESC - classifica na ordem descrescente</simpara> + </listitem> + </itemizedlist> + </para> + <para> + Sinais de tipos de classificação: + <itemizedlist> + <listitem> + <simpara>SORT_REGULAR - compara os elementos normalmente</simpara> + </listitem> + <listitem> + <simpara>SORT_NUMERIC - compara os elementos como itens numéricos</simpara> + </listitem> + <listitem> + <simpara>SORT_STRING - compara os elementos como strings</simpara> + </listitem> + </itemizedlist> + </para> + <para> + Não podem existir dois sinais de classificação do mesmo tipo + especificados depois de um mesmo array. Apenas um. Os sinais de classificação + especificados depois de um array se aplicam apenas para esse array - a + eles são atribuídos por padrão os valores SORT_ASC e SORT_REGULAR depois + de cada novo argumento do tipo array. + </para> + <para> + Retorna &true; se obtiver sucesso, &false; + se falhar. + </para> + <para> + <example> + <title>Classificando múltiplos arrays</title> + <programlisting role="php"> +<![CDATA[ +$ar1 = array ("10", 100, 100, "a"); +$ar2 = array (1, 3, "2", 1); +array_multisort ($ar1, $ar2); +]]> + </programlisting> + </example> + </para> + <para> + Nesse exemplo, depois da classificação, o primeiro array terá 1-, "a", + 100, 100. O segundo conterá 1, 1, "2", 3. Os elementos do segundo array + que correpondem aos do primeiro (100 e 100) também foram classificados. + </para> + <para> + <example> + <title>Classificando um array multi-dimensional</title> + <programlisting role="php"> +<![CDATA[ +$ar = array (array ("10", 100, 100, "a"), array (1, 3, "2", 1)); +array_multisort ($ar[0], SORT_ASC, SORT_STRING, + $ar[1], SORT_NUMERIC, SORT_DESC); +]]> + </programlisting> + </example> + </para> + <para> + Nesse exemplo, depois da classificação, o primeiro array terá 10, 100, + 100, "a" (foi classificado como strings em ordem crescente), e o segundo + conterá 1, 3, "2", 1 (classificado como números, em ordem descrescente). + </para> + </refsect1> + </refentry> + + <refentry id="function.array-pad"> + <refnamediv> + <refname>array_pad</refname> + <refpurpose> + Expande um array para um certo comprimento com um certo valor + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_pad</function></funcdef> + <paramdef>array <parameter>input</parameter></paramdef> + <paramdef>int <parameter>pad_size</parameter></paramdef> + <paramdef>mixed <parameter>pad_value</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_pad</function> retorna uma cópia de + <parameter>input</parameter> expandido para o comprimento especificado + por <parameter>pad_size</parameter> com o valor + <parameter>pad_value</parameter>. Se + <parameter>pad_size</parameter> for positivo então o array é + expandido pela direita, se for negativo, pela esquerda. Se o + valor absoluto de <parameter>pad_size</parameter> for menor ou igual + ao comprimento de <parameter>input</parameter>, então ele permanece + inalterado. + </para> + <para> + <example> + <title>Exemplo de <function>array_pad</function></title> + <programlisting role="php"> +<![CDATA[ +$input = array (12, 10, 9); + +$result = array_pad ($input, 5, 0); +// result is array (12, 10, 9, 0, 0) + +$result = array_pad ($input, -7, -1); +// result is array (-1, -1, -1, -1, 12, 10, 9) + +$result = array_pad ($input, 2, "noop"); +// not padded +]]> + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.array-pop"> + <refnamediv> + <refname>array_pop</refname> + <refpurpose>Retira um elemento do final do array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>array_pop</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_pop</function> retira e retorna o último + valor de <parameter>array</parameter>, diminuindo-o + <parameter>array</parameter> em um elemento. + Se <parameter>array</parameter> estiver vazio (ou se não for um array), + o valor &null; é retornado. + </para> + <para> + <example> + <title>Exemplo de <function>array_pop</function></title> + <programlisting role="php"> +<![CDATA[ +$cesta = array ("laranja", "melancia", "morango"); +$fruta = array_pop ($cesta); +]]> + </programlisting> + </example> + </para> + <para> + Depois disso, <varname>$cesta</varname> terá dois elementos: + "laranja" e "melancia", and <varname>$fruta</varname> terá + "morango". + </para> + <para> + Veja também <function>array_push</function>, + <function>array_shift</function>, e + <function>array_unshift</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-push"> + <refnamediv> + <refname>array_push</refname> + <refpurpose> + Adiciona um ou mais elementos no final de um array + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>array_push</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>mixed <parameter>var</parameter></paramdef> + <paramdef>mixed + <parameter><optional>...</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_push</function> trata + <parameter>array</parameter> como uma pilha, e adiciona + as variáveis passadas como argumentos no final de <parameter>array</parameter>. + O comprimento de <parameter>array</parameter> aumenta de acordo com o + número de variáveis adicionadas.. Tem o mesmo efeito de: + <programlisting role="php"> +<![CDATA[ +$array[] = $var; +]]> + </programlisting> + repetido para cada argumento <parameter>var</parameter>. + </para> + <para> + Retorna o novo número de elementos do array. + </para> + <para> + <example> + <title>Exemplo de <function>array_push</function></title> + <programlisting role="php"> +<![CDATA[ +$pilha = array (1, 2); +array_push ($pilha, "+", 3); +]]> + </programlisting> + </example> + </para> + <para> + Esse exemplo resultará em <varname>$pilha</varname> contendo 4 + elementos: 1, 2, "+", e 3. + </para> + <para> + Veja também: <function>array_pop</function>, + <function>array_shift</function>, e + <function>array_unshift</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-rand"> + <refnamediv> + <refname>array_rand</refname> + <refpurpose> + Pega um ou mais elementos aleatórios do array + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>array_rand</function></funcdef> + <paramdef>array <parameter>input</parameter></paramdef> + <paramdef>int + <parameter><optional>num_req</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_rand</function> é bastante útil quando se quer + pegar aleatoriamente um ou mais elementos de um array. Ela recebe + o array <parameter>input</parameter> e outro argumento opcional + <parameter>num_req</parameter> o qual especifica quantos elementos + se quer pegar - se não for especificado, o padrão é 1. + </para> + <para> + Se estiver pegando apenas um elemento , <function>array_rand</function> + retorna a chave para este elemento aleatório. De outra forma, ele retorna + um array com as chaves desses elementos aleatórios. Assim é possível + pegar chaves e valores aleatórios. + </para> + <para> + Não esqueça de chamar a função <function>srand</function> para disparar + o gerador de números aleatórios. + </para> + <para> + <example> + <title>Exemplo de <function>array_rand</function></title> + <programlisting role="php"> +<![CDATA[ +srand ((float) microtime() * 10000000); +$input = array ("Neo", "Morpheus", "Trinity", "Cypher", "Tank"); +$rand_keys = array_rand ($input, 2); +print $input[$rand_keys[0]]."\n"; +print $input[$rand_keys[1]]."\n"; +]]> + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.array-reverse"> + <refnamediv> + <refname>array_reverse</refname> + <refpurpose> + Retorna um array com os elementos na ordem inversa + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_reverse</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>bool + <parameter><optional>preserve_keys</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_reverse</function> recebe o argumento + <parameter>array</parameter> e retorna um novo array com ordem + dos elementos invertida, preservando as chaves se o argumento + <parameter>preserve_keys</parameter> for &true;. + </para> + <para> + <example> + <title>Exemplo de <function>array_reverse</function></title> + <programlisting role="php"> +<![CDATA[ +$input = array ("php", 4.0, array ("verde", "vermelho")); +$result = array_reverse ($input); +$result_keyed = array_reverse ($input, TRUE); +]]> + </programlisting> + </example> + </para> + <para> + Isso fará com que <varname>$result</varname> e + <varname>$result_keyed</varname> sejam <literal>array(array + ("green", "red"), 4.0, "php")</literal>. Mas + <varname>$result_keyed[0]</varname> ainda será + <literal>"php"</literal>. + </para> + <note> + <para> + O segundo argumento foi adicionado no PHP 4.0.3. + </para> + </note> + </refsect1> + </refentry> + + <refentry id="function.array-reduce"> + <refnamediv> + <refname>array_reduce</refname> + <refpurpose> + Reduz um array para um único elemento através de um processo iterativo + utilizando uma função de callback. + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>array_reduce</function></funcdef> + <paramdef>array <parameter>input</parameter></paramdef> + <paramdef>mixed <parameter>callback</parameter></paramdef> + <paramdef>int + <parameter><optional>initial</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_reduce</function> aplica iterativamente a função + <parameter>callback</parameter> nos elementos de <parameter>input</parameter>, + de forma a reduzi-lo a um único valor. Se o argumento opcional <parameter>initial</parameter> + for passado, ele será utlizado no início do processo, ou como + um resultado final se o array estiver vazio. + </para> + <para> + <example> + <title>Exemplo de <function>array_reduce</function></title> + <programlisting role="php"> +<![CDATA[ +function soma($v, $w) { + $v += $w; + return $v; +} + +function multiplicacao($v, $w) { + $v *= $w; + return $v; +} + +$a = array(1, 2, 3, 4, 5); +$x = array(); +$b = array_reduce($a, "soma"); +$c = array_reduce($a, "multiplicacao", 10); +$d = array_reduce($x, "soma", 1); +]]> + </programlisting> + </example> + </para> + <para> + Isso resultará em <varname>$b</varname> contendo + <literal>15</literal>, <varname>$c</varname> contendo + <literal>1200</literal> (= 1*2*3*4*5*10), e + <varname>$d</varname> contendo <literal>1</literal>. + </para> + <para> + Veja também <function>array_filter</function>, + <function>array_map</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-shift"> + <refnamediv> + <refname>array_shift</refname> + <refpurpose> + Retira o primeiro elemento de um array + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>array_shift</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_shift</function> retira o primeiro elemento de + <parameter>array</parameter> e o retorna, diminuindo + <parameter>array</parameter> em um elemento e movendo todos os outros + para trás. Se <parameter>array</parameter> estiver vazio (ou se não for + um array), o valor &null; é retornado. + </para> + <para> + <example> + <title>Exemplo de <function>array_shift</function></title> + <programlisting role="php"> +<![CDATA[ +$args = array ("-v", "-f"); +$opt = array_shift ($args); +]]> + </programlisting> + </example> + </para> + <para> + Isso resultaria em <varname>$args</varname> contendo apenas o elemento + "-f", e <varname>$opt</varname> sendo "-v". + </para> + <para> + Veja também <function>array_unshift</function>, + <function>array_push</function>, e + <function>array_pop</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-slice"> + <refnamediv> + <refname>array_slice</refname> + <refpurpose>Extrai uma "fatia" de um array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_slice</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>int <parameter>offset</parameter></paramdef> + <paramdef>int + <parameter> + <optional>length</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_slice</function> retorna a sequência de elementos + de <parameter>array</parameter> especificada pelos parâmetros + <parameter>offset</parameter> e <parameter>length</parameter>. + </para> + <para> + Se <parameter>offset</parameter> for positivo, a sequência + começará no início de <parameter>array</parameter>. Se + <parameter>offset</parameter> for negativo, a sequência + começará dessa distância do final de <parameter>array</parameter>. + </para> + <para> + Se <parameter>length</parameter> for especificado e positivo, então + a sequência terá essa quantidade de elementos. Se + <parameter>length</parameter> for especificado e negativo então + a sequência para dessa quantidade elementos a partir do final do + array. Se for omitido, então a sequência terá todos os elementos + a partir de <parameter>offset</parameter> até o final de + <parameter>array</parameter>. + </para> + <para> + <example> + <title>Exemplos de <function>array_slice</function></title> + <programlisting role="php"> +<![CDATA[ +$input = array ("a", "b", "c", "d", "e"); + +$output = array_slice ($input, 2); // retorna "c", "d", e "e" +$output = array_slice ($input, 2, -1); // retorna "c", "d" +$output = array_slice ($input, -2, 1); // retorna "d" +$output = array_slice ($input, 0, 3); // retorna "a", "b", e "c" +]]> + </programlisting> + </example> + </para> + <para> + Veja também <function>array_splice</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-splice"> + <refnamediv> + <refname>array_splice</refname> + <refpurpose> + Remove uma região do array e substitui por outros elementos + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_splice</function></funcdef> + <paramdef>array <parameter>input</parameter></paramdef> + <paramdef>int <parameter>offset</parameter></paramdef> + <paramdef>int + <parameter><optional>length</optional></parameter> + </paramdef> + <paramdef>array + <parameter> + <optional>replacement</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_splice</function> remove os elementos especificados + por <parameter>offset</parameter> e + <parameter>length</parameter> do array + <parameter>input</parameter>, e os substitui com os elementos + do array <parameter>replacement</parameter>, se for especificado. + </para> + <para> + Se <parameter>offset</parameter> for positivo então o começo da + região a ser removida será nessa posição a partir do início do array + <parameter>input</parameter>. Se <parameter>offset</parameter> for negativo + então o ínicio será dessa distância do final de <parameter>input</parameter>. + </para> + <para> + Se <parameter>length</parameter> for omitido, todos os elementos + a partir de <parameter>offset</parameter> até o final do array são + removidos. Se <parameter>length</parameter> for especificado e positivo, então + essa quantidade de elementos será removida. Se <parameter>length</parameter> + for especificado e negativo então o final da região a ser removida será + nessa quantidade de elementos a partir do final do array. + Dica: para remover todos elementos a partir de <parameter>offset</parameter> + até o final do array quando <parameter>replacement</parameter> também é especificado, use + <literal>count($input)</literal> para o argumento <parameter>length</parameter>. + </para> + <para> + Se o array <parameter>replacement</parameter> for especificado, então + os elementos removidos serão substituidos pelo elementos desse array. + Se <parameter>offset</parameter> e + <parameter>length</parameter> dados de forma que nada será removido, + então os elementos de <parameter>replacement</parameter> serão inseridos + no lugar especificado por <parameter>offset</parameter>. + Dica: se a substituição for de apenas um elemento + então não será necessário colocar <literal>array()</literal> + para ele, a não ser que elementos seja um array. + </para> + <para> + As seguintes equivalências abaixo são válidas: + <programlisting role="php"> +<![CDATA[ +array_push ($input, $x, $y) array_splice ($input, count ($input), 0, + array ($x, $y)) +array_pop ($input) array_splice ($input, -1) +array_shift ($input) array_splice ($input, 0, 1) +array_unshift ($input, $x, $y) array_splice ($input, 0, 0, array ($x, $y)) +$a[$x] = $y array_splice ($input, $x, 1, $y) +]]> + </programlisting> + </para> + <para> + Retorna um array contendo os elementos removidos. + </para> + <para> + <example> + <title>Exemplos de <function>array_splice</function></title> + <programlisting role="php"> +<![CDATA[ +$input = array ("vermelho", "verde", "azul", "amarelo"); +array_splice ($input, 2); +// $input será agora array ("vermelho", "verde") + +$input = array ("vermelho", "verde", "azul", "amarelo"); +array_splice ($input, 1, -1); +// $input será agora array ("vermelho", "amarelo") + +$input = array ("vermelho", "verde", "azul", "amarelo"); +array_splice ($input, 1, count($input), "laranja"); +// $input será agora array ("vermelho", "laranja") + +$input = array ("vermelho", "verde", "azul", "amarelo"); +array_splice ($input, -1, 1, array("preto", "marrom")); +// $input será agora array ("vermelho", "verde", "azul", "preto", "marron") +]]> + </programlisting> + </example> + </para> + <para> + Veja também <function>array_slice</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-sum"> + <refnamediv> + <refname>array_sum</refname> + <refpurpose> + Calcula a soma dos elementos de um array + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>array_sum</function></funcdef> + <paramdef>array <parameter>arr</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_sum</function> retorna a soma dos valores + de um array como inteiro ou real. + </para> + <para> + <example> + <title>Exemplos de <function>array_sum</function></title> + <programlisting role="php"> +<![CDATA[ +$a = array(2, 4, 6, 8); +echo "sum(a) = ".array_sum($a)."\n"; +// imprime: sum(a) = 20 + +$b = array("a"=>1.2,"b"=>2.3,"c"=>3.4); +echo "sum(b) = ".array_sum($b)."\n"; +// imprime: sum(b) = 6.9 +]]> + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.array-unique"> + <refnamediv> + <refname>array_unique</refname> + <refpurpose>Remove o valores duplicados de um array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_unique</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_unique</function> recebe o argumento + <parameter>array</parameter> e retorna um novo array sem valores + duplicados. + </para> + <para> + Note que as chaves são preservadas. <function>array_unique</function> irá + manter a primeira chave encontrada para cada valor, e ignorar + as chaves posteriores. + </para> + <note> + <simpara> + Dois elementos são considerados iguais se, e somente se, + <literal>(string) $elem1 === (string) $elem2</literal>. Em palavras: + quando a represetação em string é a mesma. + <!-- TODO: example of it... --> + </simpara> + <simpara> + O primeiro será usado. + </simpara> + </note> + <warning> + <simpara> + Essa função não funcionava no PHP 4.0.4! + <!-- TODO: when exactly was this broken?... --> + </simpara> + </warning> + <para> + <example> + <title>Exemplo de <function>array_unique</function></title> + <programlisting role="php"> +<![CDATA[ +$input = array ("a" => "verde", "vermelho", "b" => "verde", "azul", "vermelho"); +$result = array_unique ($input); +print_r($result); +// a saída será : +//Array +//( +// [a] => verde +// [0] => vermelho +// [1] => azul +//) +]]> + </programlisting> + </example> + </para> + <para> + <example> + <title><function>array_unique</function> e tipos</title> + <programlisting role="php"> +<![CDATA[ +$input = array (4,"4","3",4,3,"3"); +$result = array_unique ($input); +var_dump($result); + +/* saída: +array(2) { + [0]=> + int(4) + [1]=> + string(1) "3" +} +*/ +]]> + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.array-unshift"> + <refnamediv> + <refname>array_unshift</refname> + <refpurpose> + Adiciona um ou mais elementos no início de um array + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>array_unshift</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>mixed <parameter>var</parameter></paramdef> + <paramdef>mixed + <parameter> + <optional>...</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_unshift</function> adiciona os elementos passados como + argumentos no início de <parameter>array</parameter>. Note que a lista + de elementos é adicionada como um todo, de forma que eles ficam na + mesma ordem. + </para> + <para> + Retorna o novo número de elementos de <parameter>array</parameter>. + </para> + <para> + <example> + <title>Exemplo de <function>array_unshift</function></title> + <programlisting role="php"> +<![CDATA[ +$queue = array ("p1", "p3"); +array_unshift ($queue, "p4", "p5", "p6"); +]]> + </programlisting> + </example> + </para> + <para> + Isso resultaria em <varname>$queue</varname> contendo 5 + elementos: "p4", "p5", "p6", "p1", e "p3". + </para> + <para> + Veja também <function>array_shift</function>, + <function>array_push</function>, e + <function>array_pop</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-values"> + <refnamediv> + <refname>array_values</refname> + <refpurpose>Retorna todos os valores de um array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_values</function></funcdef> + <paramdef>array <parameter>input</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>array_values</function> retorna todos os valores do array + <parameter>input</parameter>. + </para> + <para> + <example> + <title>Exemplo de <function>array_values</function></title> + <programlisting role="php"> +<![CDATA[ +$array = array ("tamanho" => "G", "cor" => "dourado"); +array_values ($array); // retorna o array ("G", "dourado") +]]> + </programlisting> + </example> + </para> + <note> + <para> + Essa função foi adicionada no PHP 4, abaixo segue uma implementação para + aqueles que ainda usam PHP 3. + <example> + <title> + Implementação de <function>array_values</function> para PHP 3 + users + </title> + <programlisting role="php"> +<![CDATA[ +function array_values ($arr) { + $t = array(); + while (list($k, $v) = each ($arr)) { + $t[] = $v; + } + return $t; +} +]]> + </programlisting> + </example> + </para> + </note> + <para> + Veja também <function>array_keys</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-walk"> + <refnamediv> + <refname>array_walk</refname> + <refpurpose> + Aplica uma determinada funcão em cada elemento de um array + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>array_walk</function></funcdef> + <paramdef>array <parameter>arr</parameter></paramdef> + <paramdef>string <parameter>func</parameter></paramdef> + <paramdef>mixed + <parameter><optional>userdata</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <simpara> + Aplica uma função definida pelo usuário nomeada pelo argumento + <parameter>func</parameter> em cada elemento de <parameter>arr</parameter>. + <parameter>func</parameter> terá como primeiro o argumento o valor do + elemento e sua chave como segndo parâmetro. Se + <parameter>userdata</parameter> for especificado, ele será usado como + terceiro argumento da função do usuário. <parameter>func</parameter> + deve ser uma função definida pelo usuário, e não uma função nativa do PHP. + Dessa forma, você não pode usar <function>array_walk</function> juntamente com + <function>str2lower</function>, primeiro deve ser definida uma função do + usuário, e depois passá-la como argumento. + </simpara> + <simpara> + Se <parameter>func</parameter> necessita de mais de dois ou três + argumentos, dependendo de <parameter>userdata</parameter>, um + será mostrado a cada vez que + <function>array_walk</function> executar + <parameter>func</parameter>. Esses avisos podem ser suprimidos + adicionando o operador '@' a chamada da função <function>array_walk</function>, + ou usando <function>error_reporting</function>. + </simpara> + <note> + <para> + Se <parameter>func</parameter> precisar alterar realmente os valores + do array, especifique que o primeiro parâmetro de + <parameter>func</parameter> deve ser passado por referência. Então + qualquer mudança feita nesses elementos serão feitas no próprio arra + também. + itself. + </para> + </note> + <note> + <para> + A passagem das chaves e do terceiro argumento para <parameter>func</parameter> foi + adicionada no PHP 4.0. + </para> + <para> + No PHP 4 <function>reset</function> precisa ser chamada necessariamente + uma vez que <function>array_walk</function> não reinicializa o array por + padrão. + </para> + </note> + <para> + <example> + <title>Exemplo de <function>array_walk</function></title> + <programlisting role="php"> +<![CDATA[ +$frutas = array ("d"=>"limao", "a"=>"laranja", "b"=>"banana", "c"=>"melancia"); + +function test_alter (&$item1, $key, $prefix) { + $item1 = "$prefix: $item1"; +} + +function test_print ($item2, $key) { + echo "$key. $item2<br>\n"; +} + +array_walk ($frutas, 'test_print'); +reset ($frutas); +array_walk ($frutas, 'test_alter', 'fruta'); +reset ($frutas); +array_walk ($frutas, 'test_print'); +]]> + </programlisting> + </example> + </para> + <simpara> + Veja também <function>each</function> e <function>list</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.arsort"> + <refnamediv> + <refname>arsort</refname> + <refpurpose> + Classifica um array em ordem descrescente mantendo a associação entre os + índices e os elementos + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>arsort</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>int + <parameter><optional>sort_flags</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Essa função classifica um array de forma que a correlação entre índices e + elementos é mantida. Usada principalmente para classificar arrays + associativos onde a ordem dos elementos é um fator importante. + </para> + <example> + <title>Exemplo de <function>arsort</function></title> + <programlisting role="php"> +<![CDATA[ +$frutas = array ("d"=>"limao", "a"=>"laranja", "b"=>"banana", "c"=>"melancia"); +arsort ($frutas); +reset ($frutas); +while (list ($chave, $valor) = each ($frutas)) { + echo "$chave = $valor\n"; +} +]]> + </programlisting> + <para> + A saída desse exemplo seria: + <screen> +<![CDATA[ +c = melancia +d = limao +a = laranja +b = banana +]]> + </screen> + </para> + </example> + <para> + As frutas foram classificadas na ordem alfabética inversa, e os índices + associados a cada elemento foram mantidos. + </para> + <para> + Você pode modificar o comportamento da classificação usando o parâmetro + opcional <parameter>sort_flags</parameter>, para detalhes veja + <function>sort</function>. + </para> + <para> + Veja também: <function>asort</function>, <function>rsort</function>, + <function>ksort</function>, e <function>sort</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.asort"> + <refnamediv> + <refname>asort</refname> + <refpurpose> + Classifica um array mantendo a associação entre os índices e + os elementos + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>asort</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>int + <parameter><optional>sort_flags</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Essa função classifica um array de forma que a correlação entre índices e + elementos é mantida. É usada principalmente para classificar arrays + associativos onde a ordem dos elementos é um fator importante. + </para> + <example> + <title>Exemplo de <function>asort</function></title> + <programlisting role="php"> +<![CDATA[ +$frutas = array ("d"=>"limao", "a"=>"laranja", "b"=>"banana", "c"=>"melancia"); +asort ($frutas); +reset ($frutas); +while (list ($chave, $valor) = each ($frutas)) { + echo "$chave = $valor\n"; +} +]]> + </programlisting> + <para> + A saída desse programa seria: + <screen> +<![CDATA[ +b = banana +a = laranja +d = limao +c = melancia +]]> + </screen> + </para> + </example> + <para> + As frutas foram classificadas na ordem alfabética, e os índices + associados a cada elemento foram mantidos. + </para> + <para> + Você pode modificar o comportamento da classificação usando o parâmetro + opcional <parameter>sort_flags</parameter>, para mais detalhes + veja <function>sort</function>. + </para> + <para> + veja também <function>arsort</function>, <function>rsort</function>, + <function>ksort</function>, e <function>sort</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.compact"> + <refnamediv> + <refname>compact</refname> + <refpurpose> + Cria um array contendo variáveis e seus valores + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>compact</function></funcdef> + <paramdef>mixed <parameter>varname</parameter></paramdef> + <paramdef>mixed + <parameter><optional>...</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>compact</function> recebe um número variável de + parâmetros. Cada Parâmetro pode ser tanto uma string contendo o nome da + variável, como também pode ser um array de nomes de variáveis. Sendo um + array, ele pode conter outros arrays de nomes de variáveis; + <function>compact</function> os trata recursivamente. + </para> + <para> + Para cada um dos parâmetros passados, <function>compact</function> procura + uma variável com o nome especificado na tabela de símbolos e a adiciona + no array de saída de forma que o nome da variável será a chave e o seu + conteúdo será o valor para esta chave. + Em resumo, ela faz o oposto de <function>extract</function>. + Retorna um array de saída com todas as variáveis adicionadas ele. + </para> + <para> + Qualquer string com nome de uma variável que não exista será simplesmente + ignorada. + </para> + <para> + <example> + <title>Exemplo de <function>compact</function></title> + <programlisting role="php"> +<![CDATA[ +$cidade = "Sao Paulo"; +$estado = "SP"; +$evento = "SIGGRAPH"; + +$localidade = array ("cidade", "estado"); + +$result = compact ("evento", "nada_aqui", $localidade); +]]> + </programlisting> + <para> + Depois disso, <varname>$result</varname> será <literal>array + ("evento" => "SIGGRAPH", "cidade" => "Sao Paulo", + "estado" => "SP")</literal>. + </para> + </example> + </para> + <para> + Veja também <function>extract</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.count"> + <refnamediv> + <refname>count</refname> + <refpurpose>Conta o número de elementos de uma variável</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>count</function></funcdef> + <paramdef>mixed <parameter>var</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Retorna o número de elementos de <parameter>var</parameter>, + que normalmente é um <type>array</type> (uma vez que qualquer outra coisa + só terá apenas um elemento). + </para> + <para> + Se <parameter>var</parameter> não for um array, <literal>1</literal> será + retornado (excessão: <literal>count(&null;)</literal> retorna + <literal>0</literal>). + </para> + <warning> + <para> + <function>count</function> pode retornar 0 para uma variável + que não existe, mas também pode retornar 0 para uma variável que tenha + sido inicializada como um array vazio. Use + <function>isset</function> para checar se uma variável existe. + </para> + </warning> + <para> + Por favor, veja a sessão <link linkend="language.types.array">Arrays</link> + do manual para uma explicação mais detalhada sobre como os arrays são + implementados e utilizados no PHP. + </para> + <para> + <example> + <title>Exemplo de <function>count</function></title> + <programlisting role="php"> + <!-- TODO: examples about count(null), count(false), count(object).. --> +<![CDATA[ +$a[0] = 1; +$a[1] = 3; +$a[2] = 5; +$result = count ($a); +// $result == 3 + +$b[0] = 7; +$b[5] = 9; +$b[10] = 11; +$result = count ($b); +// $result == 3; +]]> + </programlisting> + </example> + </para> + <note> + <para> + A função <function>sizeof</function> é um apelido para + <function>count</function>. + </para> + </note> + <para> + Veja também: <function>sizeof</function>, + <function>isset</function>, e + <function>is_array</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.current"> + <refnamediv> + <refname>current</refname> + <refpurpose>Retorna o elemento corrente em um array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>current</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Todo array tem um ponteiro interno para o elemento "atual", + o qual é inicializado para apontar para o primeiro elemento inserido em + um array. + </para> + <para> + A função <function>current</function> simplismente retorna + o elemento do array para o qual esse ponteiro interno está apontando. + Não move o ponteiro de forma alguma. Se o ponteiro interno + estiver apontando para além do final da lista de elementos, + <function>current</function> retorna &false;. + <warning> + <para> + Se o array contêm elementos vazios (0 ou "", a + string vazia) então esta função retorna &false; + para esses elementos. Isso faz com que seja impossível + determinar se você está realmente no final da lista de elementos de + array usando <function>current</function>. Para percorrer + devidamente um array que pode conter elementos vazios, use a função + <function>each</function>. + </para> + </warning> + </para> + <para> + Veja também: <function>end</function>, <function>next</function>, + <function>prev</function>, e <function>reset</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.each"> + <refnamediv> + <refname>each</refname> + <refpurpose> + Retorna o par chave/valor corrente de um array e avança o seu cursor + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>each</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Retorna o par chave/valor corrente de + <parameter>array</parameter> e avança o seu cursor. Esse + par é retornado num array de quatro elementos, com as chaves + <emphasis>0</emphasis>, <emphasis>1</emphasis>, + <emphasis>key</emphasis>, e + <emphasis>value</emphasis>. Os elementos <emphasis>0</emphasis> e + <emphasis>key</emphasis> contêm o nome da chave do elemento do array, e + <emphasis>1</emphasis> e <emphasis>value</emphasis> contêm o valor. + </para> + <para> + Se o cursor interno do array estiver apontando para além do final do + array, <function>each</function> retorna &false;. + </para> + <para> + <example> + <title>Exemplos de <function>each</function></title> + <programlisting role="php"> +<![CDATA[ +$foo = array ("bob", "fred", "jussi", "jouni", "egon", "marliese"); +$bar = each ($foo); +]]> + </programlisting> + <para> + <varname>$bar</varname> agora contem os seguintes pares de chaves e + valores: + <itemizedlist spacing="compact"> + <listitem><simpara>0 => 0</simpara></listitem> + <listitem><simpara>1 => 'bob'</simpara></listitem> + <listitem><simpara>key => 0</simpara></listitem> + <listitem><simpara>value => 'bob'</simpara></listitem> + </itemizedlist> + <programlisting role="php"> +<![CDATA[ +$foo = array ("Robert" => "Bob", "Seppo" => "Sepi"); +$bar = each ($foo); +]]> + </programlisting> + </para> + <para> + <varname>$bar</varname> agora contem os seguintes pares de chaves e + valores: + <itemizedlist spacing="compact"> + <listitem><simpara>0 => 'Robert'</simpara></listitem> + <listitem><simpara>1 => 'Bob'</simpara></listitem> + <listitem><simpara>key => 'Robert'</simpara></listitem> + <listitem><simpara>value => 'Bob'</simpara></listitem> + </itemizedlist> + </para> + </example> + </para> + <para> + <function>each</function> é tipicamente usada em conjunto com + <function>list</function> para percorrer o array; por exemplo, + <varname>$HTTP_POST_VARS</varname>: + <example> + <title> + Percorrendo <varname>$HTTP_POST_VARS</varname> usando + <function>each</function> + </title> + <programlisting role="php"> +<![CDATA[ +echo "Valores submetidos pelo método POST:<br>"; +reset ($HTTP_POST_VARS); +while (list ($chave, $valor) = each ($HTTP_POST_VARS)) { + echo "$chave => $valor<br>"; +} +]]> + </programlisting> + </example> + </para> + <para> + Depois da execução de <function>each</function>, o cursor interno do + array vai apontar para o prócimo elemento do array, ou no último + elemento se ele chegar ao final do array. Você deve usar + <function>reset</function> se quiser percorrer o array novamente. + </para> + <para> + Veja também <function>key</function>, <function>list</function>, + <function>current</function>, <function>reset</function>, + <function>next</function>, e <function>prev</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.end"> + <refnamediv> + <refname>end</refname> + <refpurpose> + Faz com que o ponteiro interno de um array aponte para o seu último + elemento + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>end</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>end</function> avança o ponteiro interno de <parameter>array</parameter> + até o seu último elemento, e retorna esse elemento. + </para> + <para> + Veja também: <function>current</function>, + <function>each</function>, <function>end</function>, + <function>next</function>, e <function>reset</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.extract"> + <refnamediv> + <refname>extract</refname> + <refpurpose> + Importa variáveis para a tabela de símbolos a partir de um array + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>extract</function></funcdef> + <paramdef>array <parameter>var_array</parameter></paramdef> + <paramdef>int + <parameter><optional>extract_type</optional></parameter> + </paramdef> + <paramdef>string + <parameter><optional>prefix</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Essa é usada para importar variáveis a partir de um array para a tabela + de símbolos corrente. Recebe o array associativo + <parameter>var_array</parameter> e trata as suas chaves como + os nomes das variáveis e os valores como valores das variáveis. + Para cada par chave/valor ele criará uma variável na tabela de símbolos + corrente, seguindo os parâmetros + <parameter>extract_type</parameter> e + <parameter>prefix</parameter>. + </para> + <note> + <para> + Desde a versão 4.0.5 essa função retorna o número de variáveis + extraídas. + </para> + </note> + <para> + <function>extract</function> checa se cada chave do array constituinum + nome de variável válido e por colisões com as variáveis já existentes na + tabela de símbolos. O modo com que chaves inválidas ou númericas e colisões + são tratadas é determinado pelo argumento + <parameter>extract_type</parameter>. Esse argumento pode receber os + seguintes valores: + <variablelist> + <varlistentry> + <term>EXTR_OVERWRITE</term> + <listitem> + <simpara> + Se houver uma colisão, sobrescreve a variável existente. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>EXTR_SKIP</term> + <listitem> + <simpara> + Se houver uma colisão, não sobrescreve a variável existente. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>EXTR_PREFIX_SAME</term> + <listitem> + <simpara>Se houver uma colisão, adiciona um prefixo ao nome da + variável definido pelo argumento + <parameter>prefix</parameter>. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>EXTR_PREFIX_ALL</term> + <listitem> + <simpara> + Adiciona um prefixo ao nome de todas as variáveis definido por + <parameter>prefix</parameter>. Desde o PHP 4.0.5 estão incluídos + nomes numéricos. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>EXTR_PREFIX_INVALID</term> + <listitem> + <simpara> + Adiciona um prefixo definido por <parameter>prefix</parameter> apenas + para variáveis como nomes inválidos ou numéricos. Essa opção foi adicionada no + PHP 4.0.5. + </simpara> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + Se <parameter>extract_type</parameter> não for especificado, é assumido + o valor EXTR_OVERWRITE por padrão. + </para> + <para> + Note que <parameter>prefix</parameter> só é necessário se + <parameter>extract_type</parameter> for EXTR_PREFIX_SAME, + EXTR_PREFIX_ALL, ou EXTR_PREFIX_INVALID. se o nome com o prefixo + não for um nome de variável válido, ela não será importada para a tabela + de símbolos. + </para> + <para> + <function>extract</function> retorna o número de variáveis importadas + com sucesso para a tbela de símbolos. + </para> + <para> + Um uso comum de extract e na importação de + variáveis contidas num array associativo retornado pela função + <function>wddx_deserialize</function>. + </para> + <para> + <example> + <title>Exemplo de <function>extract</function></title> + <programlisting role="php"> +<![CDATA[ +<?php + +/* Suponha que $var_array é um array retornado pela função + wddx_deserialize */ + +$tamanho = "grande"; +$var_array = array ("cor" => "azul", + "tamanho" => "medio", + "forma" => "esfera"); +extract ($var_array, EXTR_PREFIX_SAME, "wddx"); + +print "$cor, $tamanho, $forma, $wddx_tamanho\n"; + +?> +]]> + </programlisting> + </example> + </para> + <para> + O exemplo acima produziria: + <programlisting> +<![CDATA[ +azul, grande, esfera, medio +]]> + </programlisting> + </para> + <para> + O <varname>$tamanho</varname> não foi sobrescrito, porque + nós especificamos EXTR_PREFIX_SAME, o que resultou na criação da variável + <varname>$wddx_tamanho</varname>. Se EXTR_SKIP fosse + utilizado, então $wddx_tamanho não seria criada. + EXTR_OVERWRITE teria feito com que <varname>$size</varname> tivesse + o valor "medio", e EXTR_PREFIX_ALL resultaria em novas variáveis + com os nomes <varname>$wddx_cor</varname>, + <varname>$wddx_tamanho</varname>, e + <varname>$wddx_forma</varname>. + </para> + <para> + Você deve usar um arra associativo, um array indexado numericamente não + produzirá resultados. + </para> + <para> + Veja também: <function>compact</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.in-array"> + <refnamediv> + <refname>in_array</refname> + <refpurpose>Retorna &true; se um valor existe no array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>in_array</function></funcdef> + <paramdef>mixed <parameter>needle</parameter></paramdef> + <paramdef>array <parameter>haystack</parameter></paramdef> + <paramdef>bool + <parameter><optional>strict</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Procura em <parameter>haystack</parameter> pelo valor + <parameter>needle</parameter> e retorna &true; + se este valor for encontrado no array, e &false; em caso contrário. + </para> + <para> + Se o terceiro parâmetro <parameter>strict</parameter> for + &true; então <function>in_array</function> + também irá checar os <link linkend="language.types">tipos</link> de + <parameter>needle</parameter> em <parameter>haystack</parameter>. + </para> + <para> + <example> + <title>Exemplo de <function>in_array</function></title> + <programlisting role="php"> +<![CDATA[ +$os = array ("Mac", "NT", "Irix", "Linux"); +if (in_array ("Irix", $os)) { + print "Tem Irix"; +} +]]> + </programlisting> + </example> + </para> + <para> + <example> + <title><function>in_array</function> com checagem de tipos</title> + <programlisting role="php"> +<![CDATA[ +<?php +$a = array('1.10', 12.4, 1.13); + +if (in_array('12.4', $a, TRUE)) + echo "'12.4' encontrado com checagem de tipo\n"; +if (in_array(1.13, $a, TRUE)) + echo "1.13 encontrado com checagem de tipo\n"; +?> + +// Isso irá produzir: + +1.13 encontrado com checagem de tipo +]]> + </programlisting> + </example> + </para> + <para> + Veja também <function>array_search</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-search"> + <refnamediv> + <refname>array_search</refname> + <refpurpose> + Procura por um valor em um array e retorna sua chave correspondente + caso seja encontrado + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>array_search</function></funcdef> + <paramdef>mixed <parameter>needle</parameter></paramdef> + <paramdef>array <parameter>haystack</parameter></paramdef> + <paramdef>bool <parameter><optional>strict</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Procura em <parameter>haystack</parameter> pelo valor + <parameter>needle</parameter> e retorna sua chave se for encontrado no + array, &false; em caso contrário. + </para> + <para> + se o terceiro parâmetro opcional <parameter>strict</parameter> for + fornecido como &true; então <function>array_search</function> + também fará uma checagem de tipos de <parameter>needle</parameter> + em <parameter>haystack</parameter>. + </para> + <para> + Veja também <function>in_array</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.key"> + <refnamediv> + <refname>key</refname> + <refpurpose>Retorna uma chave de um array associativo</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>key</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>key</function> retorna a chave da posição corrente de um + array. + </para> + <para> + Veja também <function>current</function> e <function>next</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.krsort"> + <refnamediv> + <refname>krsort</refname> + <refpurpose>Classifica um array pelas chaves em ordem descrescente</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>krsort</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>int + <parameter><optional>sort_flags</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Classifica um array pelas chaves em ordem descrescente, mantendo a + correlação entre entre as chaves e os valores. Essa função é bastante + útil em arrays associativos. + <example> + <title>Exemplo de <function>krsort</function></title> + <programlisting role="php"> +<![CDATA[ +$frutas = array ("d"=>"limao", "a"=>"laranja", "b"=>"banana", "c"=>"melancia"); +krsort ($frutas); +reset ($frutas); +while (list ($chave, $valor) = each ($frutas)) { + echo "$chave = $valor\n"; +} +]]> + </programlisting> + </example> + </para> + <para> + A saída deste programa seria: + </para> + <para> + <informalexample> + <programlisting> +<![CDATA[ +d = limao +c = melancia +b = banana +a = laranja +]]> + </programlisting> + </informalexample> + </para> + <para> + Você pode alterar o comportamento da classificação utilizando o + parâmetro opcional <parameter>sort_flags</parameter>, para mais detalhes + veja <function>sort</function>. + </para> + <simpara> + Veja também <function>asort</function>, <function>arsort</function>, + <function>ksort</function> <function>sort</function>, + <function>natsort</function> e <function>rsort</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.ksort"> + <refnamediv> + <refname>ksort</refname> + <refpurpose>Classifica um array pelas chaves</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ksort</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>int + <parameter><optional>sort_flags</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Classifica um array pelas chaves, mantendo a correlação entre as chaves e + os valores. Essa função é bastante útil principalmente em arrays + associativos. + <example> + <title>Exemplo de <function>ksort</function></title> + <programlisting role="php"> +<![CDATA[ +$frutas = array ("d"=>"limao", "a"=>"laranja", "b"=>"banana", "c"=>"melancia"); +ksort ($frutas); +reset ($frutas); +while (list ($chave, $valor) = each ($frutas)) { + echo "$chave = $valor\n"; +} +]]> + </programlisting> + </example> + </para> + <para> + O programa acima mostraria: + </para> + <para> + <informalexample> + <programlisting> +<![CDATA[ +a = laranja +b = banana +c = melancia +d = limao +]]> + </programlisting> + </informalexample> + </para> + <para> + Você pode modificar o comportamento da classificação através do parâmetro + opcional <parameter>sort_flags</parameter>, para mais detalhes + veja <function>sort</function>. + </para> + <simpara> + Veja também <function>asort</function>, <function>arsort</function>, + <function>sort</function>, <function>natsort</function>, e + <function>rsort</function>. + </simpara> + <note> + <para> + O segundo parâmetro foi adicionado a partir do PHP 4. + </para> + </note> + </refsect1> + </refentry> + + <refentry id="function.list"> + <refnamediv> + <refname>list</refname> + <refpurpose> + Cria variáveis como se fossem arrays + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>list</function></funcdef> + <varargs/> + </funcprototype> + </funcsynopsis> + <para> + Assim como <function>array</function>, não é exatamente uma função, + e sim uma estrutura da própria linguagem. <function>list</function> é usada + para criar uma lista de variáveis em apenas um operação. + <example> + <title>Exemplo de <function>list</function></title> + <programlisting role="php"> +<![CDATA[ +<table> + <tr> + <th>Nome do empregado</th> + <th>Salário</th> + </tr> + +<?php + +$resultado = mysql_query ("SELECT id, nome, salario FROM empregados",$conn); +while (list ($id, $nome, $salario) = mysql_fetch_row ($resultado)) { + print (" <tr>\n". + " <td><a href=\"info.php3?id=$id\">$nome</a></td>\n". + " <td>$salario</td>\n". + " </tr>\n"); +} + +?> + +</table> +]]> + </programlisting> + </example> + </para> + <para> + Veja também <function>each</function> e <function>array</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.natsort"> + <refnamediv> + <refname>natsort</refname> + <refpurpose> + Classifica um array utlizando o algoritmo da "ordem natural" + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>natsort</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Essa função é um implementação do algoritmo que ordena + strings alfanuméricas da forma como um ser humano faria. Isso é + chamado de "ordenação natural". Um exemplo da diferença entre + esse algoritmo e o algoritmo com o qual o computador classifica strings + (usado em <function>sort</function>) pode ser visto abaixo: + </para> + <para> + <example> + <title>Exemplo de <function>natsort</function></title> + <programlisting role="php"> +<![CDATA[ +$array1 = $array2 = array ("img12.png", "img10.png", "img2.png", "img1.png"); + +sort($array1); +echo "Classificação normal\n"; +print_r($array1); + +natsort($array2); +echo "\nClassificação da \"ordem natural\"\n"; +print_r($array2); +]]> + </programlisting> + </example> + </para> + <para> + O código acima geraria a seguinte saída: + </para> + <para> + <informalexample> + <programlisting> +<![CDATA[ +Classificação normal +Array +( + [0] => img1.png + [1] => img10.png + [2] => img12.png + [3] => img2.png +) + +Classificação da "ordem natural" +Array +( + [3] => img1.png + [2] => img2.png + [1] => img10.png + [0] => img12.png +) +]]> + </programlisting> + </informalexample> + Para mais informações veja: Martin Pool's <ulink + url="&url.strnatcmp;">Natural Order String Comparison</ulink> + page. + </para> + <para> + Veja também <function>natcasesort</function>, + <function>strnatcmp</function> e + <function>strnatcasecmp</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.natcasesort"> + <refnamediv> + <refname>natcasesort</refname> + <refpurpose> + Classifica um array utilizando o algoritmo da "ordem natural" sem + diferenciar maiúsculas e minúsculas + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>natcasesort</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Essa função implementa o algoritmo de classificação que ordena + strings alfanuméricas da forma que os humanas fariam. Essa forma de + classificação é denominada "ordenação natural". + </para> + <para> + <function>natcasesort</function> é uma versão de + <function>natsort</function> que não diferencia letras maiúsculas e + minúsculas. Veja <function>natsort</function> + para saber a diferença entrre esse algoritmo e os algoritmos + utlizados normalmente para ordenação de strings. + </para> + <para> + Para mais informações veja: Martin Pool's <ulink + url="&url.strnatcmp;">Natural Order String Comparison</ulink> + page. + </para> + <para> + Veja também <function>sort</function>, + <function>natsort</function>, + <function>strnatcmp</function> e + <function>strnatcasecmp</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.next"> + <refnamediv> + <refname>next</refname> + <refpurpose> + Avança o ponteiro interno de um array + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>next</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Retorna o elemento do array que está na próxima posição que é apontada + pelo ponteiro interno do array, &false; caso não existam mais elementos. + </para> + <para> + <function>next</function> funciona de forma semelhante a + <function>current</function>, com uma diferença. Ele avança o + ponteiro interno do array em uma posição antes de retornar o + elemento. Isso significa que ela retorna o próximo elemento do array + avançando o ponteiro interno em uma posição. Se o ponteiro + interno apontar para além do final da lista de elementos + , <function>next</function> retorna &false;. + <warning> + <para> + Se o array contiver elementos vazios, ou elementos tiverem chaves + com 0 como valor então essa função retorna &false; + para esses elementos. Para percorrer um array que + pode conter elementos vazios ou elementos que tenham chaves com 0 como valor + veja a função <function>each</function>. + </para> + </warning> + </para> + <para> + Veja também: + <function>current</function>, <function>end</function>, + <function>prev</function>, e <function>reset</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.pos"> + <refnamediv> + <refname>pos</refname> + <refpurpose>Retorna o elemento atual do array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>pos</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <simpara> + Essa função é igual a <function>current</function>. + </simpara> + <para> + See also: + <function>end</function>, <function>next</function>, + <function>prev</function> e <function>reset</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.prev"> + <refnamediv> + <refname>prev</refname> + <refpurpose>Retrocede o ponteiro interno de um array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>prev</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Retorna o elemento do array que está na posição anterior a posição apontada + pelo ponteiro interno, ou &false; se houver mais elementos. + <warning> + <para> + Se o array contiver elementos vazios então essa função retornará + &false; para esses elementos. + Para percorrer corretamente arrays que podem conter elementos vazios + veja a função <function>each</function>. + </para> + </warning> + </para> + <para> + <function>prev</function> funciona da mesma forma que + <function>next</function>, com a única sendo a de que a primeira + retrocede o ponteiro interno em uma posição ao invés de avançá-lo. + </para> + <para> + Veja também: <function>current</function>, <function>end</function>, + <function>next</function>, e <function>reset</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.range"> + <refnamediv> + <refname>range</refname> + <refpurpose> + Cria um array contendo uma faixa de elementos + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>range</function></funcdef> + <paramdef>mixed <parameter>low</parameter></paramdef> + <paramdef>mixed <parameter>high</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>range</function> retorna um array com elementos de + <parameter>low</parameter> até <parameter>high</parameter>, + com intervalo fechado. Se low > high, será de high até low. + <example> + <title>Exemplos de <function>range</function></title> + <programlisting role="php"> +<![CDATA[ +foreach(range(0, 9) as $numero) { + echo $numero; +} +foreach(range('a', 'z') as $letra) { + echo $letra; +} +foreach(range('z', 'a') as $letra) { + echo $letra; +} +]]> + </programlisting> + </example> + </para> + <note> + <para> + Até a versão 4.1.0, a função <function>range</function> só gerava + arrays de inteiros em ordem crescente. O suporte para + sequências de caracteres e arrays descrescentes foi adicionado no PHP 4.1.0. + </para> + </note> + <para> + Veja <function>shuffle</function> para outro exemplo de utilização dessa + função. + </para> + </refsect1> + </refentry> + + <refentry id="function.reset"> + <refnamediv> + <refname>reset</refname> + <refpurpose> + Faz o ponteiro interno de um array apontar para o seu primeiro elemento + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>reset</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>reset</function> retrocede o ponteiro interno de <parameter>array</parameter> + para o primeiro elemento. + </para> + <para> + <function>reset</function> retorna o valor do primeiro elemento do array. + </para> + <para> + Veja também: <function>current</function>, + <function>each</function>, <function>next</function>, + e <function>prev</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.rsort"> + <refnamediv> + <refname>rsort</refname> + <refpurpose>Classifica um array em ordem descrescente</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>rsort</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>int + <parameter><optional>sort_flags</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + essa função classifica um array para a ordem descrescente (do maior para o menor). + <example> + <title>Exemplo de <function>rsort</function></title> + <programlisting role="php"> +<![CDATA[ +$frutas = array ("limao", "laranja", "banana", "melancia"); +rsort ($frutas); +reset ($frutas); +while (list ($chave, $valor) = each ($frutas)) { + echo "$chave = $valor\n"; +} +]]> + </programlisting> + </example> + </para> + <para> + Esse exemplo mostraria: + </para> + <para> + <informalexample> + <programlisting> +<![CDATA[ +0 = melancia +1 = limao +2 = laranja +3 = banana +]]> + </programlisting> + </informalexample> + </para> + <para> + As frutas foram classificadas em ordem alfabética decrescente. + </para> + <para> + Você pode alterar o comportamento da classificação utilizando o parâmetro + opcional <parameter>sort_flags</parameter>, para mais detalhes + veja <function>sort</function>. + </para> + <para> + Veja também: <function>arsort</function>, + <function>asort</function>, <function>ksort</function>, + <function>sort</function>, e <function>usort</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.shuffle"> + <refnamediv> + <refname>shuffle</refname> + <refpurpose>Mistura os elementos de um array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>shuffle</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Essa função mistura de forma aleatória os elementos de um + array. Você deve usar essa função em conjunto com <function>srand</function>. + <example> + <title>Exemplo de <function>shuffle</function></title> + <programlisting role="php"> +<![CDATA[ +$numeros = range (1,20); +srand ((float)microtime()*1000000); +shuffle ($numeros); +while (list (, $numero) = each ($numeros)) { + echo "$numero "; +} +]]> + </programlisting> + </example> + </para> + <para> + Veja também <function>arsort</function>, <function>asort</function>, + <function>ksort</function>, <function>rsort</function>, + <function>sort</function> e <function>usort</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.sizeof"> + <refnamediv> + <refname>sizeof</refname> + <refpurpose>Retorna o número de elementos de uma variável</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>sizeof</function></funcdef> + <paramdef>mixed <parameter>var</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>sizeof</function> é igual a + <function>count</function>. + </para> + <para> + Veja também <function>count</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.sort"> + <refnamediv> + <refname>sort</refname> + <refpurpose>Classifica um array</refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>sort</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>int + <parameter><optional>sort_flags</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Essa função classifica um array. Os elementos serão ordenador + do menor para o maior ao final da execução dessa função. + <example> + <title>Exemplo de <function>sort</function></title> + <programlisting role="php"> +<![CDATA[ +<?php + +$frutas = array ("limao", "laranja", "banana", "melancia"); +sort ($frutas); +reset ($frutas); +while (list ($chave, $valor) = each ($frutas)) { + echo "frutas[".$chave."] = ".$valor."\n"; +} + +?> +]]> + </programlisting> + </example> + </para> + <para> + A saída desse programa seria: + </para> + <para> + <informalexample> + <programlisting> +<![CDATA[ +fruits[0] = banana +fruits[1] = laranja +fruits[2] = limao +fruits[3] = melancia +]]> + </programlisting> + </informalexample> + </para> + <para> + As frutas foram classificadas em ordem alfabética. + </para> + <para> + O segundo argumento opcional <parameter>sort_flags</parameter> + pode ser usada para modificar o comportamento da classificação podendo + receber os seguintes valores: + </para> + <para> + Sinais de tipo de classificação: + <itemizedlist> + <listitem> + <simpara>SORT_REGULAR - compara os itens normalmente</simpara> + </listitem> + <listitem> + <simpara>SORT_NUMERIC - compara os itens como valores numéricos</simpara> + </listitem> + <listitem> + <simpara>SORT_STRING - compara os itens como strings</simpara> + </listitem> + </itemizedlist> + </para> + <para> + Veja também: <function>arsort</function>, + <function>asort</function>, <function>ksort</function>, + <function>natsort</function>, <function>natcasesort</function>, + <function>rsort</function>, <function>usort</function>, + <function>array_multisort</function>, e + <function>uksort</function>. + </para> + <note> + <para> + O segundo parâmetro foi adicionado a partir do PHP 4. + </para> + </note> + </refsect1> + </refentry> + + <refentry id="function.uasort"> + <refnamediv> + <refname>uasort</refname> + <refpurpose> + Classifica um array utlizando uma função de comparação definida pelo usuário e mantendo + as associações dos índices + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>uasort</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>function <parameter>cmp_function</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Essa função classifica um array de forma que a correlação entre os + índices e os elementos com que estão associados. Essa função usada + principalmente para classificar arrays associativos onde a ordem dos + elementos é um fator importante. A função de comparacão é definida pelo + usuário. + </para> + <note> + <para> + Por favor, veja <function>usort</function> e + <function>uksort</function> para exemplos de funções de comparação definidas pelo + usuário. + </para> + </note> + <para> + Veja também: <function>usort</function>, <function>uksort</function>, + <function>sort</function>, <function>asort</function>, + <function>arsort</function>, <function>ksort</function> + e <function>rsort</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.uksort"> + <refnamediv> + <refname>uksort</refname> + <refpurpose> + Classifica um array pelas chaves utilizando uma função de comparação + definida pelo usuário. + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>uksort</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>function <parameter>cmp_function</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Essa função ia classificar as chaves de um array usando uma função de + comparação definida pelo usuário. Se o array + precisa ser classificado utilizando um critério não trivial, você deve + usar essa função. + </para> + <para> + <example> + <title>Exemplo de <function>uksort</function></title> + <programlisting role="php"> +<![CDATA[ +function cmp ($a, $b) { + if ($a == $b) return 0; + return ($a > $b) ? -1 : 1; +} + +$a = array (4 => "quatro", 3 => "tres", 20 => "vinte", 10 => "dez"); + +uksort ($a, "cmp"); + +while (list ($chave, $valor) = each ($a)) { + echo "$chave: $valor\n"; +} +]]> + </programlisting> + </example> + </para> + <para> + Esse exemplo mostraria: + </para> + <para> + <informalexample> + <programlisting> +<![CDATA[ +20: vinte +10: dez +4: quatro +3: tres +]]> + </programlisting> + </informalexample> + </para> + <para> + Veja também: <function>usort</function>, <function>uasort</function>, + <function>sort</function>, <function>asort</function>, + <function>arsort</function>, <function>ksort</function>, + <function>natsort</function> e <function>rsort</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.usort"> + <refnamediv> + <refname>usort</refname> + <refpurpose> + Classifica um array pelos valores utilizando uma função de comparação + definida pelo usuário + </refpurpose> + </refnamediv> + <refsect1> + <title>Descrição</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>usort</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>string <parameter>cmp_function</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Essa função irá classificar um array pelos valores usando uma função de + classificação definida pelo usuário. Se o array precisar ser classificado + utilizando um critério não trivial, você deve usar essa função. + </para> + <para> + A função de comparação deve retornar um inteiro menor, igual ou maior que + zero se o primeiro argumento for considerado respectivamente menor, + igual, ou maior que o segundo. Se dois elementos forem iguais, a ordem + deles será indefinida. + </para> + <para> + Também é possível utilizar uma função membro de um objeto como a função + de comparação. Veja o exemplo 3 abaixo: + </para> + <para> + <example> + <title>Exemplo de <function>usort</function></title> + <programlisting role="php"> +<![CDATA[ +function cmp ($a, $b) { + if ($a == $b) return 0; + return ($a > $b) ? -1 : 1; +} + +$a = array (3, 2, 5, 6, 1); + +usort ($a, "cmp"); + +while (list ($chave, $valor) = each ($a)) { + echo "$chave: $valor\n"; +} +]]> + </programlisting> + </example> + </para> + <para> + Esse exemplo mostraria: + </para> + <para> + <informalexample> + <programlisting> +<![CDATA[ +0: 6 +1: 5 +2: 3 +3: 2 +4: 1 +]]> + </programlisting> + </informalexample> + </para> + <note> + <para> + Obviamente que nesse caso trivial a função<function>rsort</function> + seria mais apropriada. + </para> + </note> + <para> + <example> + <title> + Exemplo de <function>usort</function> usando um array multi-dimensional + </title> + <programlisting role="php"> +<![CDATA[ +function cmp ($a, $b) { + return strcmp($a["fruta"], $b["fruta"]); +} + +$frutas[0]["fruta"] = "limoes"; +$frutas[1]["fruta"] = "abacaxis"; +$frutas[2]["fruta"] = "goiabas"; + +usort($frutas, "cmp"); + +while (list ($chave, $valor) = each ($frutas)) { + echo "\$frutas[$chave]: " . $valor["fruta"] . "\n"; +} +]]> + </programlisting> + </example> + </para> + <para> + Na classificação de um array multi-dimensional, $a e $b contêm + referências para o primeiro índice do array. + </para> + <para> + Esse exemplo mostraria: + </para> + <para> + <informalexample> + <programlisting> +<![CDATA[ +$fruits[0]: abacaxis +$fruits[1]: goiabas +$fruits[2]: limoes +]]> + </programlisting> + </informalexample> + </para> + + <para> + <example> + <title> + Exemplo de <function>usort</function> usando uma função membro de um + objeto + </title> + <programlisting role="php"> +class TestObj { + var $name; + + function TestObj($name) + { + $this->name = $name; + } + + /* Essa é a função estática de comparação */ + function cmp_obj($a, $b) + { + $al = strtolower($a->name); + $bl = strtolower($b->name); + if ($al == $bl) return 0; + return ($al > $bl) ? +1 : -1; + } +} + +$a[] = new TestObj("c"); +$a[] = new TestObj("b"); +$a[] = new TestObj("d"); + +uasort($a, array ("TestObj", "cmp_obj")); + +foreach ($a as $item) { + print $item->name."\n"; +} + </programlisting> + </example> + </para> + <para> + Esse exemplo mostraria: + </para> + <para> + <informalexample> + <programlisting> +b +c +d + </programlisting> + </informalexample> + </para> + <para> + <warning> + <para> + + </para> + </warning> + </para> + <para> + Veja também: <function>uasort</function>, + <function>uksort</function>, <function>sort</function>, + <function>asort</function>, + <function>arsort</function>,<function>ksort</function>, + <function>natsort</function>, e <function>rsort</function>. + </para> + </refsect1> + </refentry> + + </reference> + +<!-- 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 +sgml-parent-document:nil +sgml-default-dtd-file:"../../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 +-->