Strings.Format(Object, String) Método

Definição

Namespace:

Microsoft.VisualBasic

Assembly:

Microsoft.VisualBasic.Core.dll

Origem:

Strings.vb

Retorna uma cadeia de caracteres formatada de acordo com as instruções contidas em uma expressão String de formato.

public static string Format (object? Expression, string? Style = "");

static member Format : obj * string -> string

Public Function Format (Expression As Object, Optional Style As String = "") As String

Parâmetros

Expression

Object

Obrigatórios. Qualquer expressão válida.

Style

String

Opcional. Uma expressão válida String de formato nomeada ou definida pelo usuário.

Retornos

String

Uma cadeia de caracteres formatada de acordo com as instruções contidas em uma expressão String de formato.

Exemplos

Este exemplo mostra vários usos da função Format para formatar valores usando os formatos String e os formatos definidos pelo usuário. Para o separador de data (/), separador de hora (:) e indicadores AM/PM (t e tt), a saída formatada real exibida pelo seu sistema depende das configurações de localidade que o código está usando. Quando horas e datas são exibidas no ambiente de desenvolvimento, o formato abreviado de tempo e o formato abreviado de data do local do código são usados.

Observação

Para localidades que usam um relógio de 24 horas, os indicadores AM/PM (t e tt) não exibem nada.

Dim testDateTime As Date = #1/27/2001 5:04:23 PM#
Dim testStr As String
' Returns current system time in the system-defined long time format.
testStr = Format(Now(), "Long Time")
' Returns current system date in the system-defined long date format.
testStr = Format(Now(), "Long Date")
' Also returns current system date in the system-defined long date 
' format, using the single letter code for the format.
testStr = Format(Now(), "D")

' Returns the value of testDateTime in user-defined date/time formats.
' Returns "5:4:23".
testStr = Format(testDateTime, "h:m:s")
' Returns "05:04:23 PM".
testStr = Format(testDateTime, "hh:mm:ss tt")
' Returns "Saturday, Jan 27 2001".
testStr = Format(testDateTime, "dddd, MMM d yyyy")
' Returns "17:04:23".
testStr = Format(testDateTime, "HH:mm:ss")
' Returns "23".
testStr = Format(23)

' User-defined numeric formats.
' Returns "5,459.40".
testStr = Format(5459.4, "##,##0.00")
' Returns "334.90".
testStr = Format(334.9, "###0.00")
' Returns "500.00%".
testStr = Format(5, "0.00%")

Comentários

O String.Format método também fornece funcionalidade semelhante.

Se você estiver formatando uma cadeia de caracteres numérica não localizada, deverá usar um formato numérico definido pelo usuário para garantir a aparência desejada.

Se você tentar formatar um número sem especificar Style, a Format função fornecerá funcionalidade semelhante à Str função, embora esteja ciente internacionalmente. No entanto, números positivos formatados como cadeias de caracteres usando a Format função não incluem um espaço à esquerda reservado para o sinal do valor; aqueles convertidos usando a Str função mantêm o espaço à esquerda.

Formatos diferentes para valores numéricos diferentes

Uma expressão de formato definido pelo usuário para números pode ter de uma a três seções separadas por ponto-e-vírgula. Se o Style argumento da Format função contiver um dos formatos numéricos predefinidos, apenas uma seção será permitida.

Se você usar	Este será o resultado
Apenas uma seção	A expressão de formato é aplicada a todos os valores.
Duas seções	A primeira seção se aplica a valores positivos e zeros; a segunda se aplica a valores negativos.
Trê seções	A primeira seção se aplica a valores positivos, a segunda se aplica a valores negativos e a terceira se aplica a zeros.

O exemplo a seguir tem duas seções: a primeira define o formato para valores positivos e zeros; a segunda seção define o formato para valores negativos. Como o Style argumento da Format função usa uma cadeia de caracteres, ele é colocado entre aspas.

Dim style1 As String = "$#,##0;($#,##0)"

Se você incluir ponto e vírgula sem nada entre ele, a seção ausente será impressa usando o formato do valor positivo. Por exemplo, o formato a seguir exibe valores positivos e negativos usando o formato na primeira seção e exibe Zero se o valor é zero.

Dim style2 As String = "$#,##0;;\Z\e\r\o"

Formatos numéricos predefinidos

A tabela a seguir identifica os nomes de formatos numéricos predefinidos. Eles podem ser usados pelo nome como o Style argumento para a Format função:

Nome do formato	Descrição
General Number, G ou g	Exibe o número sem separador de milhar. Por exemplo, Format(&H3FA, "g") retorna 1018.
Currency, C ou c	Exibe o número com separador de milhar, se apropriado; exibe dois dígitos à direita do separador decimal. A saída é baseada nas configurações de localidade do sistema. Por exemplo, Format(1234567, "c") retorna $1,234,567.00.
Fixed, F ou f	Exibe pelo menos um dígito à esquerda e dois dígitos à direita do separador decimal. Por exemplo, Format(1234567, "f") retorna 1234567.00.
Standard, N ou n	Exibe o número com separador de milhar, pelo menos um dígito à esquerda e dois dígitos à direita do separador decimal. Por exemplo, Format(1234567, "n") retorna 1,234,567.00.
Percent	Exibe o número multiplicado por 100 com um sinal de porcentagem (%) imediatamente à direita; sempre exibe dois dígitos à direita do separador decimal. Por exemplo, Format(0.4744, "Percent") retorna 47.44%.
P ou p	Exibe o número com separador de milhar multiplicado por 100 com um símbolo de porcentagem (%) anexado à direita e separado por um único espaço; sempre exibe dois dígitos à direita do separador decimal. Por exemplo, Format(0.80345, "p") retorna 80.35 %.
Scientific	Usa notação científica padrão, fornecendo dois dígitos significativos. Por exemplo, Format(1234567, "Scientific") retorna 1.23E+06.
E ou e	Usa a notação científica padrão, fornecendo seis dígitos significativos. Por exemplo, Format(1234567, "e") retorna 1.234567e+006.
D ou d	Exibe o número como uma cadeia de caracteres que contém o valor do número em formato decimal (base 10). Essa opção tem suporte apenas para tipos integrais (Byte, Short, Integer, Long). Por exemplo, Format(&H7F, "d") retorna 127.
X ou x	Exibe o número como uma cadeia de caracteres que contém o valor do número em formato hexadecimal (base 16). Essa opção tem suporte apenas para tipos integrais (Byte, Short, Integer, Long). Por exemplo, Format(127, "x") retorna 7f.
Yes/No	No Exibe se o número é 0; caso contrário, exibe Yes. Por exemplo, Format(0, "Yes/No") retorna No.
True/False	False Exibe se o número é 0; caso contrário, exibe True. Por exemplo, Format(1, "True/False") retorna True.
On/Off	Off Exibe se o número é 0; caso contrário, exibe On. Por exemplo, Format(1, "On/Off") retorna On.

Anotações do desenvolvedor de dispositivo inteligente

Não há suporte para os Yes/Noformatos , True/Falsee On/Off .

Formatos numéricos definidos pelo usuário

A tabela a seguir identifica os caracteres que você pode usar para criar formatos de número definidos pelo usuário. Eles podem ser usados para criar o Style argumento para a Format função:

Caractere	Descrição
Nenhum	Exibe o número sem nenhuma formatação.
(0)	Espaço reservado de dígito. Exibe um dígito ou um zero. Se a expressão tiver um dígito na posição em que o zero aparece na cadeia de caracteres de formato, exiba-a; caso contrário, exibe um zero nessa posição. Se o número tiver menos dígitos do que zeros (em qualquer lado do decimal) na expressão de formato, exibirá zeros à esquerda ou à direita. Se o número tiver mais dígitos à direita do separador decimal do que zeros à direita do separador decimal na expressão de formato, arredondará o número para a mesma quantidade de casas decimais que há de zeros. Se o número tiver mais dígitos à esquerda do separador decimal do que zeros à esquerda do separador decimal na expressão de formato, exibirá os dígitos extras sem modificação.
(#)	Espaço reservado de dígito. Exibe um dígito ou nada. Se a expressão tiver um dígito na posição em que o # caractere aparece na cadeia de caracteres de formato, exibe-a; caso contrário, não exibe nada nessa posição. Esse símbolo funciona como o 0 espaço reservado para dígitos, exceto que zeros à esquerda e à direita não serão exibidos se o número tiver menos dígitos do que caracteres # em ambos os lados do separador decimal na expressão de formato.
(.)	Espaço reservado de decimal. O espaço reservado decimal determina quantos dígitos são exibidos à esquerda e à direita do separador decimal. Se a expressão de formato contiver apenas # caracteres à esquerda desse símbolo; números menores que 1 começarão com um separador decimal. Para mostrar um zero à esquerda exibido com números fracionários, use zero como o espaço reservado do primeiro dígito à esquerda do separador decimal. Em algumas localidades, uma vírgula é usada como o separador decimal. O caractere real usado como um espaço reservado decimal na saída formatada depende do formato de número reconhecido pelo sistema. Portanto, você deverá usar o ponto como o espaço reservado decimal nos formatos, mesmo se estiver em uma localidade que usa uma vírgula como um espaço reservado decimal. A cadeia de caracteres formatada será exibida no formato correto para a localidade.
(%)	Espaço reservado de percentual. Multiplica a expressão por 100. O caractere de porcentagem (%) é inserido na posição em que ele aparece na cadeia de caracteres de formato.
(,)	Separador de milhar. O separador de milhar separa milhares de centenas em um número que tem quatro ou mais casas à esquerda do separador decimal. O uso padrão do separador de milhar será especificado se o formato contiver um separador de milhar entre espaços reservados de dígito (0 ou #). Um separador de milhar imediatamente à esquerda do separador decimal (se um decimal é especificado ou como o caractere mais à direita na cadeia de caracteres significa "dimensionar o número dividindo-o por 1.000, arredondando conforme necessário". Números menores que 1.000, mas maiores ou iguais a 500, são exibidos como 1e números menores que 500 são exibidos como 0. Dois separadores de milhar adjacentes nessa posição são dimensionados por um fator de 1 milhão e um fator adicional de 1.000 para cada separador adicional. Vários separadores em qualquer posição que não seja imediatamente à esquerda do separador decimal ou na posição à extrema direita na cadeia de caracteres são tratados apenas como a especificação do uso de um separador de milhar. Em algumas localidades, um ponto é usado como um separador de milhar. O caractere real usado como o separador de milhar na saída formatada depende do Formato de Número reconhecido pelo seu sistema. Portanto, você deverá usar a vírgula como o separador de milhar nos formatos, mesmo se estiver em uma localidade que usa um ponto como o separador de milhar. A cadeia de caracteres formatada será exibida no formato correto para a localidade. Por exemplo, considere as três seguintes cadeias de formato: - "#,0.", que usa o separador de milhares para formatar o número 100 milhões como a cadeia de caracteres "100.000.000". - "#0,.", que usa o dimensionamento por um fator de mil para formatar o número 100 milhões como a cadeia de caracteres "100000". - "#,0,.", que usa o separador e o dimensionamento de milhares para formatar o número 100 milhões como a cadeia de caracteres "100.000".
(:)	Separador de hora. Em algumas localidades, outros caracteres podem ser usados para representar o separador de hora. O separador de horas separa hora, minutos e segundos quando os valores de hora são formatados. O caractere real usado como o separador de hora na saída formatada é determinado pelas configurações do sistema.
(/)	Separador de data. Em algumas localidades, outros caracteres podem ser usados para representar o separador de data. O separador de data separa o dia, o mês e o ano quando os valores de data são formatados. O caractere real usado como o separador de data na saída formatada é determinado pelas configurações do sistema.
(E-``E+``e-``e+)	Formato científico. Se a expressão de formato contiver pelo menos um espaço reservado de dígito (0 ou #) à esquerda de E-, E+, e-ou e+, o número será exibido no formato científico e E ou e será inserido entre o número e seu expoente. O número de espaços reservados de dígito à esquerda determina o número de dígitos no expoente. Use E- ou e- para colocar um sinal de subtração ao lado de expoentes negativos. Use E+ ou e+ para colocar um sinal de subtração ao lado de expoentes negativos e um sinal de adição ao lado de expoentes positivos. Inclua também espaços reservados de dígito à direita desse símbolo para obter a formatação correta.
-+$ ( )	Caracteres literais. Esses caracteres são exibidos exatamente como digitados na cadeia de formato. Para exibir um caractere diferente dos listados, preceda-o com uma barra invertida (\) ou coloque-o entre aspas duplas (" ").
(\)	Exibe o próximo caractere da cadeia de caracteres de formato. Para exibir um caractere que tenha um significado especial como um caractere literal, preceda-o com uma barra invertida (\). A barra invertida em si não é exibida. Usar uma barra invertida é o mesmo que colocar o próximo caractere entre aspas duplas. Para exibir uma barra invertida, use duas barras invertidas (\\). Exemplos de caracteres que não podem ser exibidos como caracteres literais são os caracteres de formatação de data e hora (a, c, , hd, m, n, qw/sypte :), os caracteres de formatação numérica (#, 0, %, E, e, vírgula e ponto) e os caracteres de formatação de cadeia de caracteres (@, &, <, >e ).!
("``ABC``")	Exibe a cadeia de caracteres entre aspas duplas (" "). Para incluir uma cadeia de caracteres no argumento de estilo de dentro do código, você deve usar Chr(34) para colocar o texto (34 é o código de caractere para uma aspa (")).

Exemplo de código herdado

A tabela a seguir contém algumas expressões de formato de exemplo para números. (Todos esses exemplos pressupõem que a configuração de localidade do sistema é inglês-EUA) A primeira coluna contém as cadeias de caracteres de formato para o Style argumento da Format função; as outras colunas contêm a saída resultante se os dados formatados tiverem o valor fornecido nos títulos de coluna.

Formato (Style)	"5" formatado como	"-5" formatado como	"0,5" formatado como
Zero-length string ("")	5	-5	0.5
0	5	-5	1
0.00	5.00	-5.00	0.50
#,##0	5	-5	1
$#,##0;($#,##0)	$5	($5)	$1
$#,##0.00;($#,##0.00)	$5.00	($5.00)	$0.50
0%	500%	-500%	50%
0.00%	500.00%	-500.00%	50.00%
0.00E+00	5.00E+00	-5.00E+00	5.00E-01
0.00E-00	5.00E00	-5.00E00	5.00E-01

Formatos de data/hora predefinidos

A tabela a seguir identifica os nomes dos formatos de data e hora predefinidos. Eles podem ser usados pelo nome como o argumento de estilo para a Format função:

Nome do formato	Descrição
General Date ou G	Exibe uma data e/ou hora. Por exemplo, 3/12/2008 11:07:31 AM. A exibição de data é determinada pelo valor de cultura atual de seu aplicativo.
Long Date, Medium Date ou D	Exibe uma data de acordo com o formato de data longa de sua cultura atual. Por exemplo, Wednesday, March 12, 2008.
Short Date ou d	Exibe uma data usando o formato de data curta de sua cultura atual. Por exemplo, 3/12/2008. O d caractere exibe o dia em um formato de data definido pelo usuário.
Long Time, Medium Time ou T	Exibe uma hora usando o formato de hora longo da cultura atual. Normalmente, inclui horas, minutos, segundos. Por exemplo, 11:07:31 AM.
Short Time ou t	Exibe uma hora usando o formato de hora abreviado da cultura atual. Por exemplo, 11:07 AM. O t caractere exibe AM ou PM valores para localidades que usam um relógio de 12 horas em um formato de hora definido pelo usuário.
f	Exibe uma data longa e uma hora curta de acordo com o formato da cultura atual. Por exemplo, Wednesday, March 12, 2008 11:07 AM.
F	Exibe uma data longa e uma hora longa de acordo com o formato da cultura atual. Por exemplo, Wednesday, March 12, 2008 11:07:31 AM.
g	Exibe data e hora curtas de acordo com o formato da cultura atual. Por exemplo, 3/12/2008 11:07 AM.
M, m	Exibe o mês e o dia de uma data. Por exemplo, March 12. O M caractere exibe o mês em um formato de data definido pelo usuário. O m caractere exibe os minutos em um formato de hora definido pelo usuário.
R, r	Formata a data de acordo com a RFC1123Pattern propriedade . Por exemplo, Wed, 12 Mar 2008 11:07:31 GMT. A data formatada não ajusta o valor de data e hora. Você deve ajustar o valor de Data/Hora para GMT antes de chamar a Format função.
s	Formata a data e a hora como um índice classificável. Por exemplo, 2008-03-12T11:07:31. O s caractere exibe os segundos em um formato de tempo definido pelo usuário.
u	Formata a data e a hora como um índice GMT classificável. Por exemplo, 2008-03-12 11:07:31Z.
U	Formata data e hora longas como GMT. Por exemplo, Wednesday, March 12, 2008 6:07:31 PM.
Y, y	Formata a data como o ano e o mês. Por exemplo, March, 2008. Os Y caracteres e y exibem o ano em um formato de data definido pelo usuário.

Para obter mais informações sobre as informações de cultura atuais do aplicativo, consulte Como a cultura afeta cadeias de caracteres no Visual Basic.

Formatos de data/hora definidos pelo usuário

A tabela a seguir mostra os caracteres que você pode usar para criar formatos de data/hora definidos pelo usuário. Ao contrário das versões anteriores do Visual Basic, esses caracteres de formato diferenciam maiúsculas de minúsculas.

Caractere	Descrição
(:)	Separador de hora. Em algumas localidades, outros caracteres podem ser usados para representar o separador de hora. O separador de horas separa hora, minutos e segundos quando os valores de hora são formatados. O caractere real que é usado como o separador de hora na saída formatada é determinado pelo valor de cultura atual do aplicativo.
(/)	Separador de data. Em algumas localidades, outros caracteres podem ser usados para representar o separador de data. O separador de data separa o dia, o mês e o ano quando os valores de data são formatados. O caractere real que é usado como o separador de data na saída formatada é determinado pela cultura atual do aplicativo.
(%)	Usado para indicar que o caractere a seguir deve ser lido como um formato de letra única sem considerar nenhuma letra à direita. Também usado para indicar que um formato de letra única é lido como um formato definido pelo usuário. Confira o conteúdo a seguir para obter mais detalhes.
d	Exibe o dia como um número sem um zero à esquerda (por exemplo, 1). Use %d se esse for o único caractere no formato numérico definido pelo usuário.
dd	Exibe o dia como um número com um zero à esquerda (por exemplo, 01).
ddd	Exibe o dia como uma abreviação (por exemplo, Sun).
dddd	Exibe o dia como um nome completo (por exemplo, Sunday).
M	Exibe o mês como um número sem um zero à esquerda (por exemplo, janeiro é representado como 1). Use %M se esse for o único caractere no formato numérico definido pelo usuário.
MM	Exibe o mês como um número com um zero à esquerda (por exemplo, 01/12/01).
MMM	Exibe o mês como uma abreviação (por exemplo, Jan).
MMMM	Exibe o mês como um nome de mês completo (por exemplo, January).
gg	Exibe a cadeia de caracteres de período/era (por exemplo, A.D.).
h	Exibe a hora como um número sem zeros à esquerda usando o relógio de 12 horas (por exemplo, 1:15:15 PM). Use %h se esse for o único caractere no formato numérico definido pelo usuário.
hh	Exibe a hora como um número com zeros à esquerda usando o relógio de 12 horas (por exemplo, 01:15:15 PM).
H	Exibe a hora como um número sem zeros à esquerda usando o relógio de 24 horas (por exemplo, 1:15:15). Use %H se esse for o único caractere no formato numérico definido pelo usuário.
HH	Exibe a hora como um número com zeros à esquerda usando o relógio de 24 horas (por exemplo, 01:15:15).
m	Exibe o minuto como um número sem zeros à esquerda (por exemplo, 12:1:15). Use %m se esse for o único caractere no formato numérico definido pelo usuário.
mm	Exibe o minuto como um número com zeros à esquerda (por exemplo, 12:01:15).
s	Exibe o segundo como um número sem zeros à esquerda (por exemplo, 12:15:5). Use %s se esse for o único caractere no formato numérico definido pelo usuário.
ss	Exibe o segundo como um número com zeros à esquerda (por exemplo, 12:15:05).
f	Exibe frações de segundos. Por exemplo ff , exibe centésimos de segundos, enquanto ffff exibe dez milésimos de segundos. Você pode usar até sete f símbolos no formato definido pelo usuário. Use %f se esse for o único caractere no formato numérico definido pelo usuário.
t	Usa o relógio de 12 horas e exibe uma maiúscula A para qualquer hora antes do meio-dia; exibe uma maiúscula P para qualquer hora entre meio-dia e 23h59. Use %t se esse for o único caractere em seu formato numérico definido pelo usuário.
tt	Para localidades que usam um relógio de 12 horas, exibe uma maiúscula AM com qualquer hora antes do meio-dia; exibe uma maiúscula PM com qualquer hora entre meio-dia e 23h59. Para localidades que usam o formato de 24 horas, não exibe nada.
y	Exibe o número do ano (0-9) sem um zero à esquerda. Use %y se esse for o único caractere no formato numérico definido pelo usuário.
yy	Exibe o ano no formato numérico de dois dígitos com um zero à esquerda, se aplicável.
yyy	Exibe o ano no formato numérico de quatro dígitos.
yyyy	Exibe o ano no formato numérico de quatro dígitos.
z	Exibe o deslocamento de fuso horário sem um zero à esquerda (por exemplo, -8). Use %z se esse for o único caractere no formato numérico definido pelo usuário.
zz	Exibe o deslocamento de fuso horário com um zero à esquerda (por exemplo, -08)
zzz	Exibe o deslocamento de fuso horário completo (por exemplo, -08:00)

Exemplo de código herdado

Veja a seguir exemplos de formatos de data e hora definidos pelo usuário para December 7, 1958, 8:50 PM, 35 seconds:

Formatar	Telas
M/d/yy	12/7/58
d-MMM	7-Dec
d-MMMM-yy	7-December-58
d MMMM	7 December
MMMM yy	December 58
hh:mm tt	08:50 PM
h:mm:ss t	8:50:35 P
H:mm	20:50
H:mm:ss	20:50:35
M/d/yyyy H:mm	12/7/1958 20:50

Anotações do desenvolvedor de dispositivo inteligente

A resolução de tempo mínimo para um dispositivo é determinada pelo fabricante do dispositivo. Se a resolução de tempo para o dispositivo for grosseira o suficiente, o f caractere de formato retornará 0 quando executado nesse dispositivo.

Confira também

• Format(String, Object)
• Str(Object)
• Resumo de manipulação da cadeia de caracteres