Синтаксис элементов форматирования

Каждый элемент форматирования имеет следующий вид и состоит из следующих компонентов:

{ index[,alignment][:formatString]}

Парные фигурные скобки ("{" и "}") здесь обязательны.

Индекс

Обязательный компонент index, также называемый описателем параметра, — это число, определяющее соответствующий объект из списка; индексация элементов ведется от нуля. Иными словами, элемент форматирования с индексом 0 отвечает за формат первого объекта в списке, элемент форматирования с индексом 1 служит для форматирования второго объекта в списке и т. д.

На один и тот же элемент в списке объектов может ссылаться сразу несколько элементов форматирования — достигается это путем задания одинакового описателя параметра. Например, одно и то же числовое значение можно отформатировать в шестнадцатеричном, экспоненциальном и десятичном виде путем задания следующей строки составного форматирования: "{0:X} {0:E} {0:N}".

Любой элемент форматирования может ссылаться на произвольный объект списка. Например, если имеется три объекта, то можно отформатировать сначала второй, а затем первый и третий объекты, задав следующую строку составного форматирования: "{1} {0} {2}". Объекты, на которые не ссылаются элементы форматирования, пропускаются. Если описатель параметра ссылается на элемент за пределами списка объектов, то во время выполнения создается исключение.

Выравнивание

Необязательный компонент alignment — это целое число со знаком, которое служит для указания желательной ширины поля форматирования. Если значение alignment меньше длины форматируемой строки, то alignment пропускается, и в качестве значения ширины поля используется длина форматируемой строки. Форматируемые данные выравниваются в поле по правому краю, если alignment имеет положительное значение, или по левому краю, если alignment имеет отрицательное значение. При необходимости отформатированная строка дополняется пробелами. При использовании компонента alignment необходимо поставить запятую.

Format String Component

The optional formatString component is a format string that is appropriate for the type of object being formatted. Specify a numeric format string if the corresponding object is a numeric value, a date and time format string if the corresponding object is a DateTime object, or an enumeration format string if the corrersponding object is an enumeration value. If formatString is not specified, the general ("G") format specifier for a numeric, date and time, or enumeration type is used. The colon is required if formatString is specified.

Escaping Braces

Opening and closing braces are interpreted as starting and ending a format item. Consequently, you must use an escape sequence to display a literal opening brace or closing brace. Specify two opening braces ("{{") in the fixed text to display one opening brace ("{"), or two closing braces ("}}") to display one closing brace ("}"). Braces in a format item are interpreted sequentially in the order they are encountered. Interpreting nested braces is not supported.

The way escaped braces are interpreted can lead to unexpected results. For example, consider the format item "{{{0:D}}}", which is intended to display an opening brace, a numeric value formatted as a decimal number, and a closing brace. However, the format item is actually interpreted in the following manner:

1. The first two opening braces ("{{") are escaped and yield one opening brace.

2. The next three characters ("{0:") are interpreted as the start of a format item.

3. The next character ("D") would be interpreted as the Decimal standard numeric format specifier, but the next two escaped braces ("}}") yield a single brace. Because the resulting string ("D}") is not a standard numeric format specifier, the resulting string is interpreted as a custom format string that means display the literal string "D}".

4. The last brace ("}") is interpreted as the end of the format item.

5. The final result that is displayed is the literal string, "{D}". The numeric value that was to be formatted is not displayed.

One way to write your code to avoid misinterpreting escaped braces and format items is to format the braces and format item separately. That is, in the first format operation display a literal opening brace, in the next operation display the result of the format item, then in the final operation display a literal closing brace.

 

Компонент строки формата

Необязательный компонент formatString — это строка формата, соответствующая типу форматируемого объекта. Если соответствующий объект является числовым значением, используется строка форматирования чисел, а если соответствующий объект относится к типу DateTime, то используется строка форматирования даты и времени; если же соответствующий объект является значением перечисления, используется строка форматирования перечислений. Если компонент formatString не задан, то для числовых значений, значений даты и времени, а также перечислений используется общий формат ("G"). При использовании компонента formatString необходимо поставить двоеточие.

Оформление фигурных скобок

Начало и конец элемента форматирования обозначаются соответственно открывающей и закрывающей фигурной скобкой. Это означает, что для вывода открывающих и закрывающих фигурных скобок необходимо использовать escape-последовательности. Для вывода открывающей или закрывающей фигурной скобки в фиксированном тексте следует поставить две открывающие или, соответственно, закрывающие фигурные скобки подряд ("{{" или "}}"). Фигурные скобки в элементе форматирования интерпретируются последовательно в порядке их обнаружения. Интерпретация вложенных скобок не поддерживается.

Порядок интерпретации скобок может привести к непредвиденным результатам. Например, рассмотрим элемент форматирования "{{{0:D}}}", который должен вывести открывающую фигурную скобку, числовое значение, отформатированное в десятичном виде, и закрывающую фигурную скобку. В действительности элемент форматирования будет интерпретирован следующим образом:

1. Первые две открывающие фигурные скобки ("{{") составляют escape-последовательность, которая дает в итоге одиночную открывающую фигурную скобку.

2. Следующие три знака ("{0:") воспринимаются как начало элемента форматирования.

3. Следующий знак ("D") должен интерпретироваться как указатель на десятичный числовой формат, но стоящая за ним пара фигурных скобок ("}}") дает в результате одиночную фигурную скобку. Поскольку результирующая строка ("D}") не является стандартным описателем числового формата, то она будет интерпретирована как строка пользовательского формата, что приведет к выводу строки "D}".

4. Последняя фигурная скобка ("}") интерпретируется как конец элемента форматирования.

5. Итоговый результат, который будет выведен — строка "{D}". Числовое значение, которое требовалось отформатировать, выведено не будет.

Одним из способов избежать неправильной интерпретации фигурных скобок и элементов форматирования при написании кода является раздельное форматирование фигурных скобок и элементов форматирования. Это означает, что первая операция форматирования должна выводить строку с открывающей фигурной скобкой, следующая операция — результат обработки элемента форматирования, а последняя операция — строку с закрывающей фигурной скобкой.

Processing Order

If the value to be formatted is null, an empty string ("") is returned.

If the type to be formatted implements the ICustomFormatter interface, the ICustomFormatter..::.Format method is called.

If the preceding step does not format the type, and the type implements the IFormattable interface, the IFormattable..::.ToString method is called.

If the preceding step does not format the type, the type's ToString method, which is inherited from the Object class, is called.

Alignment is applied after the preceding steps have been performed.

 

Порядок обработки

При форматировании значения null возвращается пустая строка ("").

Если форматируемый тип реализует интерфейс ICustomFormatter, то вызывается метод ICustomFormatter..::.Format.

Если выполнение предыдущего шага не привело к форматированию типа и тип при этом реализует интерфейс IFormattable, то будет вызван метод IFormattable..::.ToString.

Если выполнение предыдущего шага не привело к форматированию типа, то вызывается метод ToString, который тип наследует от класса Object.

После выполнения предшествующих шагов производится выравнивание.

 

Code Examples

The following example shows one string created using composite formatting and another created using an object's ToString method. Both types of formatting produce equivalent results.

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

Assuming that the current day is a Thursday in May, the value of both strings in the preceding example is Thursday May in the U.S. English culture.

Console.WriteLine exposes the same functionality as String.Format. The only difference between the two methods is that String.Format returns its result as a string, while Console.WriteLine writes the result to the output stream associated with the Console object. The following example uses the Console.WriteLine method to format the value of MyInt to a currency value.

int MyInt = 100; Console.WriteLine("{0:C}", MyInt);

This code displays $100.00 to the console on computers that have U.S. English as the current culture.

The following example demonstrates formatting multiple objects, including formatting one object two different ways.

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

The output from the preceding string is "Name = Fred, hours = 07, minutes = 23", where the current time reflects these numbers.

 

Примеры кода

В приведенном ниже примере одна строка создается с помощью составного форматирования, а другая — с помощью метода ToString. Оба способа форматирования дают идентичные результаты.

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

Предположим, что сейчас май, а текущий день недели — четверг; тогда значение обеих строк для языка и региональных параметров "Английский (США)" в предыдущем примере будет равно Thursday May.

Метод Console.WriteLine обладает той же функциональностью, что и String.Format. Единственное различие между двумя методами состоит в том, что метод String.Format возвращает результат в виде строки, а Console.WriteLine записывает результат в выходной поток, связанный с объектом Console. В следующем примере для форматирования значения переменной MyInt в виде денежной единицы используется метод Console.WriteLine.

int MyInt = 100; Console.WriteLine("{0:C}", MyInt);

На тех компьютерах, где выбраны языковые и региональные параметры "Английский (США)", этот код будет выводить на консоль строку $100.00.

В следующем примере демонстрируется форматирование нескольких объектов, в том числе форматирование одного и того же объекта двумя разными способами.

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

Результатом обработки приведенной выше строки станет строка "Name = Fred, hours = 07, minutes = 23", числа в которой соответствуют текущему времени.

 

The following examples demonstrate the use of alignment in formatting. The arguments that are formatted are placed between vertical bar characters (|) to highlight the resulting alignment.

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);   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 preceding code displays the following to the console in the U.S. English culture. Different cultures display different currency symbols and separators.

First Name = | Fred| Last Name = | Opals| Price = | $100.00| First Name = |Fred | Last Name = |Opals | Price = |$100.00 |

 

Ниже приведен пример использования выравнивания при форматировании. Форматируемые аргументы разделены знаками вертикальной черты ("|"), подчеркивающими полученное выравнивание.

ß--------------

 

При выборе языка и региональных параметров "Английский (США)" этот код выведет на консоль следующий текст. При выборе различных языковых и региональных параметров знаки денежных единиц и разделители также различаются.

First Name = | Fred| Last Name = | Opals| Price = | $100.00| First Name = |Fred | Last Name = |Opals | Price = |$100.00 |

 

Numeric Format Strings

Numeric format strings control formatting operations in which a numeric data type is represented as a string.

Numeric format strings fall into two categories:

· Standard numeric format strings.

Standard numeric format strings consist of one of a set of standard numeric format specifiers. Each standard format specifier denotes a particular, commonly used string representation of numeric data.

· Custom numeric format strings.

Custom format strings consist of one or more custom numeric format specifiers. Combine custom numeric format specifiers to define an application-specific pattern that determines how numeric data is formatted.

Numeric format strings are supported by the ToString method of numeric types. Numeric format strings are also supported by the.NET Framework composite formatting feature, which is used by certain Write and WriteLine methods of the Console and StreamWriter classes, the String..::.Format method, and the StringBuilder..::.AppendFormat method.