Составное форматирование

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

Следующие методы поддерживают функцию составного форматирования:

• String.Format— возвращает отформатированную строку результата.
• StringBuilder.AppendFormat, который добавляет форматированную строку результата к объекту StringBuilder .
• Некоторые перегрузки Console.WriteLine метода, отображающие форматированную строку результатов в консоли.
• Некоторые перегрузки метода TextWriter.WriteLine, которые записывают отформатированную строку результата в поток или файл. Классы, производные от TextWriterтаких, как StreamWriter и HtmlTextWriter, также, совместно используют эту функцию.
• Debug.WriteLine(String, Object[]) выводит отформатированное сообщение для прослушивателей трассировки.
• Методы Trace.TraceError(String, Object[]), Trace.TraceInformation(String, Object[]) и Trace.TraceWarning(String, Object[]), которые выводят отформатированные сообщения в прослушиватели трассировки.
• Метод TraceSource.TraceInformation(String, Object[]) , который записывает информационный метод для трассировки прослушивателей.

Строка составного формата

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

Рассмотрим следующий Format фрагмент кода:

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

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

Фиксированный текст — это Name = и , hours = . Элементы {0}формата, индекс которых 0 соответствует объекту name, и {1:hh}индекс которого 1 соответствует объекту DateTime.Now.

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

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

{index[,width][:formatString]}

Обязательны соответствующие фигурные скобки ({ и }).

Компонент индекса

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

string primes = string.Format("Four prime numbers: {0}, {1}, {2}, {3}",
                              2, 3, 5, 7);
Console.WriteLine(primes);

// The example displays the following output:
//      Four prime numbers: 2, 3, 5, 7

Dim primes As String = String.Format("Four prime numbers: {0}, {1}, {2}, {3}",
                                      2, 3, 5, 7)
Console.WriteLine(primes)

'The example displays the following output
'     Four prime numbers 2, 3, 5, 7

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

string multiple = string.Format("0x{0:X} {0:E} {0:N}",
                                Int64.MaxValue);
Console.WriteLine(multiple);

// The example displays the following output:
//      0x7FFFFFFFFFFFFFFF 9.223372E+018 9,223,372,036,854,775,807.00

Dim multiple As String = String.Format("0x{0:X} {0:E} {0:N}",
                                       Int64.MaxValue)
Console.WriteLine(multiple)

'The example displays the following output
'     0x7FFFFFFFFFFFFFFF 9.223372E+018 9,223,372,036,854,775,807.00

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

Компонент ширины

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

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

string[] names = { "Adam", "Bridgette", "Carla", "Daniel",
                   "Ebenezer", "Francine", "George" };
decimal[] hours = { 40, 6.667m, 40.39m, 82,
                    40.333m, 80, 16.75m };

Console.WriteLine("{0,-20} {1,5}\n", "Name", "Hours");

for (int counter = 0; counter < names.Length; counter++)
    Console.WriteLine("{0,-20} {1,5:N1}", names[counter], hours[counter]);

// The example displays the following output:
//      Name                 Hours
//      
//      Adam                  40.0
//      Bridgette              6.7
//      Carla                 40.4
//      Daniel                82.0
//      Ebenezer              40.3
//      Francine              80.0
//      George                16.8

Dim names As String() = {"Adam", "Bridgette", "Carla", "Daniel",
                         "Ebenezer", "Francine", "George"}

Dim hours As Decimal() = {40, 6.667D, 40.39D, 82,
                          40.333D, 80, 16.75D}

Console.WriteLine("{0,-20} {1,5}\n", "Name", "Hours")

For counter = 0 To names.Length - 1
    Console.WriteLine("{0,-20} {1,5:N1}", names(counter), hours(counter))
Next

'The example displays the following output
'     Name                 Hours
'     
'     Adam                  40.0
'     Bridgette              6.7
'     Carla                 40.4
'     Daniel                82.0
'     Ebenezer              40.3
'     Francine              80.0
'     George                16.8

Форматирование компонента строки

Необязательный formatString компонент — это строка форматирования, соответствующая типу отформатированного объекта. Можно указать следующее:

• Строка стандартного или настраиваемого числового формата, если соответствующий объект является числовым значением.
• Стандартная или настраиваемая строка формата даты и времени, если соответствующий DateTime объект является объектом.
• Если соответствующий объект является значением перечисления, это строка формата перечисления.

Если параметр formatString не указан, используется общий форматный спецификатор ('G') для числового типа, дат и времени или типа перечисления. Если указан formatString, требуется двоеточие.

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

Дополнительные сведения см. в статьях интерфейса IFormattable и ICustomFormatter.

Экранирование фигурных скобок

Открывающие и закрывающие фигурные скобки интерпретируются как начальный и конечный элемент формата. Чтобы отобразить литеральную фигурную скобку или закрывающую фигурную скобку, необходимо использовать escape-последовательность. Укажите две открывающие фигурные скобки ({{) в фиксированном тексте, чтобы отобразить одну открывающую скобку ({) или две закрывающие фигурные скобки (}}), чтобы отобразить одну закрывающую скобку (}).

Экранированные фигурные скобки с элементом формата по-разному анализируются в .NET и .NET Framework.

.СЕТЬ

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

1. Первые две открывающие скобки ({{) экранируются и превращаются в одну открывающую скобку.
2. Следующие три символа ({0:) интерпретируются как начало элемента формата.
3. Следующий символ (D) интерпретируется как описатель стандартного числового формата десятичного стандарта.
4. Следующая фигурная скобка (}) интерпретируется как конец элемента формата.
5. Последние две закрывающие фигурные скобки экранируются, что приводит к появлению одной закрывающей фигурной скобки.
6. Конечный результат, отображаемый, — литеральная строка {6324}.

int value = 6324;
string output = string.Format("{{{0:D}}}", value);

Console.WriteLine(output);
// The example displays the following output:
//       {6324}

Dim value As Integer = 6324
Dim output As String = String.Format("{{{0:D}}}", value)

Console.WriteLine(output)

'The example displays the following output
'      {6324}

Платформа .NET Framework

Фигурные скобки в элементе формата интерпретируются последовательно в порядке их обнаружения. Интерпретация вложенных фигурных скобок не поддерживается.

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

1. Первые две открывающие скобки ({{) экранируются и превращаются в одну открывающую скобку.
2. Следующие три символа ({0:) интерпретируются как начало элемента формата.
3. Следующий символ (D) будет интерпретирован как спецификатор десятичного стандартного числового формата, но следующие два экранированных фигурных скобок (}}) дают одну фигурную скобку. Так как результирующая строка (D}) не является стандартным числовым описателем, результирующая строка интерпретируется как настраиваемая строка форматирования, которая означает отображение литеральной строки D}.
4. Последняя фигурная скобка (}) интерпретируется как конец элемента формата.
5. Конечный результат, отображаемый, — литеральная строка {D}. Числовое значение, которое должно быть отформатировано, не отображается.

int value = 6324;
string output = string.Format("{{{0:D}}}",
                              value);
Console.WriteLine(output);

// The example displays the following output:
//       {D}

Dim value As Integer = 6324
Dim output As String = String.Format("{{{0:D}}}",
                                     value)
Console.WriteLine(output)

'The example displays the following output:
'      {D}

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

int value = 6324;
string output = string.Format("{0}{1:D}{2}",
                             "{", value, "}");
Console.WriteLine(output);

// The example displays the following output:
//       {6324}

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}

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

Если вызов метода составного форматирования включает аргумент IFormatProvider, значение которого не является null, среда выполнения вызывает его метод IFormatProvider.GetFormat для запроса реализации ICustomFormatter. Если метод может вернуть реализацию ICustomFormatter , он кэширован во время вызова метода составного форматирования.

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

1. Если значение, которое должно быть отформатировано null, возвращается пустая строка String.Empty .

2. Если реализация ICustomFormatter доступна, среда выполнения вызывает её метод Format. Среда выполнения передает значение элемента formatString формата (или null если оно отсутствует) методу. Среда выполнения также передает реализацию IFormatProvider методу. Если вызов метода ICustomFormatter.Format возвращается null, выполнение переходит к следующему шагу. В противном случае возвращается результат ICustomFormatter.Format вызова.

3. Если значение реализует IFormattable интерфейс, вызывается метод интерфейса ToString(String, IFormatProvider) . Если он присутствует в элементе форматирования, formatString значение передается методу. В противном случае передается null. Аргумент IFormatProvider определяется следующим образом:

   • Для числового значения, если вызывается составной метод форматирования с ненулевым IFormatProvider аргументом, среда выполнения запрашивает NumberFormatInfo объект из метода IFormatProvider.GetFormat . Если невозможно это указать, если значение аргумента равно null, или если у метода составного форматирования нет параметра IFormatProvider, используется объект текущих языковых и региональных настроек.

   • Для значения даты и времени, если вызывается составной метод форматирования с ненулевым IFormatProvider аргументом, среда выполнения запрашивает DateTimeFormatInfo объект из метода IFormatProvider.GetFormat . В следующих ситуациях вместо этого используется объект для текущей культуры:

     • Метод IFormatProvider.GetFormat не может предоставить DateTimeFormatInfo объект.
     • Значение аргумента — null.
     • У метода составного форматирования нет IFormatProvider параметра.

   • Для объектов других типов, если метод составного форматирования вызывается с аргументом IFormatProvider , его значение передается непосредственно в реализацию IFormattable.ToString . В противном случае null передается реализации IFormattable.ToString.

4. Метод без ToString параметров типа, который переопределяет Object.ToString() или наследует поведение базового класса, вызывается. В этом случае строка формата, указанная formatString компонентом в элементе форматирования, если она присутствует, игнорируется.

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

Примеры кода

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

string formatString1 = string.Format("{0:dddd MMMM}", DateTime.Now);
string formatString2 = DateTime.Now.ToString("dddd MMMM");

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

Предположим, что текущий день является четвергом в мае, значение обеих строк в предыдущем примере равно Thursday May в американской англоязычной культуре.

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

int myNumber = 100;
Console.WriteLine($"{myNumber:C}");

// The example displays the following output
// if en-US is the current culture:
//        $100.00

Dim myNumber As Integer = 100
Console.WriteLine("{0:C}", myNumber)

'The example displays the following output
'if en-US Is the current culture:
'       $100.00

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

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

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 firstName = "Fred";
string lastName = "Opals";
int myNumber = 100;

string formatFirstName = string.Format("First Name = |{0,10}|", firstName);
string formatLastName = string.Format("Last Name =  |{0,10}|", lastName);
string formatPrice = string.Format("Price =      |{0,10:C}|", myNumber);
Console.WriteLine(formatFirstName);
Console.WriteLine(formatLastName);
Console.WriteLine(formatPrice);
Console.WriteLine();

formatFirstName = string.Format("First Name = |{0,-10}|", firstName);
formatLastName = string.Format("Last Name =  |{0,-10}|", lastName);
formatPrice = string.Format("Price =      |{0,-10:C}|", myNumber);
Console.WriteLine(formatFirstName);
Console.WriteLine(formatLastName);
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   |

Dim firstName As String = "Fred"
Dim lastName As String = "Opals"
Dim myNumber As Integer = 100

Dim formatFirstName As String = String.Format("First Name = |{0,10}|", firstName)
Dim formatLastName As String = String.Format("Last Name =  |{0,10}|", lastName)
Dim formatPrice As String = String.Format("Price =      |{0,10:C}|", myNumber)
Console.WriteLine(formatFirstName)
Console.WriteLine(formatLastName)
Console.WriteLine(formatPrice)
Console.WriteLine()

formatFirstName = String.Format("First Name = |{0,-10}|", firstName)
formatLastName = String.Format("Last Name =  |{0,-10}|", lastName)
formatPrice = String.Format("Price =      |{0,-10:C}|", myNumber)
Console.WriteLine(formatFirstName)
Console.WriteLine(formatLastName)
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   |

См. также

• WriteLine
• String.Format
• Интерполяция строк (C#)
• Интерполяция строк (Visual Basic)
• Типы форматирования
• Стандартные строки числового формата
• строки пользовательского числового формата
• Стандартные строки формата даты и времени
• Настраиваемые строки формата даты и времени
• Строки формата Standard TimeSpan
• Пользовательские строки формата TimeSpan
• Строки формата перечисления