Modelos de formato SQL¶

Elementos de formato¶

Os elementos de formato são sequências de dígitos e/ou letras (na maioria das vezes sem diferenciar maiúsculas de minúsculas) e, em alguns casos, símbolos. Os elementos de formato podem ser diretamente concatenados uns aos outros.

Alguns elementos de formato são usados comumente em todos os modelos de formato para controle de impressão e o texto de entrada correspondente. Outros elementos de formato têm usos específicos com base no tipo de valores que são usados para converter de/para. Para obter mais informações, consulte as seções seguintes deste tópico:

• Modificadores de formato e tratamento genérico de espaço

• Elementos de formato de posição fixa

• Elementos de formato de texto mínimo

Literais de formato¶

Literais de formato são sequências que podem consistir em combinações de:

• Cadeias de caracteres arbitrários delimitados por aspas duplas (uma aspas duplas é representada como duas aspas duplas adjacentes).

• Um ou mais dos seguintes símbolos:

  Símbolo/Caractere	Notas
  . (ponto final)	Em modelos numéricos fixos, tratado como um elemento de formato quando segue 0, 9 ou X; caso contrário, preservado como está.
  , (vírgula)	Em modelos numéricos, tratado como um elemento de formato quando segue 0, 9 ou X; caso contrário, preservado como está.
  ; (ponto e vírgula)	Sempre preservado como está.
  : (dois pontos)	Sempre preservado como está.
  - (sinal de menos)	Sempre preservado como está.
  = (sinal de igual)	Sempre preservado como está.
  / (barra)	Sempre preservado como está.
  ( (parêntese esquerdo)	Sempre preservado como está.
  ) (parêntese direito)	Sempre preservado como está.

Um literal é sempre impresso como está, exatamente onde ele estava localizado no modelo de formato.

Aqui está um breve exemplo de utilização de um modelo de formato SQL para imprimir o sinal de menos após um número, e não antes dele. O MI indica onde colocar o sinal de subtração se o número for um número negativo.

select to_varchar(-123.45, '999.99MI') as EXAMPLE;

Copy

A saída seria semelhante a 123.45-, e não ao padrão -123.45.

Mais exemplos estão incluídos no final deste tópico.

Impressão de cadeias de caracteres de saída usando o modificador de modo de preenchimento¶

Por padrão, o modo de preenchimento é ajustado para preenchimento, e o modificador de modo de preenchimento FM alterna-o para compacto; o uso repetido alterna-o de volta para preenchimento etc.

Na maioria dos casos, o uso do modo preenchimento na impressão garante que os elementos de formato produzam saída de uma largura fixa inserindo números à esquerda com zeros ou espaços, e inserindo texto com espaços à direita. Isto garante que a saída colunar em fontes de largura fixa seja alinhada.

No modo compacto, a maioria dos elementos de formato produzem apenas uma saída com largura mínima (ou seja, os zeros e os espaços à esquerda e os espaços à direita são suprimidos).

Os elementos de formato que não aderem a essas regras estão considerados explicitamente abaixo.

O modificador de correspondência exata, FX, não afeta a impressão; o elemento de formato sublinhado não imprime nada.

Analisando as cadeias de caracteres de entrada usando os modificadores¶

A análise das cadeias de caracteres de entrada é afetada tanto pelo modificador de modo de preenchimento, FM, quanto pelo modificador de correspondência exata, FX. Inicialmente:

• O modo de preenchimento está definido como preenchimento e FM alterna-o para compacto e de volta.

• O modo de correspondência exata está definido como lax, e FX alterna-o para exato e de volta.

Todas as correspondências de cadeias de caracteres entre elementos de formato e literais durante a análise não diferenciam maiúsculas e minúsculas.

No modo lax, o primeiro passo da análise de entrada é pular o espaço branco inicial, à esquerda (uma sequência de espaços, tabulação, caracteres LF, CR, FF e VT); o modo na entrada inicial é estrito se o primeiro elemento de formato for FX e, caso contrário, lax.

No modo de correspondência lax, os espaços dentro dos literais são comparados com qualquer sequência de espaços de entrada não vazios; caracteres não espaciais são comparados um a um. No modo exato, todos os caracteres em um literal devem corresponder aos caracteres de entrada um a um.

Os elementos de formato numérico são comparados com as sequências de dígitos correspondentes:

• Se ambos os modos preenchimento e exato estiverem em vigor, o número de dígitos deve corresponder exatamente à largura dos elementos de formato numérico correspondentes (são esperados zeros iniciais, à esquerda).

• Se o modo compacto ou lax estiver em vigor, um número de entrada correspondente deve ter, no máximo, o número de dígitos igual à largura máxima do elemento de formato, e pelo menos um dígito; os zeros iniciais são ignorados.

Os elementos de formato textual são comparados sem fazer distinção entre maiúsculas e minúsculas:

• Se ambos os modos preenchimento e exato estiverem em vigor, é esperado o número de espaços finais, à direita, até a largura máxima do elemento.

• Caso contrário, espaços após os elementos textuais de comprimento variável são ignorados no modo lax, e é esperada uma correspondência exata com a palavra real (sem espaços de preenchimento) no modo exato.

Por último, o espaço branco à direita até o final da cadeia de caracteres de entrada é ignorado se o modo atual for lax.

Normalmente, ambos os modos lax e exato não permitem espaços correspondentes onde os espaços não estão presentes no modelo de formato ou não poderiam ser gerados pela impressão do conteúdo dos elementos de formato no modo preenchimento.

Locais onde espaços devem ser ignorados se presentes em ambos os modos lax e exato podem ser marcados explicitamente usando o elemento de formato _ (sublinhado).

Como regra geral, um formato no modo exato reconhece apenas as cadeias de caracteres de entrada impressas pelo mesmo formato, enquanto um formato no modo lax reconhece as cadeias de caracteres de entrada que foram impressas pelo formato similar com qualquer modificador de modo de preenchimento adicionado ou removido.

Formatos numéricos de posição fixa¶

Os números de posição fixa são representados usando elementos de dígitos, 0 ou 9. Por exemplo, 999 contém números de 1 a 3 dígitos decimais. A parte fracionária dos números é delimitada usando os elementos separadores, . (ponto final) ou D:

• . é sempre apresentado como um ponto final.

• Para usar um caractere diferente para os elementos D, modifique a cadeia de caracteres de entrada para substituir todos os pontos finais por vírgulas e todas as vírgulas por pontos finais antes de aplicar a função de conversão.

Normalmente, os zeros iniciais, à esquerda, na parte inteira e os zeros finais, à direita, na parte fracionária são substituídos por espaços (exceto quando o valor da parte inteira é zero, caso em que é apresentado como um único caractere 0). Para suprimir esse comportamento, utilize o elemento de formato 0 no lugar de 9; as posições correspondentes têm 0 caracteres preservados. O elemento de formato B, quando usado antes do número, suprime a preservação do último 0 no valor inteiro (ou seja, se você usar B e o valor da parte inteira do número for zero, todos os dígitos são apresentados como espaços).

O separador de grupo de dígitos , (vírgula) ou G resulta na impressão do caractere separador de grupo correspondente se o número for suficientemente grande para que os dígitos fiquem nos dois lados do separador de grupo. Um exemplo de um modelo de formato útil para imprimir somas monetárias seria 999,999.00.

Quando há mais dígitos na parte inteira do número do que posições de dígito no formato, todos os dígitos são impressos como # para indicar excesso.

O elemento expoente faz com que os números de posição fixa sejam normalizados de modo que o primeiro dígito na parte inteira seja 1 a 9 (a menos que o valor do número seja zero, caso em que o valor do expoente também é zero). O elemento EE escolhe automaticamente o número correto de dígitos no expoente, e não imprime o sinal +, enquanto EEE, EEEE e EEEEE sempre imprime o sinal + ou - para o expoente e o número solicitado de dígitos (os zeros iniciais não são suprimidos). O excedente do expoente é indicado por # no lugar dos dígitos.

Os indicadores do expoente imprimem E maiúsculo ou e minúsculo, com base na primeira letra no elemento de formato, se é maiúscula ou minúscula.

O elemento de formato X funciona como 9, exceto que os dígitos hexadecimais 0-9A-F são impressos. Atualmente, as frações hexadecimais não são aceitas. Assim como 9, X substitui os zeros iniciais por espaços. O elemento 0, quando usado junto com X, imprime dígitos hexadecimais sem levar à supressão de zeros (assim, use 000X para imprimir números hexadecimais que sempre contenham 4 dígitos).

Note que X imprime dígitos hexadecimais com letras latinas em maiúsculas, e x minúsculo imprime letras latinas em minúsculas. O elemento de formato hexadecimal 0 se baseia no elemento de formato X subsequente, se maiúsculo ou minúsuclo.

Normalmente, números hexadecimais são impressos sem sinal, ou seja, números negativos têm 1 nos bits mais significativos, mas usar o elemento X junto com um sinal explícito (S ou MI) faz com que o sinal - seja impresso junto com o valor absoluto do número.

Modelos em formato numérico de posição fixa relatam excesso em valores especiais (infinitos ou “não é um número”) de números de ponto flutuante.

Formatos numéricos de texto mínimo¶

Enquanto os modelos de formato numérico de posição fixa sempre especificam explicitamente o número de dígitos, os elementos de formato de texto mínimo utilizam um número mínimo de dígitos com base no valor do número. Os elementos de formato TM* sempre geram uma saída de comprimento variável sem espaços, independentemente do modificador de modo de preenchimento (preenchimento ou compacto).

• TM9 imprime o número como um número inteiro ou fração decimal, com base no valor do número. Qualquer valor numérico decimal de ponto fixo é impresso precisamente com o número de dígitos na parte fracionária determinado pela escala do número (os zeros finais são preservados no modo preenchimento).

• Para números de ponto flutuante, TM9 escolhe o número de dígitos fracionários com base no expoente do número (note que não é possível a conversão exata de binário para fração decimal). Se a magnitude do número de ponto flutuante for muito grande, fazendo com que a notação posicional seja muito longa, ela muda para notação científica (consulte TME abaixo). Se o número do ponto flutuante for muito pequeno, TM9 imprime zero.

• TME imprime o número na notação científica, ou seja, com expoente (assim como EE) e um dígito na posição inteira da parte fracionária. A letra maiúscula/minúscula do indicador do expoente (E ou e) corresponde à maiúscula/minúscula da primeira letra (T ou t) no elemento de formato.

• TM escolhe TM9 ou TME, dependendo da magnitude do número, para minimizar o comprimento do texto, preservando a precisão.

Formatos padrão para impressão¶

A tabela a seguir lista os formatos padrão para impressão:

Tipo de dados SQL	Parâmetro	Formato padrão
DECIMAL	nenhum	TM9
DOUBLE	nenhum	TME

Formatos padrão para a análise¶

A tabela a seguir lista os formatos padrão para análise:

Tipo de dados SQL	Parâmetro	Formato AUTO padrão
DECIMAL	Nenhum	TM9
DOUBLE	Nenhum	TME

A lista de formatos usados para conversão otimista automática de cadeias de caracteres (ou seja, para cadeias de caracteres que são automaticamente reconhecidas como numéricas) é a união de todos os formatos na tabela acima de formatos de entrada padrão.

Exemplos de saída¶

Este exemplo mostra como exibir números com zeros à esquerda:

create table sample_numbers (f float);
insert into sample_numbers (f) values (1.2);
insert into sample_numbers (f) values (123.456);
insert into sample_numbers (f) values (1234.56);
insert into sample_numbers (f) values (-123456.789);
select to_varchar(f, '999,999.999'), to_varchar(f, 'S000,000.000') from sample_numbers;

Copy

A saída será semelhante a:

+------------------------------+-------------------------------+
| TO_VARCHAR(F, '999,999.999') | TO_VARCHAR(F, 'S000,000.000') |
+==============================+===============================+
|        1.2                   | +000,001.200                  |
+------------------------------+-------------------------------+
|      123.456                 | +000,123.456                  |
+------------------------------+-------------------------------+
|    1,234.56                  | +001,234.560                  |
+------------------------------+-------------------------------+
| -123,456.789                 | -123,456.789                  |
+------------------------------+-------------------------------+

Copy

Você não precisa de zeros à esquerda para alinhar os números. O modo de preenchimento padrão é “preenchimento”, o que significa que os espaços em branco são usados para alinhar números com base nas posições das vírgulas decimais.

select to_varchar(f, '999,999.999'), to_varchar(f, 'S999,999.999') from sample_numbers;

Copy

A saída será semelhante a:

+------------------------------+-------------------------------+
| TO_VARCHAR(F, '999,999.999') | TO_VARCHAR(F, 'S999,999.999') |
+==============================+===============================+
|        1.2                   |       +1.2                    |
+------------------------------+-------------------------------+
|      123.456                 |     +123.456                  |
+------------------------------+-------------------------------+
|    1,234.56                  |   +1,234.56                   |
+------------------------------+-------------------------------+
| -123,456.789                 | -123,456.789                  |
+------------------------------+-------------------------------+

Copy

Este exemplo mostra o que acontece se você usar o modificador FM (Modo de preenchimento) para mudar do modo “preenchimento” para o modo “compacto”, ou seja, para remover os caracteres iniciais que alinhariam os números:

select  to_varchar(f, '999,999.999'), to_varchar(f, 'FM999,999.999') from sample_numbers;

Copy

A saída será semelhante a:

+------------------------------+--------------------------------+
| TO_VARCHAR(F, '999,999.999') | TO_VARCHAR(F, 'FM999,999.999') |
+==============================+================================+
|        1.2                   | 1.2                            |
+------------------------------+--------------------------------+
|      123.456                 | 123.456                        |
+------------------------------+--------------------------------+
|    1,234.56                  | 1,234.56                       |
+------------------------------+--------------------------------+
| -123,456.789                 | -123,456.789                   |
+------------------------------+--------------------------------+

Copy

Este exemplo mostra como exibir números em notação exponencial:

select to_char(1234, '9d999EE'), 'will look like', '1.234E3';

Copy

A saída será semelhante a:

+--------------------------+------------------+-----------+
| TO_CHAR(1234, '9D999EE') | 'WILL LOOK LIKE' | '1.234E3' |
+==========================+==================+===========+
| 1.234E3                  |  will look like  |  1.234E3  |
+--------------------------+------------------+-----------+

Copy

Isto mostra como incluir literais na saída. As partes literais estão contidas dentro de aspas duplas (que, por sua vez, estão dentro das aspas simples que delimitam a cadeia de caracteres).

select to_char(12, '">"99"<"');

Copy

A saída será semelhante a:

+-------+
| > 12< |
+-------+

Copy

Exemplos de entrada¶

Estes exemplos demonstram o uso de modelos de formato para entradas.

O exemplo a seguir mostra algumas operações simples de entrada, com ênfase em mostrar a diferença entre o uso de “0” e “9” para especificar o formato dos dígitos.

O dígito “9” como formatador aceitará espaços em branco ou dígitos iniciais “ausentes”. O dígito “0” como formatador não aceitará espaços em branco ou zeros à esquerda ausentes.

-- All of the following convert the input to the number 12,345.67.
SELECT TO_NUMBER('012,345.67', '999,999.99', 8, 2);
SELECT TO_NUMBER('12,345.67', '999,999.99', 8, 2);
SELECT TO_NUMBER(' 12,345.67', '999,999.99', 8, 2);
-- The first of the following works, but the others will not convert.
-- (They are not supposed to convert, so "failure" is correct.)
SELECT TO_NUMBER('012,345.67', '000,000.00', 8, 2);
SELECT TO_NUMBER('12,345.67', '000,000.00', 8, 2);
SELECT TO_NUMBER(' 12,345.67', '000,000.00', 8, 2);

Copy

Isto mostra como aceitar um dos dois formatos numéricos (-### ou ###-).

-- Create the table and insert data.
create table format1 (v varchar, i integer);
insert into format1 (v) values ('-101');
insert into format1 (v) values ('102-');
insert into format1 (v) values ('103');

-- Try to convert varchar to integer without a
-- format model.  This fails (as expected)
-- with a message similar to:
--    "Numeric value '102-' is not recognized"
update format1 set i = TO_NUMBER(v);

-- Now try again with a format specifier that allows the minus sign
-- to be at either the beginning or the end of the number.
-- Note the use of the vertical bar ("|") to indicate that
-- either format is acceptable.
update format1 set i = TO_NUMBER(v, 'MI999|999MI');
select i from format1;

Copy