pos()

Em PHP, a função pos() é uma função de array nativa que retorna o valor do elemento na posição atual do ponteiro interno do array. Todo array PHP possui um ponteiro interno que rastreia qual elemento é o "atual"; pos() lê o valor sob esse ponteiro sem movê-lo.

pos() é um alias de current(), e os dois se comportam de forma idêntica. Como aliases podem ser desencorajados ou removidos em versões futuras do PHP, current() é o nome que você deve preferir em código novo — pos() está documentado aqui principalmente para que você o reconheça em projetos legados.

Esta página aborda a sintaxe da função, o que ela retorna (incluindo o caso especial de array vazio), como ela se relaciona com as demais funções de ponteiro e quando utilizar o ponteiro realmente é a escolha certa.

Sintaxe da Função pos()

pos() recebe um único argumento — o array a inspecionar — e retorna o valor do elemento para o qual o ponteiro interno aponta atualmente.

pos(array $array): mixed

• $array — o array a ser lido. É passado por referência, portanto a variável do array deve ser atribuível (não é possível passar um literal).
• Valor de retorno — o valor do elemento atual, ou false se o array estiver vazio ou o ponteiro tiver avançado além do último elemento.

Como um elemento pode legitimamente conter o valor false, nunca use o valor de retorno sozinho para testar "houve falha?". Use key() (que retorna null após o fim) quando precisar detectar o fim de um array de forma confiável.

Exemplos de Uso da Função pos()

Vejamos alguns exemplos práticos de como a função pos() pode ser usada para recuperar o valor na posição atual do ponteiro interno.

Exemplos de Uso da Função pos()

<?php

$colors = ['red', 'green', 'blue'];

// Set the current position to the first element
reset($colors);

// Retrieve the value of the element at the current position
echo pos($colors) . '-'; // Output: red

// Move the current position to the next element
next($colors);

// Retrieve the value of the element at the current position
echo pos($colors) . '-'; // Output: green

// Move the current position to the next element
next($colors);

// Retrieve the value of the element at the current position
echo pos($colors); // Output: blue

Neste exemplo, temos um array chamado $colors com três elementos. Definimos o ponteiro interno para o primeiro elemento usando reset() e, em seguida, recuperamos o valor nessa posição com pos(). Depois avançamos o ponteiro com next() e lemos o valor novamente, repetindo o processo até o último elemento. O ponto principal: pos() por si só nunca move o ponteiro — apenas reset(), next(), prev() e end() fazem isso.

Lendo além do fim

Quando o ponteiro avança além do último elemento, pos() retorna false. É por isso que false é ambíguo como "valor atual" — pode significar tanto "o elemento é false" quanto "chegamos ao fim do array":

Quando você realmente precisa saber se chegou ao fim, combine pos() com key(): key() retorna null após o último elemento, enquanto uma chave real (0, 1, …) indica que o ponteiro ainda é válido.

pos() e as Demais Funções de Ponteiro

pos() é uma peça do conjunto de ferramentas de ponteiro interno do PHP. Cada função desempenha um papel distinto:

Quando Usar o Ponteiro Interno

Para a maioria das travessias de array, um laço foreach é mais claro e seguro — ele não toca o ponteiro interno do array. Recorra a pos()/current() e funções similares apenas quando precisar de controle manual e fino sobre a posição: por exemplo, inspecionar o elemento atual dentro de um laço while (key($arr) !== null), ou percorrer um array nas duas direções. Se você apenas quer cada elemento em ordem, prefira foreach.

Conclusão

A função pos() retorna o valor na posição do ponteiro interno de um array sem movê-lo, e é um alias legado de current(). Em código novo, prefira current(); combine-o com next(), prev(), reset() e end() para percorrer um array manualmente — e lembre-se de que um retorno false pode significar tanto um valor false quanto o fim do array, portanto use key() quando a distinção for importante.

Prática