9.7. Funções para formatar tipo de dado

As funções de formatação do PostgreSQL fornecem um poderoso conjunto de ferramentas para converter vários tipos de dado (date/time, integer, floating point, numeric) em cadeias de caracteres formatadas, e para converter cadeias de caracteres formatadas em tipos de dado específicos. A Tabela 9-22 mostra estas funções, que seguem uma convenção de chamada comum: o primeiro argumento é o valor a ser formatado, e o segundo argumento é o modelo que define o formato da entrada ou da saída.

Advertência: to_char(interval, text) está obsoleta, não devendo ser utilizada nas novas aplicações. Será removida na próxima versão.

Em uma cadeia de caracteres modelo de saída (para to_char), existem certos padrões que são reconhecidos e substituídos pelos dados devidamente formatados a partir do valor a ser formatado. Qualquer texto que não seja um modelo padrão é simplesmente copiado sem alteração. Da mesma forma, em uma cadeia de caracteres modelo de entrada (para qualquer coisa menos to_char), os modelos padrão identificam as partes da cadeia de caracteres da entrada de dados a serem procuradas, e os valores a serem encontrados nestas partes.

A Tabela 9-23 mostra os modelos padrão disponíveis para formatar valores de data e de hora.

Certos modificadores podem ser aplicados aos modelos padrão para alterar seu comportamento. Por exemplo, FMMonth é o modelo "Month" com o modificador "FM". A Tabela 9-24 mostra os modificadores de modelo para formatação de data e hora.

Notas sobre a utilização da formatação de data e hora:

• O FM suprime zeros à esquerda e espaços à direita, que de outra forma seriam adicionados para fazer a saída do modelo ter comprimento fixo.
• As funções to_timestamp e to_date saltam espaços em branco múltiplos na cadeia de caracteres de entrada quando a opção FX não é utilizada. O FX deve ser especificado como o primeiro item do modelo; por exemplo, to_timestamp('2000    JUN','YYYY MON') está correto, mas to_timestamp('2000    JUN','FXYYYY MON') retorna erro, porque to_timestamp espera um único espaço apenas.
• É permitida a presença de texto comum nos modelos para to_char, sendo mostrados literalmente na saída. Uma parte da cadeia de caracteres pode ser colocada entre aspas, para obrigar sua interpretação como um texto literal mesmo contendo palavras chave do modelo. Por exemplo, em '"Hello Year "YYYY', o YYYY será substituído pelo ano do fornecido, mas o único Y em Year não será substituído.
• Se for desejada a presença de aspas na saída, as mesmas devem ser precedidas por contrabarra. Por exemplo '\\"YYYY Month\\"'. (Duas contrabarras são necessárias, porque a contrabarra possui significado especial em uma constante cadeia de caracteres).
• A conversão YYYY de cadeia de caracteres para timestamp ou para date tem restrição quando são utilizados anos com mais de 4 dígitos. Deve ser utilizado um modelo, ou algum caractere que não seja um dígito, após YYYY, senão o ano será sempre interpretado como tendo 4 dígitos. Por exemplo, (com o ano 20000): to_date('200001121', 'YYYYMMDD') é interpretado como um ano de 4 dígitos; em vez disso, deve ser utilizado um separador que não seja um dígito após o ano, como to_date('20000-1121', 'YYYY-MMDD') ou to_date('20000Nov21', 'YYYYMonDD').
• Os valores de milissegundos MS e microssegundos US na conversão de uma cadeia de caracteres para um carimbo do tempo (timestamp), são interpretados como a sendo parte 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 interpreta como sendo 12 + 0.3 segundos. Isto significa que, para o formato SS:MS, os valores de entrada 12:3, 12:30 e 12:300 especificam o mesmo número de milissegundos. Para especificar três milissegundos deve ser utilizado 12:003, que na conversão é interpretado como 12 + 0.003 = 12.003 segundos. A seguir está mostrado um exemplo mais complexo: to_timestamp('15:12:02.020.001230','HH:MI:SS.MS.US') é interpretado como 15 horas, 12 minutos e 2 segundos + 20 milissegundos + 1230 microssegundos = 2.021230 segundos.

A Tabela 9-25 mostra os modelos padrão disponíveis para formatar valores numéricos.

Notas sobre a utilização da formatação numérica:

• O sinal formatado utilizando SG, PL ou MI não está ancorado ao número; por exemplo, to_char(-12, 'S9999') produz '  -12', mas to_char(-12, 'MI9999') produz '-  12'. A implementação do Oracle não permite utilizar o MI antes do 9, requerendo que o 9 preceda o MI.
• O 9 resulta em um valor com o mesmo número de dígitos que o número de 9s. Se não houver um dígito para colocar, é colocado espaço.
• O TH não converte valores menores que zero e não converte números fracionários.
• O PL, o SG e o TH são extensões do PostgreSQL.
• O V multiplica efetivamente os valores da entrada por 10^n, onde n é o número de dígitos após o V. A função to_char não permite o uso de V junto com o ponto decimal (Por exemplo, 99.9V99 não é permitido).

A Tabela 9-26 mostra alguns exemplos de uso da função to_char.