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

CKTIS / Java

BigDecimal.setScale — alterar a escala e arredondar

Defina a escala de um `BigDecimal` sem alterar o seu valor ou escolha explicitamente um modo de arredondamento. O objeto original fica inalterado.

Versão: Java SE 21

Sintaxe

public BigDecimal setScale(int newScale)
public BigDecimal setScale(int newScale, RoundingMode roundingMode)
@Deprecated(since = "9")
public BigDecimal setScale(int newScale, int roundingMode)

BigDecimal.setScale é um método de instância de java.math.BigDecimal. Uma escala não negativa indica o número de casas decimais; a escala -1 corresponde a múltiplos de dez. A escala não é a precisão (o número de algarismos do valor não escalado). O método devolve um BigDecimal, não texto formatado. O objeto original é imutável: utilize o valor devolvido, que não tem de ser um novo objeto.

setScale(int) conserva o valor numérico. Em notação decimal, aumentar a escala pode acrescentar zeros à direita; reduzi-la sem alterar o valor só pode retirar zeros. Se for necessário arredondar, o método lança ArithmeticException.

setScale(int, RoundingMode) aplica o modo escolhido em java.math.RoundingMode quando reduzir a escala exige arredondamento. HALF_UP escolhe o valor mais próximo à escala pedida e, em caso de empate, o mais afastado de zero: 2.675 passa a 2.68 à escala 2. UNNECESSARY exige um resultado exato e provoca uma ArithmeticException se for necessário arredondar.

A sobrecarga setScale(int, int) está obsoleta desde o Java 9 e lança IllegalArgumentException se o segundo argumento não representar um modo de arredondamento válido. Em código novo, utilize a sobrecarga com RoundingMode. Para introduzir um decimal exato, utilize new BigDecimal("2.675") em vez de new BigDecimal(2.675), que incorpora a aproximação binária do double.

Exemplos

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

public class Main {
    public static void main(String[] args) {
        BigDecimal original = new BigDecimal("2.675");
        BigDecimal padded = original.setScale(4);
        System.out.println(padded.toPlainString());
        System.out.println(padded.setScale(3).toPlainString());
        System.out.println(original.setScale(2, RoundingMode.HALF_UP).toPlainString());

        try {
            original.setScale(2);
        } catch (ArithmeticException e) {
            System.out.println("ArithmeticException");
        }

        System.out.println(original.toPlainString());
    }
}

Resultado

2.6750
2.675
2.68
ArithmeticException
2.675

As duas primeiras linhas mostram a adição e a remoção de um zero final sem alterar o valor. A terceira mostra o arredondamento, a quarta assinala a exceção capturada e a última mostra o valor original inalterado.

Lições relacionadas

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

Fontes