Strings.Format(Object, String) Método

  • Referência

Definição

Namespace:
Microsoft.VisualBasic
Assembly:
Microsoft.VisualBasic.Core.dll
Assembly:
Microsoft.VisualBasic.dll
Origem:
Strings.vb
Origem:
Strings.vb
Origem:
Strings.vb

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

public static string Format (object? Expression, string? Style = "");
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

Necessário. Qualquer expressão válida.

Style
String

Opcional. Um formato válido nomeado ou definido pelo usuário String expressão.

Retornos

String

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

Exemplos

Este exemplo mostra vários usos da função Format para formatar valores usando formatos String e formatos definidos pelo usuário. Para o separador de data (/), o separador de hora (:) e os indicadores AM/PM (t e tt), a saída formatada real exibida pelo 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 de tempo curto e o formato de data curta da localidade do código são usados.

Nota

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 método String.Format também fornece funcionalidade semelhante.

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

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

Formatos diferentes para valores numéricos diferentes

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

Se você usar Este é o resultado
Somente uma seção A expressão de formato se aplica a todos os valores.
Duas seções A primeira seção se aplica a valores positivos e zeros; o segundo se aplica a valores negativos.
Três seções A primeira seção se aplica a valores positivos, a segunda aplica-se a valores negativos e a terceira aplica-se 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 argumento Style da função Format 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 eles, 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 for zero.

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

Formatos numéricos predefinidos

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

Nome do formato Descrição
General Number, Gou g Exibe o número sem nenhum separador de mil.

Por exemplo, Format(&H3FA, "g") retorna 1018.
Currency, Cou c Exibe o número com o separador de mil, 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, Fou 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, Nou n Exibe o número com o separador de mil, 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 (%) acrescentado imediatamente à direita; sempre exibe dois dígitos à direita do separador decimal.

Por exemplo, Format(0.4744, "Percent") retorna 47.44%.
Pou p Exibe o número com o separador de milésimos multiplicado por 100 com um sinal percentual (%) acrescentado à 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.
Eou e Usa notação científica padrão, fornecendo seis dígitos significativos.

Por exemplo, Format(1234567, "e") retorna 1.234567e+006.
Dou d Exibe o número como uma cadeia de caracteres que contém o valor do número no formato Decimal (base 10). Essa opção tem suporte apenas para tipos integrais (Byte, Short, Integer, Long).

Por exemplo, Format(&H7F, "d") retorna 127.
Xou x Exibe o número como uma cadeia de caracteres que contém o valor do número no 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 Exibe No se o número for 0; caso contrário, exibe Yes.

Por exemplo, Format(0, "Yes/No") retorna No.
True/False Exibe False se o número for 0; caso contrário, exibe True.

Por exemplo, Format(1, "True/False") retorna True.
On/Off Exibe Off se o número for 0; caso contrário, exibe On.

Por exemplo, Format(1, "On/Off") retorna On.

Notas do desenvolvedor de dispositivo inteligente

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

formatos numéricos User-Defined

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 argumento Style para a função Format:

Personagem Descrição
Nenhum Exibe o número sem formatação.
(0) Espaço reservado para dígitos. 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 ambos os lados 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, arredonda o número para quantas casas decimais houver 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 para dígitos. 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, a exibirá; caso contrário, não exibirá nada nessa posição.

Esse símbolo funciona como o espaço reservado de 0 dígito, exceto que zeros à esquerda e à direita não serão exibidos se o número tiver menos dígitos do que há # caracteres em ambos os lados do separador decimal na expressão de formato.
(.) Espaço reservado 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 deste símbolo; números menores que 1 começam com um separador decimal. Para exibir 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 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ê deve usar o período como espaço reservado decimal em seus formatos mesmo se estiver em uma localidade que use uma vírgula como um espaço reservado decimal. A cadeia de caracteres formatada será exibida no formato correto para a localidade.
(%) Percentual de espaço reservado. Multiplica a expressão por 100. O caractere percentual (%) é inserido na posição em que aparece na cadeia de caracteres de formato.
(,) Separador de mil. O separador de mil separa milhares de centenas dentro de um número que tem quatro ou mais lugares à esquerda do separador decimal. O uso padrão do separador de mil será especificado se o formato contiver um separador de mil entre os espaços reservados de dígito (0 ou #).

Um separador de mil imediatamente à esquerda do separador decimal (se uma decimal é especificada ou não) 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 milhares separadores adjacentes nessa escala de posição 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 da posição mais à direita na cadeia de caracteres são tratados simplesmente como especificando o uso de um separador de mil. Em algumas localidades, um período é usado como um separador de mil. O caractere real usado como o separador de mil na saída formatada depende do Formato de Número reconhecido pelo sistema. Portanto, você deve usar a vírgula como o separador de mil em seus formatos mesmo se estiver em uma localidade que use um período como um separador de mil. A cadeia de caracteres formatada será exibida no formato correto para a localidade.

Por exemplo, considere as três seguintes cadeias de caracteres 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 tempo. Em algumas localidades, outros caracteres podem ser usados para representar o separador de tempo. O separador de tempo separa horas, minutos e segundos quando os valores de tempo são formatados. O caractere real usado como separador de tempo 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 em que os valores de data são formatados. O caractere real usado como 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 em 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. Você também deve incluir 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 caracteres de formato. Para exibir um caractere diferente de um dos listados, preceda-o com uma barra invertida (\) ou coloque-o entre aspas duplas (" ").
(\) Exibe o próximo caractere na cadeia de caracteres de formato. Para exibir um caractere que tem 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, d, h, m, n, p, q, s, t, w, y, /e :), os caracteres de formatação numérica (#, 0, %, E, e, vírgula, e ponto final) e os caracteres de formatação de cadeia de caracteres (@, &, <, >e !).
("``ABC``") Exibe a cadeia de caracteres dentro das 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 argumento Style da função Format; 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 de formato de data e hora predefinidos. Eles podem ser usados pelo nome como o argumento de estilo para a função Format:

Nome do Formato Descrição
General Dateou 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 do aplicativo.
Long Date, Medium Dateou D Exibe uma data de acordo com o formato de data longa da cultura atual. Por exemplo, Wednesday, March 12, 2008.
Short Dateou d Exibe uma data usando o formato de data curta da cultura atual. Por exemplo, 3/12/2008.

O caractere d exibe o dia em um formato de data definido pelo usuário.
Long Time, Medium Timeou T Exibe um tempo usando o formato de longo tempo da cultura atual; normalmente inclui horas, minutos, segundos. Por exemplo, 11:07:31 AM.
Short Time ou t Exibe um tempo usando o formato de tempo curto da cultura atual. Por exemplo, 11:07 AM.

O caractere t exibe valores AM ou PM para localidades que usam um relógio de 12 horas em um formato de hora definido pelo usuário.
f Exibe a data longa e o curto período de acordo com o formato da cultura atual. Por exemplo, Wednesday, March 12, 2008 11:07 AM.
F Exibe a data longa e o tempo longo de acordo com o formato da cultura atual. Por exemplo, Wednesday, March 12, 2008 11:07:31 AM.
g Exibe a data curta e o curto período 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 caractere M exibe o mês em um formato de data definido pelo usuário. O caractere m exibe os minutos em um formato de tempo definido pelo usuário.
R, r Formata a data de acordo com a propriedade RFC1123Pattern. Por exemplo, Wed, 12 Mar 2008 11:07:31 GMT. A data formatada não ajusta o valor da data e hora. Você deve ajustar o valor de Data/Hora para GMT antes de chamar a função Format.
s Formata a data e a hora como um índice classificável. Por exemplo, 2008-03-12T11:07:31.

O caractere s exibe os segundos em um formato de tempo definido pelo usuário.
u Formata a data e a hora como um índice classificável GMT. Por exemplo, 2008-03-12 11:07:31Z.
U Formata a data e a hora com a data longa e a hora longa 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 caracteres Y 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 How Culture Affects Strings in Visual Basic.

User-Defined formatos de data/hora

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.

Personagem Descrição
(:) Separador de tempo. Em algumas localidades, outros caracteres podem ser usados para representar o separador de tempo. O separador de tempo separa horas, minutos e segundos quando os valores de tempo são formatados. O caractere real usado como separador de tempo 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 em que os valores de data são formatados. O caractere real usado como 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 levar em conta as letras à direita. Também usado para indicar que um formato de letra única é lido como um formato definido pelo usuário. Veja o que se segue para obter detalhes adicionais.
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 símbolos f 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 A maiúscula para qualquer hora antes do meio-dia; exibe uma P maiúscula para qualquer hora entre meio-dia e 23h59. Use %t se esse for o único caractere no formato numérico definido pelo usuário.
tt Para localidades que usam um relógio de 12 horas, exibe uma AM maiúscula com qualquer hora antes do meio-dia; exibe uma PM maiúscula com qualquer hora entre meio-dia e 23h59.

Para localidades que usam um relógio de 24 horas, não exibe nada.
y Exibe o número do ano (0-9) sem zeros à esquerda. Use %y se esse for o único caractere no formato numérico definido pelo usuário.
yy Exibe o ano em formato numérico de dois dígitos com um zero à esquerda, se aplicável.
yyy Exibe o ano em formato numérico de quatro dígitos.
yyyy Exibe o ano em 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:

Formato Exibe
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

Notas 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 caractere de formato f retornará 0 quando executado nesse dispositivo.

Aplica-se a

Confira também