Categorias:

Funções de conversão

TO_CHAR , TO_VARCHAR

Converte a expressão de entrada em uma cadeia de caracteres. Para a entrada NULL, a saída será NULL.

Estas funções são sinônimas.

Sintaxe

TO_CHAR( <expr> )
TO_CHAR( <numeric_expr> [, '<format>' ] )
TO_CHAR( <date_or_time_expr> [, '<format>' ] )
TO_CHAR( <binary_expr> [, '<format>' ] )

TO_VARCHAR( <expr> )
TO_VARCHAR( <numeric_expr> [, '<format>' ] )
TO_VARCHAR( <date_or_time_expr> [, '<format>' ] )
TO_VARCHAR( <binary_expr> [, '<format>' ] )
Copy

Argumentos

Obrigatório:

expr

Uma expressão de qualquer tipo de dados.

numeric_expr

Uma expressão numérica.

date_or_time_expr

Uma expressão do tipo DATE, TIME ou TIMESTAMP.

binary_expr

Uma expressão do tipo BINARY ou VARBINARY.

Opcional:

format

O formato da cadeia de caracteres de saída:

Retornos

Esta função retorna um valor do tipo de dados NULL ou VARCHAR.

Notas de uso

  • Para entradas VARIANT, ARRAY ou OBJECT, a saída é a cadeia de caracteres contendo um documento JSON ou valor elementar JSON (a menos que VARIANT ou OBJECT contenha uma tag XML, nesse caso a saída será uma cadeia de caracteres contendo um documento XML):

    • Uma cadeia de caracteres armazenada em VARIANT é preservada como está (ou seja, não é convertida em uma cadeia de caracteres JSON).

    • Um valor nulo JSON é convertido em uma cadeia de caracteres contendo a palavra “nulo”.

Exemplos

Os exemplos a seguir convertem números, carimbos de data/hora e datas em cadeias de caracteres.

Exemplos que convertem números

Converta valores numéricos em cadeias de caracteres nos formatos especificados:

CREATE OR REPLACE TABLE convert_numbers_to_strings(column1 NUMBER);

INSERT INTO convert_numbers_to_strings VALUES
  (-12.391),
  (0),
  (-1),
  (0.10),
  (0.01),
  (3987),
  (1.111);

SELECT column1 AS orig_value,
       TO_CHAR(column1, '">"$99.0"<"') AS D2_1,
       TO_CHAR(column1, '">"B9,999.0"<"') AS D4_1,
       TO_CHAR(column1, '">"TME"<"') AS TME,
       TO_CHAR(column1, '">"TM9"<"') AS TM9,
       TO_CHAR(column1, '">"0XXX"<"') AS X4,
       TO_CHAR(column1, '">"S0XXX"<"') AS SX4
  FROM convert_numbers_to_strings;
Copy
+------------+----------+------------+-------------+------------+--------+---------+
| ORIG_VALUE | D2_1     | D4_1       | TME         | TM9        | X4     | SX4     |
|------------+----------+------------+-------------+------------+--------+---------|
|    -12.391 | >-$12.4< | >   -12.4< | >-1.2391E1< | >-12.391<  | >FFF4< | >-000C< |
|      0.000 | >  $0.0< | >      .0< | >0E0<       | >0.000<    | >0000< | >+0000< |
|     -1.000 | > -$1.0< | >    -1.0< | >-1E0<      | >-1.000<   | >FFFF< | >-0001< |
|      0.100 | >  $0.1< | >      .1< | >1E-1<      | >0.100<    | >0000< | >+0000< |
|      0.010 | >  $0.0< | >      .0< | >1E-2<      | >0.010<    | >0000< | >+0000< |
|   3987.000 | > $##.#< | > 3,987.0< | >3.987E3<   | >3987.000< | >0F93< | >+0F93< |
|      1.111 | >  $1.1< | >     1.1< | >1.111E0<   | >1.111<    | >0001< | >+0001< |
+------------+----------+------------+-------------+------------+--------+---------+

A saída ilustra como os valores são convertidos em cadeias de caracteres com base nos formatos especificados:

  • Os símbolos > e < são literais de cadeia de caracteres que são incluídos na saída. Eles facilitam a visualização de onde os espaços são inseridos.

  • A coluna D2_1 mostra os valores com um $ impresso antes dos dígitos.

    • No caso do valor 3987, há mais dígitos na parte inteira do número do que posições de dígitos no formato, portanto, todos os dígitos são impressos como # para indicar estouro.

    • Para os valores 0.10, 0.01 e 1.111, há mais dígitos na parte fracionária do número do que posições de dígitos no formato, então os valores fracionários são truncados.

  • A coluna D4_1 mostra que valores zero são representados como espaços nas partes inteiras dos números.

    • Para os valores 0, 0.10 e 0.01, um espaço substitui o zero antes do separador.

    • Para os valores 0.10, 0.01 e 1.111, há mais dígitos na parte fracionária do número do que posições de dígitos no formato, então os valores fracionários são truncados.

  • A coluna TME mostra os valores em notação científica.

  • A coluna TM9 mostra os valores como inteiros ou frações decimais, com base no valor do número.

  • A coluna X4 mostra os valores como dígitos hexadecimais sem as partes fracionárias.

  • A coluna SX4 mostra os valores como dígitos hexadecimais do valor absoluto dos números e inclui o sinal numérico (+ ou -).

Este exemplo converte um valor logarítmico em uma cadeia de caracteres:

SELECT TO_VARCHAR(LOG(3,4));
Copy
+----------------------+
| TO_VARCHAR(LOG(3,4)) |
|----------------------|
| 1.261859507          |
+----------------------+

Exemplos que convertem carimbos de data/hora e datas

Converter um valor TIMESTAMP em uma cadeia de caracteres no formato especificado:

SELECT TO_VARCHAR('2024-04-05 01:02:03'::TIMESTAMP, 'mm/dd/yyyy, hh24:mi hours');
Copy
+---------------------------------------------------------------------------+
| TO_VARCHAR('2024-04-05 01:02:03'::TIMESTAMP, 'MM/DD/YYYY, HH24:MI HOURS') |
|---------------------------------------------------------------------------|
| 04/05/2024, 01:02 hours                                                   |
+---------------------------------------------------------------------------+

Converter um valor DATE em uma cadeia de caracteres no formato padrão:

SELECT TO_VARCHAR('03-April-2024'::DATE);
Copy
+-----------------------------------+
| TO_VARCHAR('03-APRIL-2024'::DATE) |
|-----------------------------------|
| 2024-04-03                        |
+-----------------------------------+

Converter um valor DATE em uma cadeia de caracteres no formato especificado:

SELECT TO_VARCHAR('03-April-2024'::DATE, 'yyyy.mm.dd');
Copy
+-------------------------------------------------+
| TO_VARCHAR('03-APRIL-2024'::DATE, 'YYYY.MM.DD') |
|-------------------------------------------------|
| 2024.04.03                                      |
+-------------------------------------------------+
Linguagem: Português