String format c что это

Строки настраиваемых форматов даты и времени

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примеры кода

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

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

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

Источник

String. Format Method

Definition

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Converts the value of objects to strings based on the formats specified and inserts them into another string.

If you are new to the String.Format method, see the Get started with the String.Format method section for a quick overview.

See the Remarks section for general documentation for the String.Format method.

Overloads

Replaces one or more format items in a string with the string representation of a specified object.

Replaces the format item in a specified string with the string representation of a corresponding object in a specified array.

Replaces the format item or items in a specified string with the string representation of the corresponding object. A parameter supplies culture-specific formatting information.

Replaces the format items in a string with the string representations of corresponding objects in a specified array. A parameter supplies culture-specific formatting information.

Replaces the format items in a string with the string representation of two specified objects.

Replaces the format items in a string with the string representation of two specified objects. A parameter supplies culture-specific formatting information.

Replaces the format items in a string with the string representation of three specified objects.

Replaces the format items in a string with the string representation of three specified objects. An parameter supplies culture-specific formatting information.

Examples

Numerous examples that call the Format method are interspersed through the Remarks section of this article.

The following are some of the examples included in the article:

Create a format string

Control formatted output

Make format strings culture-sensitive

Customize the formatting operation

Remarks

Instead of calling the String.Format method or using composite format strings, you can use interpolated strings if your language supports them. An interpolated string is a string that contains interpolated expressions. Each interpolated expression is resolved with the expression’s value and included in the result string when the string is assigned. For more information, see String interpolation (C# Reference) and Interpolated Strings (Visual Basic Reference).

Get started with the String.Format method

Use String.Format if you need to insert the value of an object, variable, or expression into another string. For example, you can insert the value of a Decimal value into a string to display it to the user as a single string:

And you can control that value’s formatting:

Besides formatting, you can also control alignment and spacing.

Insert a string

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. For example:

The <0>in the format string is a format item. 0 is the index of the object whose string value will be inserted at that position. (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.

Here’s another example that uses two format items and two objects in the object list:

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. You also don’t have to worry about which overload you call; the compiler will select the appropriate one for you.

Control formatting

You can follow the index in a format item with a format string to control how an object is formatted. For example, <0:d>applies the «d» format string to the first object in the object list. Here is an example with a single object and two format items:

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. You can also add support for format strings to your own types.

Control spacing

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. In this case, the string representation of the first object is right-aligned in the 12-character field. (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.)

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. Note that the characters are right-aligned in the field.

Control alignment

By default, strings are right-aligned within their field if you specify a field width. 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.

The following example is similar to the previous one, except that it left-aligns both labels and data.

String.Format makes use of the composite formatting feature. For more information, see Composite Formatting.

Which method do I call?

The Format method in brief

The format item

A format item has this syntax:

Brackets denote optional elements. The opening and closing braces are required. (To include a literal opening or closing brace in the format string, see the Escaping Braces section in the Composite Formatting article.)

For example, a format item to format a currency value might appear like this:

A format item has the following elements:

alignment
Optional. 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). If you omit alignment, the string representation of the corresponding argument is inserted in a field with no leading or trailing spaces.

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.

formatString
Optional. A string that specifies the format of the corresponding argument’s result string. If you omit formatString, the corresponding argument’s parameterless ToString method is called to produce its string representation. If you specify formatString, the argument referenced by the format item must implement the IFormattable interface. Types that support format strings include:

However, note that any custom type can implement IFormattable or extend an existing type’s IFormattable implementation.

The following example uses the alignment and formatString arguments to produce formatted output.

How arguments are formatted

Format items are processed sequentially from the beginning of the string. Each format item has an index that corresponds to an object in the method’s argument list. The Format method retrieves the argument and derives its string representation as follows:

If you call the Format(IFormatProvider, String, Object[]) overload and the provider object’s IFormatProvider.GetFormat implementation returns a non-null ICustomFormatter implementation, the argument is passed to its ICustomFormatter.Format(String, Object, IFormatProvider) method. If the format item includes a formatString argument, it is passed as the first argument to the method. If the ICustomFormatter implementation is available and produces a non-null string, that string is returned as the string representation of the argument; otherwise, the next step executes.

If the argument implements the IFormattable interface, its IFormattable.ToString implementation is called.

The argument’s parameterless ToString method, which either overrides or inherits from a base class implementation, is called.

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.

For more information, see the Processing Order section in the Composite Formatting article.

Format items that have the same index

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. However, format can include more format items than there are arguments, as long as multiple format items have the same index. 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.

Format and culture

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. You can control this behavior by calling one of the overloads of Format that includes a provider parameter. The provider parameter is an IFormatProvider implementation that supplies custom and culture-specific formatting information that is used to moderate the formatting process.

CultureInfo. Its GetFormat method returns a culture-specific NumberFormatInfo object for formatting numeric values and a culture-specific DateTimeFormatInfo object for formatting date and time values.

DateTimeFormatInfo, which is used for culture-specific formatting of date and time values. Its GetFormat method returns itself.

NumberFormatInfo, which is used for culture-specific formatting of numeric values. Its GetFormat property returns itself.

Custom formatting operations

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. For example, you could format an integer as an identification number or as a telephone number. To perform custom formatting, your provider argument must implement both the IFormatProvider and ICustomFormatter interfaces. 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. It then calls the returned ICustomFormatter object’s Format method to format each format item in the composite string passed to it.

For more information about providing custom formatting solutions, see How to: Define and Use Custom Numeric Format Providers and ICustomFormatter. For an example that converts integers to formatted custom numbers, see Example: A custom formatting operation. For an example that converts unsigned bytes to Roman numerals, see Example: An intercept provider and Roman numeral formatter.

Example: A custom formatting operation

This example defines a format provider that formats an integer value as a customer account number in the form x-xxxxx-xx.

Example: An intercept provider and Roman numeral formatter

This example defines a custom format provider that implements the ICustomFormatter and IFormatProvider interfaces to do two things:

It displays the parameters passed to its ICustomFormatter.Format implementation. 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. This can be useful when you’re debugging your application.

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.

String.Format Q & A

Why do you recommend string interpolation over calls to the String.Format method?

String interpolation is:

More flexible. It can be used in any string without requiring a call to a method that supports composite formatting. Otherwise, you have to call the Format method or another method that supports composite formatting, such as Console.WriteLine or StringBuilder.AppendFormat.

More readable. 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. 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.

A comparison of the following two code examples illustrates the superiority of interpolated strings over string concatenation and calls to composite formatting methods. The use of multiple string concatenation operations in the following example produces verbose and hard-to-read code.

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.

Where can I find a list of the predefined format strings that can be used with format items?

For Guid values, see the Remarks section of the Guid.ToString(String) reference page.

How do I control the alignment of the result strings that replace format items?

The general syntax of a format item is:

where alignment is a signed integer that defines the field width. If this value is negative, text in the field is left-aligned. If it is positive, text is right-aligned.

How do I control the number of digits after the decimal separator?

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. The following example uses standard numeric format strings to control the number of decimal digits in the result string.

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.

How do I control the number of integral digits?

By default, formatting operations only display non-zero integral digits. 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.

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.

How many items can I include in the format list?

There is no practical limit. 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.

How do I include literal braces («<" and ">«) in the result string?

For example, how do you prevent the following method call from throwing a FormatException exception?

A single opening or closing brace is always interpreted as the beginning or end of a format item. To be interpreted literally, it must be escaped. You escape a brace by adding another brace («<<" and ">>» instead of «<" and ">«), as in the following method call:

However, even escaped braces are easily misinterpreted. 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.

Why does my call to the String.Format method throw a FormatException?

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. Usually this indicates that you’ve misnumbered the indexes of format items or you’ve forgotten to include an object in the format list. Attempting to include an unescaped left or right brace character also throws a FormatException. 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).

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?

For example, the following code throws a FormatException exception:

This is a problem of compiler overload resolution. 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. The exception is thrown because there are four format items but only a single item in the format list.

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. The following example provides one implementation.

Format(String, Object)

Replaces one or more format items in a string with the string representation of a specified object.

Parameters

The object to format.

Returns

Exceptions

The format item in format is invalid.

The index of a format item is not zero.

Remarks

Instead of calling the String.Format method or using composite format strings, you can use interpolated strings if your language supports them. An interpolated string is a string that contains interpolated expressions. Each interpolated expression is resolved with the expression’s value and included in the result string when the string is assigned. For more information, see String interpolation (C# Reference) and Interpolated Strings (Visual Basic Reference).

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.

However, when calling the String.Format method, it is not necessary to focus on the particular overload that you want to call. Instead, you can call the method with a composite format string that includes one or more format items. You assign each format item a numeric index; the first index starts at 0. In addition to the initial string, your method call should have as many additional arguments as it has index values. 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. Your language compiler will then resolve your method call to a particular overload of the String.Format method.

For more detailed documentation on using the String.Format method, see Getting started with the String.Format method and Which method do I call?.

Example: Formatting a single argument

The following example uses the Format(String, Object) method to embed an individual’s age in the middle of a string.

See also

Applies to

Format(String, Object[])

Replaces the format item in a specified string with the string representation of a corresponding object in a specified array.

Parameters

An object array that contains zero or more objects to format.

Returns

Exceptions

The index of a format item is less than zero, or greater than or equal to the length of the args array.

Remarks

Instead of calling the String.Format method or using composite format strings, you can use interpolated strings if your language supports them. An interpolated string is a string that contains interpolated expressions. Each interpolated expression is resolved with the expression’s value and included in the result string when the string is assigned. For more information, see String interpolation (C# Reference) and Interpolated Strings (Visual Basic Reference).

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. 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.

However, when calling the String.Format method, it is not necessary to focus on the particular overload that you want to call. Instead, you can call the method with a composite format string that includes one or more format items. You assign each format item a numeric index; the first index starts at 0. In addition to the initial string, your method call should have as many additional arguments as it has index values. 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. Your language compiler will then resolve your method call to a particular overload of the String.Format method.

For more detailed documentation on using the String.Format method, see Getting started with the String.Format method and Which method do I call?.

Example: Format more than three arguments

This example creates a string that contains data on the high and low temperature on a particular date. The composite format string has five format items in the C# example and six in the Visual Basic example. 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.

You can also pass the objects to be formatted as an array rather than as an argument list.

See also

Applies to

Format(IFormatProvider, String, Object)

Replaces the format item or items in a specified string with the string representation of the corresponding object. A parameter supplies culture-specific formatting information.

Parameters

An object that supplies culture-specific formatting information.

The object to format.

Returns

Exceptions

The index of a format item is not zero.

Remarks

Instead of calling the String.Format method or using composite format strings, you can use interpolated strings if your language supports them. An interpolated string is a string that contains interpolated expressions. Each interpolated expression is resolved with the expression’s value and included in the result string when the string is assigned. For more information, see String interpolation (C# Reference) and Interpolated Strings (Visual Basic Reference).

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. In performing the conversion, the method uses culture-sensitive formatting or a custom formatter. 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. If these methods don’t exist, it calls the object’s parameterless ToString method.

However, when calling the String.Format method, it is not necessary to focus on the particular overload that you want to call. 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. You assign each format item a numeric index; the first index starts at 0. In addition to the initial string, your method call should have as many additional arguments as it has index values. 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. Your language compiler will then resolve your method call to a particular overload of the String.Format method.

For more detailed documentation on using the String.Format method, see Getting started with the String.Format method and Which method do I call?.

Applies to

Format(IFormatProvider, String, Object[])

Replaces the format items in a string with the string representations of corresponding objects in a specified array. A parameter supplies culture-specific formatting information.

Parameters

An object that supplies culture-specific formatting information.

An object array that contains zero or more objects to format.

Returns

Exceptions

The index of a format item is less than zero, or greater than or equal to the length of the args array.

Remarks

Instead of calling the String.Format method or using composite format strings, you can use interpolated strings if your language supports them. An interpolated string is a string that contains interpolated expressions. Each interpolated expression is resolved with the expression’s value and included in the result string when the string is assigned. For more information, see String interpolation (C# Reference) and Interpolated Strings (Visual Basic Reference).

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. In performing the conversion, the method uses culture-sensitive formatting or a custom formatter. 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. If these methods don’t exist, it calls the object’s parameterless ToString method.

However, when calling the String.Format method, it is not necessary to focus on the particular overload that you want to call. 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. You assign each format item a numeric index; the first index starts at 0. In addition to the initial string, your method call should have as many additional arguments as it has index values. 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. Your language compiler will then resolve your method call to a particular overload of the String.Format method.

For more detailed documentation on using the String.Format method, see Getting started with the String.Format method and Which method do I call?.

Example: Culture-sensitive formatting

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.

Источник

• ← Как называется сумерки все части
• В чем закаляют металл →