6.7. Funções para formatar tipos de dado

As funções de formatação do PostgreSQL disponibilizam um poderoso conjunto de ferramentas para converter diversos tipos de dado (date/time, integer, floating point, numeric) em cadeias de caracteres formatadas, e para converter cadeias de caracteres formatadas nos tipos de dado especificados. A Tabela 6-12 mostra estas funções, que seguem uma convenção de chamada comum: o primeiro argumento é o valor a ser formatado, e o segundo argumento é a máscara que define o formato da entrada ou da saída.

Na cadeia de caracteres usada como máscara de saída, existem certos elementos que são reconhecidos e substituídos pelos dados devidamente formatados a partir do valor a ser formatado. Qualquer texto que não faça parte de um elemento da máscara é simplesmente copiado sem alteração. Da mesma forma, na cadeia de caracteres usada como máscara de entrada, os elementos da máscara identificam as partes procuradas na cadeia de caracteres da entrada, e os valores a ser encontrados nestas posições.

A Tabela 6-13 mostra os elementos que podem ser utilizados na máscara para formatar valores de data e de hora.

Certos modificadores podem ser aplicados a qualquer elemento da máscara para alterar seu comportamento. Por exemplo, "FMMonth" é o elemento "Month" com o prefixo "FM". A Tabela 6-14 mostra os modificadores de elemento para formatação de data e hora.

Notas relativas à 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 o elemento da saída ter comprimento fixo.

• As funções to_timestamp e to_date desprezam os múltiplos espaços em branco na cadeia de caracteres de entrada quando a opção FX não é utilizada. O FX deve ser especificado como o primeiro elemento da máscara; 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 em branco.

• Se for desejada a presença de uma contrabarra ("\") em uma constante cadeia de caracteres, devem ser escritas duas contrabarras ("\\"); por exemplo '\\HH\\MI\\SS'. Isto vale para qualquer constante cadeia de caracteres no PostgreSQL.

• Texto comum é permitido nas máscaras da função to_char, sendo reproduzidos literalmente. Podem ser colocados caracteres entre aspas para serem interpretados como texto literal, mesmo contendo palavras chaves para elemento. Por exemplo, em '"Hello Year "YYYY', o YYYY é substituído pelo ano da data, porém o Y de "Year" não é.

• Se for desejada uma aspa na saída esta deve ser precedida por uma contrabarra. Por exemplo '\\"YYYY Month\\"'.

• A conversão YYYY de cadeia de caracteres para timestamp ou para date tem restrições quando são utilizados mais de 4 dígitos para o ano. Deve ser utilizado algum caractere que não seja um dígito ou um outro elemento após YYYY, senão o ano será sempre interpretado como tendo 4 dígitos. Por exemplo, (com o ano 20000): to_date('200001131', 'YYYYMMDD') é interpretado como um ano de 4 dígitos; o melhor é utilizar um separador que não seja um dígito após o ano, como to_date('20000-1131', 'YYYY-MMDD') ou to_date('20000Nov31', 'YYYYMonDD').

• Os valores de milissegundos MS e microssegundos US, na conversão de uma cadeia de caracteres para um carimbo de tempo (time stamp), 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. 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, 2 segundos + 20 milissegundos + 1230 microssegundos = 2.021230 segundos.

A Tabela 6-15 mostra os elementos usados nas máscaras disponíveis para formatar valores numéricos.

Notas relativas à utilização da formatação numérica:

• O sinal formatado utilizando SG, PL ou MI não está ancorado no 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, requer que o 9 preceda o MI.

• O 9 especifica um valor com o mesmo número de dígitos que o número de 9s. Se não houver um dígito disponível, é colocado um espaço.

• O TH não converte valores menores que zero e não converte números decimais.

• O PL, o SG e o TH são extensões do PostgreSQL.

• O V efetivamente multiplica os valores de entrada por 10^n, onde n é o número de dígitos após o V. A função to_char não aceita utilizar V juntamente com o ponto decimal (Por exemplo, 99.9V99 não é permitido).

A Tabela 6-16 mostra alguns exemplos de utilização da função to_char.