count_chars()

A função PHP count_chars() reporta, para cada valor de byte possível (0 a 255), quantas vezes ele aparece numa string. Em vez de analisar palavras ou caracteres um a um, ela fornece um instantâneo de frequência de toda a string numa única chamada. Isso a torna útil para tarefas como construir histogramas de caracteres, detectar quais caracteres uma string utiliza ou identificar rapidamente bytes inesperados numa entrada.

Esta página aborda a sintaxe, todos os valores de $mode e exatamente o que cada um retorna, um exemplo prático e as armadilhas comuns (como as chaves ASCII e como ela lida com texto multibyte).

Sintaxe

count_chars(string $string, int $mode = 0): array|string

• $string — a string a ser analisada.
• $mode — controla o formato do resultado (padrão 0). Veja os modos abaixo.

As chaves retornadas por count_chars() são valores de byte (0–255), não os próprios caracteres. Por exemplo, o byte 108 é a letra l. Use chr() para converter um valor de byte de volta ao seu caractere, e ord() para fazer o caminho inverso.

Os cinco modos

Os modos 0, 1 e 2 retornam um array; os modos 3 e 4 retornam uma string.

Exemplo básico

O modo 1 é o mais utilizado — ele lista apenas os caracteres que realmente ocorrem e quantas vezes cada um aparece.

A saída é:

Array
(
    [32] => 1
    [33] => 1
    [44] => 1
    [72] => 1
    [87] => 1
    [100] => 1
    [101] => 1
    [108] => 3
    [111] => 2
    [114] => 1
)

Cada chave é um valor de byte e cada valor é a sua contagem. Portanto, [108] => 3 significa que o byte 108 (a letra l) aparece três vezes, e [111] => 2 significa que o aparece duas vezes. O espaço (32), a vírgula (44) e o ponto de exclamação (33) também são contabilizados.

Obtendo saída legível com chr()

Como as chaves são valores de byte, a saída bruta é difícil de ler. Converta cada chave de volta ao seu caractere com chr():

<?php
$string = "Hello, World!";
foreach (count_chars($string, 1) as $byte => $times) {
    printf("'%s' (byte %d) appears %d time(s)\n", chr($byte), $byte, $times);
}
?>

Saída:

' ' (byte 32) appears 1 time(s)
'!' (byte 33) appears 1 time(s)
',' (byte 44) appears 1 time(s)
'H' (byte 72) appears 1 time(s)
'W' (byte 87) appears 1 time(s)
'd' (byte 100) appears 1 time(s)
'e' (byte 101) appears 1 time(s)
'l' (byte 108) appears 3 time(s)
'o' (byte 111) appears 2 time(s)
'r' (byte 114) appears 1 time(s)

Modos 3 e 4: quais caracteres são (ou não) utilizados

Quando você só precisa saber quais caracteres aparecem — e não quantas vezes — os modos 3 e 4 retornam uma string compacta em vez de um array.

<?php
$string = "Hello, World!";

echo count_chars($string, 3) . "\n"; //  !,HWdelor
echo strlen(count_chars($string, 3)) . "\n"; // 10  (10 distinct bytes used)
echo strlen(count_chars($string, 4)) . "\n"; // 246 (256 - 10 = bytes never used)
?>

O modo 3 é uma forma rápida de obter o conjunto de caracteres distintos de uma string, já ordenados.

Armadilhas comuns

• As chaves são bytes, não caracteres. Lembre-se sempre que count_chars() indexa pelo valor de byte 0–255. Use chr() para uma saída legível por humanos.
• Não é compatível com multibyte. Um caractere UTF-8 como é ocupa dois bytes, e count_chars() contará cada byte separadamente, e não o caractere como um todo. Para texto Unicode, prefira mb_strlen() / preg_match_all().
• O modo 0 é grande. Ele sempre retorna 256 entradas (a maioria com contagem 0), por isso use o modo 1 quando quiser apenas os caracteres que aparecem.

Funções relacionadas

• strlen() — comprimento total de uma string em bytes.
• substr_count() — conta ocorrências de uma substring (não de um único byte).
• str_word_count() — conta palavras em vez de caracteres.
• str_split() — divide uma string num array de caracteres.
• ord() e chr() — convertem entre um caractere e seu valor de byte.

Prática