Složené formátování

Článek
08/11/2011

Funkce složeného formátování v rozhraní .NET Framework přebírá seznam objektů a složený formátovací řetězec jako vstup. Složený formátovací řetězec se skládá z pevného textu smíšeného s indexovanými zástupnými symboly, které se nazývají položky formátu, které odpovídají objektům v seznamu. Výsledkem operace formátování je výsledný řetězec, který se skládá z původního pevného textu smíšeného s řetězcovou reprezentací objektů v seznamu.

Funkce složeného formátování je podporována například metodami Format, AppendFormat a některými přetíženími z WriteLine a TextWriter.WriteLine. Výsledkem metody String.Format je formátovaný výsledný řetězec, metoda AppendFormat přidá formátovaný výsledný řetězec k objektu StringBuilder, metoda Console.WriteLine zobrazí formátovaný výsledný řetězec do konzoly a metoda TextWriter.WriteLine zapíše formátovaný výsledný řetězec do datového proudu nebo souboru.

Složený formátovací řetězec

Složený formátovací řetězec a seznam objektů jsou používány jako argumenty metod, které podporují funkci složeného formátování. Složený formátovací řetězec se skládá z nula nebo více výskytů pevného textu smíšených s jednou nebo více položkami formátu. Pevný text je jakýkoli řetězec, který zvolíte a každá položka formátu odpovídá objektu nebo ohraničené struktuře v seznamu. Funkce složeného formátování vrátí nový výsledný řetězec, kde je každá položka formátu nahrazena řetězcovou reprezentací odpovídajícího objektu v seznamu.

Předpokládejme následující fragment kódu Format.

Dim myName As String = "Fred"
String.Format("Name = {0}, hours = {1:hh}", myName, DateTime.Now)

string myName = "Fred";
String.Format("Name = {0}, hours = {1:hh}", myName, DateTime.Now);

Pevný text je Name = a , hours = . Položky formátu jsou {0}, jejíž index je 0, což odpovídá objektu myName a {1:hh}, jejíž index je 1, která odpovídá objektu DateTime.Now.

Syntaxe položky formátu

Každá položka formátu má následující podobu a skládá se z následujících součástí:

{index[,alignment][:formatString]}

Jsou požadovány odpovídající závorky ("{" a "}").

Součást Index

Povinná součást Index, také nazývaná specifikátor parametru, je číslo začínající od 0, které identifikuje odpovídající položku v seznamu objektů. To znaméná, že, položka formátu, jejíž specifikátor parametru je 0, formátuje první objekt v seznamu, položka formátu, jejíž specifikátor parametru je 1, formátuje druhý objekt v seznamu atd.

Více položek formátu může odkazovat na stejný prvek v seznamu objektů zadáním stejného specifikátoru parametru. Například můžete formátovat stejnou číselnou hodnotu v šestnáctkovém, vědeckém a číselném formátu určením složeného řetězce formátu tímto způsobem: {0:X} {0:E} {0:N}.

Každá položka formátu může odkazovat na libovolný objekt v seznamu. Například pokud existují tři objekty, můžete formátovat druhý, první a třetí objekt zadáním řetězec složeného formátu tímto způsobem: "{1} {0} {2}". Objekt, který není odkazován položkou formátu je ignorován. Pokud specifikátor parametru označí položku mimo rozsah seznamu objektů, dojde k výjimce modulu runtime.

Přidružená součást

Volitelná součást alignment je celé číslo se znaménkem udávající šířku pole upřednostňovaného formátu. Pokud hodnota alignment je menší než délka formátovaného řetězce, alignment je ignorováno a jako šířka pole je použita délka formátovaného řetězce. Formátovaná data v poli jsou zarovnána doprava pokud je alignment kladné a zarovnána vlevo pokud je alignment záporné. Pokud je nutné doplňení znaků, jsou použity prázdné znaky. Čárka je požadováno pokud je alignment zadáno.

Součást řetězce formátu

Volitelná součást formatString je řetězec formátu, který je odpovídající pro typ objektu, který je formátován. Zadejte standardní nebo vlastní číselný formátovací řetězec, pokud je odpovídající objekt číselné hodnoty, standardní nebo vlastní formátovací řetězec data a času, jestliže je odpovídající objekt objektem DateTime nebo řetězec formátu výčtu, pokud je odpovídající objekt hodnotou výčtu. Pokud není zadán formatString, bude použitý obecný specifikátor formátu G pro použité hodnoty, které jsou číselné, data a času nebo výčty. Dvojtečka je vyžadována, pokud je formatString určen.

Poznámka
Seznam standardních a vlastních číselných formátovacích řetězců naleznete v tématu Standardní číselné formátovací řetězce a Vlastní číselné formátovací řetězce. Seznam standardních formátovacích řetězců data a času naleznete v tématu Standardní formátovací řetězce data a času a Vlastní formátovací řetězce data a času.

Řídící znaky pro závorky

Levé a pravé závorky jsou interpretovány jako počátek a konec položky formátu. V důsledku toho je nutné použít sekvenci řídicích znaků pro zobrazení literálního významu počátečních a koncových závorek. Zadejte dvě počáteční závorky ("{{") v pevném textu pro zobrazení jedné počáteční závorky ("{"), nebo dvě konečné závorky ("}}") pro zobrazení jedné konečné závorky ("}"). Závorky v položce formátu jsou interpretovány postupně v pořadí, v jakém se vyskytují. Interpretace vnořených závorek není podporována.

Způsob, jakým jsou interpretovány závorky vložené pomocí řídících znaků může vést k neočekávaným výsledkům. Zvažte například položku formátu {{{0:D}}}, která je určena k zobrazování počáteční závorky, číselnou hodnotu formátovanou jako desítkové číslo a uzavírající závorku. Avšak položka formátu je ve skutečnosti interpretována následujícím způsobem:

První dvě počáteční závorky ("{{") jsou tvořeny řídícími znaky, a proto je výsledkem jedna počáteční závorka.
Další tři znaky ("{0:") jsou interpretovány jako start formát položky.
Další znak D je interpretován jako standardní specifikátor číselného desítkového formátu, ale další dvě závorky, tvořené řídícími znaky ("}}") vytvoří ve výsledku jednu závorku. Protože výsledný řetězec ("D}") není standardním specifikátorem číselného formátu, je výsledný řetězec interpretován jako vlastní formátovací řetězec, což znamená, že se zobrazí literální řetězec D}.
Poslední závorka ("}") je interpretována jako konec položky formátu.
Konečný výsledek, který se zobrazí, je literální řetězec "{D}". Číselná hodnota, která měla být formátována, se nezobrazí.

Jedním způsobem, jak napsat váš kód tak, aby bylo zabráněno chybné interpretaci závorek tvořených řídícími znaky je formátování závorek a položek formátu odděleně. To znamená, že se v první operaci formátování zobrazí literální znak počáteční závorky, v další operaci se zobrazí výsledek položky formátu a nakonec se v poslední operaci zobrazí literální znak uzavírací závorky. Následující příklad ukazuje tento přístup.

Dim value As Integer = 6324
Dim output As String = String.Format("{0}{1:D}{2}", _
                                     "{", value, "}")
Console.WriteLine(output)   
' The example displays the following output:
'       {6324}

int value = 6324;
string output = string.Format("{0}{1:D}{2}", 
                             "{", value, "}");
Console.WriteLine(output);
// The example displays the following output:
//       {6324}

Zpracování objednávky

Každá hodnota v seznamu parametrů, která odpovídá položce formátu je převedena na řetězec pomocí kroků v následujícím seznamu. Pokud je splněna některá z podmínek v prvních třech krocích, je v tomto kroku vráceno řetězcové vyjádření hodnoty a následné kroky již nebudou provedeny.

Pokud je hodnota, která má být formátována null, je vrácen prázdný řetězec ("").
Pokud metoda složeného formátování obsahuje parametr typu IFormatProvider, který také implementuje rozhraní ICustomFormatter, je hodnota předána metodě ICustomFormatter.Format.
Pokud hodnota implementuje rozhraní IFormattable, je volána jeho metoda IFormattable.ToString.
Je volána metoda typu ToString, která je přepsána nebo zděděna ze třídy Object.

Zarovnání se aplikuje po provedení předchozích kroků.

Příklady kódu

Následující příklad ukazuje jeden řetězec vytvořený pomocí složeného formátování a další vytvořený pomocí metody objektu ToString. Oba typy formátování poskyují stejné výsledky.

Dim FormatString1 As String = String.Format("{0:dddd MMMM}", DateTime.Now)
Dim FormatString2 As String = DateTime.Now.ToString("dddd MMMM")

string FormatString1 = String.Format("{0:dddd MMMM}", DateTime.Now);
string FormatString2 = DateTime.Now.ToString("dddd MMMM");

Za předpokladu, že aktuální den je čtvrtek v květnu, hodnota obou řetězců v předchozím příkladu je Thursday May v jazykové verzi U.S. English.

Console.WriteLine poskytuje stejnou funkci jako String.Format. Jediný rozdíl mezi těmito dvěma metodami je, že String.Format vrátí výsledek jako řetězec, zatímco Console.WriteLine zapíše výsledek do výstupního datového proudu asociovaného s objektem Console. Následující příklad používá metodu Console.WriteLine pro formátování hodnoty MyInt na hodnotu měny.

Dim MyInt As Integer = 100
Console.WriteLine("{0:C}", MyInt)
' The example displays the following output
' if en-US is the current culture:
'        $100.00

int MyInt = 100;
Console.WriteLine("{0:C}", MyInt);
// The example displays the following output 
// if en-US is the current culture:
//        $100.00

Následující příklad ukazuje formátování více objektů, včetně formátování jednoho objektu dvěma různými způsoby.

Dim myName As String = "Fred"
Console.WriteLine(String.Format("Name = {0}, hours = {1:hh}, minutes = {1:mm}", _
                  myName, DateTime.Now))
' Depending on the current time, the example displays output like the following:
'    Name = Fred, hours = 11, minutes = 30

string myName = "Fred";
Console.WriteLine(String.Format("Name = {0}, hours = {1:hh}, minutes = {1:mm}",
      myName, DateTime.Now));
// Depending on the current time, the example displays output like the following:
//    Name = Fred, hours = 11, minutes = 30

Následující příklad ukazuje použití zarovnání ve formátování. Argumenty, které jsou formátovány jsou umístěny mezi znaky svislé čáry | pro zvýraznění výsledného zarovnání.

Dim myFName As String = "Fred"
Dim myLName As String = "Opals"

Dim myInt As Integer = 100
Dim FormatFName As String = String.Format("First Name = |{0,10}|", myFName)
Dim FormatLName As String = String.Format("Last Name = |{0,10}|", myLName)
Dim FormatPrice As String = String.Format("Price = |{0,10:C}|", myInt)
Console.WriteLine(FormatFName)
Console.WriteLine(FormatLName)
Console.WriteLine(FormatPrice)
Console.WriteLine()

FormatFName = String.Format("First Name = |{0,-10}|", myFName)
FormatLName = String.Format("Last Name = |{0,-10}|", myLName)
FormatPrice = String.Format("Price = |{0,-10:C}|", myInt)
Console.WriteLine(FormatFName)
Console.WriteLine(FormatLName)
Console.WriteLine(FormatPrice)
' The example displays the following output on a system whose current
' culture is en-US:
'          First Name = |      Fred|
'          Last Name = |     Opals|
'          Price = |   $100.00|
'
'          First Name = |Fred      |
'          Last Name = |Opals     |
'          Price = |$100.00   |

string myFName = "Fred";
string myLName = "Opals";
int myInt = 100;
string FormatFName = String.Format("First Name = |{0,10}|", myFName);
string FormatLName = String.Format("Last Name = |{0,10}|", myLName);
string FormatPrice = String.Format("Price = |{0,10:C}|", myInt); 
Console.WriteLine(FormatFName);
Console.WriteLine(FormatLName);
Console.WriteLine(FormatPrice);
Console.WriteLine();

FormatFName = String.Format("First Name = |{0,-10}|", myFName);
FormatLName = String.Format("Last Name = |{0,-10}|", myLName);
FormatPrice = String.Format("Price = |{0,-10:C}|", myInt);
Console.WriteLine(FormatFName);
Console.WriteLine(FormatLName);
Console.WriteLine(FormatPrice);
// The example displays the following output on a system whose current
// culture is en-US:
//          First Name = |      Fred|
//          Last Name = |     Opals|
//          Price = |   $100.00|
//
//          First Name = |Fred      |
//          Last Name = |Opals     |
//          Price = |$100.00   |