is_nan()

A função is_nan() no PHP verifica se um valor de ponto flutuante é NaN ("Not a Number") — o valor especial que o padrão IEEE 754 usa para resultados matematicamente indefinidos. Esta página explica o que é NaN, por que não se pode testá-lo com ==, como is_nan() resolve esse problema e os cuidados a ter.

Sintaxe

is_nan(float $num): bool

Recebe um único argumento de ponto flutuante e retorna true se esse valor for NaN, e false para qualquer número comum (incluindo 0.0 e infinito).

O que é NaN?

NaN é um marcador produzido pela aritmética de ponto flutuante quando uma operação não tem resposta real e representável. Fontes comuns incluem:

• acos(1.5) — o arco cosseno só é definido para entradas entre -1 e 1.
• sqrt(-1) — não existe raiz quadrada real de um número negativo.
• log(-1) — o logaritmo natural é indefinido para números não positivos.
• fdiv(0, 0) — dividir zero por zero no estilo de ponto flutuante.
• A constante embutida NAN em si.

NaN tem tipo double (o tipo float do PHP), portanto passa despercebido em código que apenas verifica is_float(). É exatamente por isso que existe um teste dedicado.

Nota: escrever 0 / 0 diretamente lança um DivisionByZeroError no PHP 8+, portanto não retorna NaN silenciosamente. Use fdiv(0, 0) quando quiser o resultado NaN de ponto flutuante em vez de uma exceção.

Por que não se pode comparar NaN com ==

A propriedade mais importante do NaN é que ele não é igual a nada, nem mesmo a si mesmo. Qualquer comparação envolvendo NaN retorna false:

<?php
var_dump(NAN == NAN);   // bool(false)
var_dump(NAN === NAN);  // bool(false)
var_dump(NAN < 1);      // bool(false)
var_dump(NAN > 1);      // bool(false)
?>

Como $x == NAN é sempre falso, não é possível detectar NaN por comparação. is_nan() é a forma correta — e a única confiável — de verificar.

Como usar a função is_nan()

Você passa um valor (geralmente o resultado de algum cálculo) para is_nan() e ramifica com base no boolean retornado:

Aqui acos(1.5) é indefinido, então retorna NaN, is_nan() retorna true e o script exibe The number is not a number.

Validando o resultado de um cálculo

Um uso típico no mundo real é proteger a saída: execute um cálculo e recuse exibir ou armazenar o resultado se ele vier como NaN.

<?php
function safeRatio(float $a, float $b): string {
    $result = $a * sqrt($b); // sqrt of a negative number yields NaN

    if (is_nan($result)) {
        return "Invalid input: result is not a number";
    }

    return "Result: " . $result;
}

echo safeRatio(2, 9), PHP_EOL;   // Result: 6
echo safeRatio(2, -9), PHP_EOL;  // Invalid input: result is not a number
?>

is_nan() vs verificações relacionadas

Use is_finite() para confirmar que um número é um valor comum e utilizável, is_infinite() para detectar estouro para infinito, e is_nan() especificamente para o caso de "resultado indefinido". Para validar strings fornecidas pelo usuário antes que cheguem a qualquer cálculo, use is_numeric().

Conclusão

is_nan() é a forma confiável de detectar o valor NaN do IEEE 754, que os operadores de igualdade nunca conseguem capturar porque NaN não é igual a si mesmo. Use-a para validar a saída de funções matemáticas como acos(), sqrt() e log() antes de confiar no resultado, e combine-a com is_finite() e is_float() quando precisar de um quadro completo do estado de um float.

Prática