Windows forms string format

Строки настраиваемых числовых форматов Custom numeric format strings

Чтобы определить способ форматирования числовых данных, можно создать строку настраиваемого числового формата, состоящую из одного или нескольких описателей настраиваемого формата. You can create a custom numeric format string, which consists of one or more custom numeric specifiers, to define how to format numeric data. Строка настраиваемого числового формата — это любая строка формата, не являющаяся строкой стандартного числового формата. A custom numeric format string is any format string that is not a standard numeric format string.

Строки настраиваемых числовых форматов поддерживаются некоторыми перегрузками метода ToString всех числовых типов. Custom numeric format strings are supported by some overloads of the ToString method of all numeric types. Например, можно задать строку числового формата для методов ToString(String) и ToString(String, IFormatProvider) типа Int32 . For example, you can supply a numeric format string to the ToString(String) and ToString(String, IFormatProvider) methods of the Int32 type. Строки настраиваемых числовых форматов также поддерживаются функцией составного форматирования .NET Framework, используемой некоторыми методами Write и WriteLine классов Console и StreamWriter, а также методами String.Format и StringBuilder.AppendFormat. Custom numeric format strings are also supported by the .NET composite formatting feature, which is used by some Write and WriteLine methods of the Console and StreamWriter classes, the String.Format method, and the StringBuilder.AppendFormat method. Функция интерполяции строк также поддерживает строки настраиваемого числового формата. String interpolation feature also supports custom numeric format strings.

Вы можете загрузить служебную программу форматирования — приложение Windows Forms для .NET Core, позволяющее применять строки формата к значениям даты и времени и числовым значениям и отображающее результирующую строку. You can download the Formatting Utility, a .NET Core Windows Forms application that lets you apply format strings to either numeric or date and time values and displays the result string. Исходный код доступен для C# и Visual Basic. Source code is available for C# and Visual Basic.

В следующей таблице приведены описатели стандартного числового формата и примеры выходных данных, формируемых каждым описателем формата. The following table describes the custom numeric format specifiers and displays sample output produced by each format specifier. Дополнительные сведения об использовании строк настраиваемого числового формата см. в разделе Примечания ; обширную демонстрацию их использования см. в разделе Пример . See the Notes section for additional information about using custom numeric format strings, and the Example section for a comprehensive illustration of their use.

В приведенных ниже разделах содержится подробная информация о всех описателях настраиваемого числового формата. The following sections provide detailed information about each of the custom numeric format specifiers.

Некоторые примеры C# в этой статье выполняются во встроенном средстве выполнения кода и на тестовой площадке Try.NET. Some of the C# examples in this article run in the Try.NET inline code runner and playground. Нажмите на кнопку Выполнить, чтобы выполнить пример в интерактивном окне. Select the Run button to run an example in an interactive window. После выполнения кода вы можете изменить его и выполнить измененный код, снова нажав на кнопку Выполнить. Once you execute the code, you can modify it and run the modified code by selecting Run again. Либо в интерактивном окне выполняется измененный код, либо, если компиляция завершается с ошибкой, в интерактивном окне отображаются все сообщения об ошибках компилятора C#. The modified code either runs in the interactive window or, if compilation fails, the interactive window displays all C# compiler error messages.

Настраиваемый описатель «0» The «0» custom specifier

Описатель настраиваемого формата «0» служит нулевым символом-заполнителем. The «0» custom format specifier serves as a zero-placeholder symbol. Если форматируемое значение содержит цифру в позиции, где в строке формата стоит ноль, то эта цифра копируется в результирующую строку; в противном случае в результирующей строке будет стоять ноль. If the value that is being formatted has a digit in the position where the zero appears in the format string, that digit is copied to the result string; otherwise, a zero appears in the result string. Позиция крайнего левого нуля перед разделителем целой и дробной частей и позиция крайнего правого нуля после разделителя целой и дробной частей определяют диапазон цифр, которые всегда включаются в результирующую строку. The position of the leftmost zero before the decimal point and the rightmost zero after the decimal point determines the range of digits that are always present in the result string.

Спецификатор «00» приводит к округлению значения до ближайшего значения цифры, предшествующей десятичной точке-разделителю, если назначено использование округления от нуля. The «00» specifier causes the value to be rounded to the nearest digit preceding the decimal, where rounding away from zero is always used. Например, в результате форматирования числа 34,5 с помощью строки «00» будет получена строка со значением»35″. For example, formatting 34.5 with «00» would result in the value 35.

В следующем примере показано форматирование нескольких значений с помощью строк настраиваемого формата, содержащих нулевые заполнители. The following example displays several values that are formatted by using custom format strings that include zero placeholders.

Настраиваемый описатель «#» The «#» custom specifier

Описатель настраиваемого формата «#» служит символом-заполнителем для цифр. The «#» custom format specifier serves as a digit-placeholder symbol. Если в форматируемом значении на позиции, где в строке формата присутствует символ «#», есть цифра, то эта цифра копируется в результирующую строку. If the value that is being formatted has a digit in the position where the «#» symbol appears in the format string, that digit is copied to the result string. В противном случае в выходной строке на этой позиции ничего не записывается. Otherwise, nothing is stored in that position in the result string.

Обратите внимание, что при использовании этого описателя незначащие нули не отображаются, даже если ноль является единственной цифрой в строке. Note that this specifier never displays a zero that is not a significant digit, even if zero is the only digit in the string. Ноль отображается только в том случае, если он является значащей цифрой отображаемого числа. It will display zero only if it is a significant digit in the number that is being displayed.

Строка формата «##» приводит к округлению значения до ближайшего значения цифры, предшествующей десятичному разделителю, если назначено использование округления от нуля. The «##» format string causes the value to be rounded to the nearest digit preceding the decimal, where rounding away from zero is always used. Например, в результате форматирования числа 34,5 с помощью строки «##» будет получена строка со значением «35». For example, formatting 34.5 with «##» would result in the value 35.

В следующем примере показано форматирование нескольких значений с помощью строк настраиваемого формата, содержащих заполнители для цифр. The following example displays several values that are formatted by using custom format strings that include digit placeholders.

Чтобы получить итоговую строку, в которой отсутствуют цифры или начальные нули заменены пробелами, используйте функциональность составного форматирования и укажите ширину поля, как показано в следующем примере. To return a result string in which absent digits or leading zeroes are replaced by spaces, use the composite formatting feature and specify a field width, as the following example illustrates.

Настраиваемый описатель «.» The «.» custom specifier

Описатель настраиваемого формата «.» вставляет в результирующую строку локализованный разделитель целой и дробной частей числа. The «.» custom format specifier inserts a localized decimal separator into the result string. Первая точка в строке формата определяет расположение разделителя целой и дробной частей форматированного значения, а все прочие точки игнорируются. The first period in the format string determines the location of the decimal separator in the formatted value; any additional periods are ignored.

Символ, используемый в качестве разделителя целой и дробной части в результирующей строке, не всегда будет точкой; его значение определяется свойством NumberDecimalSeparator объекта NumberFormatInfo , управляющего форматированием. The character that is used as the decimal separator in the result string is not always a period; it is determined by the NumberDecimalSeparator property of the NumberFormatInfo object that controls formatting.

В следующем примере спецификатор формата «.» используется для определения местоположения десятичного разделителя в нескольких выходных строках. The following example uses the «.» format specifier to define the location of the decimal point in several result strings.

Настраиваемый описатель «,» The «,» custom specifier

Символ «,» служит в качестве описателя разделителя групп и описателя масштабирования чисел. The «,» character serves as both a group separator and a number scaling specifier.

Разделитель групп. Если между двумя заполнителями для цифр («0» или «#»), задающими форматирование целой части числа, стоит одна или несколько запятых, то между всеми группами целой части числа вставляется символ-разделитель групп. Group separator: If one or more commas are specified between two digit placeholders (0 or #) that format the integral digits of a number, a group separator character is inserted between each number group in the integral part of the output.

Свойства NumberGroupSeparator и NumberGroupSizes текущего объекта NumberFormatInfo определяют знак, используемый в качестве разделителя групп числа и размера каждой группы числа. The NumberGroupSeparator and NumberGroupSizes properties of the current NumberFormatInfo object determine the character used as the number group separator and the size of each number group. Например, если строка «#,#» и неизменяемый язык и региональные параметры используются для форматирования числа 1000, то результатом является «1,000». For example, if the string «#,#» and the invariant culture are used to format the number 1000, the output is «1,000».

Описатель масштабирования чисел. Если сразу слева от явно или неявно заданного разделителя целой и дробной части стоит одна или несколько запятых, форматируемое число делится на 1000 для каждой указанной запятой. Number scaling specifier: If one or more commas are specified immediately to the left of the explicit or implicit decimal point, the number to be formatted is divided by 1000 for each comma. Например, если строка «0,,» используется для форматирования числа 100 миллионов, то результатом является «100». For example, if the string «0,,» is used to format the number 100 million, the output is «100».

Разделитель групп и описатель масштабирования чисел можно использовать в строке формата одновременно. You can use group separator and number scaling specifiers in the same format string. Например, если строка «#, 0,,» и неизменяемый язык и региональные параметры используются для форматирования числа один миллиард, то результатом является «1,000». For example, if the string «#,0,,» and the invariant culture are used to format the number one billion, the output is «1,000».

В следующем примере демонстрируется использование запятой в качестве разделителя групп. The following example illustrates the use of the comma as a group separator.

Следующий пример иллюстрирует использование запятой как спецификатора масштабирования числа. The following example illustrates the use of the comma as a specifier for number scaling.

Настраиваемый описатель «%» The «%» custom specifier

При использовании символа процента («%») в строке формата число перед форматированием будет умножено на 100. A percent sign (%) in a format string causes a number to be multiplied by 100 before it is formatted. В то место, где в строке формата стоит символ «%», в число будет вставлен локализованный символ процента. The localized percent symbol is inserted in the number at the location where the % appears in the format string. Используемый при этом символ процента определяется свойством PercentSymbol текущего объекта NumberFormatInfo . The percent character used is defined by the PercentSymbol property of the current NumberFormatInfo object.

В следующем примере определяется несколько строк настраиваемого формата, включающих настраиваемый описатель «%». The following example defines several custom format strings that include the «%» custom specifier.

Настраиваемый описатель «‰» The «‰» custom specifier

При использовании в строке формата символа промилле («‰» или «\u2030») перед форматированием число будет умножено на 1000. A per mille character (‰ or \u2030) in a format string causes a number to be multiplied by 1000 before it is formatted. В позицию возвращаемой строки, соответствующую положению символа «‰» в строке формата, будет вставлен необходимый символ промилле. The appropriate per mille symbol is inserted in the returned string at the location where the ‰ symbol appears in the format string. Используемый знак промилле определяется значением свойства NumberFormatInfo.PerMilleSymbol объекта, содержащего сведения о форматировании для заданного языка и региональных параметров. The per mille character used is defined by the NumberFormatInfo.PerMilleSymbol property of the object that provides culture-specific formatting information.

В следующем примере определяется строка настраиваемого формата, включающая настраиваемый описатель «‰». The following example defines a custom format string that includes the «‰» custom specifier.

Настраиваемые описатели «E» и «e» The «E» and «e» custom specifiers

Если в строке формата присутствует подстрока «E», «E+», «E-«, «e», «e+» или «e-«, за которой сразу следует по меньшей мере один ноль, то число форматируется с использованием экспоненциальной нотации. Между числом и экспонентой при этом вставляется символ «E» или «e». If any of the strings «E», «E+», «E-«, «e», «e+», or «e-» are present in the format string and are followed immediately by at least one zero, the number is formatted by using scientific notation with an «E» or «e» inserted between the number and the exponent. Минимальное число цифр экспоненты в результирующей строке определяется количеством нулей, стоящих после индикатора экспоненциальной нотации. The number of zeros following the scientific notation indicator determines the minimum number of digits to output for the exponent. Форматы «E+» и «e+» указывают на то, что перед экспонентой всегда должен стоять положительный или отрицательный знак. The «E+» and «e+» formats indicate that a plus sign or minus sign should always precede the exponent. Форматы «E», «e», «E-» и «e-» указывают на то, что символ знака должен ставиться только перед экспонентой с отрицательным значением. The «E», «E-«, «e», or «e-» formats indicate that a sign character should precede only negative exponents.

В следующем примере несколько числовых значений форматируются с помощью спецификаторов экспоненциального представления. The following example formats several numeric values using the specifiers for scientific notation.

Escape-символ «\» The «\» escape character

Символы «#», «0», «.», «,», «%» и «‰» в строке формата воспринимаются как описатели формата, а не как символы-литералы. The «#», «0», «.», «,», «%», and «‰» symbols in a format string are interpreted as format specifiers rather than as literal characters. В зависимости от положения в строке настраиваемого формата символ «E» верхнего и нижнего регистра, также как и символы «+» и «-«, могут восприниматься как описатели формата. Depending on their position in a custom format string, the uppercase and lowercase «E» as well as the + and — symbols may also be interpreted as format specifiers.

Чтобы предотвратить интерпретацию символа в качестве описателя формата, перед ним можно поставить так называемый escape-символ — обратную косую черту. To prevent a character from being interpreted as a format specifier, you can precede it with a backslash, which is the escape character. Наличие escape-символа означает, что следующий за ним символ является литералом, который следует перенести в результирующую строку без изменений. The escape character signifies that the following character is a character literal that should be included in the result string unchanged.

Чтобы включить в результирующую строку обратную косую черту, перед ней нужно поставить дополнительную обратную косую черту ( \\ ). To include a backslash in a result string, you must escape it with another backslash ( \\ ).

Кроме того, в некоторых компиляторах, например компиляторах C++ и C#, одиночная обратная косая черта также может восприниматься как escape-символ. Some compilers, such as the C++ and C# compilers, may also interpret a single backslash character as an escape character. Чтобы гарантировать, что строка будет правильно воспринята при форматировании, можно поставить символ буквального строкового литерала (символ «@») перед строкой в C# или добавить дополнительный символ обратной косой черты перед каждой обратной косой чертой в C# и C++. To ensure that a string is interpreted correctly when formatting, you can use the verbatim string literal character (the @ character) before the string in C#, or add another backslash character before each backslash in C# and C++. В следующем примере кода на языке C# демонстрируются оба подхода. The following C# example illustrates both approaches.

В следующем примере интерпретация символов #, 0 и \ в качестве escape-символов или описателей формата при форматировании предотвращается с помощью escape-символа. The following example uses the escape character to prevent the formatting operation from interpreting the «#», «0», and «\» characters as either escape characters or format specifiers. В примерах на языке C# используется дополнительная обратная косая черта, позволяющая гарантировать, что обратная косая черта будет воспринята как символ-литерал. The C# examples uses an additional backslash to ensure that a backslash is interpreted as a literal character.

Разделитель секций «;» The «;» section separator

Точка с запятой («;») — это описатель условного формата, применяющий разное форматирование к числу в зависимости от того, является оно положительным числом, отрицательным числом или нулем. The semicolon (;) is a conditional format specifier that applies different formatting to a number depending on whether its value is positive, negative, or zero. Для этого следует создать строку формата, состоящую из трех секций, разделенных точкой с запятой. To produce this behavior, a custom format string can contain up to three sections separated by semicolons. Эти секции описаны в следующей таблице. These sections are described in the following table.

При форматировании конечного значения разделители секций игнорируют любое существовавшее ранее форматирование, связанное с числом. Section separators ignore any preexisting formatting associated with a number when the final value is formatted. Например, при использовании разделителей секций отрицательные значения всегда отображаются без знака «минус». For example, negative values are always displayed without a minus sign when section separators are used. Чтобы конечное отформатированное значение содержало знак «минус», его следует явным образом включить в настраиваемый спецификатор формата. If you want the final formatted value to have a minus sign, you should explicitly include the minus sign as part of the custom format specifier.

В следующем примере описатель формата «;» используется для форматирования положительных чисел, отрицательных чисел и нулей различными способами. The following example uses the «;» format specifier to format positive, negative, and zero numbers differently.

Символьные литералы Character literals

Описатели формата, которые появляются в строке настраиваемых числовых форматов, всегда интерпретируются как символы формата и никогда не обрабатываются как литеральные символы. Format specifiers that appear in a custom numeric format string are always interpreted as formatting characters and never as literal characters. К ним относятся следующие символы: This includes the following characters:

Все остальные символы всегда интерпретируется как символьные литералы. В операции форматирования они включаются в результирующую строку без изменений. All other characters are always interpreted as character literals and, in a formatting operation, are included in the result string unchanged. В операции анализа они должны точно соответствовать символам во входной строке. При сравнении учитывается регистр. In a parsing operation, they must match the characters in the input string exactly; the comparison is case-sensitive.

В следующем примере демонстрируется распространенный пример применения литеральных символов единиц измерения (в данном случае тысяч): The following example illustrates one common use of literal character units (in this case, thousands):

Указать необходимость интерпретации символов как литеральных, а не как символов формата, для их последующего включения в результирующую строку или успешного анализа во входной строке можно двумя способами: There are two ways to indicate that characters are to be interpreted as literal characters and not as formatting characters, so that they can be included in a result string or successfully parsed in an input string:

Путем экранирования символа формата. By escaping a formatting character. Дополнительные сведения см. в разделе Escape-символ «\». For more information, see The «\» escape character.

Путем заключения всей литеральной строки в апострофы. By enclosing the entire literal string in quotation apostrophes.

В следующем примере применяются оба подхода, что позволяет включить зарезервированные символы в настраиваемую строку числового формата. The following example uses both approaches to include reserved characters in a custom numeric format string.

Примечания Notes

Бесконечности действительных чисел с плавающей запятой и NaN Floating-Point infinities and NaN

Если вне зависимости от строки формата значение типа с плавающей запятой Single или Double является положительной бесконечностью, отрицательной бесконечностью или не является числом (NaN), отформатированная строка будет содержать значение соответствующего свойства ( PositiveInfinitySymbol, NegativeInfinitySymbolили NaNSymbol ), применимого в настоящий момент объекта NumberFormatInfo . Regardless of the format string, if the value of a Single or Double floating-point type is positive infinity, negative infinity, or not a number (NaN), the formatted string is the value of the respective PositiveInfinitySymbol, NegativeInfinitySymbol, or NaNSymbol property specified by the currently applicable NumberFormatInfo object.

Параметры панели управления Control Panel settings

Параметры элемента панели управления Язык и региональные стандарты влияют на выходную строку, получаемую в результате операции форматирования. The settings in the Regional and Language Options item in Control Panel influence the result string produced by a formatting operation. Эти параметры используются для инициализации объекта NumberFormatInfo , связанного с текущей культурой потока, а текущая культура потока предоставляет значения, которые используются для управления форматированием. Those settings are used to initialize the NumberFormatInfo object associated with the current thread culture, and the current thread culture provides values used to govern formatting. Результирующие строки будут различаться на компьютерах с разными параметрами. Computers that use different settings generate different result strings.

Кроме того, если конструктор CultureInfo(String) используется для создания нового экземпляра объекта CultureInfo , представляющего язык и региональные параметры, аналогичные текущему языку и региональным параметрам системы, то все настройки, заданные в разделе Язык и региональные стандарты панели управления, будут применяться к новому объекту CultureInfo . In addition, if you use the CultureInfo(String) constructor to instantiate a new CultureInfo object that represents the same culture as the current system culture, any customizations established by the Regional and Language Options item in Control Panel will be applied to the new CultureInfo object. Можно воспользоваться конструктором CultureInfo(String, Boolean) для создания объекта CultureInfo , который не отражает настройки системы. You can use the CultureInfo(String, Boolean) constructor to create a CultureInfo object that does not reflect a system’s customizations.

Строки формата с фиксированной запятой и округлением Rounding and fixed-point format strings

Строки формата с фиксированной запятой (строки формата, не содержащие символов экспоненциальной нотации) округляют значение с точностью, определяемой количеством символов-заполнителей, стоящих справа от разделителя целой и дробной частей. For fixed-point format strings (that is, format strings that do not contain scientific notation format characters), numbers are rounded to as many decimal places as there are digit placeholders to the right of the decimal point. Если в строке формата нет десятичной точки, то число округляется до ближайшего целого значения. If the format string does not contain a decimal point, the number is rounded to the nearest integer. Если слева от десятичной точки больше цифр, чем знаков-заместителей цифр, то лишние знаки копируются в выходную строку перед первым знаком-заместителем цифры. If the number has more digits than there are digit placeholders to the left of the decimal point, the extra digits are copied to the result string immediately before the first digit placeholder.

Пример Example

В следующем примере показаны две строки настраиваемого числового формата. The following example demonstrates two custom numeric format strings. В обоих случаях заполнитель для цифр ( # ) отображает числовые данные, а все остальные символы копируются в результирующую строку. In both cases, the digit placeholder ( # ) displays the numeric data, and all other characters are copied to the result string.

Источник