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) |
|---|
Converte carimbo de data e hora em cadeia de caracteres, conforme o formato indicado.
|
Converte o intervalo em cadeia de caracteres, conforme o formato indicado.
|
Converte número em cadeia de caracteres, conforme o formato
indicado; disponível para os tipos de dados
|
|
Converte cadeia de caracteres em data, conforme o formato indicado.
|
Converte cadeia de caracteres em numérico, conforme o formato indicado.
|
Converte cadeia de caracteres em carimbo de data e hora, conforme
o formato indicado. (Veja também
|
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ão | Descrição |
|---|---|
HH | hora do dia (01–12) |
HH12 | hora do dia (01–12) |
HH24 | hora do dia (00–23) |
MI | minuto (00–59) |
SS | segundo (00–59) |
MS | milissegundo (000–999) |
US | microssegundo (000000–999999) |
FF1 | décimo de segundo (0–9) |
FF2 | centésimo de segundo (00–99) |
FF3 | milissegundo (000–999) |
FF4 | décimo de milissegundo (0000–9999) |
FF5 | centésimo de milissegundo (00000–99999) |
FF6 | microssegundo (000000–999999) |
SSSS, SSSSS | segundos após a meia-noite (0–86399) |
AM, am,
PM ou pm | indicador de meridiano (sem pontos) |
A.M., a.m.,
P.M. ou p.m. | indicador de meridiano (com pontos) |
Y,YYY | ano (4 ou mais dígitos) com vírgula |
YYYY | ano (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 |
IYYY | ano, 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 ad | indicador de era (sem pontos) |
B.C., b.c.,
A.D. ou a.d. | indicador de era (com pontos) |
MONTH | nome completo do mês em letras maiúsculas (preenchido com branco para 9 caracteres) |
Month | nome completo do mês com a primeira letra maiúscula (preenchido com branco para 9 caracteres) |
month | nome completo do mês em letras minúsculas (preenchido com branco para 9 caracteres) |
MON | nome abreviado do mês em letras maiúsculas (3 caracteres em inglês, o comprimento varia conforme a localidade) |
Mon | nome abreviado do mês com a primeira letra maiúscula (3 caracteres em inglês, o comprimento varia conforme a localidade) |
mon | nome abreviado do mês em letras minúsculas (3 caracteres em inglês, o comprimento varia conforme a localidade) |
MM | número do mês (01–12) |
DAY | nome completo do dia em letras maiúsculas (preenchido com branco para 9 caracteres) |
Day | nome completo do dia com a primeira letra maiúscula (preenchido com branco para 9 caracteres) |
day | nome completo do dia em letras minúsculas (preenchido com branco para 9 caracteres) |
DY | nome do dia abreviado em letras maiúsculas (3 caracteres em inglês, o comprimento varia conforme a localidade) |
Dy | nome do dia abreviado com a primeira letra maiúscula (3 caracteres em inglês, o comprimento varia conforme a localidade) |
dy | nome do dia abreviado em letras minúsculas (3 caracteres em inglês, o comprimento varia conforme a localidade) |
DDD | dia do ano (001–366) |
IDDD | dia do ano, da data com número da semana ISO 8601 (001–371; dia 1 do ano é segunda-feira da primeira semana ISO) |
DD | dia do mês (01–31) |
D | dia da semana, Domingo (1) a Sábado (7) |
ID | dia da semana, da data com número da semana ISO 8601, Segunda (1) a Domingo (7) |
W | semana do mês (1–5) (a primeira semana começa no primeiro dia do mês) |
WW | número da semana do ano (1–53) (a primeira semana começa no primeiro dia do ano) |
IW | número da semana, da data com número da semana ISO 8601 (01–53; a primeira quinta-feira do ano está na semana 1) |
CC | século (2 dígitos) (o século XXI começou em 2001-01-01) |
J | Data Juliana (dias inteiros desde 24 de novembro de 4714 aC à meia-noite local; veja a Seção B.7) |
Q | trimestre |
RM | mês em algarismos romanos maiúsculos (I–XII; I=Janeiro) |
rm | mês em algarismos romanos minúsculos (i–xii; i=Janeiro) |
TZ | abreviatura de zona horária em letras maiúsculas |
tz | abreviatura de zona horária em letras minúsculas |
TZH | horas da zona horária |
TZM | minutos da zona horária |
OF | deslocamento 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
| Modificador | Descrição | Exemplo |
|---|---|---|
FM prefixo | modo de preenchimento (suprimir zeros à esquerda e espaços em branco de preenchimento) | FMMonth |
TH sufixo | sufixo de número ordinal maiúsculo | DDTH; por exemplo, 12TH |
th sufixo | sufixo de número ordinal minúsculo | DDth, por exemplo, 12th |
FX prefixo | opção global de formato fixo (veja notas de uso) | FX Month DD Day |
TM prefixo | modo de tradução (usar nomes de dia e mês localizados com base em lc_time) | TMMonth |
SP sufixo | modo falado (não implementado) | DDSP |
Notas de uso para formatação de data e hora:
FM suprime zeros à esquerda e espaços em branco
à direita que, de outra forma, seriam adicionados para tornar a
saída de um padrão de largura fixa.
No PostgreSQL, FM
modifica apenas a próxima especificação, enquanto no
Oracle
FM afeta todas as especificações subsequentes,
e modificadores FM repetidos ativam e desativam
o modo de preenchimento.
TM suprime espaços em branco à direita,
independentemente de FM ser especificado ou não.
As funções to_timestamp e
to_date não diferenciam letras maiúsculas e
minúsculas na entrada; então, por exemplo, MON,
Mon e mon aceitam as mesmas
cadeias de caracteres.
Quando se usa o modificador TM, a transformação
em maiúsculas/minúsculas é feita segundo as regras de
ordenação da entrada da função (veja a Seção 23.2).
As funções to_timestamp e
to_date saltam múltiplos espaços em branco no
início da cadeia de caracteres de entrada, e em torno dos valores
de data e hora, a menos que a opção FX seja usada.
Por exemplo,
to_timestamp(' 2000 JUN', 'YYYY MON') e
to_timestamp('2000 - JUN', 'YYYY-MON') funcionam, mas
to_timestamp('2000 JUN', 'FXYYYY MON')
retorna um erro, porque a função to_timestamp
espera apenas um único espaço. FX
deve ser especificado como o primeiro item no modelo.
Um separador (espaço, ou caractere que não seja letra ou dígito)
na cadeia de caracteres do modelo das funções
to_timestamp e to_date
corresponde a qualquer separador único na cadeia de caracteres de
entrada, ou é ignorado, a menos que a opção FX
seja usada.
Por exemplo, to_timestamp('2000JUN', 'YYYY///MON') e
to_timestamp('2000/JUN', 'YYYY MON') funcionam,
mas to_timestamp('2000//JUN', 'YYYY/MON')
retorna um erro, porque o número de separadores na cadeia de
caracteres da entrada excede o número de separadores no modelo.
Se for especificado FX, um separador na cadeia
de caracteres do modelo corresponde exatamente a um caractere na
cadeia de caracteres de entrada.
Mas observe que o caractere da cadeia de caracteres de entrada
não precisa ser idêntico ao separador da cadeia de caracteres
do modelo. Por exemplo,
to_timestamp('2000/JUN', 'FXYYYY MON') funciona,
mas to_timestamp('2000/JUN', 'FXYYYY MON')
retorna um erro, porque o segundo espaço na cadeia de caracteres
do modelo consome a letra J da cadeia de
caracteres da entrada.
Um padrão de modelo TZH pode corresponder a um
número com sinal.
Sem a opção FX, os sinais de menos podem se
tornar ambíguos, podendo ser interpretados como separador.
Esta ambiguidade é resolvida da seguinte forma: Se o número de
separadores antes de TZH na cadeia de caracteres
do modelo for menor que o número de separadores antes do sinal de
menos na cadeia de caracteres da entrada, o sinal de menos será
interpretado como parte de TZH. Caso contrário,
o sinal de menos é considerado um separador entre os valores.
Por exemplo, to_timestamp('2000 -10', 'YYYY TZH')
corresponde a -10 para TZH, mas
to_timestamp('2000 -10', 'YYYY TZH')
corresponde a 10 para TZH.
É permitido texto comum em modelos para a função
to_char, e será gerado diretamente.
Pode ser colocada uma sub-cadeia de caracteres entre aspas para
forçá-la a ser interpretada como texto literal, mesmo que
contenha padrões de modelo.
Por exemplo, em '"Hello Year "YYYY',
YYYY será substituído pelo ano da data, mas o
caractere Y em Year
não será. Nas funções to_date,
to_number e to_timestamp,
texto literal e cadeias de caracteres entre aspas resultam em
pular o número de caracteres contidos na cadeia de caracteres;
por exemplo, "XX" pula dois caracteres de
entrada (sejam eles XX ou não).
Antes do PostgreSQL 12,
era possível pular texto arbitrário na cadeia de caracteres da
entrada usando caracteres que não fossem letras ou dígitos.
Por exemplo,
to_timestamp('2000y6m1d', 'yyyy-MM-DD')
costumava funcionar. Agora só podem ser usados caracteres de
letras para esta finalidade.
Por exemplo,
to_timestamp('2000y6m1d', 'yyyytMMtDDt') e
to_timestamp('2000y6m1d', 'yyyy"y"MM"m"DD"d"')
pulam y, m e
d.
Se for desejado ter aspas na saída, estas devem ser precedidas por
uma contrabarra; por exemplo, '\"YYYY Month\"'.
As contrabarras não são caracteres especiais fora das cadeias de
caracteres entre aspas.
Dentro de uma cadeia de caracteres entre aspas, uma contrabarra
faz com que o próximo caractere seja interpretado literalmente,
seja este qual for (mas isto não tem nenhum efeito especial,
a menos que o próximo caractere seja uma aspa ou outra contrabarra).
Nas funções to_timestamp e
to_date, se a especificação do formato do
ano tiver menos que quatro dígitos, como, por exemplo,
YYY, e o ano fornecido tiver menos que quatro
dígitos, o ano será ajustado para ficar o mais próximo do ano
de 2020; por exemplo, 95 se torna 1995.
Nas funções to_timestamp e
to_date, anos negativos são tratados como
significando BC. Se for escrito um ano negativo e um campo
BC explícito, será obtido AD novamente.
Uma entrada de ano igual a zero é tratada como 1 BC.
Nas funções to_timestamp e
to_date, a conversão YYYY
tem restrição ao processar anos com mais de 4 dígitos.
Deve ser usado algum caractere ou modelo que não seja dígito após
o YYYY, caso contrário, o ano é sempre
interpretado como tendo 4 dígitos.
Por exemplo, (com o ano 20000):
to_date('200001130', 'YYYYMMDD')
será interpretado como um ano de 4 dígitos; em seu lugar,
deve ser usado um separador sem dígito após o ano, como
to_date('20000-1130', 'YYYY-MMDD') ou
to_date('20000Nov30', 'YYYYMonDD').
Nas funções to_timestamp e
to_date, o campo CC (século)
é aceito, mas ignorado se houver um campo YYY,
YYYY ou Y,YYY.
Se CC for usado com YY ou
Y, então o resultado é calculado como aquele
ano no século especificado. Se o século for especificado, mas o
ano não, será assumido o primeiro ano do século.
Nas funções to_timestamp e
to_date, os nomes ou números dos dias da semana
(DAY, D e tipos de campos
relacionados) são aceitos, mas são ignorados para fins de cálculo
do resultado. O mesmo vale para os campos de trimestre
(Q).
Nas funções to_timestamp e
to_date, uma data com número da semana
ISO 8601 (diferente de uma data gregoriana) pode ser especificada
de duas maneiras:
Ano, número da semana, dia da semana: por exemplo,
to_date('2006-42-4', 'IYYY-IW-ID')
retorna a data 2006-10-19. Se for omitido
o dia da semana, será assumido o dia 1 (segunda-feira).
Ano e dia do ano: por exemplo,
to_date('2006-291', 'IYYY-IDDD')
também retorna 2006-10-19.
A tentativa de inserir uma data usando uma mistura de campos de numeração de semana ISO 8601 e campos de data gregoriana não faz sentido e gera erro. No contexto da data com número da semana ISO 8601, os conceitos de “mês” e “dia do mês” não fazem nenhum sentido. No contexto de ano gregoriano, a semana ISO 8601 não tem significado.
Enquanto a função to_date rejeita uma
mistura de campos Gregorianos e data com número da semana
ISO 8601, a função to_char não rejeita,
uma vez que especificações de formato de saída como
YYYY-MM-DD (IYYY-IDDD) podem ser úteis.
Mas deve ser evitado escrever algo como IYYY-MM-DD,
que pode causar resultados surpreendentes perto do início do ano.
(Veja a Seção 9.9.1 para obter
mais informações.)
Na função to_timestamp, os campos
milissegundo (MS) ou microssegundo (US)
são usados como os dígitos dos segundos após o ponto decimal.
Por exemplo, to_timestamp('12.3', 'SS.MS') não
são 3 milissegundos, mas 300, porque a conversão o trata como
12 + 0.3 segundos.
Portanto, para o formato SS.MS, os valores de
entrada 12.3, 12.30 e
12.300 especificam o mesmo número de
milissegundos. Para obter três milissegundos, deve ser escrito
12.003, que a conversão trata como
12 + 0.003 = 12.003 segundos.
Aqui está um exemplo mais complexo:
to_timestamp('15:12:02.020.001230', 'HH24:MI:SS.MS.US')
significa 15 horas, 12 minutos e 2 segundos + 20 milissegundos +
1230 microssegundos = 2,021230 segundos.
A numeração do dia da semana de to_char(..., 'ID')
corresponde à função extract(isodow from ...),
mas a de to_char(..., 'D') não corresponde à
numeração do dia de extract(dow from ...).
A função to_char(interval) formata
HH e HH12 como mostrado em
um relógio de 12 horas; por exemplo, tanto zero hora quanto
36 horas têm como saída 12, enquanto
HH24 gera o valor da hora completo, que pode
exceder 23 em um valor do tipo de dados interval.
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ão | Descrição |
|---|---|
9 | posição de um dígito (pode ser descartado se não for significativo) |
0 | posiçã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) |
PR | valor negativo entre <colchetes angulares> |
S | sinal ancorado ao número (usa a localidade) |
L | símbolo de moeda (usa a localidade) |
D | ponto decimal (usa a localidade) |
G | separador de grupo (usa a localidade) |
MI | sinal de menos na posição especificada (se o número for < 0) |
PL | sinal de mais na posição especificada (se o número for > 0) |
SG | sinal de mais/menos na posição especificada |
RN ou rn | numeral romano (valores entre 1 e 3999) |
TH ou th | sufixo de número ordinal |
V | deslocar o número especificado de dígitos (ver notas) |
EEEE | expoente para notação científica |
Notas de uso para formatação numérica:
0 determina uma posição de dígito que sempre
será impressa, mesmo que contenha um zero à esquerda ou à direita;
9 também determina uma posição de dígito,
mas se for um zero à esquerda será substituído por um espaço,
enquanto se for um zero à direita, e for especificado modo
de preenchimento, será excluído.
(Para a função to_number(), estes dois
caracteres do padrão são equivalentes.)
Se o formato fornecer menos dígitos fracionários do que o número
sendo formatado, a função to_char() irá
arredondar o número para o número especificado de dígitos
fracionários.
Os caracteres de padrão S, L,
D e G representam os
caracteres de sinal, símbolo de moeda, ponto decimal e separador
de milhares definidos pela localidade corrente
(veja lc_monetary e
lc_numeric).
Os caracteres do padrão ponto e vírgula representam estes
caracteres exatamente, com os significados de ponto decimal e
separador de milhares, independentemente da localidade.
Se nenhuma provisão explícita for feita para o sinal no padrão
da função to_char(), será reservada uma coluna
para o sinal, e será ancorado (aparecendo à esquerda) do número.
Se aparecer um S à esquerda de alguns
9, também será ancorado ao número.
Um sinal usando SG, PL ou
MI não está ancorado ao número; por exemplo,
to_char(-12, 'MI9999') produz '- 12',
mas to_char(-12, 'S9999') produz ' -12'.
(A implementação do Oracle não permite o uso do
MI antes do 9, o elemento
de formato MI pode aparecer apenas na última
posição de um modelo de formato numérico, ou seja, no
Oracle
to_char(-12, '9999MI') produz
'12-')
TH não converte valores inferiores a zero e
não converte números fracionários.
PL, SG e
TH são extensões do
PostgreSQL.
Na função to_number, se forem usados padrões
de modelo que não sejam de dados, como L ou
TH, o número correspondente de caracteres de
entrada é ignorado, independentemente de corresponderem ou não ao
padrão do modelo, a menos que sejam caracteres de dados
(ou seja, dígitos, sinal, ponto decimal ou vírgula).
Por exemplo, TH pula dois caracteres não
sejam caracteres de dados.
V com a função to_char
multiplica o valor da entrada por
10^, onde
nn é o número de dígitos após
V; V com a função
to_number divide de maneira semelhante.
O V pode ser interpretado como um marcador
da posição de um ponto decimal implícito na cadeia de caracteres
de entrada ou saída.
As funções to_char e
to_number não oferecem suporte ao uso de
V combinado com o ponto decimal
(por exemplo, 99.9V99 não é permitido).
EEEE (notação científica) não pode ser usado
em combinação com qualquer um dos outros padrões de formatação ou
modificadores que não sejam padrões de dígitos e pontos decimais,
e deve estar no final da cadeia de caracteres de formato
(por exemplo, 9.99EEEE é um padrão válido).
Na função to_number() o padrão
RN converte numerais romanos
(no formato padrão) em números.
A entrada não diferencia letras maiúsculas de minúsculas, então
RN e rn são equivalentes.
RN não pode ser usado em combinação com
quaisquer outros padrões ou modificadores de formatação, exceto
FM, que é aplicável somente na função
to_char() sendo ignorado na função
to_number().
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
| Modificador | Descrição | Exemplo |
|---|---|---|
FM prefixo | modo de preenchimento (suprime zeros à direita e espaços em branco de preenchimento) | FM99.99 |
TH sufixo | sufixo de número ordinal maiúsculo | 999TH |
th sufixo | sufixo de número ordinal minúsculo | 999th |
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ão | Resultado |
|---|---|
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-' |