ROUND¶

Sintaxe¶

ROUND( <input_expr> [ , <scale_expr> [ , '<rounding_mode>' ] ] )

ROUND( EXPR => <input_expr> ,
       SCALE => <scale_expr>
       [ , ROUNDING_MODE => '<rounding_mode>'  ] )

Argumentos¶

Obrigatório:

input_expr . OR . EXPR => input_expr

O valor ou expressão a ser utilizado. O tipo de dados deve ser do tipo numérico, como FLOAT ou NUMBER.

Se você especificar o argumento nomeado EXPR =>, também deverá especificar o argumento nomeado SCALE =>.

Opcional:

scale_expr . OR . SCALE => scale_expr

O número de dígitos que a saída inclui após o ponto decimal. A expressão deve ser avaliada como um número inteiro de -38 a +38.

O padrão scale_expr é zero, o que significa que a função remove todos os dígitos após o ponto decimal.

Para obter mais informações sobre números negativos, consulte Notas de uso.

Se você especificar o argumento nomeado SCALE =>, deverá especificar EXPR => como o argumento nomeado anterior.

'rounding_mode' . OR . ROUNDING_MODE => 'rounding_mode'

O modo de arredondamento a ser usado. Especifique um dos seguintes valores:

• HALF_AWAY_FROM_ZERO. Este modo arredonda o valor para cima.

• HALF_TO_EVEN. Este modo arredonda o valor para o par mais próximo.

Padrão: HALF_AWAY_FROM_ZERO

Se você especificar o argumento nomeado ROUNDING_MODE =>, deverá especificar EXPR => e SCALE => como argumentos nomeados anteriores.

Nota

Se você especificar qualquer um dos valores para o argumento rounding_mode, o tipo de dados input_expr deve ser um dos tipos de dados para um número de ponto fixo.

Os tipos de dados para números de ponto flutuante (por exemplo, FLOAT) não são compatíveis com esse argumento.

Retornos¶

O tipo de retorno é baseado no tipo de entrada:

• Se a expressão de entrada for um FLOAT, o tipo retornado será um FLOAT.

• Se a expressão de entrada for um NUMBER, o tipo retornado será um NUMBER.

  • Se a escala de entrada for constante:

    • Se a escala de entrada for positiva, o tipo retornado terá uma escala igual à escala de entrada e terá uma precisão grande o suficiente para abranger qualquer resultado possível.

    • Se a escala de entrada for negativa, o tipo retornado terá uma escala de 0.

  • Se a escala de entrada não for constante, a escala do tipo retornado será a mesma que a da expressão de entrada.

Se a escala for zero, então o valor é efetivamente um INTEGER.

Por exemplo:

• O tipo de dados retornado por ROUND(3.14::FLOAT, 1) é FLOAT.

• O NUMBER retornado por ROUND(3.14, 1) tem escala 1 e precisão de pelo menos 3.

• O NUMBER retornado por ROUND(-9.99, 0) tem escala 0 e precisão de pelo menos 2.

• O NUMBER retornado por ROUND(33.33, -1) tem escala 0 e precisão de pelo menos 3.

Se input_expr ou scale_expr for NULL, a função retornará NULL.

Notas de uso¶

• Você deve especificar todos os argumentos por nome ou por posição. Você não pode especificar alguns dos argumentos por nome e outros argumentos por posição.

  Ao especificar um argumento por nome, você não pode usar aspas duplas no nome do argumento.

• Se scale_expr for negativo, ele especificará o número de casas antes do ponto decimal para ajustar o número. Por exemplo, se a escala for -2, o resultado será um múltiplo de 100.

• Se scale_expr for maior do que a escala de expressão de entrada, a função não terá qualquer efeito.

• Por padrão, os meios pontos são arredondadas para cima para os decimais. Por exemplo, -0,5 é arredondado para -1,0.

  Para mudar o modo de arredondamento para arredondar o valor para o par mais próximo (por exemplo, para arredondar -0,5 para 0), especifique 'HALF_TO_EVEN' para o argumento rounding_mode.

  Nota

  Se você especificar o argumento rounding_mode, o tipo de dados do argumento input_expr deve ser um dos tipos de dados para um número de ponto fixo.

• Os números de pontos flutuantes são valores aproximados. Um número de ponto flutuante pode não arredondar como esperado.

• Se o arredondamento colocar o número fora do intervalo de valores do tipo de dados, a função retornará um erro.

Exemplos¶

Este exemplo mostra um uso simples de ROUND, com o número padrão de casas decimais (0):

SELECT ROUND(135.135), ROUND(-975.975);

+----------------+-----------------+
| ROUND(135.135) | ROUND(-975.975) |
|----------------+-----------------|
|            135 |            -976 |
+----------------+-----------------+

O próximo exemplo consulta os dados da seguinte tabela:

CREATE TABLE test_ceiling (n FLOAT, scale INTEGER);

INSERT INTO test_ceiling (n, scale) VALUES
  (-975.975, -1),
  (-975.975,  0),
  (-975.975,  2),
  ( 135.135, -2),
  ( 135.135,  0),
  ( 135.135,  1),
  ( 135.135,  3),
  ( 135.135, 50),
  ( 135.135, NULL);

Consulte a tabela e use um intervalo de valores para o argumento scale_expr:

SELECT n, scale, ROUND(n, scale)
  FROM test_ceiling
  ORDER BY n, scale;

+----------+-------+-----------------+
|        N | SCALE | ROUND(N, SCALE) |
|----------+-------+-----------------|
| -975.975 |    -1 |        -980     |
| -975.975 |     0 |        -976     |
| -975.975 |     2 |        -975.98  |
|  135.135 |    -2 |         100     |
|  135.135 |     0 |         135     |
|  135.135 |     1 |         135.1   |
|  135.135 |     3 |         135.135 |
|  135.135 |    50 |         135.135 |
|  135.135 |  NULL |            NULL |
+----------+-------+-----------------+

Os próximos dois exemplos mostram a diferença entre o uso do modo de arredondamento padrão ('HALF_AWAY_FROM_ZERO') e o modo de arredondamento 'HALF_TO_EVEN': Ambos os exemplos chamam a função ROUND duas vezes, primeiro com o comportamento de arredondamento padrão e depois com 'HALF_TO_EVEN'.

O primeiro exemplo usa um valor de entrada positivo de 2,5:

SELECT ROUND(2.5, 0), ROUND(2.5, 0, 'HALF_TO_EVEN');

+---------------+-------------------------------+
| ROUND(2.5, 0) | ROUND(2.5, 0, 'HALF_TO_EVEN') |
|---------------+-------------------------------|
|             3 |                             2 |
+---------------+-------------------------------+

O segundo exemplo usa um valor de entrada negativo de -2,5:

SELECT ROUND(-2.5, 0), ROUND(-2.5, 0, 'HALF_TO_EVEN');

+----------------+--------------------------------+
| ROUND(-2.5, 0) | ROUND(-2.5, 0, 'HALF_TO_EVEN') |
|----------------+--------------------------------|
|             -3 |                             -2 |
+----------------+--------------------------------+

Os próximos dois exemplos mostram como especificar os argumentos para a função por nome, em vez de por posição:

SELECT ROUND(
  EXPR => -2.5,
  SCALE => 0) AS named_arguments;

+-----------------+
| NAMED_ARGUMENTS |
|-----------------|
|              -3 |
+-----------------+

SELECT ROUND(
  EXPR => -2.5,
  SCALE => 0,
  ROUNDING_MODE => 'HALF_TO_EVEN') AS named_with_rounding_mode;

+--------------------------+
| NAMED_WITH_ROUNDING_MODE |
|--------------------------|
|                       -2 |
+--------------------------+

O próximo exemplo mostra que os valores FLOAT nem sempre são armazenados exatamente. Como você pode ver abaixo, em alguns casos ,005 é arredondado para ,01, enquanto em outros casos é arredondado para 0. A diferença não está no arredondamento, está na representação do número de ponto flutuante porque 1.005 é armazenado como um número um pouco menor que 1.005 (aproximadamente 1,004999). O valor DECIMAL, entretanto, é armazenado como um número exato, e é arredondado para ,01 como esperado em todos os casos.

Criar e carregar uma tabela:

CREATE OR REPLACE TEMP TABLE rnd1(f float, d DECIMAL(10, 3));

INSERT INTO rnd1 (f, d) VALUES
  ( -10.005,  -10.005),
  (  -1.005,   -1.005),
  (   1.005,    1.005),
  (  10.005,   10.005);

Mostrar exemplos da diferença entre os valores arredondados FLOAT e os valores arredondados DECIMAL:

SELECT f,
       ROUND(f, 2),
       d,
       ROUND(d, 2)
  FROM rnd1
  ORDER BY 1;

+---------+-------------+---------+-------------+
|       F | ROUND(F, 2) |       D | ROUND(D, 2) |
|---------+-------------+---------+-------------|
| -10.005 |      -10.01 | -10.005 |      -10.01 |
|  -1.005 |       -1    |  -1.005 |       -1.01 |
|   1.005 |        1    |   1.005 |        1.01 |
|  10.005 |       10.01 |  10.005 |       10.01 |
+---------+-------------+---------+-------------+