String.Format String.Format String.Format String.Format Method

Definição

Converte o valor de objetos em cadeias de caracteres com base nos formatos especificados e os insere em outra cadeia de caracteres.Converts the value of objects to strings based on the formats specified and inserts them into another string.

Se você não estiver familiarizado com o método String.Format, consulte a seção Introdução ao método String.Format para obter uma visão geral rápida.If you are new to the String.Format method, see the Get started with the String.Format method section for a quick overview.

Consulte a seção Comentários para ver a documentação geral do método String.Format.See the Remarks section for general documentation for the String.Format method.

Sobrecargas

Format(String, Object) Format(String, Object) Format(String, Object) Format(String, Object)

Substitui um ou mais itens de formato em uma cadeia de caracteres pela representação de cadeia de caracteres de um objeto especificado.Replaces one or more format items in a string with the string representation of a specified object.

Format(String, Object[]) Format(String, Object[]) Format(String, Object[]) Format(String, Object[])

Substitui o item de formato em uma cadeia de caracteres especificada pela representação de cadeia de caracteres de um objeto correspondente em uma matriz especificada.Replaces the format item in a specified string with the string representation of a corresponding object in a specified array.

Format(IFormatProvider, String, Object) Format(IFormatProvider, String, Object) Format(IFormatProvider, String, Object) Format(IFormatProvider, String, Object)

Substitui o item ou itens de formato em uma cadeia de caracteres especificada pela representação de cadeia de caracteres do objeto correspondente.Replaces the format item or items in a specified string with the string representation of the corresponding object. Um parâmetro fornece informações de formatação específicas da cultura.A parameter supplies culture-specific formatting information.

Format(IFormatProvider, String, Object[]) Format(IFormatProvider, String, Object[]) Format(IFormatProvider, String, Object[]) Format(IFormatProvider, String, Object[])

Substitui os itens de formato em uma cadeia de caracteres pelas representações cadeia de caracteres de objetos correspondentes em uma matriz especificada.Replaces the format items in a string with the string representations of corresponding objects in a specified array. Um parâmetro fornece informações de formatação específicas da cultura.A parameter supplies culture-specific formatting information.

Format(String, Object, Object) Format(String, Object, Object) Format(String, Object, Object) Format(String, Object, Object)

Substitui os itens de formato em uma cadeia de caracteres pela representação de cadeia de caracteres de dois objetos especificados.Replaces the format items in a string with the string representation of two specified objects.

Format(IFormatProvider, String, Object, Object) Format(IFormatProvider, String, Object, Object) Format(IFormatProvider, String, Object, Object) Format(IFormatProvider, String, Object, Object)

Substitui os itens de formato em uma cadeia de caracteres pela representação de cadeia de caracteres de dois objetos especificados.Replaces the format items in a string with the string representation of two specified objects. Um parâmetro fornece informações de formatação específicas da cultura.A parameter supplies culture-specific formatting information.

Format(String, Object, Object, Object) Format(String, Object, Object, Object) Format(String, Object, Object, Object) Format(String, Object, Object, Object)

Substitui os itens de formato em uma cadeia de caracteres pela representação de cadeia de caracteres de três objetos especificados.Replaces the format items in a string with the string representation of three specified objects.

Format(IFormatProvider, String, Object, Object, Object) Format(IFormatProvider, String, Object, Object, Object) Format(IFormatProvider, String, Object, Object, Object) Format(IFormatProvider, String, Object, Object, Object)

Substitui os itens de formato em uma cadeia de caracteres pela representação de cadeia de caracteres de três objetos especificados.Replaces the format items in a string with the string representation of three specified objects. Um parâmetro fornece informações de formatação específicas da cultura.An parameter supplies culture-specific formatting information.

Exemplos

Ver vários exemplos que chamam a Format método são intercalados por meio de comentários seção deste artigo.Numerous examples that call the Format method are interspersed through the Remarks section of this article.

Observação

Os exemplos de C# neste artigo são executados no executador de código embutido Try.NET e no playground.The C# examples in this article run in the Try.NET inline code runner and playground. Clique no botão Executar para executar um exemplo em uma janela interativa.Select the Run button to run an example in an interactive window. Ao executar o código, é possível modificá-lo e executar o código modificado clicando em Executar novamente.Once you execute the code, you can modify it and run the modified code by selecting Run again. O código modificado será executado na janela interativa ou, se a compilação falhar, a janela interativa exibirá todos as mensagens de erro do compilador C#.The modified code either runs in the interactive window or, if compilation fails, the interactive window displays all C# compiler error messages.

Você também pode baixar um conjunto completo de String.Format exemplos, que são incluídos uma projeto .NET Core 2.0 para c# e uma projeto .NET Core 2.0 para o Visual Basic, da dotnet / repositório GitHub de exemplos.You can also download a complete set of String.Format examples, which are included a .NET Core 2.0 project for C# and a .NET Core 2.0 project for Visual Basic, from the dotnet/samples GitHub repository.

Seguem alguns exemplos incluídos neste artigo:The following are some of the examples included in the article:

Criar uma cadeia de caracteres de formatoCreate a format string

Inserindo uma cadeia de caracteresInserting a string
O item de formatoThe format item
Itens de formato que têm o mesmo índiceFormat items that have the same index

Controlar a saída formatadaControl formatted output

Controlando a formataçãoControlling formatting
Controlar o espaçamentoControlling spacing
Controlar o alinhamentoControlling alignment
Controlar o número de dígitos integraisControlling the number of integral digits
Controlando o número de dígitos após o separador decimalControlling the number of digits after the decimal separator
Incluindo chaves literais em uma cadeia de caracteres de resultadoIncluding literal braces in a result string

Tornar sensível à cultura de cadeias de caracteres de formatoMake format strings culture-sensitive

Formatação sensível à culturaCulture-sensitive formatting

Personalizar a operação de formataçãoCustomize the formatting operation

Uma operação de formatação personalizadaA custom formatting operation
Um provedor de interceptação e formatador de algarismo romanoAn intercept provider and Roman numeral formatter

Comentários

Importante

Em vez de chamar o método String.Format ou usar cadeias de caracteres de formato de composição, é possível usar cadeias de caracteres interpoladas quando a linguagem é compatível com eles.Instead of calling the String.Format method or using composite format strings, you can use interpolated strings if your language supports them. Uma cadeia de caracteres interpolada é uma cadeia de caracteres que contém expressões interpoladas.An interpolated string is a string that contains interpolated expressions. Cada expressão interpolada é resolvida com o valor da expressão e incluída na cadeia de caracteres resultante quando a cadeia de caracteres é atribuída.Each interpolated expression is resolved with the expression's value and included in the result string when the string is assigned. Para saber mais, consulte o tópico Interpolação de cadeia de caracteres (Referência do C#) ou Cadeias de caracteres interpoladas (Referência do Visual Basic).For more information, see String interpolation (C# Reference) and Interpolated Strings (Visual Basic Reference).

Nesta seção:In this section:

Comece com o método String. Format Get started with the String.Format method
Qual método chamar? Which method do I call?
O método Format resumido The Format method in brief
O item de formato The Format item
Como os argumentos são formatados How arguments are formatted
Itens de formato que têm o mesmo índice Format items that have the same index
Formatação e cultura Formatting and culture
Operações de formatação personalizadas Custom formatting operations
String.Format Q & AString.Format Q & A

Comece com o método String. FormatGet started with the String.Format method

Use String.Format se você precisar inserir o valor de um objeto, variável ou expressão em outra cadeia de caracteres.Use String.Format if you need to insert the value of an object, variable, or expression into another string. Por exemplo, você pode inserir o valor de uma Decimal valor em uma cadeia de caracteres para exibi-lo ao usuário como uma única cadeia de caracteres:For example, you can insert the value of a Decimal value into a string to display it to the user as a single string:

Decimal pricePerOunce = (Decimal)17.36;
String^ s = String::Format("The current price is {0} per ounce.",
                           pricePerOunce);
// Result: The current price is 17.36 per ounce.
Decimal pricePerOunce = 17.36m;
String s = String.Format("The current price is {0} per ounce.",
                         pricePerOunce);
Console.WriteLine(s);
// Result: The current price is 17.36 per ounce.
Dim pricePerOunce As Decimal = 17.36d
Dim s As String = String.Format("The current price is {0} per ounce.",
                                pricePerOunce)
' Result: The current price is 17.36 per ounce.

E você pode controlar esse valor de formatação:And you can control that value's formatting:

Decimal pricePerOunce = (Decimal)17.36;
String^ s = String::Format("The current price is {0:C2} per ounce.",
                           pricePerOunce);
// Result if current culture is en-US:
//      The current price is $17.36 per ounce.
Decimal pricePerOunce = 17.36m;
String s = String.Format("The current price is {0:C2} per ounce.",
                         pricePerOunce);
Console.WriteLine(s);
// Result if current culture is en-US:
//      The current price is $17.36 per ounce.
Dim pricePerOunce As Decimal = 17.36d
Dim s As String = String.Format("The current price is {0:C2} per ounce.",
                                pricePerOunce)
' Result if current culture is en-US:
'      The current price is $17.36 per ounce.

Além de formatação, você também pode controlar espaçamento e alinhamento.Besides formatting, you can also control alignment and spacing.

Inserindo uma cadeia de caracteresInserting a string

String.Format começa com uma cadeia de caracteres de formato, seguida por um ou mais objetos ou expressões que serão convertidas em cadeias de caracteres e inseridas em um local especificado na cadeia de caracteres de formato.String.Format starts with a format string, followed by one or more objects or expressions that will be converted to strings and inserted at a specified place in the format string. Por exemplo:For example:

Decimal temp = (Decimal)20.4;
String^ s = String::Format("The temperature is {0}°C.", temp);
Console::WriteLine(s);
// Displays 'The temperature is 20.4°C.'
decimal temp = 20.4m;
string s = String.Format("The temperature is {0}°C.", temp);
Console.WriteLine(s);
// Displays 'The temperature is 20.4°C.'
Dim temp As Decimal = 20.4d
Dim s As String = String.Format("The temperature is {0}°C.", temp)
Console.WriteLine(s)
' Displays 'The temperature is 20.4°C.'

O {0} no formato de cadeia de caracteres é um item de formato.The {0} in the format string is a format item. 0 é o índice do objeto cujo valor de cadeia de caracteres será inserido nessa posição.0 is the index of the object whose string value will be inserted at that position. (Os índices começam com 0). Se o objeto a ser inserido não é uma cadeia de caracteres, seu ToString método é chamado para convertê-lo em um antes de inseri-lo na cadeia de caracteres resultante.(Indexes start at 0.) If the object to be inserted is not a string, its ToString method is called to convert it to one before inserting it in the result string.

Aqui está outro exemplo que usa dois itens de formato e dois objetos na lista de objetos:Here's another example that uses two format items and two objects in the object list:

String^ s = String::Format("At {0}, the temperature is {1}°C.",
                           DateTime::Now, 20.4);
// Output similar to: 'At 4/10/2015 9:29:41 AM, the temperature is 20.4°C.'
string s = String.Format("At {0}, the temperature is {1}°C.",
                         DateTime.Now, 20.4);
Console.WriteLine(s);
// Output similar to: 'At 4/10/2015 9:29:41 AM, the temperature is 20.4°C.'
Dim s As String = String.Format("At {0}, the temperature is {1}°C.",
                                Date.Now, 20.4)
' Output similar to: 'At 4/10/2015 9:29:41 AM, the temperature is 20.4°C.'

Você pode ter quantos itens de formato e a quantidade de objetos na lista de objetos que você deseja, desde que o índice de cada item de formato tem um objeto correspondente na lista de objetos.You can have as many format items and as many objects in the object list as you want, as long as the index of every format item has a matching object in the object list. Você também não precisa se preocupar sobre qual sobrecarga você chamar; o compilador irá selecionar aquela que for apropriada para você.You also don't have to worry about which overload you call; the compiler will select the appropriate one for you.

Controlando a formataçãoControlling formatting

Você pode seguir o índice de um item de formato com uma cadeia de caracteres de formato para controlar como um objeto é formatado.You can follow the index in a format item with a format string to control how an object is formatted. Por exemplo, {0:d} aplica-se a cadeia de caracteres de formato "d" para o primeiro objeto na lista de objetos.For example, {0:d} applies the "d" format string to the first object in the object list. Aqui está um exemplo com um único objeto e dois itens de formato:Here is an example with a single object and two format items:

String^ s = String::Format("It is now {0:d} at {0:t}",
                           DateTime::Now);
// Output similar to: 'It is now 4/10/2015 at 10:04 AM'
string s = String.Format("It is now {0:d} at {0:t}", DateTime.Now);
Console.WriteLine(s);
// Output similar to: 'It is now 4/10/2015 at 10:04 AM'
Dim s As String = String.Format("It is now {0:d} at {0:t}",
                                Date.Now)
' Output similar to: 'It is now 4/10/2015 at 10:04 AM'

Um número de suporte de tipos de formato de cadeias de caracteres, incluindo todos os tipos numéricos (ambos standard e personalizado Formatar cadeias de caracteres), todas as datas e horas (tanto padrão e personalizado Formatar cadeias de caracteres) e intervalos de tempo (ambos padrão e personalizado Formatar cadeias de caracteres), todos os tipos de enumeração tipos de enumeração , e GUIDs.A number of types support format strings, including all numeric types (both standard and custom format strings), all dates and times (both standard and custom format strings) and time intervals (both standard and custom format strings), all enumeration types enumeration types, and GUIDs. Você também pode adicionar suporte para cadeias de caracteres de formato para seus próprios tipos.You can also add support for format strings to your own types.

Controlar o espaçamentoControlling spacing

Você pode definir a largura da cadeia de caracteres que é inserida na cadeia de caracteres de resultado usando sintaxe como {0,12}, que insere uma cadeia de caracteres de 12 caracteres.You can define the width of the string that is inserted into the result string by using syntax such as {0,12}, which inserts a 12-character string. Nesse caso, a representação de cadeia de caracteres do primeiro objeto é alinhado à direita no campo de 12 caracteres.In this case, the string representation of the first object is right-aligned in the 12-character field. (Se a representação de cadeia de caracteres do primeiro objeto é mais de 12 caracteres de comprimento, no entanto, a largura preferencial do campo será ignorada e a cadeia de caracteres inteira é inserida na cadeia de caracteres de resultado.)(If the string representation of the first object is more than 12 characters in length, though, the preferred field width is ignored, and the entire string is inserted into the result string.)

O exemplo a seguir define um campo de 6 caracteres para conter a cadeia de caracteres "Ano" e algumas cadeias de caracteres do ano, bem como um campo de 15 caracteres para conter a cadeia de caracteres "População" e alguns dados de população.The following example defines a 6-character field to hold the string "Year" and some year strings, as well as an 15-character field to hold the string "Population" and some population data. Observe que os caracteres são alinhados à direita no campo.Note that the characters are right-aligned in the field.

array<int>^ years = { 2013, 2014, 2015 };
array<int>^ population = { 1025632, 1105967, 1148203 };
StringBuiler^ sb = gcnew StringBuilder();
sb->Append(String::Format("{0,6} {1,15}\n\n", "Year", "Population"));
for(int index = 0; index < years->Length; index++)
   sb->AppendFormat("{0,6} {1,15:N0}\n",
                    years[index], population[index]);
// Result:
//      Year      Population
//
//      2013       1,025,632
//      2014       1,105,967
//      2015       1,148,203
int[] years = { 2013, 2014, 2015 };
int[] population = { 1025632, 1105967, 1148203 };
var sb = new System.Text.StringBuilder();
sb.Append(String.Format("{0,6} {1,15}\n\n", "Year", "Population"));
for (int index = 0; index < years.Length; index++)
   sb.Append(String.Format("{0,6} {1,15:N0}\n", years[index], population[index]));

Console.WriteLine(sb);

// Result:
//      Year      Population
//
//      2013       1,025,632
//      2014       1,105,967
//      2015       1,148,203
Dim years() As Integer = { 2013, 2014, 2015 }
Dim population() As Integer  = { 1025632, 1105967, 1148203 }
Dim sb As New StringBuilder()
sb.Append(String.Format("{0,6} {1,15}{2}{2}",
                        "Year", "Population", vbCrLf))
For index As Integer = 0 To years.Length - 1
   sb.AppendFormat("{0,6} {1,15:N0}{2}",
                   years(index), population(index), vbCrLf)
Next
' Result:
'      Year      Population
'
'      2013       1,025,632
'      2014       1,105,967
'      2015       1,148,203

Controlar o alinhamentoControlling alignment

Por padrão, cadeias de caracteres são alinhados à direita em seu campo se você especificar uma largura de campo.By default, strings are right-aligned within their field if you specify a field width. Para alinhar à esquerda cadeias de caracteres em um campo, você preceda a largura do campo com um sinal negativo, tais como {0,-12} para definir um campo de 12 caracteres alinhada à esquerda.To left-align strings in a field, you preface the field width with a negative sign, such as {0,-12} to define a 12-character left-aligned field.

O exemplo a seguir é semelhante ao anterior, exceto pelo fato de ele alinha à esquerda os rótulos e os dados.The following example is similar to the previous one, except that it left-aligns both labels and data.

array<int>^ years = { 2013, 2014, 2015 };
array<int>^ population = { 1025632, 1105967, 1148203 };
String^ s = String::Format("{0,-10} {1,-10}\n\n", "Year", "Population");
for(int index = 0; index < years->Length; index++)
   s += String::Format("{0,-10} {1,-10:N0}\n",
                      years[index], population[index]);
// Result:
//    Year       Population
//
//    2013       1,025,632
//    2014       1,105,967
//    2015       1,148,203
int[] years = { 2013, 2014, 2015 };
int[] population = { 1025632, 1105967, 1148203 };
String s = String.Format("{0,-10} {1,-10}\n\n", "Year", "Population");
for(int index = 0; index < years.Length; index++)
   s += String.Format("{0,-10} {1,-10:N0}\n",
                      years[index], population[index]);
Console.WriteLine($"\n{s}");
// Result:
//    Year       Population
//
//    2013       1,025,632
//    2014       1,105,967
//    2015       1,148,203
Dim years() As Integer = { 2013, 2014, 2015 }
Dim population() As Integer  = { 1025632, 1105967, 1148203 }
Dim s As String = String.Format("{0,-10} {1,-10}{2}{2}",
                                "Year", "Population", vbCrLf)
For index As Integer = 0 To years.Length - 1
   s += String.Format("{0,-10} {1,-10:N0}{2}",
                      years(index), population(index), vbCrLf)
Next
' Result:
'    Year       Population
'
'    2013       1,025,632
'    2014       1,105,967
'    2015       1,148,203

String.Format faz uso de recurso de formatação composta.String.Format makes use of the composite formatting feature. Para obter mais informações, veja Formatação de composição.For more information, see Composite Formatting.

Qual método devo chamar?Which method do I call?

ParaTo CallCall
Formate um ou mais objetos usando as convenções da cultura atual.Format one or more objects by using the conventions of the current culture. Exceto para as sobrecargas que incluem uma provider parâmetro, o restante Format sobrecargas incluem um String parâmetro seguido por um ou mais parâmetros de objeto.Except for the overloads that include a provider parameter, the remaining Format overloads include a String parameter followed by one or more object parameters. Por isso, você não precisa determinar qual Format sobrecarga que você pretende chamar.Because of this, you don't have to determine which Format overload you intend to call. O compilador de linguagem seleciona a sobrecarga apropriada dentre as sobrecargas que não têm um provider parâmetro, com base em sua lista de argumentos.Your language compiler selects the appropriate overload from among the overloads that don't have a provider parameter, based on your argument list. Por exemplo, se sua lista de argumentos tiver cinco argumentos, o compilador chama o Format(String, Object[]) método.For example, if your argument list has five arguments, the compiler calls the Format(String, Object[]) method.
Formate um ou mais objetos usando as convenções de uma cultura específica.Format one or more objects by using the conventions of a specific culture. Cada Format sobrecarga que começa com um provider parâmetro é seguido por um String parâmetro e um ou mais parâmetros do objeto.Each Format overload that begins with a provider parameter is followed by a String parameter and one or more object parameters. Por isso, você não precisa determinar qual específicas Format sobrecarga que você pretende chamar.Because of this, you don't have to determine which specific Format overload you intend to call. O compilador de linguagem seleciona a sobrecarga apropriada dentre as sobrecargas que têm um provider parâmetro, com base em sua lista de argumentos.Your language compiler selects the appropriate overload from among the overloads that have a provider parameter, based on your argument list. Por exemplo, se sua lista de argumentos tiver cinco argumentos, o compilador chama o Format(IFormatProvider, String, Object[]) método.For example, if your argument list has five arguments, the compiler calls the Format(IFormatProvider, String, Object[]) method.
Executar uma operação de formatação personalizada com uma ICustomFormatter implementação ou um IFormattable implementação.Perform a custom formatting operation either with an ICustomFormatter implementation or an IFormattable implementation. Qualquer um dos quatro sobrecargas com um provider parâmetro.Any of the four overloads with a provider parameter. O compilador seleciona a sobrecarga apropriada dentre as sobrecargas que têm um provider parâmetro, com base em sua lista de argumentos.The compiler selects the appropriate overload from among the overloads that have a provider parameter, based on your argument list.

O método Format resumidoThe Format method in brief

Cada sobrecarga da Format usa o recurso de formatação composta para incluir com base em zero espaços reservados indexados, chamados formatar itens, em uma cadeia de caracteres de formato composto.Each overload of the Format method uses the composite formatting feature to include zero-based indexed placeholders, called format items, in a composite format string. Em tempo de execução, cada item de formato é substituído pela representação de cadeia de caracteres do argumento correspondente em uma lista de parâmetros.At run time, each format item is replaced with the string representation of the corresponding argument in a parameter list. Se o valor do argumento for null, o item de formato é substituído pelo String.Empty.If the value of the argument is null, the format item is replaced with String.Empty. Por exemplo, a seguinte chamada para o Format(String, Object, Object, Object) método inclui uma cadeia de caracteres de formato com três itens de formato {0}, {1}, e {2}e uma lista de argumentos com três itens.For example, the following call to the Format(String, Object, Object, Object) method includes a format string with three format items, {0}, {1}, and {2}, and an argument list with three items.

using namespace System;

void main()
{
   DateTime^ dat = gcnew DateTime(2012, 1, 17, 9, 30, 0); 
   String^ city = "Chicago";
   int temp = -16;
   String^ output = String::Format("At {0} in {1}, the temperature was {2} degrees.",
                                   dat, city, temp);
   Console::WriteLine(output);
}
// The example displays the following output: 
//    At 1/17/2012 9:30:00 AM in Chicago, the temperature was -16 degrees.   
DateTime dat = new DateTime(2012, 1, 17, 9, 30, 0); 
string city = "Chicago";
int temp = -16;
string output = String.Format("At {0} in {1}, the temperature was {2} degrees.",
                              dat, city, temp);
Console.WriteLine(output);
// The example displays output like the following:
//    At 1/17/2012 9:30:00 AM in Chicago, the temperature was -16 degrees.   
Dim dat As Date = #1/17/2012 9:30AM# 
Dim city As String = "Chicago"
Dim temp As Integer = -16
Dim output As String = String.Format("At {0} in {1}, the temperature was {2} degrees.",
                                     dat, city, temp)
Console.WriteLine(output)
' The example displays the following output:
'    At 1/17/2012 9:30:00 AM in Chicago, the temperature was -16 degrees.   

O item de formatoThe format item

Um item de formato tem a seguinte sintaxe:A format item has this syntax:

{index[,alignment][:formatString]}  

Colchetes indicam elementos opcionais.Brackets denote optional elements. As chaves de abertura e fechamento são necessárias.The opening and closing braces are required. (Para incluir uma literal abertura ou fechamento na cadeia de caracteres de formato, consulte o chaves de escape seção o formatação de composição artigo.)(To include a literal opening or closing brace in the format string, see the Escaping Braces section in the Composite Formatting article.)

Por exemplo, um item de formato para formatar um valor de moeda pode aparecer como este:For example, a format item to format a currency value might appear like this:

String::Format("{0,-10:C}", (Decimal) 126347.89);         
var value = String.Format("{0,-10:C}", 126347.89m);         
Console.WriteLine(value);
String.Format("{0,-10:C}", 126347.89d)        

Um item de formato tem os seguintes elementos:A format item has the following elements:

indexindex
O índice baseado em zero do argumento cuja representação de cadeia de caracteres deve ser incluído nessa posição na cadeia de caracteres.The zero-based index of the argument whose string representation is to be included at this position in the string. Se esse argumento for null, uma cadeia de caracteres vazia será incluída nessa posição na cadeia de caracteres.If this argument is null, an empty string will be included at this position in the string.

alignmentalignment
Opcional.Optional. Um inteiro com sinal que indica o comprimento total do campo em que o argumento é inserido e se ele estiver alinhado à direita (um inteiro positivo) ou alinhado à esquerda (um inteiro negativo).A signed integer that indicates the total length of the field into which the argument is inserted and whether it is right-aligned (a positive integer) or left-aligned (a negative integer). Se você omitir alinhamento, a representação de cadeia de caracteres do argumento correspondente é inserida em um campo sem espaços à esquerda ou direita.If you omit alignment, the string representation of the corresponding argument is inserted in a field with no leading or trailing spaces.

Se o valor de alinhamento é menor que o comprimento do argumento a ser inserido, alinhamento será ignorado e o comprimento da representação de cadeia de caracteres do argumento é usado como a largura do campo.If the value of alignment is less than the length of the argument to be inserted, alignment is ignored and the length of the string representation of the argument is used as the field width.

formatStringformatString
Opcional.Optional. Uma cadeia de caracteres que especifica o formato de cadeia de caracteres de resultado do argumento correspondente.A string that specifies the format of the corresponding argument's result string. Se você omitir formatString, o argumento correspondente sem parâmetros ToString método é chamado para produzir sua representação de cadeia de caracteres.If you omit formatString, the corresponding argument's parameterless ToString method is called to produce its string representation. Se você especificar formatString, o argumento referenciado pelo item de formato deve implementar o IFormattable interface.If you specify formatString, the argument referenced by the format item must implement the IFormattable interface. Os tipos que oferecem suporte a cadeias de caracteres de formato incluem:Types that support format strings include:

No entanto, observe que qualquer tipo personalizado pode implementar IFormattable ou estender um tipo existente IFormattable implementação.However, note that any custom type can implement IFormattable or extend an existing type's IFormattable implementation.

O exemplo a seguir usa o alignment e formatString argumentos para produzir saída formatada.The following example uses the alignment and formatString arguments to produce formatted output.

using namespace System;

void main()
{
   // Create array of 5-tuples with population data for three U.S. cities, 1940-1950.
   array<Tuple<String^, DateTime, int, DateTime, int>^>^ cities = gcnew array<Tuple<String^, DateTime, int, DateTime, int>^> 
         { gcnew Tuple<String^, DateTime, int, DateTime, int>("Los Angeles", DateTime(1940, 1, 1), 1504277, 
                        DateTime(1950, 1, 1), 1970358),
         gcnew Tuple<String^, DateTime, int, DateTime, int>("New York", DateTime(1940, 1, 1), 7454995, 
                        DateTime(1950, 1, 1), 7891957),  
         gcnew Tuple<String^, DateTime, int, DateTime, int>("Chicago", DateTime(1940, 1, 1), 3396808, 
                        DateTime(1950, 1, 1), 3620962),  
         gcnew Tuple<String^, DateTime, int, DateTime, int>("Detroit", DateTime(1940, 1, 1), 1623452, 
                        DateTime(1950, 1, 1), 1849568) };

   // Display header
   String^ header = String::Format("{0,-12}{1,8}{2,12}{1,8}{2,12}{3,14}\n",
                                   "City", "Year", "Population", "Change (%)");
   Console::WriteLine(header);
   String^ output;      
   for each (Tuple<String^, DateTime, int, DateTime, int>^ city in cities) {
      output = String::Format("{0,-12}{1,8:yyyy}{2,12:N0}{3,8:yyyy}{4,12:N0}{5,14:P1}",
                              city->Item1, city->Item2, city->Item3, city->Item4, city->Item5,
                              (city->Item5 - city->Item3)/ (double)city->Item3);
      Console::WriteLine(output);
   }
}
// The example displays the following output:
//    City            Year  Population    Year  Population    Change (%)
//    
//    Los Angeles     1940   1,504,277    1950   1,970,358        31.0 %
//    New York        1940   7,454,995    1950   7,891,957         5.9 %
//    Chicago         1940   3,396,808    1950   3,620,962         6.6 %
//    Detroit         1940   1,623,452    1950   1,849,568        13.9 %
// Create array of 5-tuples with population data for three U.S. cities, 1940-1950.
Tuple<string, DateTime, int, DateTime, int>[] cities = 
    { Tuple.Create("Los Angeles", new DateTime(1940, 1, 1), 1504277, 
                   new DateTime(1950, 1, 1), 1970358),
      Tuple.Create("New York", new DateTime(1940, 1, 1), 7454995, 
                   new DateTime(1950, 1, 1), 7891957),  
      Tuple.Create("Chicago", new DateTime(1940, 1, 1), 3396808, 
                   new DateTime(1950, 1, 1), 3620962),  
      Tuple.Create("Detroit", new DateTime(1940, 1, 1), 1623452, 
                   new DateTime(1950, 1, 1), 1849568) };

// Display header
var header = String.Format("{0,-12}{1,8}{2,12}{1,8}{2,12}{3,14}\n",
                              "City", "Year", "Population", "Change (%)");
Console.WriteLine(header);
foreach (var city in cities) {
   var output = String.Format("{0,-12}{1,8:yyyy}{2,12:N0}{3,8:yyyy}{4,12:N0}{5,14:P1}",
                          city.Item1, city.Item2, city.Item3, city.Item4, city.Item5,
                          (city.Item5 - city.Item3)/ (double)city.Item3);
   Console.WriteLine(output);
}
// The example displays the following output:
//    City            Year  Population    Year  Population    Change (%)
//  
//    Los Angeles     1940   1,504,277    1950   1,970,358        31.0 %
//    New York        1940   7,454,995    1950   7,891,957         5.9 %
//    Chicago         1940   3,396,808    1950   3,620,962         6.6 %
//    Detroit         1940   1,623,452    1950   1,849,568        13.9 %
Module Example
   Public Sub Main()
      ' Create array of 5-tuples with population data for three U.S. cities, 1940-1950.
      Dim cities()  = _
          { Tuple.Create("Los Angeles", #1/1/1940#, 1504277, #1/1/1950#, 1970358),
            Tuple.Create("New York", #1/1/1940#, 7454995, #1/1/1950#, 7891957),  
            Tuple.Create("Chicago", #1/1/1940#, 3396808, #1/1/1950#, 3620962),  
            Tuple.Create("Detroit", #1/1/1940#, 1623452, #1/1/1950#, 1849568) }

      ' Display header
      Dim header As String = String.Format("{0,-12}{1,8}{2,12}{1,8}{2,12}{3,14}",
                                           "City", "Year", "Population", "Change (%)")
      Console.WriteLine(header)
      Console.WriteLine()
      For Each city In cities
         Dim output = String.Format("{0,-12}{1,8:yyyy}{2,12:N0}{3,8:yyyy}{4,12:N0}{5,14:P1}",
                                city.Item1, city.Item2, city.Item3, city.Item4, city.Item5,
                                (city.Item5 - city.Item3)/city.Item3)
         Console.WriteLine(output)
      Next
   End Sub
End Module
' The example displays the following output:
'    City            Year  Population    Year  Population    Change (%)
'    
'    Los Angeles     1940   1,504,277    1950   1,970,358        31.0 %
'    New York        1940   7,454,995    1950   7,891,957         5.9 %
'    Chicago         1940   3,396,808    1950   3,620,962         6.6 %
'    Detroit         1940   1,623,452    1950   1,849,568        13.9 %

Como os argumentos são formatadosHow arguments are formatted

Itens de formato são processados em sequência, desde o início da cadeia de caracteres.Format items are processed sequentially from the beginning of the string. Cada item de formato tem um índice que corresponde a um objeto na lista de argumentos do método.Each format item has an index that corresponds to an object in the method's argument list. O Format recupera o argumento de método e sua representação de cadeia de caracteres é derivado da seguinte maneira:The Format method retrieves the argument and derives its string representation as follows:

Para obter um exemplo que intercepta as chamadas para o ICustomFormatter.Format método e permite que você veja quais informações o Format passes de método para um método de formatação para cada item de formato em uma cadeia de caracteres de formato de composição, consulte exemplo: Um provedor de interceptação e formatador de algarismo romano.For an example that intercepts calls to the ICustomFormatter.Format method and allows you to see what information the Format method passes to a formatting method for each format item in a composite format string, see Example: An intercept provider and Roman numeral formatter.

Para obter mais informações, consulte o ordem de processamento seção o formatação de composição artigo.For more information, see the Processing Order section in the Composite Formatting article.

Itens de formato que têm o mesmo índiceFormat items that have the same index

O Format método lança um FormatException exceção se o índice de um item do índice é maior que ou igual ao número de argumentos na lista de argumentos.The Format method throws a FormatException exception if the index of an index item is greater than or equal to the number of arguments in the argument list. No entanto, format pode incluir mais itens de formato que o número de argumentos, desde que vários itens de formato têm o mesmo índice.However, format can include more format items than there are arguments, as long as multiple format items have the same index. Na chamada para o Format(String, Object) método no exemplo a seguir, a lista de argumentos tem um único argumento, mas a cadeia de caracteres de formato inclui dois itens de formato: um exibe o valor decimal de um número e o outro exibe seu valor hexadecimal.In the call to the Format(String, Object) method in following example, the argument list has a single argument, but the format string includes two format items: one displays the decimal value of a number, and the other displays its hexadecimal value.

short[] values= { Int16.MinValue, -27, 0, 1042, Int16.MaxValue };
Console.WriteLine("{0,10}  {1,10}\n", "Decimal", "Hex");
foreach (short value in values)
{
   string formatString = String.Format("{0,10:G}: {0,10:X}", value);
   Console.WriteLine(formatString);
}   
// The example displays the following output:
//       Decimal         Hex
//    
//        -32768:       8000
//           -27:       FFE5
//             0:          0
//          1042:        412
//         32767:       7FFF
Module Example
   Public Sub Main()
      Dim values() As Short = { Int16.MinValue, -27, 0, 1042, Int16.MaxValue }
      Console.WriteLine("{0,10}  {1,10}", "Decimal", "Hex")
      Console.WriteLine()
      For Each value As Short In values
         Dim formatString As String = String.Format("{0,10:G}: {0,10:X}", value)
         Console.WriteLine(formatString)
      Next        
   End Sub
End Module
' The example displays the following output:
'       Decimal         Hex
'    
'        -32768:       8000
'           -27:       FFE5
'             0:          0
'          1042:        412
'         32767:       7FFF

Formatação e culturaFormatting and culture

Em geral, os objetos na lista de argumentos são convertidos em suas representações de cadeia de caracteres usando as convenções da cultura atual, que é retornado pelo CultureInfo.CurrentCulture propriedade.Generally, objects in the argument list are converted to their string representations by using the conventions of the current culture, which is returned by the CultureInfo.CurrentCulture property. Você pode controlar esse comportamento, chamando uma das sobrecargas de Format que inclui um provider parâmetro.You can control this behavior by calling one of the overloads of Format that includes a provider parameter. O provider parâmetro é um IFormatProvider o processo de implementação que fornece informações de formatação específicas da cultura e personalizadas que são usadas para moderar a formatação.The provider parameter is an IFormatProvider implementation that supplies custom and culture-specific formatting information that is used to moderate the formatting process.

O IFormatProvider interface tem um único membro, GetFormat, que é responsável por retornar o objeto que fornece informações de formatação.The IFormatProvider interface has a single member, GetFormat, which is responsible for returning the object that provides formatting information. .NET tem três IFormatProvider implementações que fornecem a formatação de cultura específica:.NET has three IFormatProvider implementations that provide culture-specific formatting:

Operações de formatação personalizadasCustom formatting operations

Você também pode chamar qualquer uma das sobrecargas do Format método que tem um provider parâmetro do tipo IFormatProvider para executar operações de formatação personalizadas.You can also call the any of the overloads of the Format method that have a provider parameter of type IFormatProvider to perform custom formatting operations. Por exemplo, você pode formatar um número inteiro como um número de identificação ou como um número de telefone.For example, you could format an integer as an identification number or as a telephone number. Para executar a formatação personalizada, sua provider argumento deve implementar ambas as IFormatProvider e ICustomFormatter interfaces.To perform custom formatting, your provider argument must implement both the IFormatProvider and ICustomFormatter interfaces. Quando o Format método recebe um ICustomFormatter implementação como o provider argumento, o Format chamadas de método seu IFormatProvider.GetFormat implementação e solicita um objeto do tipo ICustomFormatter.When the Format method is passed an ICustomFormatter implementation as the provider argument, the Format method calls its IFormatProvider.GetFormat implementation and requests an object of type ICustomFormatter. Em seguida, chama retornado ICustomFormatter do objeto Format método para cada item de formato na cadeia de caracteres composta de formato passado para ele.It then calls the returned ICustomFormatter object's Format method to format each format item in the composite string passed to it.

Para obter mais informações sobre como fornecer soluções personalizadas de formatação, consulte como: Definir e usar provedores de formato numérico personalizado e ICustomFormatter.For more information about providing custom formatting solutions, see How to: Define and Use Custom Numeric Format Providers and ICustomFormatter. Para obter um exemplo que converte números inteiros em números formatados de personalizado, consulte exemplo: Uma operação de formatação personalizada.For an example that converts integers to formatted custom numbers, see Example: A custom formatting operation. Veja um exemplo que converte bytes sem sinal em numerais romanos, exemplo: Um provedor de interceptação e formatador de algarismo romano.For an example that converts unsigned bytes to Roman numerals, see Example: An intercept provider and Roman numeral formatter.

Exemplo: Uma operação de formatação personalizadaExample: A custom formatting operation

Este exemplo define um provedor de formato que formata um valor inteiro como um número de conta do cliente no formato x-xxxxx-xx.This example defines a format provider that formats an integer value as a customer account number in the form x-xxxxx-xx.

using namespace System;

ref class CustomerFormatter : IFormatProvider, ICustomFormatter
{
public:
   virtual Object^ GetFormat(Type^ formatType) 
   {
      if (formatType == ICustomFormatter::typeid)        
         return this; 
      else 
         return nullptr; 
   }
   
   virtual String^ Format(String^ format, 
	               Object^ arg, 
	               IFormatProvider^ formatProvider) 
   {                       
      if (! this->Equals(formatProvider))
      {
         return nullptr;
      }
      else
      {
         if (String::IsNullOrEmpty(format)) 
            format = "G";
         
         String^ customerString = arg->ToString();
         if (customerString->Length < 8)
            customerString = customerString->PadLeft(8, '0');
         
         format = format->ToUpper();
         if (format == L"G") 
               return customerString->Substring(0, 1) + "-" +
                                     customerString->Substring(1, 5) + "-" +
                                     customerString->Substring(6);
         else if (format == L"S")                          
               return customerString->Substring(0, 1) + "/" +
                                     customerString->Substring(1, 5) + "/" +
                                     customerString->Substring(6);
         else if (format == L"P")
               return customerString->Substring(0, 1) + "." +
                                     customerString->Substring(1, 5) + "." +
                                     customerString->Substring(6);
         else
               throw gcnew FormatException( 
                         String::Format("The '{0}' format specifier is not supported.", format));
         }
    }   
};

void main()
{
   int acctNumber = 79203159;
   Console::WriteLine(String::Format(gcnew CustomerFormatter, "{0}", acctNumber));
   Console::WriteLine(String::Format(gcnew CustomerFormatter, "{0:G}", acctNumber));
   Console::WriteLine(String::Format(gcnew CustomerFormatter, "{0:S}", acctNumber));
   Console::WriteLine(String::Format(gcnew CustomerFormatter, "{0:P}", acctNumber));
   try {
      Console::WriteLine(String::Format(gcnew CustomerFormatter, "{0:X}", acctNumber));
   }
   catch (FormatException^ e) {
      Console::WriteLine(e->Message);
   }
}
// The example displays the following output:
//       7-92031-59
//       7-92031-59
//       7/92031/59
//       7.92031.59
//       The 'X' format specifier is not supported.
using System;

public class TestFormatter
{
   public static void Main()
   {
      int acctNumber = 79203159;
      Console.WriteLine(String.Format(new CustomerFormatter(), "{0}", acctNumber));
      Console.WriteLine(String.Format(new CustomerFormatter(), "{0:G}", acctNumber));
      Console.WriteLine(String.Format(new CustomerFormatter(), "{0:S}", acctNumber));
      Console.WriteLine(String.Format(new CustomerFormatter(), "{0:P}", acctNumber));
      try {
         Console.WriteLine(String.Format(new CustomerFormatter(), "{0:X}", acctNumber));
      }
      catch (FormatException e) {
         Console.WriteLine(e.Message);
      }
   }
}

public class CustomerFormatter : IFormatProvider, ICustomFormatter
{
   public object GetFormat(Type formatType) 
   {
      if (formatType == typeof(ICustomFormatter))        
         return this; 
      else
         return null;
   }
   
   public string Format(string format, 
	                     object arg, 
	                     IFormatProvider formatProvider) 
   {                       
      if (! this.Equals(formatProvider))
      {
         return null;
      }
      else
      {
         if (String.IsNullOrEmpty(format)) 
            format = "G";
         
         string customerString = arg.ToString();
         if (customerString.Length < 8)
            customerString = customerString.PadLeft(8, '0');
         
         format = format.ToUpper();
         switch (format)
         {
            case "G":
               return customerString.Substring(0, 1) + "-" +
                                     customerString.Substring(1, 5) + "-" +
                                     customerString.Substring(6);
            case "S":                          
               return customerString.Substring(0, 1) + "/" +
                                     customerString.Substring(1, 5) + "/" +
                                     customerString.Substring(6);
            case "P":                          
               return customerString.Substring(0, 1) + "." +
                                     customerString.Substring(1, 5) + "." +
                                     customerString.Substring(6);
            default:
               throw new FormatException( 
                         String.Format("The '{0}' format specifier is not supported.", format));
         }
      }   
   }
}
// The example displays the following output:
//       7-92031-59
//       7-92031-59
//       7/92031/59
//       7.92031.59
//       The 'X' format specifier is not supported.
Module TestFormatter
   Public Sub Main()
      Dim acctNumber As Integer = 79203159
      Console.WriteLine(String.Format(New CustomerFormatter, "{0}", acctNumber))
      Console.WriteLine(String.Format(New CustomerFormatter, "{0:G}", acctNumber))
      Console.WriteLine(String.Format(New CustomerFormatter, "{0:S}", acctNumber))
      Console.WriteLine(String.Format(New CustomerFormatter, "{0:P}", acctNumber))
      Try
         Console.WriteLine(String.Format(New CustomerFormatter, "{0:X}", acctNumber))
      Catch e As FormatException
         Console.WriteLine(e.Message)
      End Try   
   End Sub
End Module

Public Class CustomerFormatter : Implements IFormatProvider, ICustomFormatter
   Public Function GetFormat(type As Type) As Object  _
                   Implements IFormatProvider.GetFormat
      If type Is GetType(ICustomFormatter) Then
         Return Me
      Else
         Return Nothing
      End If
   End Function
   
   Public Function Format(fmt As String, _
	                       arg As Object, _
	                       formatProvider As IFormatProvider) As String _
	                Implements ICustomFormatter.Format
      If Not Me.Equals(formatProvider) Then
         Return Nothing
      Else
         If String.IsNullOrEmpty(fmt) Then fmt = "G"
         
         Dim customerString As String = arg.ToString()
         if customerString.Length < 8 Then _
            customerString = customerString.PadLeft(8, "0"c)
         
         Select Case fmt
            Case "G"
               Return customerString.Substring(0, 1) & "-" & _
                                     customerString.Substring(1, 5) & "-" & _
                                     customerString.Substring(6)
            Case "S"                         
               Return customerString.Substring(0, 1) & "/" & _
                                     customerString.Substring(1, 5) & "/" & _
                                     customerString.Substring(6)
            Case "P"
               Return customerString.Substring(0, 1) & "." & _
                                     customerString.Substring(1, 5) & "." & _
                                     customerString.Substring(6)
            Case Else
               Throw New FormatException( _
                         String.Format("The '{0}' format specifier is not supported.", fmt))
         End Select                                                     
      End If   
   End Function
End Class
' The example displays the following output:
'       7-92031-59
'       7-92031-59
'       7/92031/59
'       7.92031.59
'       The 'X' format specifier is not supported.

Exemplo: Um provedor de interceptação e formatador de algarismo romanoExample: An intercept provider and Roman numeral formatter

Este exemplo define um provedor de formato personalizado que implementa o ICustomFormatter e IFormatProvider interfaces fazer duas coisas:This example defines a custom format provider that implements the ICustomFormatter and IFormatProvider interfaces to do two things:

  • Ele exibe os parâmetros passados para seus ICustomFormatter.Format implementação.It displays the parameters passed to its ICustomFormatter.Format implementation. Isso nos permite ver quais parâmetros a Format(IFormatProvider, String, Object[]) método está passando para a implementação de formatação personalizada para cada objeto que ele tenta formatar.This enables us to see what parameters the Format(IFormatProvider, String, Object[]) method is passing to the custom formatting implementation for each object that it tries to format. Isso pode ser útil quando você estiver depurando seu aplicativo.This can be useful when you're debugging your application.

  • Se o objeto a ser formatado for um valor de byte sem sinal que deve ser formatada usando a cadeia de caracteres de formato padrão "R", o formatador personalizado formata o valor numérico como um numeral romano.If the object to be formatted is an unsigned byte value that is to be formatted by using the "R" standard format string, the custom formatter formats the numeric value as a Roman numeral.

using namespace System;
using namespace System::Globalization;

ref class InterceptProvider : IFormatProvider, ICustomFormatter
{
public:
   virtual Object^ GetFormat(Type^ formatType)
   {
      if (formatType == ICustomFormatter::typeid)   
         return this;
      else
         return nullptr;
   }
   
   virtual String^ Format(String^ format, Object^ obj, IFormatProvider^ provider) 
   {
      // Display information about method call.
      String^ formatString = format != nullptr ? format : "<null>";
      Console::WriteLine("Provider: {0}, Object: {1}, Format String: {2}",
                        provider, obj != nullptr ? obj : "<null>", formatString);
                        
      if (obj == nullptr) return String::Empty;
            
      // If this is a byte and the "R" format string, format it with Roman numerals.
      if (obj->GetType() == Byte::typeid && formatString->ToUpper()->Equals("R")) {
         Byte value = (Byte) obj;
         int remainder;
         int result;
         String^ returnString = String::Empty;

         // Get the hundreds digit(s)
         result = Math::DivRem(value, 100, remainder);
         if (result > 0)  
            returnString = gcnew String('C', result);
         value = (Byte) remainder;
         // Get the 50s digit
         result = Math::DivRem(value, 50, remainder);
         if (result == 1)
            returnString += "L";
         value = (Byte) remainder;
         // Get the tens digit.
         result = Math::DivRem(value, 10, remainder);
         if (result > 0)
            returnString += gcnew String('X', result);
         value = (Byte) remainder; 
         // Get the fives digit.
         result = Math::DivRem(value, 5, remainder);
         if (result > 0)
            returnString += "V";
         value = (Byte) remainder;
         // Add the ones digit.
         if (remainder > 0) 
            returnString += gcnew String('I', remainder);
         
         // Check whether we have too many X characters.
         int pos = returnString->IndexOf("XXXX");
         if (pos >= 0) {
            int xPos = returnString->IndexOf("L"); 
            if ((xPos >= 0) & (xPos == pos - 1))
               returnString = returnString->Replace("LXXXX", "XC");
            else
               returnString = returnString->Replace("XXXX", "XL");   
         }
         // Check whether we have too many I characters
         pos = returnString->IndexOf("IIII");
         if (pos >= 0)
            if (returnString->IndexOf("V") >= 0)
               returnString = returnString->Replace("VIIII", "IX");
            else
               returnString = returnString->Replace("IIII", "IV");    

         return returnString; 
      }   

      // Use default for all other formatting.
      if (obj->GetType() == IFormattable::typeid)
         return ((IFormattable^) obj)->ToString(format, CultureInfo::CurrentCulture);
      else
         return obj->ToString();
   }
};

void main()
{
   int n = 10;
   double value = 16.935;
   DateTime day = DateTime::Now;
   InterceptProvider^ provider = gcnew InterceptProvider();
   Console::WriteLine(String::Format(provider, "{0:N0}: {1:C2} on {2:d}\n", n, value, day));
   Console::WriteLine(String::Format(provider, "{0}: {1:F}\n", "Today: ", 
                                    (DayOfWeek) DateTime::Now.DayOfWeek));
   Console::WriteLine(String::Format(provider, "{0:X}, {1}, {2}\n", 
                                    (Byte) 2, (Byte) 12, (Byte) 199));
   Console::WriteLine(String::Format(provider, "{0:R}, {1:R}, {2:R}\n", 
                                    (Byte) 2, (Byte) 12, (Byte) 199));
}
// The example displays the following output:
//    Provider: InterceptProvider, Object: 10, Format String: N0
//    Provider: InterceptProvider, Object: 16.935, Format String: C2
//    Provider: InterceptProvider, Object: 1/31/2013 6:10:28 PM, Format String: d
//    10: $16.94 on 1/31/2013
//    
//    Provider: InterceptProvider, Object: Today: , Format String: <null>
//    Provider: InterceptProvider, Object: Thursday, Format String: F
//    Today: : Thursday
//    
//    Provider: InterceptProvider, Object: 2, Format String: X
//    Provider: InterceptProvider, Object: 12, Format String: <null>
//    Provider: InterceptProvider, Object: 199, Format String: <null>
//    2, 12, 199
//    
//    Provider: InterceptProvider, Object: 2, Format String: R
//    Provider: InterceptProvider, Object: 12, Format String: R
//    Provider: InterceptProvider, Object: 199, Format String: R
//    II, XII, CXCIX
using System;
using System.Globalization;

public class InterceptProvider : IFormatProvider, ICustomFormatter
{
   public object GetFormat(Type formatType)
   {
      if (formatType == typeof(ICustomFormatter))
         return this;
      else
         return null;
   }
   
   public string Format(String format, Object obj, IFormatProvider provider) 
   {
      // Display information about method call.
      string formatString = format ?? "<null>";
      Console.WriteLine("Provider: {0}, Object: {1}, Format String: {2}",
                        provider.GetType().Name, obj ?? "<null>", formatString);
                        
      if (obj == null) return String.Empty;
            
      // If this is a byte and the "R" format string, format it with Roman numerals.
      if (obj is Byte && formatString.ToUpper().Equals("R")) {
         Byte value = (Byte) obj;
         int remainder;
         int result;
         String returnString = String.Empty;

         // Get the hundreds digit(s)
         result = Math.DivRem(value, 100, out remainder);
         if (result > 0)  
            returnString = new String('C', result);
         value = (Byte) remainder;
         // Get the 50s digit
         result = Math.DivRem(value, 50, out remainder);
         if (result == 1)
            returnString += "L";
         value = (Byte) remainder;
         // Get the tens digit.
         result = Math.DivRem(value, 10, out remainder);
         if (result > 0)
            returnString += new String('X', result);
         value = (Byte) remainder; 
         // Get the fives digit.
         result = Math.DivRem(value, 5, out remainder);
         if (result > 0)
            returnString += "V";
         value = (Byte) remainder;
         // Add the ones digit.
         if (remainder > 0) 
            returnString += new String('I', remainder);
         
         // Check whether we have too many X characters.
         int pos = returnString.IndexOf("XXXX");
         if (pos >= 0) {
            int xPos = returnString.IndexOf("L"); 
            if (xPos >= 0 & xPos == pos - 1)
               returnString = returnString.Replace("LXXXX", "XC");
            else
               returnString = returnString.Replace("XXXX", "XL");   
         }
         // Check whether we have too many I characters
         pos = returnString.IndexOf("IIII");
         if (pos >= 0)
            if (returnString.IndexOf("V") >= 0)
               returnString = returnString.Replace("VIIII", "IX");
            else
               returnString = returnString.Replace("IIII", "IV");    

         return returnString; 
      }   

      // Use default for all other formatting.
      if (obj is IFormattable)
         return ((IFormattable) obj).ToString(format, CultureInfo.CurrentCulture);
      else
         return obj.ToString();
   }
}

public class Example
{
   public static void Main()
   {
      int n = 10;
      double value = 16.935;
      DateTime day = DateTime.Now;
      InterceptProvider provider = new InterceptProvider();
      Console.WriteLine(String.Format(provider, "{0:N0}: {1:C2} on {2:d}\n", n, value, day));
      Console.WriteLine(String.Format(provider, "{0}: {1:F}\n", "Today: ", 
                                      (DayOfWeek) DateTime.Now.DayOfWeek));
      Console.WriteLine(String.Format(provider, "{0:X}, {1}, {2}\n", 
                                      (Byte) 2, (Byte) 12, (Byte) 199));
      Console.WriteLine(String.Format(provider, "{0:R}, {1:R}, {2:R}\n", 
                                      (Byte) 2, (Byte) 12, (Byte) 199));
   }
}
// The example displays the following output:
//    Provider: InterceptProvider, Object: 10, Format String: N0
//    Provider: InterceptProvider, Object: 16.935, Format String: C2
//    Provider: InterceptProvider, Object: 1/31/2013 6:10:28 PM, Format String: d
//    10: $16.94 on 1/31/2013
//    
//    Provider: InterceptProvider, Object: Today: , Format String: <null>
//    Provider: InterceptProvider, Object: Thursday, Format String: F
//    Today: : Thursday
//    
//    Provider: InterceptProvider, Object: 2, Format String: X
//    Provider: InterceptProvider, Object: 12, Format String: <null>
//    Provider: InterceptProvider, Object: 199, Format String: <null>
//    2, 12, 199
//    
//    Provider: InterceptProvider, Object: 2, Format String: R
//    Provider: InterceptProvider, Object: 12, Format String: R
//    Provider: InterceptProvider, Object: 199, Format String: R
//    II, XII, CXCIX
Imports System.Globalization

Public Class InterceptProvider : Implements IFormatProvider, ICustomFormatter
   Public Function GetFormat(formatType As Type) As Object _
         Implements IFormatProvider.GetFormat
      If formatType Is GetType(ICustomFormatter) Then
         Return Me
      Else
         Return Nothing
      End If
   End Function
   
   Public Function Format(fmt As String, obj As Object, provider As IFormatProvider) As String _
         Implements ICustomFormatter.Format

      Dim formatString As String = If(fmt IsNot Nothing, fmt, "<null>")
      Console.WriteLine("Provider: {0}, Object: {1}, Format String: {2}",
                        provider, If(obj IsNot Nothing, obj, "<null>"), formatString)

      If obj Is Nothing Then Return String.Empty
            
      ' If this is a byte and the "R" format string, format it with Roman numerals.
      If TypeOf(obj) Is Byte AndAlso formatString.ToUpper.Equals("R") Then
         Dim value As Byte = CByte(obj)
         Dim remainder As Integer
         Dim result As Integer
         Dim returnString As String = String.Empty

         ' Get the hundreds digit(s)
         result = Math.DivRem(value, 100, remainder)
         If result > 0 Then returnString = New String("C"c, result)
         value = CByte(remainder)
         ' Get the 50s digit
         result = Math.DivRem(value, 50, remainder)
         If result = 1 Then returnString += "L"
         value = CByte(remainder)
         ' Get the tens digit.
         result = Math.DivRem(value, 10, remainder)
         If result > 0 Then returnString += New String("X"c, result)
         value = CByte(remainder) 
         ' Get the fives digit.
         result = Math.DivRem(value, 5, remainder)
         If result > 0 Then returnString += "V"
         value = CByte(remainder)
         ' Add the ones digit.
         If remainder > 0 Then returnString += New String("I"c, remainder)
         
         ' Check whether we have too many X characters.
         Dim pos As Integer = returnString.IndexOf("XXXX")
         If pos >= 0 Then
            Dim xPos As Integer = returnString.IndexOf("L") 
            If xPos >= 0 And xPos = pos - 1 Then
               returnString = returnString.Replace("LXXXX", "XC")
            Else
               returnString = returnString.Replace("XXXX", "XL")   
            End If         
         End If
         ' Check whether we have too many I characters
         pos = returnString.IndexOf("IIII")
         If pos >= 0 Then
            If returnString.IndexOf("V") >= 0 Then
               returnString = returnString.Replace("VIIII", "IX")
            Else
               returnString = returnString.Replace("IIII", "IV")    
            End If
         End If
         Return returnString 
      End If   

      ' Use default for all other formatting.
      If obj Is GetType(IFormattable)
         Return CType(obj, IFormattable).ToString(fmt, CultureInfo.CurrentCulture)
      Else
         Return obj.ToString()
      End If
   End Function
End Class

Module Example
   Public Sub Main()
      Dim n As Integer = 10
      Dim value As Double = 16.935
      Dim day As DateTime = Date.Now
      Dim provider As New InterceptProvider()
      Console.WriteLine(String.Format(provider, "{0:N0}: {1:C2} on {2:d}", n, value, day))
      Console.WriteLine()
      Console.WriteLine(String.Format(provider, "{0}: {1:F}", "Today", 
                                      CType(Date.Now.DayOfWeek, DayOfWeek)))
      Console.WriteLine()
      Console.WriteLine(String.Format(provider, "{0:X}, {1}, {2}\n", 
                                      CByte(2), CByte(12), CByte(199)))
      Console.WriteLine()
      Console.WriteLine(String.Format(provider, "{0:R}, {1:R}, {2:R}", 
                                      CByte(2), CByte(12), CByte(199)))
   End Sub
End Module
' The example displays the following output:
'    Provider: InterceptProvider, Object: 10, Format String: N0
'    Provider: InterceptProvider, Object: 16.935, Format String: C2
'    Provider: InterceptProvider, Object: 1/31/2013 6:10:28 PM, Format String: d
'    10: $16.94 on 1/31/2013
'    
'    Provider: InterceptProvider, Object: Today: , Format String: <null>
'    Provider: InterceptProvider, Object: Thursday, Format String: F
'    Today: : Thursday
'    
'    Provider: InterceptProvider, Object: 2, Format String: X
'    Provider: InterceptProvider, Object: 12, Format String: <null>
'    Provider: InterceptProvider, Object: 199, Format String: <null>
'    2, 12, 199
'    
'    Provider: InterceptProvider, Object: 2, Format String: R
'    Provider: InterceptProvider, Object: 12, Format String: R
'    Provider: InterceptProvider, Object: 199, Format String: R
'    II, XII, CXCIX

String.Format Q & AString.Format Q & A

Por que você recomenda interpolação de cadeia de caracteres em chamadas para o String.Format método?Why do you recommend string interpolation over calls to the String.Format method?

Interpolação de cadeia de caracteres é:String interpolation is:

  • Mais flexível.More flexible. Ele pode ser usado em qualquer cadeia de caracteres sem a necessidade de uma chamada para um método que dá suporte à formatação de composição.It can be used in any string without requiring a call to a method that supports composite formatting. Caso contrário, você precisará chamar o Format método ou outro método que oferece suporte a formatação de composição, como Console.WriteLine ou StringBuilder.AppendFormat.Otherwise, you have to call the Format method or another method that supports composite formatting, such as Console.WriteLine or StringBuilder.AppendFormat.

  • Mais legível.More readable. Como a expressão a ser inserido em uma cadeia de caracteres aparece na expressão interpolada em vez de em uma lista de argumentos, cadeias de caracteres interpoladas são muito mais fácil para o código e ler.Because the expression to insert into a string appears in the interpolated expression rather than in a argument list, interpolated strings are far easier to code and to read. Devido a sua maior legibilidade, cadeias de caracteres interpoladas podem substituir não apenas as chamadas para métodos de formato composto, mas eles também podem ser usados em operações de concatenação de cadeia de caracteres para produzir um código mais conciso e mais claro.Because of their greater readability, interpolated strings can replace not only calls to composite format methods, but they can also be used in string concatenation operations to produce more concise, clearer code.

Uma comparação dos seguintes exemplos de código ilustra a superioridade do cadeias de caracteres interpoladas ao longo de concatenação de cadeia de caracteres e chamadas para métodos de formatação de composição.A comparison of the following two code examples illustrates the superiority of interpolated strings over string concatenation and calls to composite formatting methods. O uso de várias operações de concatenação de cadeia de caracteres no exemplo a seguir produz código detalhado e difícil de ler.The use of multiple string concatenation operations in the following example produces verbose and hard-to-read code.

string[] names = { "Balto", "Vanya", "Dakota", "Samuel", "Koani", "Yiska", "Yuma" };
string output = names[0] + ", " + names[1] + ", " + names[2] + ", " + 
                names[3] + ", " + names[4] + ", " + names[5] + ", " + 
                names[6];  

output += "\n";  
var date = DateTime.Now;
output += String.Format("It is {0:t} on {0:d}. The day of the week is {1}.", 
                        date, date.DayOfWeek);
Console.WriteLine(output);                           
// The example displays the following output:
//     Balto, Vanya, Dakota, Samuel, Koani, Yiska, Yuma
//     It is 10:29 AM on 1/8/2018. The day of the week is Monday.

Module Example
   Public Sub Main()
      Dim names = { "Balto", "Vanya", "Dakota", "Samuel", "Koani", "Yiska", "Yuma" }
      Dim output = names(0) + ", " + names(1) + ", " + names(2) + ", " + 
                   names(3) + ", " + names(4) + ", " + names(5) + ", " + 
                   names(6)  
    
      output += vbCrLf  
      Dim dat = DateTime.Now
      output += String.Format("It is {0:t} on {0:d}. The day of the week is {1}.", 
                              dat, dat.DayOfWeek)
      Console.WriteLine(output)                           
   End Sub
End Module
' The example displays the following output:
'     Balto, Vanya, Dakota, Samuel, Koani, Yiska, Yuma
'     It is 10:29 AM on 1/8/2018. The day of the week is Monday.


Em contraste, o uso de cadeias de caracteres interpoladas no exemplo a seguir produz código mais conciso e bem mais claro que a instrução de concatenação de cadeia de caracteres e a chamada para o Format método no exemplo anterior.In contrast, the use of interpolated strings in the following example produce much clearer, more concise code than the string concatenation statement and the call to the Format method in the previous example.

string[] names = { "Balto", "Vanya", "Dakota", "Samuel", "Koani", "Yiska", "Yuma" };
string output = $"{names[0]}, {names[1]}, {names[2]}, {names[3]}, {names[4]}, " + 
                $"{names[5]}, {names[6]}";  

var date = DateTime.Now;
output += $"\nIt is {date:t} on {date:d}. The day of the week is {date.DayOfWeek}.";
Console.WriteLine(output);                           
// The example displays the following output:
//     Balto, Vanya, Dakota, Samuel, Koani, Yiska, Yuma
//     It is 10:29 AM on 1/8/2018. The day of the week is Monday.

Module Example
   Public Sub Main()
      Dim names = { "Balto", "Vanya", "Dakota", "Samuel", "Koani", "Yiska", "Yuma" }
      Dim output = $"{names(0)}, {names(1)}, {names(2)}, {names(3)}, {names(4)}, " + 
                   $"{names(5)}, {names(6)}"  
    
      Dim dat = DateTime.Now
      output += $"{vbCrLf}It is {dat:t} on {dat:d}. The day of the week is {dat.DayOfWeek}." 
      Console.WriteLine(output)                           
   End Sub
End Module
' The example displays the following output:
'     Balto, Vanya, Dakota, Samuel, Koani, Yiska, Yuma
'     It is 10:29 AM on 1/8/2018. The day of the week is Monday.


Onde posso encontrar uma lista de cadeias de caracteres de formato predefinido que pode ser usado com itens de formato?Where can I find a list of the predefined format strings that can be used with format items?

Como controlar o alinhamento das cadeias de caracteres resultado substituir itens de formato?How do I control the alignment of the result strings that replace format items?

A sintaxe geral de um item de formato é:The general syntax of a format item is:

{index[,alignment][: formatString]}  

em que alinhamento é um inteiro com sinal que define a largura do campo.where alignment is a signed integer that defines the field width. Se esse valor for negativo, o texto do campo é alinhado à esquerda.If this value is negative, text in the field is left-aligned. Se ele for positivo, o texto é alinhado à direita.If it is positive, text is right-aligned.

Como controlar o número de dígitos após o separador decimal?How do I control the number of digits after the decimal separator?

Todos os cadeias de caracteres de formato numérico padrão exceto "D" (que é usado com apenas números inteiros), "G", "R" e "X" permitir que um especificador de precisão que define o número de dígitos decimais na cadeia de caracteres de resultado.All standard numeric format strings except "D" (which is used with integers only), "G", "R", and "X" allow a precision specifier that defines the number of decimal digits in the result string. O exemplo a seguir usa cadeias de caracteres de formato numérico padrão para controlar o número de dígitos decimais na cadeia de caracteres de resultado.The following example uses standard numeric format strings to control the number of decimal digits in the result string.

object[] values = { 1603, 1794.68235, 15436.14 };
string result;
foreach (var value in values) {
   result = String.Format("{0,12:C2}   {0,12:E3}   {0,12:F4}   {0,12:N3}  {1,12:P2}\n",
                          Convert.ToDouble(value), Convert.ToDouble(value) / 10000);
   Console.WriteLine(result);
}                           
// The example displays output like the following:
//       $1,603.00     1.603E+003      1603.0000      1,603.000       16.03 %
//    
//       $1,794.68     1.795E+003      1794.6824      1,794.682       17.95 %
//    
//      $15,436.14     1.544E+004     15436.1400     15,436.140      154.36 %
Module Example
   Public Sub Main()
      Dim values() As Object = { 1603, 1794.68235, 15436.14 }
      Dim result As String
      For Each value In values
         result = String.Format("{0,12:C2}   {0,12:E3}   {0,12:F4}   {0,12:N3}  {1,12:P2}",
                                value, CDbl(value) / 10000)
         Console.WriteLine(result) 
         Console.WriteLine()
      Next                             
   End Sub
End Module
' The example displays the following output:
'       $1,603.00     1.603E+003      1603.0000      1,603.000       16.03 %
'    
'       $1,794.68     1.795E+003      1794.6824      1,794.682       17.95 %
'    
'      $15,436.14     1.544E+004     15436.1400     15,436.140      154.36 %

Se você estiver usando um cadeia de caracteres de formato numérico personalizado, use o especificador de formato "0" para controlar o número de dígitos decimais na cadeia de caracteres resultante, como mostra o exemplo a seguir.If you're using a custom numeric format string, use the "0" format specifier to control the number of decimal digits in the result string, as the following example shows.

decimal value = 16309.5436m;
string result = String.Format("{0,12:#.00000} {0,12:0,000.00} {0,12:000.00#}", 
                              value);
Console.WriteLine(result);
// The example displays the following output:
//        16309.54360    16,309.54    16309.544
Module Example
   Public Sub Main()
      Dim value As Decimal = 16309.5436d
      Dim result As String = String.Format("{0,12:#.00000} {0,12:0,000.00} {0,12:000.00#}", 
                                           value)
      Console.WriteLine(result)
   End Sub
End Module
' The example displays the following output:
'    16309.54360    16,309.54    16309.544

Como controlar o número de dígitos integrais?How do I control the number of integral digits?

Por padrão, operações de formatação exibem somente os dígitos integrais de diferente de zero.By default, formatting operations only display non-zero integral digits. Se você estiver formatando números inteiros, você pode usar um especificador de precisão com "D" e "X" cadeias de caracteres de formato padrão para controlar o número de dígitos.If you are formatting integers, you can use a precision specifier with the "D" and "X" standard format strings to control the number of digits.

int value = 1326;
string result = String.Format("{0,10:D6} {0,10:X8}", value);
Console.WriteLine(result);
// The example displays the following output:
//     001326   0000052E
Module Example
   Public Sub Main()
      Dim value As Integer = 1326
      Dim result As String = String.Format("{0,10:D6} {0,10:X8}", value)
      Console.WriteLine(result)
   End Sub
End Module
' The example displays the following output:
'       001326   0000052E

Você pode preencher um inteiro ou um número de ponto flutuante com zeros à esquerda para produzir uma cadeia de caracteres de resultado com um número especificado de dígitos integrais usando o "0" especificador de formato numérico personalizado, como mostra o exemplo a seguir.You can pad an integer or floating-point number with leading zeros to produce a result string with a specified number of integral digits by using the "0" custom numeric format specifier, as the following example shows.

int value = 16342;
string result = String.Format("{0,18:00000000} {0,18:00000000.000} {0,18:000,0000,000.0}", 
                              value);
Console.WriteLine(result);
// The example displays the following output:
//           00016342       00016342.000    0,000,016,342.0
Module Example
   Public Sub Main()
      Dim value As Integer = 16342
      Dim result As String = String.Format("{0,18:00000000} {0,18:00000000.000} {0,18:000,0000,000.0}", 
                                           value)
      Console.WriteLine(result)
   End Sub
End Module
' The example displays the following output:
'           00016342       00016342.000    0,000,016,342.0

Quantos itens podem incluir na lista formato?How many items can I include in the format list?

Não há nenhum limite prático.There is no practical limit. O segundo parâmetro do Format(IFormatProvider, String, Object[]) método é marcado com o ParamArrayAttribute atributo, que permite que você inclua uma lista delimitada por ponto ou uma matriz de objetos como sua lista de formato.The second parameter of the Format(IFormatProvider, String, Object[]) method is tagged with the ParamArrayAttribute attribute, which allows you to include either a delimited list or an object array as your format list.

Como incluir a chaves literais ("{" e "}") na cadeia de caracteres de resultado?How do I include literal braces ("{" and "}") in the result string?

Por exemplo, como evitar a seguinte chamada de método, gere um FormatException exceção?For example, how do you prevent the following method call from throwing a FormatException exception?

result = String.Format("The text has {0} '{' characters and {1} '}' characters.",
                       nOpen, nClose);
result = String.Format("The text has {0} '{' characters and {1} '}' characters.",
                       nOpen, nClose)

Um simples de abertura ou fechamento é sempre interpretado como o início ou final de um item de formato.A single opening or closing brace is always interpreted as the beginning or end of a format item. Para ser interpretado literalmente, ela deverá ser substituída.To be interpreted literally, it must be escaped. Você fazer o escape de uma chave com a adição de outra chave ("{{" e "}}" em vez de "{" e "}"), conforme mostrado no seguinte chamada de método:You escape a brace by adding another brace ("{{" and "}}" instead of "{" and "}"), as in the following method call:

string result;
int nOpen = 1;
int nClose = 2;
result = String.Format("The text has {0} '{{' characters and {1} '}}' characters.",
                       nOpen, nClose);
Console.WriteLine(result);
result = String.Format("The text has {0} '{{' characters and {1} '}}' characters.",
                       nOpen, nClose)

No entanto, as chaves de escape ainda são facilmente mal interpretadas.However, even escaped braces are easily misinterpreted. É recomendável que você inclua chaves na lista de formato e usa itens de formato para inseri-los na cadeia de caracteres de resultado, como mostra o exemplo a seguir.We recommend that you include braces in the format list and use format items to insert them in the result string, as the following example shows.

string result;
int nOpen = 1;
int nClose = 2;
result = String.Format("The text has {0} '{1}' characters and {2} '{3}' characters.",
                       nOpen, "{", nClose, "}");
Console.WriteLine(result);
result = String.Format("The text has {0} '{1}' characters and {2} '{3}' characters.",
                       nOpen, "{", nClose, "}")

Por que minha chamada ao método String. Format lança uma FormatException?Why does my call to the String.Format method throw a FormatException?

A causa mais comum da exceção é que o índice de um item de formato não corresponde a um objeto na lista de formato.The most common cause of the exception is that the index of a format item doesn't correspond to an object in the format list. Normalmente, isso indica que você já misnumbered os índices dos itens de formato ou você esqueceu de incluir um objeto na lista de formato.Usually this indicates that you've misnumbered the indexes of format items or you've forgotten to include an object in the format list. A tentativa de incluir uma chave esquerda ou direita sem escape caractere também gera um FormatException.Attempting to include an unescaped left or right brace character also throws a FormatException. Ocasionalmente, a exceção é o resultado de um erro de digitação; Por exemplo, um erro típico é incorretamente "[" (o colchete esquerdo), em vez de "{" (a chave à esquerda).Occasionally, the exception is the result of a typo; for example, a typical mistake is to mistype "[" (the left bracket) instead of "{" (the left brace).

Se o método Format(System.IFormatProvider,System.String,System.Object[]) dá suporte a matrizes de parâmetro, por que meu código lançar uma exceção quando eu uso uma matriz?If the Format(System.IFormatProvider,System.String,System.Object[]) method supports parameter arrays, why does my code throw an exception when I use an array?

Por exemplo, o código a seguir gera um FormatException exceção:For example, the following code throws a FormatException exception:

Random rnd = new Random();
int[]  numbers = new int[4];
int total = 0;
for (int ctr = 0; ctr <= 2; ctr++) {
   int number = rnd.Next(1001);
   numbers[ctr] = number;
   total += number;
}   
numbers[3] = total;
Console.WriteLine("{0} + {1} + {2} = {3}", numbers);   
Imports System.Collections.Generic

Module Example
   Public Sub Main()
      Dim rnd As New Random()
      Dim numbers(3) As Integer
      Dim total As Integer = 0
      For ctr = 0 To 2
         Dim number As Integer = rnd.Next(1001)
         numbers(ctr) = number
         total += number
      Next
      numbers(3) = total
      Console.WriteLine("{0} + {1} + {2} = {3}", numbers)   
   End Sub
End Module

Este é um problema de resolução de sobrecarga do compilador.This is a problem of compiler overload resolution. Porque o compilador não pode converter uma matriz de inteiros em uma matriz de objetos, ele trata a matriz de inteiros como um único argumento, para que ele chama o Format(String, Object) método.Because the compiler cannot convert an array of integers to an object array, it treats the integer array as a single argument, so it calls the Format(String, Object) method. A exceção é gerada porque há quatro itens de formato, mas apenas um único item na lista de formato.The exception is thrown because there are four format items but only a single item in the format list.

Como o Visual Basic nem c# pode converter uma matriz de inteiros para uma matriz de objetos, você precisa executar a conversão antes de chamar o Format(String, Object[]) método.Because neither Visual Basic nor C# can convert an integer array to an object array, you have to perform the conversion yourself before calling the Format(String, Object[]) method. O exemplo a seguir fornece uma implementação.The following example provides one implementation.

Random rnd = new Random();
int[]  numbers = new int[4];
int total = 0;
for (int ctr = 0; ctr <= 2; ctr++) {
   int number = rnd.Next(1001);
   numbers[ctr] = number;
   total += number;
}   
numbers[3] = total;
object[] values = new object[numbers.Length];
numbers.CopyTo(values, 0);
Console.WriteLine("{0} + {1} + {2} = {3}", values);   
Imports System.Collections.Generic

Module Example
   Public Sub Main()
      Dim rnd As New Random()
      Dim numbers(3) As Integer
      Dim total As Integer = 0
      For ctr = 0 To 2
         Dim number As Integer = rnd.Next(1001)
         numbers(ctr) = number
         total += number
      Next
      numbers(3) = total
      Dim values(numbers.Length - 1) As Object
      numbers.CopyTo(values, 0) 
      Console.WriteLine("{0} + {1} + {2} = {3}", values)   
   End Sub
End Module

Format(String, Object) Format(String, Object) Format(String, Object) Format(String, Object)

Substitui um ou mais itens de formato em uma cadeia de caracteres pela representação de cadeia de caracteres de um objeto especificado.Replaces one or more format items in a string with the string representation of a specified object.

public:
 static System::String ^ Format(System::String ^ format, System::Object ^ arg0);
public static string Format (string format, object arg0);
static member Format : string * obj -> string
Public Shared Function Format (format As String, arg0 As Object) As String

Parâmetros

arg0
Object Object Object Object

O objeto a ser formatado.The object to format.

Retornos

Uma cópia do format na qual os itens de formato são substituídos pela representação de cadeia de caracteres de arg0.A copy of format in which any format items are replaced by the string representation of arg0.

Exceções

O item de formato em format é inválido.The format item in format is invalid.

- ou --or- O índice de um item de formato não é zero.The index of a format item is not zero.

Comentários

Importante

Em vez de chamar o método String.Format ou usar cadeias de caracteres de formato de composição, é possível usar cadeias de caracteres interpoladas quando a linguagem é compatível com eles.Instead of calling the String.Format method or using composite format strings, you can use interpolated strings if your language supports them. Uma cadeia de caracteres interpolada é uma cadeia de caracteres que contém expressões interpoladas.An interpolated string is a string that contains interpolated expressions. Cada expressão interpolada é resolvida com o valor da expressão e incluída na cadeia de caracteres resultante quando a cadeia de caracteres é atribuída.Each interpolated expression is resolved with the expression's value and included in the result string when the string is assigned. Para saber mais, consulte o tópico Interpolação de cadeia de caracteres (Referência do C#) ou Cadeias de caracteres interpoladas (Referência do Visual Basic).For more information, see String interpolation (C# Reference) and Interpolated Strings (Visual Basic Reference).

Esse método usa o recurso de formatação composta para converter o valor de uma expressão em sua representação de cadeia de caracteres e inserir essa representação em uma cadeia de caracteres.This method uses the composite formatting feature to convert the value of an expression to its string representation and to embed that representation in a string.

Entretanto, ao chamar o método String.Format, não é necessário se concentrar na sobrecarga específica que você deseja chamar.However, when calling the String.Format method, it is not necessary to focus on the particular overload that you want to call. Em vez disso, é possível chamar o método com uma cadeia de caracteres de formato composto que inclui um ou mais itens de formato.Instead, you can call the method with a composite format string that includes one or more format items. Você atribui a cada item de formato um índice numérico. O primeiro índice começa em 0.You assign each format item a numeric index; the first index starts at 0. Além da cadeia de caracteres inicial, sua chamada de método deve ter tantos argumentos adicionais quantos valores de índice.In addition to the initial string, your method call should have as many additional arguments as it has index values. Por exemplo, uma cadeia de caracteres cujos itens de formato têm índices 0 e 1 deve ter 2 argumentos; uma com índices de 0 a 5 deve ter 6 argumentos.For example, a string whose format items have indexes of 0 and 1 should have 2 arguments; one with indexes 0 through 5 should have 6 arguments. O compilador de linguagem, então, resolverá a chamada de método para uma sobrecarga específica do método String.Format.Your language compiler will then resolve your method call to a particular overload of the String.Format method.

Para obter uma documentação mais detalhada sobre como usar o método String.Format, consulte o Guia de Introdução ao método String.Format e Qual método chamar?.For more detailed documentation on using the String.Format method, see Getting started with the String.Format method and Which method do I call?.

Exemplo: Formatando um único argumentoExample: Formatting a single argument

O exemplo a seguir usa o Format(String, Object) método para inserir a idade de um indivíduo no meio de uma cadeia de caracteres.The following example uses the Format(String, Object) method to embed an individual's age in the middle of a string.

using namespace System;

void main()
{
   DateTime birthdate = DateTime(1993, 7, 28);
   array<DateTime>^ dates = gcnew array<DateTime> { DateTime(1993, 8, 16), 
                                                    DateTime(1994, 7, 28), 
                                                    DateTime(2000, 10, 16), 
                                                    DateTime(2003, 7, 27), 
                                                    DateTime(2007, 5, 27) };

   for each (DateTime dateValue in dates)
   {
      TimeSpan interval = dateValue - birthdate;
      // Get the approximate number of years, without accounting for leap years.
      int years = ((int)interval.TotalDays) / 365;
      // See if adding the number of years exceeds dateValue.
      String^ output;
      if (birthdate.AddYears(years) <= dateValue) {
         output = String::Format("You are now {0} years old.", years);
         Console::WriteLine(output);
      }   
      else {
         output = String::Format("You are now {0} years old.", years - 1);
         Console::WriteLine(output);
      }      
   }
}
// The example displays the following output:
//       You are now 0 years old.
//       You are now 1 years old.
//       You are now 7 years old.
//       You are now 9 years old.
//       You are now 13 years old.
DateTime birthdate = new DateTime(1993, 7, 28);
DateTime[] dates = { new DateTime(1993, 8, 16), 
                     new DateTime(1994, 7, 28), 
                     new DateTime(2000, 10, 16), 
                     new DateTime(2003, 7, 27), 
                     new DateTime(2007, 5, 27) };

foreach (DateTime dateValue in dates)
{
   TimeSpan interval = dateValue - birthdate;
   // Get the approximate number of years, without accounting for leap years.
   int years = ((int) interval.TotalDays) / 365;
   // See if adding the number of years exceeds dateValue.
   string output;
   if (birthdate.AddYears(years) <= dateValue) {
      output = String.Format("You are now {0} years old.", years);
      Console.WriteLine(output);
   }   
   else {
      output = String.Format("You are now {0} years old.", years - 1);
      Console.WriteLine(output);
   }      
}
// The example displays the following output:
//       You are now 0 years old.
//       You are now 1 years old.
//       You are now 7 years old.
//       You are now 9 years old.
//       You are now 13 years old.
Module Example
   Public Sub Main()
      Dim birthdate As Date = #7/28/1993#
      Dim dates() As Date = { #9/16/1993#, #7/28/1994#, #10/16/2000#, _
                              #7/27/2003#, #5/27/2007# }
      For Each dateValue As Date In dates
         Dim interval As TimeSpan = dateValue - birthdate
         ' Get the approximate number of years, without accounting for leap years.
         Dim years As Integer = CInt(interval.TotalDays) \ 365
         ' See if adding the number of years exceeds dateValue.
         Dim output As String
         If birthdate.AddYears(years) <= dateValue Then
            output = String.Format("You are now {0} years old.", years)
            Console.WriteLine(output)
         Else
            output = String.Format("You are now {0} years old.", years - 1)
            Console.WriteLine(output)   
         End If
      Next
   End Sub
End Module
' The example displays the following output:
'       You are now 0 years old.
'       You are now 1 years old.
'       You are now 7 years old.
'       You are now 9 years old.
'       You are now 13 years old.
Veja também

Format(String, Object[]) Format(String, Object[]) Format(String, Object[]) Format(String, Object[])

Substitui o item de formato em uma cadeia de caracteres especificada pela representação de cadeia de caracteres de um objeto correspondente em uma matriz especificada.Replaces the format item in a specified string with the string representation of a corresponding object in a specified array.

public:
 static System::String ^ Format(System::String ^ format, ... cli::array <System::Object ^> ^ args);
public static string Format (string format, params object[] args);
static member Format : string * obj[] -> string
Public Shared Function Format (format As String, ParamArray args As Object()) As String

Parâmetros

args
Object[]

Uma matriz de objetos que contém zero ou mais objetos a serem formatados.An object array that contains zero or more objects to format.

Retornos

Uma cópia do format na qual os itens de formato foram substituídos pela representação de cadeia de caracteres dos objetos correspondentes no args.A copy of format in which the format items have been replaced by the string representation of the corresponding objects in args.

Exceções

format é inválido.format is invalid.

- ou --or- O índice de um item de formato é menor que zero, ou maior ou igual ao tamanho da matriz args.The index of a format item is less than zero, or greater than or equal to the length of the args array.

Comentários

Importante

Em vez de chamar o método String.Format ou usar cadeias de caracteres de formato de composição, é possível usar cadeias de caracteres interpoladas quando a linguagem é compatível com eles.Instead of calling the String.Format method or using composite format strings, you can use interpolated strings if your language supports them. Uma cadeia de caracteres interpolada é uma cadeia de caracteres que contém expressões interpoladas.An interpolated string is a string that contains interpolated expressions. Cada expressão interpolada é resolvida com o valor da expressão e incluída na cadeia de caracteres resultante quando a cadeia de caracteres é atribuída.Each interpolated expression is resolved with the expression's value and included in the result string when the string is assigned. Para saber mais, consulte o tópico Interpolação de cadeia de caracteres (Referência do C#) ou Cadeias de caracteres interpoladas (Referência do Visual Basic).For more information, see String interpolation (C# Reference) and Interpolated Strings (Visual Basic Reference).

Esse método usa o recurso de formatação composta para converter o valor de quatro ou mais expressões em suas representações de cadeia de caracteres e incorporar essas representações em uma cadeia de caracteres.This method uses the composite formatting feature to convert the value of four or more expressions to their string representations and to embed those representations in a string. Uma vez que o args parâmetro é marcado com o System.ParamArrayAttribute atributo, você pode passar os objetos para o método como argumentos individuais ou como um Object matriz.Since the args parameter is marked with the System.ParamArrayAttribute attribute, you can pass the objects to the method as individual arguments or as an Object array.

Entretanto, ao chamar o método String.Format, não é necessário se concentrar na sobrecarga específica que você deseja chamar.However, when calling the String.Format method, it is not necessary to focus on the particular overload that you want to call. Em vez disso, é possível chamar o método com uma cadeia de caracteres de formato composto que inclui um ou mais itens de formato.Instead, you can call the method with a composite format string that includes one or more format items. Você atribui a cada item de formato um índice numérico. O primeiro índice começa em 0.You assign each format item a numeric index; the first index starts at 0. Além da cadeia de caracteres inicial, sua chamada de método deve ter tantos argumentos adicionais quantos valores de índice.In addition to the initial string, your method call should have as many additional arguments as it has index values. Por exemplo, uma cadeia de caracteres cujos itens de formato têm índices 0 e 1 deve ter 2 argumentos; uma com índices de 0 a 5 deve ter 6 argumentos.For example, a string whose format items have indexes of 0 and 1 should have 2 arguments; one with indexes 0 through 5 should have 6 arguments. O compilador de linguagem, então, resolverá a chamada de método para uma sobrecarga específica do método String.Format.Your language compiler will then resolve your method call to a particular overload of the String.Format method.

Para obter uma documentação mais detalhada sobre como usar o método String.Format, consulte o Guia de Introdução ao método String.Format e Qual método chamar?.For more detailed documentation on using the String.Format method, see Getting started with the String.Format method and Which method do I call?.

Exemplo: Formatando mais de três argumentosExample: Formatting more than three arguments

Este exemplo cria uma cadeia de caracteres que contém dados sobre a temperatura alta e baixa em uma determinada data.This example creates a string that contains data on the high and low temperature on a particular date. A cadeia de caracteres de formato de composição tem cinco itens de formato no exemplo de c# e seis no exemplo do Visual Basic.The composite format string has five format items in the C# example and six in the Visual Basic example. Dois dos itens de formato definem a largura da representação de cadeia de caracteres do valor de seu correspondente e o primeiro item de formato também inclui um padrão de data e a cadeia de caracteres de formato de hora.Two of the format items define the width of their corresponding value's string representation, and the first format item also includes a standard date and time format string.

using namespace System;

void main()
{
   DateTime date1 = DateTime(2009, 7, 1);
   TimeSpan hiTime = TimeSpan(14, 17, 32);
   Decimal hiTemp = (Decimal) 62.1; 
   TimeSpan loTime = TimeSpan(3, 16, 10);
   Decimal loTemp = (Decimal)54.8; 

   String^ result1 = String::Format("Temperature on {0:d}:\n{1,11}: {2} degrees (hi)\n{3,11}: {4} degrees (lo)", 
                                    date1, hiTime, hiTemp, loTime, loTemp);
   Console::WriteLine(result1);
   Console::WriteLine();
           
   String^ result2 = String::Format("Temperature on {0:d}:\n{1,11}: {2} degrees (hi)\n{3,11}: {4} degrees (lo)", 
                                    gcnew array<Object^> { date1, hiTime, hiTemp, loTime, loTemp });
   Console::WriteLine(result2);
}
// The example displays the following output:
//       Temperature on 7/1/2009:
//          14:17:32: 62.1 degrees (hi)
//          03:16:10: 54.8 degrees (lo)
//       Temperature on 7/1/2009:
//          14:17:32: 62.1 degrees (hi)
//          03:16:10: 54.8 degrees (lo)
DateTime date1 = new DateTime(2009, 7, 1);
TimeSpan hiTime = new TimeSpan(14, 17, 32);
decimal hiTemp = 62.1m; 
TimeSpan loTime = new TimeSpan(3, 16, 10);
decimal loTemp = 54.8m; 

string result1 = String.Format("Temperature on {0:d}:\n{1,11}: {2} degrees (hi)\n{3,11}: {4} degrees (lo)", 
                               date1, hiTime, hiTemp, loTime, loTemp);
Console.WriteLine(result1);
Console.WriteLine();
     
string result2 = String.Format("Temperature on {0:d}:\n{1,11}: {2} degrees (hi)\n{3,11}: {4} degrees (lo)", 
                               new object[] { date1, hiTime, hiTemp, loTime, loTemp });
Console.WriteLine(result2);
// The example displays output like the following:
//       Temperature on 7/1/2009:
//          14:17:32: 62.1 degrees (hi)
//          03:16:10: 54.8 degrees (lo)
//       Temperature on 7/1/2009:
//          14:17:32: 62.1 degrees (hi)
//          03:16:10: 54.8 degrees (lo)
Module Example
   Public Sub Main()
      Dim date1 As Date = #7/1/2009#
      Dim hiTime As New TimeSpan(14, 17, 32)
      Dim hiTemp As Decimal = 62.1d 
      Dim loTime As New TimeSpan(3, 16, 10)
      Dim loTemp As Decimal = 54.8d 

      Dim result1 As String = String.Format("Temperature on {0:d}:{5}{1,11}: {2} degrees (hi){5}{3,11}: {4} degrees (lo)", _
                                           date1, hiTime, hiTemp, loTime, loTemp, vbCrLf)
      Console.WriteLine(result1)
      Console.WriteLine()
           
      Dim result2 As String = String.Format("Temperature on {0:d}:{5}{1,11}: {2} degrees (hi){5}{3,11}: {4} degrees (lo)", _
                                            New Object() { date1, hiTime, hiTemp, loTime, loTemp, vbCrLf })
      Console.WriteLine(result2)                                            
   End Sub
End Module
' The example displays the following output:
'       Temperature on 7/1/2009:
'          14:17:32: 62.1 degrees (hi)
'          03:16:10: 54.8 degrees (lo)
'
'       Temperature on 7/1/2009:
'          14:17:32: 62.1 degrees (hi)
'          03:16:10: 54.8 degrees (lo)

Você também pode passar os objetos a serem formatados como uma matriz em vez de uma lista de argumentos.You can also pass the objects to be formatted as an array rather than as an argument list.

using namespace System;

ref class CityInfo
{
public:
   CityInfo(String^ name, int population, Decimal area, int year)
   {
      this->Name = name;
      this->Population = population;
      this->Area = area;
      this->Year = year;
   }
   
   String^ Name; 
   int Population;
   Decimal Area;
   int Year;
};

ref class Example
{
public:
   static void ShowPopulationData(CityInfo^ city)
   {
      array<Object^>^ args = gcnew array<Object^> { city->Name, city->Year, city->Population, city->Area };
      String^ result = String::Format("{0} in {1}: Population {2:N0}, Area {3:N1} sq. feet", 
                                    args);
      Console::WriteLine(result); 
   }
};

void main()
{
   CityInfo^ nyc2010 = gcnew CityInfo("New York", 8175133, (Decimal) 302.64, 2010);
   Example::ShowPopulationData(nyc2010);
   CityInfo^ sea2010 = gcnew CityInfo("Seattle", 608660, (Decimal) 83.94, 2010);      
   Example::ShowPopulationData(sea2010); 
}
// The example displays the following output:
//       New York in 2010: Population 8,175,133, Area 302.6 sq. feet
//       Seattle in 2010: Population 608,660, Area 83.9 sq. feet
using System;

public class CityInfo
{
   public CityInfo(String name, int population, Decimal area, int year)
   {
      this.Name = name;
      this.Population = population;
      this.Area = area;
      this.Year = year;
   }
   
   public readonly String Name; 
   public readonly int Population;
   public readonly Decimal Area;
   public readonly int Year;
}

public class Example
{
   public static void Main()
   {
      CityInfo nyc2010 = new CityInfo("New York", 8175133, 302.64m, 2010);
      ShowPopulationData(nyc2010);
      CityInfo sea2010 = new CityInfo("Seattle", 608660, 83.94m, 2010);      
      ShowPopulationData(sea2010); 
   }

   private static void ShowPopulationData(CityInfo city)
   {
      object[] args = { city.Name, city.Year, city.Population, city.Area };
      String result = String.Format("{0} in {1}: Population {2:N0}, Area {3:N1} sq. feet", 
                                    args);
      Console.WriteLine(result); 
   }
}
// The example displays the following output:
//       New York in 2010: Population 8,175,133, Area 302.6 sq. feet
//       Seattle in 2010: Population 608,660, Area 83.9 sq. feet
Public Class CityInfo
   Public Sub New(name As String, population As Integer, area As Decimal, year As Integer)
      Me.Name = name
      Me.Population = population
      Me.Area = area
      Me.Year = year
   End Sub
   
   Public ReadOnly Name As String
   Public ReadOnly Population As Integer
   Public ReadOnly Area As Decimal
   Public ReadOnly Year As Integer
End Class

Module Example
   Public Sub Main()
      Dim nyc2010 As New CityInfo("New York", 8175133, 302.64d, 2010)
      ShowPopulationData(nyc2010)
      Dim sea2010 As New CityInfo("Seattle", 608660, 83.94d, 2010)      
      ShowPopulationData(sea2010) 
   End Sub
   
   Private Sub ShowPopulationData(city As CityInfo)
      Dim args() As Object = { city.Name, city.Year, city.Population, city.Area }
      Dim result = String.Format("{0} in {1}: Population {2:N0}, Area {3:N1} sq. feet", args)
      Console.WriteLine(result) 
   End Sub
End Module
' The example displays the following output:
'       New York in 2010: Population 8,175,133, Area 302.6 sq. feet
'       Seattle in 2010: Population 608,660, Area 83.9 sq. feet   
Veja também

Format(IFormatProvider, String, Object) Format(IFormatProvider, String, Object) Format(IFormatProvider, String, Object) Format(IFormatProvider, String, Object)

Substitui o item ou itens de formato em uma cadeia de caracteres especificada pela representação de cadeia de caracteres do objeto correspondente.Replaces the format item or items in a specified string with the string representation of the corresponding object. Um parâmetro fornece informações de formatação específicas da cultura.A parameter supplies culture-specific formatting information.

public:
 static System::String ^ Format(IFormatProvider ^ provider, System::String ^ format, System::Object ^ arg0);
public static string Format (IFormatProvider provider, string format, object arg0);
static member Format : IFormatProvider * string * obj -> string
Public Shared Function Format (provider As IFormatProvider, format As String, arg0 As Object) As String

Parâmetros

provider
IFormatProvider IFormatProvider IFormatProvider IFormatProvider

Um objeto que fornece informações de formatação específicas de cultura.An object that supplies culture-specific formatting information.

arg0
Object Object Object Object

O objeto a ser formatado.The object to format.

Retornos

Uma cópia do format na qual o item ou itens de formato foram substituídos pela representação de cadeia de caracteres do arg0.A copy of format in which the format item or items have been replaced by the string representation of arg0.

Exceções

format é inválido.format is invalid.

- ou --or- O índice de um item de formato não é zero.The index of a format item is not zero.

Comentários

Importante

Em vez de chamar o método String.Format ou usar cadeias de caracteres de formato de composição, é possível usar cadeias de caracteres interpoladas quando a linguagem é compatível com eles.Instead of calling the String.Format method or using composite format strings, you can use interpolated strings if your language supports them. Uma cadeia de caracteres interpolada é uma cadeia de caracteres que contém expressões interpoladas.An interpolated string is a string that contains interpolated expressions. Cada expressão interpolada é resolvida com o valor da expressão e incluída na cadeia de caracteres resultante quando a cadeia de caracteres é atribuída.Each interpolated expression is resolved with the expression's value and included in the result string when the string is assigned. Para saber mais, consulte o tópico Interpolação de cadeia de caracteres (Referência do C#) ou Cadeias de caracteres interpoladas (Referência do Visual Basic).For more information, see String interpolation (C# Reference) and Interpolated Strings (Visual Basic Reference).

Esse método usa o recurso de formatação composta para converter o valor de uma expressão em sua representação de cadeia de caracteres e inserir essa representação em uma cadeia de caracteres.This method uses the composite formatting feature to convert the value of an expression to its string representation and to embed that representation in a string. Na execução da conversão, o método usa formatação sensível à cultura ou um formatador personalizado.In performing the conversion, the method uses culture-sensitive formatting or a custom formatter. O método converte arg0 em sua representação de cadeia de caracteres chamando seus ToString(IFormatProvider) método ou, se o objeto a correspondente do item de formato inclui uma cadeia de caracteres de formato, chamando seu ToString ( String, IFormatProvider) método.The method converts arg0 to its string representation by calling its ToString(IFormatProvider) method or, if the object's corresponding format item includes a format string, by calling its ToString(String,IFormatProvider) method. Se esses métodos não existirem, ele chama o objeto sem parâmetros ToString método.If these methods don't exist, it calls the object's parameterless ToString method.

Entretanto, ao chamar o método String.Format, não é necessário se concentrar na sobrecarga específica que você deseja chamar.However, when calling the String.Format method, it is not necessary to focus on the particular overload that you want to call. Em vez disso, é possível chamar o método com um objeto que fornece formatação personalizada ou sensível à cultura e uma cadeia de caracteres de formato composto que inclui um ou mais itens de formato.Instead, you can call the method with an object that provides culture-sensitive or custom formatting and a composite format string that includes one or more format items. Você atribui a cada item de formato um índice numérico. O primeiro índice começa em 0.You assign each format item a numeric index; the first index starts at 0. Além da cadeia de caracteres inicial, sua chamada de método deve ter tantos argumentos adicionais quantos valores de índice.In addition to the initial string, your method call should have as many additional arguments as it has index values. Por exemplo, uma cadeia de caracteres cujos itens de formato têm índices 0 e 1 deve ter 2 argumentos; uma com índices de 0 a 5 deve ter 6 argumentos.For example, a string whose format items have indexes of 0 and 1 should have 2 arguments; one with indexes 0 through 5 should have 6 arguments. O compilador de linguagem, então, resolverá a chamada de método para uma sobrecarga específica do método String.Format.Your language compiler will then resolve your method call to a particular overload of the String.Format method.

Para obter uma documentação mais detalhada sobre como usar o método String.Format, consulte o Guia de Introdução ao método String.Format e Qual método chamar?.For more detailed documentation on using the String.Format method, see Getting started with the String.Format method and Which method do I call?.

Format(IFormatProvider, String, Object[]) Format(IFormatProvider, String, Object[]) Format(IFormatProvider, String, Object[]) Format(IFormatProvider, String, Object[])

Substitui os itens de formato em uma cadeia de caracteres pelas representações cadeia de caracteres de objetos correspondentes em uma matriz especificada.Replaces the format items in a string with the string representations of corresponding objects in a specified array. Um parâmetro fornece informações de formatação específicas da cultura.A parameter supplies culture-specific formatting information.

public:
 static System::String ^ Format(IFormatProvider ^ provider, System::String ^ format, ... cli::array <System::Object ^> ^ args);
public static string Format (IFormatProvider provider, string format, params object[] args);
static member Format : IFormatProvider * string * obj[] -> string
Public Shared Function Format (provider As IFormatProvider, format As String, ParamArray args As Object()) As String

Parâmetros

provider
IFormatProvider IFormatProvider IFormatProvider IFormatProvider

Um objeto que fornece informações de formatação específicas de cultura.An object that supplies culture-specific formatting information.

args
Object[]

Uma matriz de objetos que contém zero ou mais objetos a serem formatados.An object array that contains zero or more objects to format.

Retornos

Uma cópia do format na qual os itens de formato foram substituídos pela representação de cadeia de caracteres dos objetos correspondentes no args.A copy of format in which the format items have been replaced by the string representation of the corresponding objects in args.

Exceções

format é inválido.format is invalid.

- ou --or- O índice de um item de formato é menor que zero, ou maior ou igual ao tamanho da matriz args.The index of a format item is less than zero, or greater than or equal to the length of the args array.

Comentários

Importante

Em vez de chamar o método String.Format ou usar cadeias de caracteres de formato de composição, é possível usar cadeias de caracteres interpoladas quando a linguagem é compatível com eles.Instead of calling the String.Format method or using composite format strings, you can use interpolated strings if your language supports them. Uma cadeia de caracteres interpolada é uma cadeia de caracteres que contém expressões interpoladas.An interpolated string is a string that contains interpolated expressions. Cada expressão interpolada é resolvida com o valor da expressão e incluída na cadeia de caracteres resultante quando a cadeia de caracteres é atribuída.Each interpolated expression is resolved with the expression's value and included in the result string when the string is assigned. Para saber mais, consulte o tópico Interpolação de cadeia de caracteres (Referência do C#) ou Cadeias de caracteres interpoladas (Referência do Visual Basic).For more information, see String interpolation (C# Reference) and Interpolated Strings (Visual Basic Reference).

Esse método usa o recurso de formatação composta para converter quatro ou mais expressões em suas representações de cadeia de caracteres e incorporar essas representações em uma cadeia de caracteres.This method uses the composite formatting feature to convert four or more expressions to their string representations and to embed those representations in a string. Na execução da conversão, o método usa formatação sensível à cultura ou um formatador personalizado.In performing the conversion, the method uses culture-sensitive formatting or a custom formatter. O método converte cada Object argumento para a representação de cadeia de caracteres chamando seus ToString(IFormatProvider) método ou, se o objeto a correspondente do item de formato inclui uma cadeia de caracteres de formato, chamando seu ToString(String,IFormatProvider) método.The method converts each Object argument to its string representation by calling its ToString(IFormatProvider) method or, if the object's corresponding format item includes a format string, by calling its ToString(String,IFormatProvider) method. Se esses métodos não existirem, ele chama o objeto sem parâmetros ToString método.If these methods don't exist, it calls the object's parameterless ToString method.

Entretanto, ao chamar o método String.Format, não é necessário se concentrar na sobrecarga específica que você deseja chamar.However, when calling the String.Format method, it is not necessary to focus on the particular overload that you want to call. Em vez disso, é possível chamar o método com um objeto que fornece formatação personalizada ou sensível à cultura e uma cadeia de caracteres de formato composto que inclui um ou mais itens de formato.Instead, you can call the method with an object that provides culture-sensitive or custom formatting and a composite format string that includes one or more format items. Você atribui a cada item de formato um índice numérico. O primeiro índice começa em 0.You assign each format item a numeric index; the first index starts at 0. Além da cadeia de caracteres inicial, sua chamada de método deve ter tantos argumentos adicionais quantos valores de índice.In addition to the initial string, your method call should have as many additional arguments as it has index values. Por exemplo, uma cadeia de caracteres cujos itens de formato têm índices 0 e 1 deve ter 2 argumentos; uma com índices de 0 a 5 deve ter 6 argumentos.For example, a string whose format items have indexes of 0 and 1 should have 2 arguments; one with indexes 0 through 5 should have 6 arguments. O compilador de linguagem, então, resolverá a chamada de método para uma sobrecarga específica do método String.Format.Your language compiler will then resolve your method call to a particular overload of the String.Format method.

Para obter uma documentação mais detalhada sobre como usar o método String.Format, consulte o Guia de Introdução ao método String.Format e Qual método chamar?.For more detailed documentation on using the String.Format method, see Getting started with the String.Format method and Which method do I call?.

Exemplo: Formatação sensível à culturaExample: Culture-sensitive formatting

Este exemplo usa o Format(IFormatProvider, String, Object[]) método para exibir a representação de cadeia de caracteres de alguns valores de data e hora e valores numéricos usando várias culturas diferentes.This example uses the Format(IFormatProvider, String, Object[]) method to display the string representation of some date and time values and numeric values by using several different cultures.

string[] cultureNames = { "en-US", "fr-FR", "de-DE", "es-ES" };

DateTime dateToDisplay = new DateTime(2009, 9, 1, 18, 32, 0);
double value = 9164.32;

Console.WriteLine("Culture     Date                                Value\n");
foreach (string cultureName in cultureNames)
{
   System.Globalization.CultureInfo culture = new System.Globalization.CultureInfo(cultureName);
   string output = String.Format(culture, "{0,-11} {1,-35:D} {2:N}", 
                                 culture.Name, dateToDisplay, value);
   Console.WriteLine(output);
}    
// The example displays the following output:
//    Culture     Date                                Value
//    
//    en-US       Tuesday, September 01, 2009         9,164.32
//    fr-FR       mardi 1 septembre 2009              9 164,32
//    de-DE       Dienstag, 1. September 2009         9.164,32
//    es-ES       martes, 01 de septiembre de 2009    9.164,32
Imports System.Globalization

Module Example
   Public Sub Main()
      Dim cultureNames() As String = { "en-US", "fr-FR", "de-DE", "es-ES" }
      
      Dim dateToDisplay As Date = #9/1/2009 6:32PM#
      Dim value As Double = 9164.32

      Console.WriteLine("Culture     Date                                Value")
      Console.WriteLine()      
      For Each cultureName As String In cultureNames
         Dim culture As New CultureInfo(cultureName)
         Dim output As String = String.Format(culture, "{0,-11} {1,-35:D} {2:N}", _
                                              culture.Name, dateToDisplay, value)
         Console.WriteLine(output)
      Next    
   End Sub
End Module
' The example displays the following output:
'       Culture     Date                                Value
'       
'       en-US       Tuesday, September 01, 2009         9,164.32
'       fr-FR       mardi 1 septembre 2009              9 164,32
'       de-DE       Dienstag, 1. September 2009         9.164,32
'       es-ES       martes, 01 de septiembre de 2009    9.164,32
Veja também

Format(String, Object, Object) Format(String, Object, Object) Format(String, Object, Object) Format(String, Object, Object)

Substitui os itens de formato em uma cadeia de caracteres pela representação de cadeia de caracteres de dois objetos especificados.Replaces the format items in a string with the string representation of two specified objects.

public:
 static System::String ^ Format(System::String ^ format, System::Object ^ arg0, System::Object ^ arg1);
public static string Format (string format, object arg0, object arg1);
static member Format : string * obj * obj -> string
Public Shared Function Format (format As String, arg0 As Object, arg1 As Object) As String

Parâmetros

arg0
Object Object Object Object

O primeiro objeto a ser formatado.The first object to format.

arg1
Object Object Object Object

O segundo objeto a ser formatado.The second object to format.

Retornos

Uma cópia do format na qual os itens de formato são substituídos pelas representações da cadeia de caracteres de arg0 e arg1.A copy of format in which format items are replaced by the string representations of arg0 and arg1.

Exceções

format é inválido.format is invalid.

- ou --or- O índice de um item de formato não é zero nem um.The index of a format item is not zero or one.

Comentários

Importante

Em vez de chamar o método String.Format ou usar cadeias de caracteres de formato de composição, é possível usar cadeias de caracteres interpoladas quando a linguagem é compatível com eles.Instead of calling the String.Format method or using composite format strings, you can use interpolated strings if your language supports them. Uma cadeia de caracteres interpolada é uma cadeia de caracteres que contém expressões interpoladas.An interpolated string is a string that contains interpolated expressions. Cada expressão interpolada é resolvida com o valor da expressão e incluída na cadeia de caracteres resultante quando a cadeia de caracteres é atribuída.Each interpolated expression is resolved with the expression's value and included in the result string when the string is assigned. Para saber mais, consulte o tópico Interpolação de cadeia de caracteres (Referência do C#) ou Cadeias de caracteres interpoladas (Referência do Visual Basic).For more information, see String interpolation (C# Reference) and Interpolated Strings (Visual Basic Reference).

Esse método usa o recurso de formatação composta para converter o valor de duas expressões em suas representações de cadeia de caracteres e incorporar essas representações em uma cadeia de caracteres.This method uses the composite formatting feature to convert the value of two expressions to their string representations and to embed those representations in a string.

Entretanto, ao chamar o método String.Format, não é necessário se concentrar na sobrecarga específica que você deseja chamar.However, when calling the String.Format method, it is not necessary to focus on the particular overload that you want to call. Em vez disso, é possível chamar o método com uma cadeia de caracteres de formato composto que inclui um ou mais itens de formato.Instead, you can call the method with a composite format string that includes one or more format items. Você atribui a cada item de formato um índice numérico. O primeiro índice começa em 0.You assign each format item a numeric index; the first index starts at 0. Além da cadeia de caracteres inicial, sua chamada de método deve ter tantos argumentos adicionais quantos valores de índice.In addition to the initial string, your method call should have as many additional arguments as it has index values. Por exemplo, uma cadeia de caracteres cujos itens de formato têm índices 0 e 1 deve ter 2 argumentos; uma com índices de 0 a 5 deve ter 6 argumentos.For example, a string whose format items have indexes of 0 and 1 should have 2 arguments; one with indexes 0 through 5 should have 6 arguments. O compilador de linguagem, então, resolverá a chamada de método para uma sobrecarga específica do método String.Format.Your language compiler will then resolve your method call to a particular overload of the String.Format method.

Para obter uma documentação mais detalhada sobre como usar o método String.Format, consulte o Guia de Introdução ao método String.Format e Qual método chamar?.For more detailed documentation on using the String.Format method, see Getting started with the String.Format method and Which method do I call?.

Exemplo: Formatando dois argumentosExample: Formatting two arguments

Este exemplo usa o Format(String, Object, Object) método para exibir dados de tempo e a temperatura armazenados em um genérico Dictionary<TKey,TValue> objeto.This example uses the Format(String, Object, Object) method to display time and temperature data stored in a generic Dictionary<TKey,TValue> object. Observe que a cadeia de caracteres de formato tem três itens de formato, embora existam apenas dois objetos a serem formatados.Note that the format string has three format items, although there are only two objects to format. Isso ocorre porque o primeiro objeto na lista (um valor de data e hora) é usado pelos itens de formato de dois: O primeiro formato item exibe a hora e a segunda exibe a data.This is because the first object in the list (a date and time value) is used by two format items: The first format item displays the time, and the second displays the date.

using namespace System;
using namespace System::Collections::Generic;

void main()
{
   Dictionary<DateTime, Double>^ temperatureInfo = gcnew Dictionary<DateTime, Double>(); 
   temperatureInfo->Add(DateTime(2010, 6, 1, 14, 0, 0), 87.46);
   temperatureInfo->Add(DateTime(2010, 12, 1, 10, 0, 0), 36.81);
      
   Console::WriteLine("Temperature Information:\n");
   String^ output;   
   for each (KeyValuePair<DateTime, Double>^ item in temperatureInfo)
   {
      output = String::Format("Temperature at {0,8:t} on {0,9:d}: {1,5:N1}�F", 
                              item->Key, item->Value);
      Console::WriteLine(output);
   }
}
// The example displays the following output:
//       Temperature Information:
//       
//       Temperature at  2:00 PM on  6/1/2010:  87.5�F
//       Temperature at 10:00 AM on 12/1/2010:  36.8�F
Dictionary<DateTime, Double> temperatureInfo = new Dictionary<DateTime, Double>(); 
temperatureInfo.Add(new DateTime(2010, 6, 1, 14, 0, 0), 87.46);
temperatureInfo.Add(new DateTime(2010, 12, 1, 10, 0, 0), 36.81);

Console.WriteLine("Temperature Information:\n");
string output;   
foreach (var item in temperatureInfo)
{
   output = String.Format("Temperature at {0,8:t} on {0,9:d}: {1,5:N1}°F", 
                          item.Key, item.Value);
   Console.WriteLine(output);
}
// The example displays output like the following:
//       Temperature Information:
//       
//       Temperature at  2:00 PM on  6/1/2010:  87.5°F
//       Temperature at 10:00 AM on 12/1/2010:  36.8°F
Imports System.Collections.Generic

Module Example
   Public Sub Main()
      Dim temperatureInfo As New Dictionary(Of Date, Double) 
      temperatureInfo.Add(#6/1/2010 2:00PM#, 87.46)
      temperatureInfo.Add(#12/1/2010 10:00AM#, 36.81)
      
      Console.WriteLine("Temperature Information:")
      Console.WriteLine()
      Dim output As String   
      For Each item In temperatureInfo
         output = String.Format("Temperature at {0,8:t} on {0,9:d}: {1,5:N1}°F", _
                                item.Key, item.Value)
         Console.WriteLine(output)
      Next
   End Sub
End Module
' The example displays the following output:
'       Temperature Information:
'       
'       Temperature at  2:00 PM on  6/1/2010:  87.5°F
'       Temperature at 10:00 AM on 12/1/2010:  36.8°F
Veja também

Format(IFormatProvider, String, Object, Object) Format(IFormatProvider, String, Object, Object) Format(IFormatProvider, String, Object, Object) Format(IFormatProvider, String, Object, Object)

Substitui os itens de formato em uma cadeia de caracteres pela representação de cadeia de caracteres de dois objetos especificados.Replaces the format items in a string with the string representation of two specified objects. Um parâmetro fornece informações de formatação específicas da cultura.A parameter supplies culture-specific formatting information.

public:
 static System::String ^ Format(IFormatProvider ^ provider, System::String ^ format, System::Object ^ arg0, System::Object ^ arg1);
public static string Format (IFormatProvider provider, string format, object arg0, object arg1);
static member Format : IFormatProvider * string * obj * obj -> string
Public Shared Function Format (provider As IFormatProvider, format As String, arg0 As Object, arg1 As Object) As String

Parâmetros

provider
IFormatProvider IFormatProvider IFormatProvider IFormatProvider

Um objeto que fornece informações de formatação específicas de cultura.An object that supplies culture-specific formatting information.

arg0
Object Object Object Object

O primeiro objeto a ser formatado.The first object to format.

arg1
Object Object Object Object

O segundo objeto a ser formatado.The second object to format.

Retornos

Uma cópia do format na qual os itens de formato são substituídos pelas representações da cadeia de caracteres de arg0 e arg1.A copy of format in which format items are replaced by the string representations of arg0 and arg1.

Exceções

format é inválido.format is invalid.

- ou --or- O índice de um item de formato não é zero nem um.The index of a format item is not zero or one.

Comentários

Importante

Em vez de chamar o método String.Format ou usar cadeias de caracteres de formato de composição, é possível usar cadeias de caracteres interpoladas quando a linguagem é compatível com eles.Instead of calling the String.Format method or using composite format strings, you can use interpolated strings if your language supports them. Uma cadeia de caracteres interpolada é uma cadeia de caracteres que contém expressões interpoladas.An interpolated string is a string that contains interpolated expressions. Cada expressão interpolada é resolvida com o valor da expressão e incluída na cadeia de caracteres resultante quando a cadeia de caracteres é atribuída.Each interpolated expression is resolved with the expression's value and included in the result string when the string is assigned. Para saber mais, consulte o tópico Interpolação de cadeia de caracteres (Referência do C#) ou Cadeias de caracteres interpoladas (Referência do Visual Basic).For more information, see String interpolation (C# Reference) and Interpolated Strings (Visual Basic Reference).

Esse método usa o recurso de formatação composta converter duas expressões em suas representações de cadeia de caracteres e incorporar essas representações em uma cadeia de caracteres.This method uses the composite formatting feature to convert two expressions to their string representations and to embed those representations in a string. Na execução da conversão, o método usa formatação sensível à cultura ou um formatador personalizado.In performing the conversion, the method uses culture-sensitive formatting or a custom formatter. O método converte cada Object argumento para a representação de cadeia de caracteres chamando seus ToString(IFormatProvider) método ou, se o objeto a correspondente do item de formato inclui uma cadeia de caracteres de formato, chamando seu ToString(String,IFormatProvider) método.The method converts each Object argument to its string representation by calling its ToString(IFormatProvider) method or, if the object's corresponding format item includes a format string, by calling its ToString(String,IFormatProvider) method. Se esses métodos não existirem, ele chama o objeto sem parâmetros ToString método.If these methods don't exist, it calls the object's parameterless ToString method.

Entretanto, ao chamar o método String.Format, não é necessário se concentrar na sobrecarga específica que você deseja chamar.However, when calling the String.Format method, it is not necessary to focus on the particular overload that you want to call. Em vez disso, é possível chamar o método com um objeto que fornece formatação personalizada ou sensível à cultura e uma cadeia de caracteres de formato composto que inclui um ou mais itens de formato.Instead, you can call the method with an object that provides culture-sensitive or custom formatting and a composite format string that includes one or more format items. Você atribui a cada item de formato um índice numérico. O primeiro índice começa em 0.You assign each format item a numeric index; the first index starts at 0. Além da cadeia de caracteres inicial, sua chamada de método deve ter tantos argumentos adicionais quantos valores de índice.In addition to the initial string, your method call should have as many additional arguments as it has index values. Por exemplo, uma cadeia de caracteres cujos itens de formato têm índices 0 e 1 deve ter 2 argumentos; uma com índices de 0 a 5 deve ter 6 argumentos.For example, a string whose format items have indexes of 0 and 1 should have 2 arguments; one with indexes 0 through 5 should have 6 arguments. O compilador de linguagem, então, resolverá a chamada de método para uma sobrecarga específica do método String.Format.Your language compiler will then resolve your method call to a particular overload of the String.Format method.

Para obter uma documentação mais detalhada sobre como usar o método String.Format, consulte o Guia de Introdução ao método String.Format e Qual método chamar?.For more detailed documentation on using the String.Format method, see Getting started with the String.Format method and Which method do I call?.

Format(String, Object, Object, Object) Format(String, Object, Object, Object) Format(String, Object, Object, Object) Format(String, Object, Object, Object)

Substitui os itens de formato em uma cadeia de caracteres pela representação de cadeia de caracteres de três objetos especificados.Replaces the format items in a string with the string representation of three specified objects.

public:
 static System::String ^ Format(System::String ^ format, System::Object ^ arg0, System::Object ^ arg1, System::Object ^ arg2);
public static string Format (string format, object arg0, object arg1, object arg2);
static member Format : string * obj * obj * obj -> string
Public Shared Function Format (format As String, arg0 As Object, arg1 As Object, arg2 As Object) As String

Parâmetros

arg0
Object Object Object Object

O primeiro objeto a ser formatado.The first object to format.

arg1
Object Object Object Object

O segundo objeto a ser formatado.The second object to format.

arg2
Object Object Object Object

O terceiro objeto a ser formatado.The third object to format.

Retornos

Uma cópia do format na qual ou itens de formato foram substituídos pela representação de cadeia de caracteres de arg0, arg1 e arg2.A copy of format in which the format items have been replaced by the string representations of arg0, arg1, and arg2.

Exceções

format é inválido.format is invalid.

- ou --or- O índice de um item de formato é menor que zero ou maior que dois.The index of a format item is less than zero, or greater than two.

Comentários

Importante

Em vez de chamar o método String.Format ou usar cadeias de caracteres de formato de composição, é possível usar cadeias de caracteres interpoladas quando a linguagem é compatível com eles.Instead of calling the String.Format method or using composite format strings, you can use interpolated strings if your language supports them. Uma cadeia de caracteres interpolada é uma cadeia de caracteres que contém expressões interpoladas.An interpolated string is a string that contains interpolated expressions. Cada expressão interpolada é resolvida com o valor da expressão e incluída na cadeia de caracteres resultante quando a cadeia de caracteres é atribuída.Each interpolated expression is resolved with the expression's value and included in the result string when the string is assigned. Para saber mais, consulte o tópico Interpolação de cadeia de caracteres (Referência do C#) ou Cadeias de caracteres interpoladas (Referência do Visual Basic).For more information, see String interpolation (C# Reference) and Interpolated Strings (Visual Basic Reference).

Esse método usa o recurso de formatação composta para converter o valor das três expressões em suas representações de cadeia de caracteres e incorporar essas representações em uma cadeia de caracteres.This method uses the composite formatting feature to convert the value of three expressions to their string representations and to embed those representations in a string.

Entretanto, ao chamar o método String.Format, não é necessário se concentrar na sobrecarga específica que você deseja chamar.However, when calling the String.Format method, it is not necessary to focus on the particular overload that you want to call. Em vez disso, é possível chamar o método com uma cadeia de caracteres de formato composto que inclui um ou mais itens de formato.Instead, you can call the method with a composite format string that includes one or more format items. Você atribui a cada item de formato um índice numérico. O primeiro índice começa em 0.You assign each format item a numeric index; the first index starts at 0. Além da cadeia de caracteres inicial, sua chamada de método deve ter tantos argumentos adicionais quantos valores de índice.In addition to the initial string, your method call should have as many additional arguments as it has index values. Por exemplo, uma cadeia de caracteres cujos itens de formato têm índices 0 e 1 deve ter 2 argumentos; uma com índices de 0 a 5 deve ter 6 argumentos.For example, a string whose format items have indexes of 0 and 1 should have 2 arguments; one with indexes 0 through 5 should have 6 arguments. O compilador de linguagem, então, resolverá a chamada de método para uma sobrecarga específica do método String.Format.Your language compiler will then resolve your method call to a particular overload of the String.Format method.

Para obter uma documentação mais detalhada sobre como usar o método String.Format, consulte o Guia de Introdução ao método String.Format e Qual método chamar?.For more detailed documentation on using the String.Format method, see Getting started with the String.Format method and Which method do I call?.

Exemplo: Formatando três argumentosExample: Formatting three arguments

Este exemplo usa o Format(String, Object, Object, Object) método para criar uma cadeia de caracteres que ilustra o resultado de um valor booliano And operação com dois valores inteiros.This example uses the Format(String, Object, Object, Object) method to create a string that illustrates the result of a Boolean And operation with two integer values. Observe que a cadeia de caracteres de formato inclui seis itens de formato, mas o método tem apenas três itens na lista de parâmetros, porque cada item é formatada de duas maneiras diferentes.Note that the format string includes six format items, but the method has only three items in its parameter list, because each item is formatted in two different ways.

using namespace System;

void main()
{
   String^ formatString = "    {0,10} ({0,8:X8})\n" + 
                           "And {1,10} ({1,8:X8})\n" + 
                           "  = {2,10} ({2,8:X8})";
   int value1 = 16932;
   int value2 = 15421;
   String^ result = String::Format(formatString, 
                                   value1, value2, value1 & value2);
   Console::WriteLine(result);
}
// The example displays the following output:
//                16932 (00004224)
//       And      15421 (00003C3D)
//         =         36 (00000024)
string formatString = "    {0,10} ({0,8:X8})\n" + 
                      "And {1,10} ({1,8:X8})\n" + 
                      "  = {2,10} ({2,8:X8})";
int value1 = 16932;
int value2 = 15421;
string result = String.Format(formatString, 
                              value1, value2, value1 & value2);
Console.WriteLine(result);
// The example displays the following output:
//                16932 (00004224)
//       And      15421 (00003C3D)
//         =         36 (00000024)
Public Module Example
   Public Sub Main()
      Dim formatString As String = "    {0,10} ({0,8:X8})" + vbCrLf +  _
                                   "And {1,10} ({1,8:X8})" + vbCrLf + _
                                   "  = {2,10} ({2,8:X8})"
      Dim value1 As Integer = 16932
      Dim value2 As Integer = 15421
      Dim result As String = String.Format(formatString, _
                                           value1, value2, value1 And value2)
      Console.WriteLine(result)                          
   End Sub
End Module
' The example displays the following output:
'                16932 (00004224)
'       And      15421 (00003C3D)
'         =         36 (00000024)
Veja também

Format(IFormatProvider, String, Object, Object, Object) Format(IFormatProvider, String, Object, Object, Object) Format(IFormatProvider, String, Object, Object, Object) Format(IFormatProvider, String, Object, Object, Object)

Substitui os itens de formato em uma cadeia de caracteres pela representação de cadeia de caracteres de três objetos especificados.Replaces the format items in a string with the string representation of three specified objects. Um parâmetro fornece informações de formatação específicas da cultura.An parameter supplies culture-specific formatting information.

public:
 static System::String ^ Format(IFormatProvider ^ provider, System::String ^ format, System::Object ^ arg0, System::Object ^ arg1, System::Object ^ arg2);
public static string Format (IFormatProvider provider, string format, object arg0, object arg1, object arg2);
static member Format : IFormatProvider * string * obj * obj * obj -> string
Public Shared Function Format (provider As IFormatProvider, format As String, arg0 As Object, arg1 As Object, arg2 As Object) As String

Parâmetros

provider
IFormatProvider IFormatProvider IFormatProvider IFormatProvider

Um objeto que fornece informações de formatação específicas de cultura.An object that supplies culture-specific formatting information.

arg0
Object Object Object Object

O primeiro objeto a ser formatado.The first object to format.

arg1
Object Object Object Object

O segundo objeto a ser formatado.The second object to format.

arg2
Object Object Object Object

O terceiro objeto a ser formatado.The third object to format.

Retornos

Uma cópia do format na qual ou itens de formato foram substituídos pela representação de cadeia de caracteres de arg0, arg1 e arg2.A copy of format in which the format items have been replaced by the string representations of arg0, arg1, and arg2.

Exceções

format é inválido.format is invalid.

- ou --or- O índice de um item de formato é menor que zero ou maior que dois.The index of a format item is less than zero, or greater than two.

Comentários

Importante

Em vez de chamar o método String.Format ou usar cadeias de caracteres de formato de composição, é possível usar cadeias de caracteres interpoladas quando a linguagem é compatível com eles.Instead of calling the String.Format method or using composite format strings, you can use interpolated strings if your language supports them. Uma cadeia de caracteres interpolada é uma cadeia de caracteres que contém expressões interpoladas.An interpolated string is a string that contains interpolated expressions. Cada expressão interpolada é resolvida com o valor da expressão e incluída na cadeia de caracteres resultante quando a cadeia de caracteres é atribuída.Each interpolated expression is resolved with the expression's value and included in the result string when the string is assigned. Para saber mais, consulte o tópico Interpolação de cadeia de caracteres (Referência do C#) ou Cadeias de caracteres interpoladas (Referência do Visual Basic).For more information, see String interpolation (C# Reference) and Interpolated Strings (Visual Basic Reference).

Esse método usa o recurso de formatação composta converter três expressões em suas representações de cadeia de caracteres e incorporar essas representações em uma cadeia de caracteres.This method uses the composite formatting feature to convert three expressions to their string representations and to embed those representations in a string. Na execução da conversão, o método usa formatação sensível à cultura ou um formatador personalizado.In performing the conversion, the method uses culture-sensitive formatting or a custom formatter. O método converte cada Object argumento para a representação de cadeia de caracteres chamando seus ToString(IFormatProvider) método ou, se o objeto a correspondente do item de formato inclui uma cadeia de caracteres de formato, chamando seu ToString(String,IFormatProvider) método.The method converts each Object argument to its string representation by calling its ToString(IFormatProvider) method or, if the object's corresponding format item includes a format string, by calling its ToString(String,IFormatProvider) method. Se esses métodos não existirem, ele chama o objeto sem parâmetros ToString método.If these methods don't exist, it calls the object's parameterless ToString method.

Entretanto, ao chamar o método String.Format, não é necessário se concentrar na sobrecarga específica que você deseja chamar.However, when calling the String.Format method, it is not necessary to focus on the particular overload that you want to call. Em vez disso, é possível chamar o método com um objeto que fornece formatação personalizada ou sensível à cultura e uma cadeia de caracteres de formato composto que inclui um ou mais itens de formato.Instead, you can call the method with an object that provides culture-sensitive or custom formatting and a composite format string that includes one or more format items. Você atribui a cada item de formato um índice numérico. O primeiro índice começa em 0.You assign each format item a numeric index; the first index starts at 0. Além da cadeia de caracteres inicial, sua chamada de método deve ter tantos argumentos adicionais quantos valores de índice.In addition to the initial string, your method call should have as many additional arguments as it has index values. Por exemplo, uma cadeia de caracteres cujos itens de formato têm índices 0 e 1 deve ter 2 argumentos; uma com índices de 0 a 5 deve ter 6 argumentos.For example, a string whose format items have indexes of 0 and 1 should have 2 arguments; one with indexes 0 through 5 should have 6 arguments. O compilador de linguagem, então, resolverá a chamada de método para uma sobrecarga específica do método String.Format.Your language compiler will then resolve your method call to a particular overload of the String.Format method.

Para obter uma documentação mais detalhada sobre como usar o método String.Format, consulte o Guia de Introdução ao método String.Format e Qual método chamar?.For more detailed documentation on using the String.Format method, see Getting started with the String.Format method and Which method do I call?.

Aplica-se a