9.8. Funções de formatação de tipo de dados #

As funções de formatação do PostgreSQL fornecem um poderoso conjunto de ferramentas para converter vários tipos de dados (data e hora, inteiro, ponto flutuante, numérico) em cadeia de caracteres formatadas, e para converter cadeia de caracteres formatadas em tipos de dados específicos. Estas funções estão descritas na Tabela 9.26, e todas seguem uma convenção de chamada comum: o primeiro argumento é o valor a ser formatado, e o segundo argumento é um modelo que define o formato de saída ou de entrada.

Tabela 9.26. Funções de formatação

Função

Descrição

Exemplo(s)

to_char ( timestamp, text ) → text

to_char ( timestamp with time zone, text ) → text

Converte carimbo de data e hora em cadeia de caracteres, conforme o formato indicado.

to_char(timestamp '2002-04-20 17:31:12.66', 'HH12:MI:SS')05:31:12

to_char ( interval, text ) → text

Converte o intervalo em cadeia de caracteres, conforme o formato indicado.

to_char(interval '15h 2m 12s', 'HH24:MI:SS')15:02:12

to_char ( numeric_type, text ) → text

Converte número em cadeia de caracteres, conforme o formato indicado; disponível para os tipos de dados integer, bigint, numeric, real e double precision.

to_char(125, '999')125

to_char(125.8::real, '999D9')125.8

to_char(-125.8, '999D99S')125.80-

to_date ( text, text ) → date

Converte cadeia de caracteres em data, conforme o formato indicado.

to_date('05 Dec 2000', 'DD Mon YYYY')2000-12-05

to_number ( text, text ) → numeric

Converte cadeia de caracteres em numérico, conforme o formato indicado.

to_number('12,454.8-', '99G999D9S')-12454.8

to_timestamp ( text, text ) → timestamp with time zone

Converte cadeia de caracteres em carimbo de data e hora, conforme o formato indicado. (Veja também to_timestamp(double precision) na Tabela 9.33.)

to_timestamp('05 Dec 2000', 'DD Mon YYYY')2000-12-05 00:00:00-05


Dica

As funções to_timestamp e to_date existem para lidar com formatos de entrada que não podem ser convertidos por conversão simples. Para a maioria dos formatos de data e hora padrão, apenas converter a cadeia de caracteres de origem para o tipo de dados requerido funciona, sendo muito mais fácil. Da mesma forma, a função to_number é desnecessária para representações numéricas padrão.

Em uma cadeia de caracteres de modelo de saída da função to_char, existem certos padrões reconhecidos e substituídos por dados formatados de forma apropriada com base no valor fornecido. Qualquer texto que não seja um padrão de modelo é apenas copiado diretamente. Da mesma forma, em uma cadeia de caracteres de modelo de entrada (para as outras funções), os padrões de modelo identificam os valores a serem fornecidos pela cadeia de caracteres de dados de entrada. Se houver caracteres na cadeia de caracteres de modelo que não sejam padrões de modelo, os caracteres que correspondem na cadeia de caracteres de dados de entrada serão apenas ignorados (sendo ou não iguais aos caracteres da cadeia de caracteres do modelo).

A Tabela 9.27 descreve os padrões de modelo disponíveis para formatar valores de data e hora.

Tabela 9.27. Padrões de modelo para formatação de data e hora

PadrãoDescrição
HHhora do dia (01–12)
HH12hora do dia (01–12)
HH24hora do dia (00–23)
MIminuto (00–59)
SSsegundo (00–59)
MSmilissegundo (000–999)
USmicrossegundo (000000–999999)
FF1décimo de segundo (0–9)
FF2centésimo de segundo (00–99)
FF3milissegundo (000–999)
FF4décimo de milissegundo (0000–9999)
FF5centésimo de milissegundo (00000–99999)
FF6microssegundo (000000–999999)
SSSS, SSSSSsegundos após a meia-noite (0–86399)
AM, am, PM ou pmindicador de meridiano (sem pontos)
A.M., a.m., P.M. ou p.m.indicador de meridiano (com pontos)
Y,YYYano (4 ou mais dígitos) com vírgula
YYYYano (4 ou mais dígitos)
YYYúltimos 3 dígitos do ano
YYúltimos 2 dígitos do ano
Yúltimo dígito do ano
IYYYano, da data com número da semana ISO 8601 (4 ou mais dígitos)
IYYúltimos 3 dígitos do ano, da data com número da semana ISO 8601
IYúltimos 2 dígitos do ano, da data com número da semana ISO 8601
Iúltimo dígito do ano, da data com número da semana ISO 8601
BC, bc, AD ou adindicador de era (sem pontos)
B.C., b.c., A.D. ou a.d.indicador de era (com pontos)
MONTHnome completo do mês em letras maiúsculas (preenchido com branco para 9 caracteres)
Monthnome completo do mês com a primeira letra maiúscula (preenchido com branco para 9 caracteres)
monthnome completo do mês em letras minúsculas (preenchido com branco para 9 caracteres)
MONnome abreviado do mês em letras maiúsculas (3 caracteres em inglês, o comprimento varia conforme a localidade)
Monnome abreviado do mês com a primeira letra maiúscula (3 caracteres em inglês, o comprimento varia conforme a localidade)
monnome abreviado do mês em letras minúsculas (3 caracteres em inglês, o comprimento varia conforme a localidade)
MMnúmero do mês (01–12)
DAYnome completo do dia em letras maiúsculas (preenchido com branco para 9 caracteres)
Daynome completo do dia com a primeira letra maiúscula (preenchido com branco para 9 caracteres)
daynome completo do dia em letras minúsculas (preenchido com branco para 9 caracteres)
DYnome do dia abreviado em letras maiúsculas (3 caracteres em inglês, o comprimento varia conforme a localidade)
Dynome do dia abreviado com a primeira letra maiúscula (3 caracteres em inglês, o comprimento varia conforme a localidade)
dynome do dia abreviado em letras minúsculas (3 caracteres em inglês, o comprimento varia conforme a localidade)
DDDdia do ano (001–366)
IDDDdia do ano, da data com número da semana ISO 8601 (001–371; dia 1 do ano é segunda-feira da primeira semana ISO)
DDdia do mês (01–31)
Ddia da semana, Domingo (1) a Sábado (7)
IDdia da semana, da data com número da semana ISO 8601, Segunda (1) a Domingo (7)
Wsemana do mês (1–5) (a primeira semana começa no primeiro dia do mês)
WWnúmero da semana do ano (1–53) (a primeira semana começa no primeiro dia do ano)
IWnúmero da semana, da data com número da semana ISO 8601 (01–53; a primeira quinta-feira do ano está na semana 1)
CCséculo (2 dígitos) (o século XXI começou em 2001-01-01)
JData Juliana (dias inteiros desde 24 de novembro de 4714 aC à meia-noite local; veja a Seção B.7)
Qtrimestre
RMmês em algarismos romanos maiúsculos (I–XII; I=Janeiro)
rmmês em algarismos romanos minúsculos (i–xii; i=Janeiro)
TZabreviatura de zona horária em letras maiúsculas
tzabreviatura de zona horária em letras minúsculas
TZHhoras da zona horária
TZMminutos da zona horária
OFdeslocamento do UTC da zona horária (HH ou HH:MM)

Podem ser aplicados modificadores a qualquer padrão de modelo para alterar o seu comportamento. Por exemplo, FMMonth é o padrão Month com o modificador FM. A Tabela 9.28 descreve os modificadores de padrão de modelo para formatação de data e hora.

Tabela 9.28. Modificadores de padrão de modelo para formatação de data e hora

ModificadorDescriçãoExemplo
FM prefixomodo de preenchimento (suprimir zeros à esquerda e espaços em branco de preenchimento)FMMonth
TH sufixosufixo de número ordinal maiúsculoDDTH; por exemplo, 12TH
th sufixosufixo de número ordinal minúsculoDDth, por exemplo, 12th
FX prefixoopção global de formato fixo (veja notas de uso)FX Month DD Day
TM prefixomodo de tradução (usar nomes de dia e mês localizados com base em lc_time)TMMonth
SP sufixomodo falado (não implementado)DDSP

Notas de uso para formatação de data e hora:

A Tabela 9.29 descreve os padrões de modelo disponíveis para formatar valores numéricos.

Tabela 9.29. Padrões de modelo para formatação numérica

PadrãoDescrição
9posição de um dígito (pode ser descartado se não for significativo)
0posição de um dígito (não pode ser descartado, mesmo se não for significativo)
. (ponto)ponto decimal
, (vírgula)separador de grupo (milhares)
PRvalor negativo entre <colchetes angulares>
Ssinal ancorado ao número (usa a localidade)
Lsímbolo de moeda (usa a localidade)
Dponto decimal (usa a localidade)
Gseparador de grupo (usa a localidade)
MIsinal de menos na posição especificada (se o número for < 0)
PLsinal de mais na posição especificada (se o número for > 0)
SGsinal de mais/menos na posição especificada
RN ou rnnumeral romano (valores entre 1 e 3999)
TH ou thsufixo de número ordinal
Vdeslocar o número especificado de dígitos (ver notas)
EEEEexpoente para notação científica

Notas de uso para formatação numérica:

Certos modificadores podem ser aplicados a qualquer padrão de modelo para alterar o seu comportamento. Por exemplo, FM99.99 é o padrão 99.99 com o modificador FM. A Tabela 9.30 descreve os modificadores de padrão de modelo para formatação numérica.

Tabela 9.30. Modificadores de padrão de modelo para formatação numérica

ModificadorDescriçãoExemplo
FM prefixomodo de preenchimento (suprime zeros à direita e espaços em branco de preenchimento)FM99.99
TH sufixosufixo de número ordinal maiúsculo999TH
th sufixosufixo de número ordinal minúsculo999th

A Tabela 9.31 mostra alguns exemplos de uso da função to_char.

Tabela 9.31. Exemplos usando a função to_char

ExpressãoResultado
to_char(current_timestamp, 'Day, DD  HH12:MI:SS')'Tuesday  , 06  05:39:18'
to_char(current_timestamp, 'FMDay, FMDD  HH12:MI:SS')'Tuesday, 6  05:39:18'
to_char(current_timestamp AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"')'2022-12-06T05:39:18Z', formato estendido ISO 8601
to_char(-0.1, '99.99')'  -.10'
to_char(-0.1, 'FM9.99')'-.1'
to_char(-0.1, 'FM90.99')'-0.1'
to_char(0.1, '0.9')' 0.1'
to_char(12, '9990999.9')'    0012.0'
to_char(12, 'FM9990999.9')'0012.'
to_char(485, '999')' 485'
to_char(-485, '999')'-485'
to_char(485, '9 9 9')' 4 8 5'
to_char(1485, '9,999')' 1,485'
to_char(1485, '9G999')' 1.485'
to_char(148.5, '999.999')' 148.500'
to_char(148.5, 'FM999.999')'148.5'
to_char(148.5, 'FM999.990')'148.500'
to_char(148.5, '999D999')' 148,500'
to_char(3148.5, '9G999D999')'  3.148,500'
to_char(-485, '999S')'485-'
to_char(-485, '999MI')'485-'
to_char(485, '999MI')'485 '
to_char(485, 'FM999MI')'485'
to_char(485, 'PL999')'+485'
to_char(485, 'SG999')'+485'
to_char(-485, 'SG999')'-485'
to_char(-485, '9SG99')'4-85'
to_char(-485, '999PR')'<485>'
to_char(485, 'L999')'R$ 485'
to_char(485, 'RN')'        CDLXXXV'
to_char(485, 'FMRN')'CDLXXXV'
to_char(5.2, 'FMRN')'V'
to_char(482, '999th')' 482nd'
to_char(485, '"Bom número:"999')'Bom número: 485'
to_char(485.8, '"Pre:"999" Post:" .999')'Pre: 485 Post: .800'
to_char(12, '99V999')' 12000'
to_char(12.4, '99V999')' 12400'
to_char(12.45, '99V9')' 125'
to_char(0.0004859, '9.99EEEE')' 4.86e-04'
trim(to_char(-10000,'L99G999D99MI'))'R$10.000,00-'