Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / Java

BigDecimal.add — soma exata ou arredondada

Some valores BigDecimal sem arredondamento ou utilize MathContext para definir a precisão e o modo de arredondamento do resultado.

Versão: Java SE 21

Sintaxe

import java.math.BigDecimal;
import java.math.MathContext;

BigDecimal exact = a.add(b);
BigDecimal rounded = a.add(b, mc);

// Instance method signatures in java.math.BigDecimal:
// public BigDecimal add(BigDecimal augend)
// public BigDecimal add(BigDecimal augend, MathContext mc)

BigDecimal.add é um método de instância de java.math.BigDecimal. Em a.add(b), o objeto a e o argumento b são as duas parcelas. Não é possível somar dois objetos BigDecimal com +. Estes objetos são imutáveis: o método devolve o resultado sem alterar nenhuma parcela. Guarde ou utilize o valor devolvido; a.add(b); por si só não atualiza a.

a.add(b) devolve a soma exata com a escala max(a.scale(), b.scale()). Uma escala não negativa indica o número de casas decimais, incluindo os zeros finais. A escala também pode ser negativa: com escala -2, o valor é o inteiro armazenado multiplicado por 100.

a.add(b, mc) recebe um MathContext de java.math. Uma precisão positiva limita o número de algarismos significativos do resultado, não o número de casas decimais. O método arredonda a soma exata, se necessário, segundo o modo indicado no contexto, pelo que a escala do resultado pode mudar. Com precisão positiva, se apenas uma das parcelas for zero, o resultado tem o valor numérico da parcela não nula, arredondado se necessário. A escala do resultado pode diferir da escala da parcela não nula, mesmo quando não é necessário arredondar. Por exemplo, somar 0.00 a 1 com precisão 3 dá 1.00. A precisão 0, como em MathContext.UNLIMITED, indica uma soma sem arredondamento.

Se o arredondamento alterar o valor, RoundingMode.UNNECESSARY provoca uma ArithmeticException. Passar null como b ou mc provoca uma NullPointerException.

Exemplos

import java.math.BigDecimal;
import java.math.MathContext;
import java.math.RoundingMode;

public class Main {
    public static void main(String[] args) {
        BigDecimal a = new BigDecimal("12.40");
        BigDecimal b = new BigDecimal("0.350");
        MathContext mc = new MathContext(3, RoundingMode.HALF_UP);

        BigDecimal exact = a.add(b);
        BigDecimal rounded = a.add(b, mc);

        System.out.println(exact.toPlainString());
        System.out.println(rounded.toPlainString());
        System.out.println(a.toPlainString());
    }
}

Resultado

12.750
12.8
12.40

As parcelas são construídas a partir de cadeias de caracteres para evitar uma conversão prévia para `double`. A soma exata `12.750` tem escala 3; com três algarismos significativos, `HALF_UP` dá `12.8`. A última linha mostra que `a` continua a valer `12.40`.

Lições relacionadas

  • Java · Lição 4 · Básico · Versão: 2
  • Java · Lição 69 · Básico · Versão: 2

Fontes