intdiv()

A função intdiv() no PHP realiza divisão inteira: ela divide um inteiro por outro e retorna o quociente como número inteiro, descartando qualquer resto. Foi introduzida no PHP 7.0 para oferecer uma maneira clara e explícita de expressar "quantas vezes B cabe em A" sem recorrer ao operador / e a uma conversão de tipo manual.

Esta página explica o que intdiv() retorna, como ela difere dos operadores / e %, como trata números negativos e floats, e como lidar com os erros que ela pode lançar.

Sintaxe

intdiv(int $num1, int $num2): int

• $num1 — o dividendo (o número a ser dividido).
• $num2 — o divisor (o número pelo qual se divide).
• Retorna o quociente $num1 / $num2 como um int, com a parte fracionária descartada.

Um Exemplo Básico

10 / 3 é 3.333…, então intdiv() mantém a parte inteira, 3, e descarta o 0.333….

intdiv() vs. os Operadores / e %

O operador de divisão regular / sempre produz um float quando os números não se dividem exatamente, enquanto intdiv() sempre produz um int. O operador módulo % fornece o resto que intdiv() descarta. Juntos, intdiv() e % recuperam o número original:

<?php
echo 10 / 3;          // 3.3333333333333 (float)
echo "\n";
echo intdiv(10, 3);   // 3   (int quotient)
echo "\n";
echo 10 % 3;          // 1   (remainder)
echo "\n";

// quotient * divisor + remainder == dividend
echo intdiv(10, 3) * 3 + (10 % 3); // 10
?>

Use intdiv() quando você genuinamente deseja um resultado inteiro, como dividir itens em páginas, converter segundos em minutos ou distribuir uma quantidade em grupos de tamanho fixo.

Truncamento em Direção ao Zero

intdiv() trunca em direção ao zero, não em direção ao infinito negativo. Isso importa para operandos negativos e é uma fonte comum de erros quando as pessoas assumem que ela arredonda para baixo:

<?php
echo intdiv(7, 2);    // 3
echo "\n";
echo intdiv(-7, 2);   // -3  (not -4)
echo "\n";
echo intdiv(7, -2);   // -3
echo "\n";
echo intdiv(-7, -2);  // 3
?>

-7 / 2 é -3.5; truncar em direção ao zero resulta em -3. (Se você quiser especificamente o comportamento de piso, use floor(-7 / 2), que retorna -4.)

Tratamento de Erros

intdiv() lança uma exceção em dois casos, ambos os quais você deve proteger contra:

• Divisão por zero lança um DivisionByZeroError.
• intdiv(PHP_INT_MIN, -1) lança um ArithmeticError, pois o resultado matematicamente correto é maior do que o valor máximo que um inteiro pode armazenar.

<?php
function safeIntdiv($a, $b) {
    try {
        return intdiv($a, $b);
    } catch (DivisionByZeroError $e) {
        return "Cannot divide by zero";
    } catch (ArithmeticError $e) {
        return "Result out of integer range";
    }
}

echo safeIntdiv(20, 4);   // 5
echo "\n";
echo safeIntdiv(20, 0);   // Cannot divide by zero
?>

Nota: intdiv() espera argumentos inteiros. Um float como 7.9 é convertido para inteiro (sua parte fracionária descartada) antes de a divisão ser executada, então intdiv(7.9, 2) se comporta como intdiv(7, 2). Para divisão que mantém a parte fracionária de floats, use a função fmod() ou o operador /.

Conclusão

A função intdiv() fornece uma maneira confiável e explícita de realizar divisão inteira no PHP. Lembre-se de que ela trunca em direção ao zero, que o resto descartado está disponível por meio do %, e que ela pode lançar DivisionByZeroError e ArithmeticError. Para mais informações sobre operações numéricas, consulte PHP Math, PHP Operators e PHP Numbers.

Prática